A USB "gadget" can be set up entirely through configfs. This patch adds options to build the USB functions' modules without building "old" gadget modules, e.g. build usb_f_acm.ko or usb_f_ecm.ko, but not g_cdc.ko. Please see: http://www.spinics.net/lists/linux-usb/msg83460.html http://www.spinics.net/lists/linux-usb/msg85065.html http://www.spinics.net/lists/linux-usb/msg85156.html for what functions are already available through configfs; so far the equivalents of g_serial, g_ncm and g_cdc can be set up through configfs. Please note, that the actual gadget composition can consist of any functions available, not just those available in a given "old" g_xxxxxx.ko gadget. That is, one can take some functions found in g_serial, some in g_ncm and some in g_cdc, e.g. such a gadget can consist of acm, generic serial, obex and ecm, functions, while the g_serial consists of acm, generic serial, obex, the g_ncm consists of ncm and g_cdc consists of acm and ecm. The concept is illustrated in the table below, taking into account the currently available configfs support: --------------------------------------------------------------------------- | gadget | |----------------------------------------------------------- function | g_serial | g_ncm | g_cdc | set up through configfs | --------------------------------------------------------------------------- acm | * | | * | o | generic serial | * | | | o | obex | * | | | o | ncm | | * | | o | ecm | | | * | o | | | | | | . . . . . . . . . . . . . . . . . . << more functions to come >> . . . . . . . . . . . . . . . . . . --------------------------------------------------------------------------- "*" - built-in, mandatory, no other functions possible "o" - option So one can create, using only mkdir/echo/ln from shell, a gadget which provides e.g. acm, generic serial, obex and ecm without adding and compiling a new g_serial_with_ecm.c. A documentation file is added to Documentation/usb. Function's attributes are described in Documentation/ABI/*/configfs-usb-gadget* The latter might need adjusting the "KernelVersion" and "Date" tags. Signed-off-by: Andrzej Pietrasiewicz <andrzej.p@xxxxxxxxxxx> Signed-off-by: Kyungmin Park <kyungmin.park@xxxxxxxxxxx> --- Documentation/ABI/testing/configfs-usb-gadget | 81 ++++ Documentation/ABI/testing/configfs-usb-gadget-acm | 8 + Documentation/ABI/testing/configfs-usb-gadget-ecm | 16 + Documentation/ABI/testing/configfs-usb-gadget-ncm | 15 + Documentation/ABI/testing/configfs-usb-gadget-obex | 9 + .../ABI/testing/configfs-usb-gadget-serial | 9 + Documentation/usb/gadget_configfs.txt | 384 ++++++++++++++++++++ drivers/usb/gadget/Kconfig | 65 ++++ 8 files changed, 587 insertions(+), 0 deletions(-) create mode 100644 Documentation/ABI/testing/configfs-usb-gadget create mode 100644 Documentation/ABI/testing/configfs-usb-gadget-acm create mode 100644 Documentation/ABI/testing/configfs-usb-gadget-ecm create mode 100644 Documentation/ABI/testing/configfs-usb-gadget-ncm create mode 100644 Documentation/ABI/testing/configfs-usb-gadget-obex create mode 100644 Documentation/ABI/testing/configfs-usb-gadget-serial create mode 100644 Documentation/usb/gadget_configfs.txt diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget new file mode 100644 index 0000000..10e304e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -0,0 +1,81 @@ +What: /config/usb-gadget +Date: Apr 2013 +KenelVersion: 3.9 +Description: + This group contains sub-groups corresponding to created + USB gadgets. + +What: /config/usb-gadget/gadget +Date: Apr 2013 +KenelVersion: 3.9 +Description: + + The attributes of a gadget: + + UDC - bind a gadget to UDC/unbind a gadget; + write UDC's name found in /sys/class/udc/* + to bind a gadget, empty string "" to unbind. + + bDeviceClass - USB device class code + bDeviceSubClass - USB device subclass code + bDeviceProtocol - USB device protocol code + bMaxPacketSize0 - maximum endpoint 0 packet size + bcdDevice - bcd device release number + bcdUSB - bcd USB specification version number + idProduct - product ID + idVendor - vendor ID + +What: /config/usb-gadget/gadget/configs +Date: Apr 2013 +KenelVersion: 3.9 +Description: + This group contains a USB gadget's configurations + +What: /config/usb-gadget/gadget/configs/config +Date: Apr 2013 +KernelVersion: 3.9 +Description: + The attributes of a configuration: + + bmAttributes - configuration characteristics + MaxPower - maximum power consumption from the bus + +What: /config/usb-gadget/gadget/configs/config/strings +Date: Apr 2013 +KernelVersion: 3.9 +Description: + This group contains subdirectories for language-specific + strings for this configuration. + +What: /config/usb-gadget/gadget/configs/config/strings/language +Date: Apr 2013 +KernelVersion: 3.9 +Description: + The attributes: + + configuration - configuration description + + +What: /config/usb-gadget/gadget/functions +Date: Apr 2013 +KenelVersion: 3.9 +Description: + This group contains functions available to this USB gadget. + +What: /config/usb-gadget/gadget/strings +Date: Apr 2013 +KenelVersion: 3.9 +Description: + This group contains subdirectories for language-specific + strings for this gadget. + +What: /config/usb-gadget/gadget/strings/language +Date: Apr 2013 +KenelVersion: 3.9 +Description: + The attributes: + + serialnumber - gadget's serial number (string) + product - gadget's product description + manufacturer - gadget's manufacturer description + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm new file mode 100644 index 0000000..e9f8b9b --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-acm @@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/acm.name +Date: Apr 2013 +KenelVersion: 3.9 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with acm function's instance "name". diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm new file mode 100644 index 0000000..97344d6 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm @@ -0,0 +1,16 @@ +What: /config/usb-gadget/gadget/functions/ecm.name +Date: Apr 2013 +KenelVersion: 3.10 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ncm b/Documentation/ABI/testing/configfs-usb-gadget-ncm new file mode 100644 index 0000000..42fc951 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ncm @@ -0,0 +1,15 @@ +What: /config/usb-gadget/gadget/functions/ncm.name +Date: Apr 2013 +KenelVersion: 3.10 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-obex b/Documentation/ABI/testing/configfs-usb-gadget-obex new file mode 100644 index 0000000..b232b58 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-obex @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/obex.name +Date: Apr 2013 +KenelVersion: 3.10 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with obex function's instance "name". + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-serial b/Documentation/ABI/testing/configfs-usb-gadget-serial new file mode 100644 index 0000000..10f8114 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-serial @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/gser.name +Date: Apr 2013 +KenelVersion: 3.10 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with gser function's instance "name". + diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt new file mode 100644 index 0000000..8ec2a67 --- /dev/null +++ b/Documentation/usb/gadget_configfs.txt @@ -0,0 +1,384 @@ + + + + + Linux USB gadget configured through configfs + + + 25th April 2013 + + + + +Overview +======== + +A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can +be connected to a USB Host to extend it with additional functions like a serial +port or a mass storage capability. + +A gadget is seen by its host as a set of configurations, each of which contains +a number of interfaces which, from the gadget's perspective, are known as +functions, each function representing e.g. a serial connection or a SCSI disk. + +Linux provides a number of functions for gadgets to use. + +Creating a gadget means deciding what configurations there will be +and which functions each configuration will provide. + +Configfs (please see Documentation/filesystems/configfs/*) lends itslef nicely +for the purpose of telling the kernel about the above mentioned decision. +This document is about how to do it. + +It also describes how configfs integration into gadget is designed. + + + + +Requirements +============ + +In order for this to work configfs must be available, so CONFIGFS_FS must be +'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. + + + + +Usage +===== + +(The original post describing the first function +made available through configfs can be seen here: +http://www.spinics.net/lists/linux-usb/msg76388.html) + +$ modprobe libcomposite +$ mount none $CONFIGFS_HOME -t configfs + +where CONFIGFS_HOME is the mount point for configfs + +1. Creating the gadgets +----------------------- + +For each gadget to be created its corresponding directory must be created: + +$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + +e.g.: + +$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + +... +... +... + +$ cd $CONFIGFS_HOME/usb_gadget/g1 + +Each gadget needs to have its vendor id <VID> and product id <PID> specified: + +$ echo <VID> > idVendor +$ echo <PID> > idProduct + +A gadget also needs its serial number, manufacturer and product strings. +In order to have a place to store them, a strings subdirectory must be created +for each language, e.g.: + +$ mkdir strings/0x409 + +Then the strings can be specified: + +$ echo <serial number> > strings/0x409/serialnumber +$ echo <manufacturer> > strings/0x409/manufacturer +$ echo <product> > strings/0x409/product + +2. Creating the configurations +------------------------------ + +Each gadget will consist of a number of configurations, their corresponding +directories must be created: + +$ mkdir configs/<name>.<number> + +where <name> can be any string which is legal in a filesystem and the +<numebr> is the configuration's number, e.g.: + +$ mkdir configs/c.1 + +... +... +... + +Each configuration also needs its strings, so a subdirectory must be created +for each language, e.g.: + +$ mkdir configs/c.1/strings/0x409 + +Then the configuration string can be specified: + +$ echo <configuration> > configs/c.1/strings/0x409/configuration + +Some attributes can also be set for a configuration, e.g.: + +$ echo 120 > configs/c.1/MaxPower + +3. Creating the functions +------------------------- + +The gadget will provide some functions, for each function its corresponding +directory must be created: + +$ mkdir functions/<name>.<instance name> + +where <name> corresponds to one of allowed function names and instance name +is an arbitrary string allowed in a filesystem, e.g.: + +$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + +... +... +... + +Each function provides its specific set of attributes, with either read-only +or read-write access. Where applicable they need to be written to as +appropriate. +Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. + +4. Associating the functions with their configurations +------------------------------------------------------ + +At this moment a number of gadgets is created, each of which has a number of +configurations specified and a number of functions available. What remains +is specifying which function is available in which configuration (the same +function can be used in multiple configurations). This is achieved with +creating symbolic links: + +$ ln -s functions/<name>.<instance name> configs/<name>.<number> + +e.g.: + +$ ln -s functions/ncm.usb0 configs/c.1 + +... +... +... + +5. Enabling the gadget +---------------------- + +All the above steps serve the purpose of composing the gadget of +configurations and functions. + +An example directory structure might look like this: + +. +./strings +./strings/0x409 +./strings/0x409/serialnumber +./strings/0x409/product +./strings/0x409/manufacturer +./configs +./configs/c.1 +./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 +./configs/c.1/strings +./configs/c.1/strings/0x409 +./configs/c.1/strings/0x409/configuration +./configs/c.1/bmAttributes +./configs/c.1/MaxPower +./functions +./functions/ncm.usb0 +./functions/ncm.usb0/ifname +./functions/ncm.usb0/qmult +./functions/ncm.usb0/host_addr +./functions/ncm.usb0/dev_addr +./UDC +./bcdUSB +./bcdDevice +./idProduct +./idVendor +./bMaxPacketSize0 +./bDeviceProtocol +./bDeviceSubClass +./bDeviceClass + + +Such a gadget must be finally enabled so that the USB host can enumerate it. +In order to enable the gadget it must be bound to a UDC (USB Device Controller). + +$ echo <udc name> > UDC + +where <udc name> is one of those found in /sys/class/udc/* +e.g.: + +$ echo s3c-hsotg > UDC + + +6. Disabling the gadget +----------------------- + +$ echo "" > UDC + +7. Cleaning up +-------------- + +Remove functions from configurations: + +$ rm configs/<config name>.<number>/<function> + +where <config name>.<number> specify the configuration and <function> is +a symlink to a function being removed from the configuration, e.g.: + +$ rm configfs/c.1/ncm.usb0 + +... +... +... + +Remove strings directories in configurations + +$ rmdir configs/<config name>.<number>/strings/<lang> + +e.g.: + +$ rmdir configs/c.1/strings/0x409 + +... +... +... + +and remove the configurations + +$ rmdir configs/<config name>.<number> + +e.g.: + +rmdir configs/c.1 + +... +... +... + +Remove functions (function modules are not unloaded, though) + +$ rmdir functions/<name>.<instance name> + +e.g.: + +$ rmdir functions/ncm.usb0 + +... +... +... + +Remove strings directories in the gadget + +$ rmdir strings/<lang> + +e.g.: + +$ rmdir strings/0x409 + +and finally remove the gadget: + +$ cd .. +$ rmdir <gadget name> + +e.g.: + +$ rmdir g1 + + + + +Implementation design +===================== + +Below the idea of how configfs works is presented. +In configfs there are items and groups, both represented as directories. +The difference between an item and a group is that a group can contain +other groups. In the picture below only an item is shown. +Both items and groups can have attributes, which are represented as files. +The user can create and remove directories, but cannot remove files, +which can be read-only or read-write, depending on what they represent. + +The filesystem part of configfs operates on config_items/groups and +configfs_attributes which are generic and of the same type for all +configured elements. However, they are embedded in usage-specific +larger structures. In the picture below there is a "cs" which contains +a config_item and an "sa" which contains a configfs_attribute. + +The filesystem view would be like this: + +./ +./cs (directory) + | + +--sa (file) + | + . + . + . + +Whenever a user reads/writes the "sa" file, a function is called +which accepts a struct config_item and a struct configfs_attribute. +In the said function the "cs" and "sa" are retrieved using the well +known container_of technique and an appropriate sa's function (show or +store) is called and passed the "cs" and a character buffer. The "show" +is for displaying the file's contents (copy data from the cs to the +buffer), while the "store" is for modifying the file's contents (copy data +from the buffer to the cs), but it is up to the implementer of the +two functions to decide what they actually do. + +typedef struct configured_structure cs; +typedef struc specific_attribute sa; + + sa + +----------------------------------+ + cs | (*show)(cs *, buffer); | ++-----------------+ | (*store)(cs *, buffer, length); | +| | | | +| +-------------+ | | +------------------+ | +| | struct |-|----|------>|struct | | +| | config_item | | | |configfs_attribute| | +| +-------------+ | | +------------------+ | +| | +----------------------------------+ +| data to be set | . +| | . ++-----------------+ . + +The file names are decided by the config item/group designer, while +the directories in general can be named at will. A group can have +a number of its default sub-groups created automatically. + +For more information on configfs please see +Documentation/filesystems/configfs/*. + +The concepts described above translate to USB gadgets like this: + +1. A gadget has its config group, which has some attributes (idVendor, +idProduct etc) and default sub-groups (configs, functions, strings). +Writing to the attributes causes the information to be stored in +appropriate locations. In the configs, functions and strings sub-groups +a user can create their sub-groups to represent configurations, functions, +and groups of strings in a given language. + +2. The user creates configurations and functions, in the configurations +creates symbolic links to functions. This information is used when the +gadget's UDC attribute is written to, which means binding the gadget +to the UDC. The code in drivers/usb/gadget/configfs.c iterates over +all configurations, and in each configuration it iterates over all +functions and binds them. This way the whole gadget is bound. + +3. The file drivers/usb/gadget/configfs.c contains code for + + - gadget's config_group + - gadget's default groups (configs, functions, strings) + - associating functions with configurations (symlinks) + +4. Each USB function naturally has its own view of what it wants +configured, so config_groups for particular functions are defined +in the functions implementation files drivers/usb/gadget/f_*.c. + +5. Funciton's code is written in such a way that it uses + +usb_get_function_instance(), which, in turn, calls request_module. +So, provided that modprobe works, modules for particular functions +are loaded automatically. Please note that the converse is not true: +after a gadget is disabled and torn down, the modules remain loaded. diff --git a/drivers/usb/gadget/Kconfig b/drivers/usb/gadget/Kconfig index 17aa4ad..fa29a78 100644 --- a/drivers/usb/gadget/Kconfig +++ b/drivers/usb/gadget/Kconfig @@ -596,6 +596,71 @@ choice # this first set of drivers all depend on bulk-capable hardware. +config USB_CONFIGFS + tristate "USB functions configurable through configfs" + select USB_LIBCOMPOSITE + help + A Linux USB "gadget" can be set up through configfs. + If this is the case, the USB functions (which from the host's + perspective are seen as interfaces) and configurations are + specified simply by creating appropriate directories in configfs. + Associating functions with configurations is done by creating + appropriate symbolic links. + For more information see Documentation/usb/gadget-configfs.txt. + +config USB_CONFIGFS_SERIAL + boolean "Generic serial bulk in/out" + depends on USB_CONFIGFS + depends on TTY + select USB_U_SERIAL + select USB_F_SERIAL + help + The function talks to the Linux-USB generic serial driver. + +config USB_CONFIGFS_ACM + boolean "Abstract Control Model (CDC ACM)" + depends on USB_CONFIGFS + depends on TTY + select USB_U_SERIAL + select USB_F_ACM + help + ACM serial link. This function can be used to interoperate with + MS-Windows hosts or with the Linux-USB "cdc-acm" driver. + +config USB_CONFIGFS_OBEX + boolean "Object Exchange Model (CDC OBEX)" + depends on USB_CONFIGFS + depends on TTY + select USB_U_SERIAL + select USB_F_OBEX + help + You will need a user space OBEX server talking to /dev/ttyGS*, + since the kernel itself doesn't implement the OBEX protocol. + +config USB_CONFIGFS_NCM + boolean "Network Control Model (CDC NCM)" + depends on USB_CONFIGFS + depends on NET + select USB_U_ETHER + select USB_F_NCM + help + NCM is an advanced protocol for Ethernet encapsulation, allows + grouping of several ethernet frames into one USB transfer and + different alignment possibilities. + +config USB_CONFIGFS_ECM + boolean "Ethernet Control Model (CDC ECM)" + depends on USB_CONFIGFS + depends on NET + select USB_U_ETHER + select USB_F_ECM + help + The "Communication Device Class" (CDC) Ethernet Control Model. + That protocol is often avoided with pure Ethernet adapters, in + favor of simpler vendor-specific hardware, but is widely + supported by firmware for smart network devices. + + config USB_ZERO tristate "Gadget Zero (DEVELOPMENT)" select USB_LIBCOMPOSITE -- 1.7.0.4 -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
