diff options
Diffstat (limited to 'Documentation/usb/gadget_configfs.txt')
| -rw-r--r-- | Documentation/usb/gadget_configfs.txt | 306 |
1 files changed, 156 insertions, 150 deletions
diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt index b8cb38a98c19..54fb08baae22 100644 --- a/Documentation/usb/gadget_configfs.txt +++ b/Documentation/usb/gadget_configfs.txt @@ -1,11 +1,9 @@ +============================================ +Linux USB gadget configured through configfs +============================================ - - - Linux USB gadget configured through configfs - - - 25th April 2013 +25th April 2013 @@ -26,7 +24,7 @@ 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 itself nicely +Configfs (please see `Documentation/filesystems/configfs/*`) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it. @@ -51,44 +49,46 @@ Usage 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 +:: + + $ 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: +For each gadget to be created its corresponding directory must be created:: -$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> -e.g.: +e.g.:: -$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + $ mkdir $CONFIGFS_HOME/usb_gadget/g1 -... -... -... + ... + ... + ... -$ cd $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: +Each gadget needs to have its vendor id <VID> and product id <PID> specified:: -$ echo <VID> > idVendor -$ echo <PID> > idProduct + $ 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.: +for each language, e.g.:: -$ mkdir strings/0x409 + $ mkdir strings/0x409 -Then the strings can be specified: +Then the strings can be specified:: -$ echo <serial number> > strings/0x409/serialnumber -$ echo <manufacturer> > strings/0x409/manufacturer -$ echo <product> > strings/0x409/product + $ echo <serial number> > strings/0x409/serialnumber + $ echo <manufacturer> > strings/0x409/manufacturer + $ echo <product> > strings/0x409/product 2. Creating the configurations ------------------------------ @@ -99,43 +99,43 @@ directories must be created: $ mkdir configs/<name>.<number> where <name> can be any string which is legal in a filesystem and the -<number> is the configuration's number, e.g.: +<number> is the configuration's number, e.g.:: -$ mkdir configs/c.1 + $ mkdir configs/c.1 -... -... -... + ... + ... + ... Each configuration also needs its strings, so a subdirectory must be created -for each language, e.g.: +for each language, e.g.:: -$ mkdir configs/c.1/strings/0x409 + $ mkdir configs/c.1/strings/0x409 -Then the configuration string can be specified: +Then the configuration string can be specified:: -$ echo <configuration> > configs/c.1/strings/0x409/configuration + $ echo <configuration> > configs/c.1/strings/0x409/configuration -Some attributes can also be set for a configuration, e.g.: +Some attributes can also be set for a configuration, e.g.:: -$ echo 120 > configs/c.1/MaxPower + $ 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: +directory must be created:: -$ mkdir functions/<name>.<instance name> + $ 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.: +is an arbitrary string allowed in a filesystem, e.g.:: -$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + $ 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 @@ -149,17 +149,17 @@ 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: +creating symbolic links:: -$ ln -s functions/<name>.<instance name> configs/<name>.<number> + $ ln -s functions/<name>.<instance name> configs/<name>.<number> -e.g.: +e.g.:: -$ ln -s functions/ncm.usb0 configs/c.1 + $ ln -s functions/ncm.usb0 configs/c.1 -... -... -... + ... + ... + ... 5. Enabling the gadget ---------------------- @@ -167,123 +167,127 @@ $ ln -s functions/ncm.usb0 configs/c.1 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 +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 +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.: +e.g.:: -$ echo s3c-hsotg > UDC + $ echo s3c-hsotg > UDC 6. Disabling the gadget ----------------------- -$ echo "" > UDC +:: + + $ echo "" > UDC 7. Cleaning up -------------- -Remove functions from configurations: +Remove functions from configurations:: -$ rm configs/<config name>.<number>/<function> + $ 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.: +a symlink to a function being removed from the configuration, e.g.:: -$ rm configs/c.1/ncm.usb0 + $ rm configs/c.1/ncm.usb0 -... -... -... + ... + ... + ... -Remove strings directories in configurations +Remove strings directories in configurations: -$ rmdir configs/<config name>.<number>/strings/<lang> + $ rmdir configs/<config name>.<number>/strings/<lang> -e.g.: +e.g.:: -$ rmdir configs/c.1/strings/0x409 + $ rmdir configs/c.1/strings/0x409 -... -... -... + ... + ... + ... -and remove the configurations +and remove the configurations:: -$ rmdir configs/<config name>.<number> + $ rmdir configs/<config name>.<number> -e.g.: +e.g.:: -rmdir configs/c.1 + rmdir configs/c.1 -... -... -... + ... + ... + ... -Remove functions (function modules are not unloaded, though) +Remove functions (function modules are not unloaded, though): -$ rmdir functions/<name>.<instance name> + $ rmdir functions/<name>.<instance name> -e.g.: +e.g.:: -$ rmdir functions/ncm.usb0 + $ rmdir functions/ncm.usb0 -... -... -... + ... + ... + ... -Remove strings directories in the gadget +Remove strings directories in the gadget:: -$ rmdir strings/<lang> + $ rmdir strings/<lang> -e.g.: +e.g.:: -$ rmdir strings/0x409 + $ rmdir strings/0x409 -and finally remove the gadget: +and finally remove the gadget:: -$ cd .. -$ rmdir <gadget name> + $ cd .. + $ rmdir <gadget name> -e.g.: +e.g.:: -$ rmdir g1 + $ rmdir g1 @@ -305,16 +309,16 @@ 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: +The filesystem view would be like this:: -./ -./cs (directory) - | - +--sa (file) - | - . - . - . + ./ + ./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. @@ -326,29 +330,31 @@ 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 struct specific_attribute sa; - - sa - +----------------------------------+ - cs | (*show)(cs *, buffer); | -+-----------------+ | (*store)(cs *, buffer, length); | -| | | | -| +-------------+ | | +------------------+ | -| | struct |-|----|------>|struct | | -| | config_item | | | |configfs_attribute| | -| +-------------+ | | +------------------+ | -| | +----------------------------------+ -| data to be set | . -| | . -+-----------------+ . +:: + + typedef struct configured_structure cs; + typedef struct 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/*. +`Documentation/filesystems/configfs/*`. The concepts described above translate to USB gadgets like this: |