401 lines · plain
1============================================2Linux USB gadget configured through configfs3============================================4 5 625th April 20137 8 9 10 11Overview12========13 14A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can15be connected to a USB Host to extend it with additional functions like a serial16port or a mass storage capability.17 18A gadget is seen by its host as a set of configurations, each of which contains19a number of interfaces which, from the gadget's perspective, are known as20functions, each function representing e.g. a serial connection or a SCSI disk.21 22Linux provides a number of functions for gadgets to use.23 24Creating a gadget means deciding what configurations there will be25and which functions each configuration will provide.26 27Configfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely28for the purpose of telling the kernel about the above mentioned decision.29This document is about how to do it.30 31It also describes how configfs integration into gadget is designed.32 33 34 35 36Requirements37============38 39In order for this to work configfs must be available, so CONFIGFS_FS must be40'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.41 42 43 44 45Usage46=====47 48(The original post describing the first function49made available through configfs can be seen here:50http://www.spinics.net/lists/linux-usb/msg76388.html)51 52::53 54 $ modprobe libcomposite55 $ mount none $CONFIGFS_HOME -t configfs56 57where CONFIGFS_HOME is the mount point for configfs58 591. Creating the gadgets60-----------------------61 62For each gadget to be created its corresponding directory must be created::63 64 $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>65 66e.g.::67 68 $ mkdir $CONFIGFS_HOME/usb_gadget/g169 70 ...71 ...72 ...73 74 $ cd $CONFIGFS_HOME/usb_gadget/g175 76Each gadget needs to have its vendor id <VID> and product id <PID> specified::77 78 $ echo <VID> > idVendor79 $ echo <PID> > idProduct80 81A gadget also needs its serial number, manufacturer and product strings.82In order to have a place to store them, a strings subdirectory must be created83for each language, e.g.::84 85 $ mkdir strings/0x40986 87Then the strings can be specified::88 89 $ echo <serial number> > strings/0x409/serialnumber90 $ echo <manufacturer> > strings/0x409/manufacturer91 $ echo <product> > strings/0x409/product92 93Further custom string descriptors can be created as directories within the94language's directory, with the string text being written to the "s" attribute95within the string's directory:96 97 $ mkdir strings/0x409/xu.098 $ echo <string text> > strings/0x409/xu.0/s99 100Where function drivers support it, functions may allow symlinks to these custom101string descriptors to associate those strings with class descriptors.102 1032. Creating the configurations104------------------------------105 106Each gadget will consist of a number of configurations, their corresponding107directories must be created:108 109$ mkdir configs/<name>.<number>110 111where <name> can be any string which is legal in a filesystem and the112<number> is the configuration's number, e.g.::113 114 $ mkdir configs/c.1115 116 ...117 ...118 ...119 120Each configuration also needs its strings, so a subdirectory must be created121for each language, e.g.::122 123 $ mkdir configs/c.1/strings/0x409124 125Then the configuration string can be specified::126 127 $ echo <configuration> > configs/c.1/strings/0x409/configuration128 129Some attributes can also be set for a configuration, e.g.::130 131 $ echo 120 > configs/c.1/MaxPower132 1333. Creating the functions134-------------------------135 136The gadget will provide some functions, for each function its corresponding137directory must be created::138 139 $ mkdir functions/<name>.<instance name>140 141where <name> corresponds to one of allowed function names and instance name142is an arbitrary string allowed in a filesystem, e.g.::143 144 $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module()145 146 ...147 ...148 ...149 150Each function provides its specific set of attributes, with either read-only151or read-write access. Where applicable they need to be written to as152appropriate.153Please refer to Documentation/ABI/testing/configfs-usb-gadget for more information.154 1554. Associating the functions with their configurations156------------------------------------------------------157 158At this moment a number of gadgets is created, each of which has a number of159configurations specified and a number of functions available. What remains160is specifying which function is available in which configuration (the same161function can be used in multiple configurations). This is achieved with162creating symbolic links::163 164 $ ln -s functions/<name>.<instance name> configs/<name>.<number>165 166e.g.::167 168 $ ln -s functions/ncm.usb0 configs/c.1169 170 ...171 ...172 ...173 1745. Enabling the gadget175----------------------176 177All the above steps serve the purpose of composing the gadget of178configurations and functions.179 180An example directory structure might look like this::181 182 .183 ./strings184 ./strings/0x409185 ./strings/0x409/serialnumber186 ./strings/0x409/product187 ./strings/0x409/manufacturer188 ./configs189 ./configs/c.1190 ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0191 ./configs/c.1/strings192 ./configs/c.1/strings/0x409193 ./configs/c.1/strings/0x409/configuration194 ./configs/c.1/bmAttributes195 ./configs/c.1/MaxPower196 ./functions197 ./functions/ncm.usb0198 ./functions/ncm.usb0/ifname199 ./functions/ncm.usb0/qmult200 ./functions/ncm.usb0/host_addr201 ./functions/ncm.usb0/dev_addr202 ./UDC203 ./bcdUSB204 ./bcdDevice205 ./idProduct206 ./idVendor207 ./bMaxPacketSize0208 ./bDeviceProtocol209 ./bDeviceSubClass210 ./bDeviceClass211 212 213Such a gadget must be finally enabled so that the USB host can enumerate it.214 215In order to enable the gadget it must be bound to a UDC (USB Device216Controller)::217 218 $ echo <udc name> > UDC219 220where <udc name> is one of those found in /sys/class/udc/*221e.g.::222 223 $ echo s3c-hsotg > UDC224 225 2266. Disabling the gadget227-----------------------228 229::230 231 $ echo "" > UDC232 2337. Cleaning up234--------------235 236Remove functions from configurations::237 238 $ rm configs/<config name>.<number>/<function>239 240where <config name>.<number> specify the configuration and <function> is241a symlink to a function being removed from the configuration, e.g.::242 243 $ rm configs/c.1/ncm.usb0244 245 ...246 ...247 ...248 249Remove strings directories in configurations:250 251 $ rmdir configs/<config name>.<number>/strings/<lang>252 253e.g.::254 255 $ rmdir configs/c.1/strings/0x409256 257 ...258 ...259 ...260 261and remove the configurations::262 263 $ rmdir configs/<config name>.<number>264 265e.g.::266 267 rmdir configs/c.1268 269 ...270 ...271 ...272 273Remove functions (function modules are not unloaded, though):274 275 $ rmdir functions/<name>.<instance name>276 277e.g.::278 279 $ rmdir functions/ncm.usb0280 281 ...282 ...283 ...284 285Remove strings directories in the gadget::286 287 $ rmdir strings/<lang>288 289e.g.::290 291 $ rmdir strings/0x409292 293and finally remove the gadget::294 295 $ cd ..296 $ rmdir <gadget name>297 298e.g.::299 300 $ rmdir g1301 302 303 304 305Implementation design306=====================307 308Below the idea of how configfs works is presented.309In configfs there are items and groups, both represented as directories.310The difference between an item and a group is that a group can contain311other groups. In the picture below only an item is shown.312Both items and groups can have attributes, which are represented as files.313The user can create and remove directories, but cannot remove files,314which can be read-only or read-write, depending on what they represent.315 316The filesystem part of configfs operates on config_items/groups and317configfs_attributes which are generic and of the same type for all318configured elements. However, they are embedded in usage-specific319larger structures. In the picture below there is a "cs" which contains320a config_item and an "sa" which contains a configfs_attribute.321 322The filesystem view would be like this::323 324 ./325 ./cs (directory)326 |327 +--sa (file)328 |329 .330 .331 .332 333Whenever a user reads/writes the "sa" file, a function is called334which accepts a struct config_item and a struct configfs_attribute.335In the said function the "cs" and "sa" are retrieved using the well336known container_of technique and an appropriate sa's function (show or337store) is called and passed the "cs" and a character buffer. The "show"338is for displaying the file's contents (copy data from the cs to the339buffer), while the "store" is for modifying the file's contents (copy data340from the buffer to the cs), but it is up to the implementer of the341two functions to decide what they actually do.342 343::344 345 typedef struct configured_structure cs;346 typedef struct specific_attribute sa;347 348 sa349 +----------------------------------+350 cs | (*show)(cs *, buffer); |351 +-----------------+ | (*store)(cs *, buffer, length); |352 | | | |353 | +-------------+ | | +------------------+ |354 | | struct |-|----|------>|struct | |355 | | config_item | | | |configfs_attribute| |356 | +-------------+ | | +------------------+ |357 | | +----------------------------------+358 | data to be set | .359 | | .360 +-----------------+ .361 362The file names are decided by the config item/group designer, while363the directories in general can be named at will. A group can have364a number of its default sub-groups created automatically.365 366For more information on configfs please see367`Documentation/filesystems/configfs.rst`.368 369The concepts described above translate to USB gadgets like this:370 3711. A gadget has its config group, which has some attributes (idVendor,372idProduct etc) and default sub-groups (configs, functions, strings).373Writing to the attributes causes the information to be stored in374appropriate locations. In the configs, functions and strings sub-groups375a user can create their sub-groups to represent configurations, functions,376and groups of strings in a given language.377 3782. The user creates configurations and functions, in the configurations379creates symbolic links to functions. This information is used when the380gadget's UDC attribute is written to, which means binding the gadget381to the UDC. The code in drivers/usb/gadget/configfs.c iterates over382all configurations, and in each configuration it iterates over all383functions and binds them. This way the whole gadget is bound.384 3853. The file drivers/usb/gadget/configfs.c contains code for386 387 - gadget's config_group388 - gadget's default groups (configs, functions, strings)389 - associating functions with configurations (symlinks)390 3914. Each USB function naturally has its own view of what it wants392configured, so config_groups for particular functions are defined393in the functions implementation files drivers/usb/gadget/f_*.c.394 3955. Function's code is written in such a way that it uses396 397usb_get_function_instance(), which, in turn, calls request_module.398So, provided that modprobe works, modules for particular functions399are loaded automatically. Please note that the converse is not true:400after a gadget is disabled and torn down, the modules remain loaded.401