1============================================ 2Linux USB gadget configured through configfs 3============================================ 4 5 625th April 2013 7 8 9 10 11Overview 12======== 13 14A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can 15be connected to a USB Host to extend it with additional functions like a serial 16port or a mass storage capability. 17 18A gadget is seen by its host as a set of configurations, each of which contains 19a number of interfaces which, from the gadget's perspective, are known as 20functions, 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 be 25and which functions each configuration will provide. 26 27Configfs (please see `Documentation/filesystems/configfs/*`) lends itself nicely 28for 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 36Requirements 37============ 38 39In order for this to work configfs must be available, so CONFIGFS_FS must be 40'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. 41 42 43 44 45Usage 46===== 47 48(The original post describing the first function 49made available through configfs can be seen here: 50http://www.spinics.net/lists/linux-usb/msg76388.html) 51 52:: 53 54 $ modprobe libcomposite 55 $ mount none $CONFIGFS_HOME -t configfs 56 57where CONFIGFS_HOME is the mount point for configfs 58 591. Creating the gadgets 60----------------------- 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/g1 69 70 ... 71 ... 72 ... 73 74 $ cd $CONFIGFS_HOME/usb_gadget/g1 75 76Each gadget needs to have its vendor id <VID> and product id <PID> specified:: 77 78 $ echo <VID> > idVendor 79 $ echo <PID> > idProduct 80 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 created 83for each language, e.g.:: 84 85 $ mkdir strings/0x409 86 87Then the strings can be specified:: 88 89 $ echo <serial number> > strings/0x409/serialnumber 90 $ echo <manufacturer> > strings/0x409/manufacturer 91 $ echo <product> > strings/0x409/product 92 932. Creating the configurations 94------------------------------ 95 96Each gadget will consist of a number of configurations, their corresponding 97directories must be created: 98 99$ mkdir configs/<name>.<number> 100 101where <name> can be any string which is legal in a filesystem and the 102<number> is the configuration's number, e.g.:: 103 104 $ mkdir configs/c.1 105 106 ... 107 ... 108 ... 109 110Each configuration also needs its strings, so a subdirectory must be created 111for each language, e.g.:: 112 113 $ mkdir configs/c.1/strings/0x409 114 115Then the configuration string can be specified:: 116 117 $ echo <configuration> > configs/c.1/strings/0x409/configuration 118 119Some attributes can also be set for a configuration, e.g.:: 120 121 $ echo 120 > configs/c.1/MaxPower 122 1233. Creating the functions 124------------------------- 125 126The gadget will provide some functions, for each function its corresponding 127directory must be created:: 128 129 $ mkdir functions/<name>.<instance name> 130 131where <name> corresponds to one of allowed function names and instance name 132is an arbitrary string allowed in a filesystem, e.g.:: 133 134 $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() 135 136 ... 137 ... 138 ... 139 140Each function provides its specific set of attributes, with either read-only 141or read-write access. Where applicable they need to be written to as 142appropriate. 143Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. 144 1454. Associating the functions with their configurations 146------------------------------------------------------ 147 148At this moment a number of gadgets is created, each of which has a number of 149configurations specified and a number of functions available. What remains 150is specifying which function is available in which configuration (the same 151function can be used in multiple configurations). This is achieved with 152creating symbolic links:: 153 154 $ ln -s functions/<name>.<instance name> configs/<name>.<number> 155 156e.g.:: 157 158 $ ln -s functions/ncm.usb0 configs/c.1 159 160 ... 161 ... 162 ... 163 1645. Enabling the gadget 165---------------------- 166 167All the above steps serve the purpose of composing the gadget of 168configurations and functions. 169 170An example directory structure might look like this:: 171 172 . 173 ./strings 174 ./strings/0x409 175 ./strings/0x409/serialnumber 176 ./strings/0x409/product 177 ./strings/0x409/manufacturer 178 ./configs 179 ./configs/c.1 180 ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 181 ./configs/c.1/strings 182 ./configs/c.1/strings/0x409 183 ./configs/c.1/strings/0x409/configuration 184 ./configs/c.1/bmAttributes 185 ./configs/c.1/MaxPower 186 ./functions 187 ./functions/ncm.usb0 188 ./functions/ncm.usb0/ifname 189 ./functions/ncm.usb0/qmult 190 ./functions/ncm.usb0/host_addr 191 ./functions/ncm.usb0/dev_addr 192 ./UDC 193 ./bcdUSB 194 ./bcdDevice 195 ./idProduct 196 ./idVendor 197 ./bMaxPacketSize0 198 ./bDeviceProtocol 199 ./bDeviceSubClass 200 ./bDeviceClass 201 202 203Such a gadget must be finally enabled so that the USB host can enumerate it. 204 205In order to enable the gadget it must be bound to a UDC (USB Device 206Controller):: 207 208 $ echo <udc name> > UDC 209 210where <udc name> is one of those found in /sys/class/udc/* 211e.g.:: 212 213 $ echo s3c-hsotg > UDC 214 215 2166. Disabling the gadget 217----------------------- 218 219:: 220 221 $ echo "" > UDC 222 2237. Cleaning up 224-------------- 225 226Remove functions from configurations:: 227 228 $ rm configs/<config name>.<number>/<function> 229 230where <config name>.<number> specify the configuration and <function> is 231a symlink to a function being removed from the configuration, e.g.:: 232 233 $ rm configs/c.1/ncm.usb0 234 235 ... 236 ... 237 ... 238 239Remove strings directories in configurations: 240 241 $ rmdir configs/<config name>.<number>/strings/<lang> 242 243e.g.:: 244 245 $ rmdir configs/c.1/strings/0x409 246 247 ... 248 ... 249 ... 250 251and remove the configurations:: 252 253 $ rmdir configs/<config name>.<number> 254 255e.g.:: 256 257 rmdir configs/c.1 258 259 ... 260 ... 261 ... 262 263Remove functions (function modules are not unloaded, though): 264 265 $ rmdir functions/<name>.<instance name> 266 267e.g.:: 268 269 $ rmdir functions/ncm.usb0 270 271 ... 272 ... 273 ... 274 275Remove strings directories in the gadget:: 276 277 $ rmdir strings/<lang> 278 279e.g.:: 280 281 $ rmdir strings/0x409 282 283and finally remove the gadget:: 284 285 $ cd .. 286 $ rmdir <gadget name> 287 288e.g.:: 289 290 $ rmdir g1 291 292 293 294 295Implementation design 296===================== 297 298Below the idea of how configfs works is presented. 299In configfs there are items and groups, both represented as directories. 300The difference between an item and a group is that a group can contain 301other groups. In the picture below only an item is shown. 302Both items and groups can have attributes, which are represented as files. 303The user can create and remove directories, but cannot remove files, 304which can be read-only or read-write, depending on what they represent. 305 306The filesystem part of configfs operates on config_items/groups and 307configfs_attributes which are generic and of the same type for all 308configured elements. However, they are embedded in usage-specific 309larger structures. In the picture below there is a "cs" which contains 310a config_item and an "sa" which contains a configfs_attribute. 311 312The filesystem view would be like this:: 313 314 ./ 315 ./cs (directory) 316 | 317 +--sa (file) 318 | 319 . 320 . 321 . 322 323Whenever a user reads/writes the "sa" file, a function is called 324which accepts a struct config_item and a struct configfs_attribute. 325In the said function the "cs" and "sa" are retrieved using the well 326known container_of technique and an appropriate sa's function (show or 327store) is called and passed the "cs" and a character buffer. The "show" 328is for displaying the file's contents (copy data from the cs to the 329buffer), while the "store" is for modifying the file's contents (copy data 330from the buffer to the cs), but it is up to the implementer of the 331two functions to decide what they actually do. 332 333:: 334 335 typedef struct configured_structure cs; 336 typedef struct specific_attribute sa; 337 338 sa 339 +----------------------------------+ 340 cs | (*show)(cs *, buffer); | 341 +-----------------+ | (*store)(cs *, buffer, length); | 342 | | | | 343 | +-------------+ | | +------------------+ | 344 | | struct |-|----|------>|struct | | 345 | | config_item | | | |configfs_attribute| | 346 | +-------------+ | | +------------------+ | 347 | | +----------------------------------+ 348 | data to be set | . 349 | | . 350 +-----------------+ . 351 352The file names are decided by the config item/group designer, while 353the directories in general can be named at will. A group can have 354a number of its default sub-groups created automatically. 355 356For more information on configfs please see 357`Documentation/filesystems/configfs/*`. 358 359The concepts described above translate to USB gadgets like this: 360 3611. A gadget has its config group, which has some attributes (idVendor, 362idProduct etc) and default sub-groups (configs, functions, strings). 363Writing to the attributes causes the information to be stored in 364appropriate locations. In the configs, functions and strings sub-groups 365a user can create their sub-groups to represent configurations, functions, 366and groups of strings in a given language. 367 3682. The user creates configurations and functions, in the configurations 369creates symbolic links to functions. This information is used when the 370gadget's UDC attribute is written to, which means binding the gadget 371to the UDC. The code in drivers/usb/gadget/configfs.c iterates over 372all configurations, and in each configuration it iterates over all 373functions and binds them. This way the whole gadget is bound. 374 3753. The file drivers/usb/gadget/configfs.c contains code for 376 377 - gadget's config_group 378 - gadget's default groups (configs, functions, strings) 379 - associating functions with configurations (symlinks) 380 3814. Each USB function naturally has its own view of what it wants 382configured, so config_groups for particular functions are defined 383in the functions implementation files drivers/usb/gadget/f_*.c. 384 3855. Function's code is written in such a way that it uses 386 387usb_get_function_instance(), which, in turn, calls request_module. 388So, provided that modprobe works, modules for particular functions 389are loaded automatically. Please note that the converse is not true: 390after a gadget is disabled and torn down, the modules remain loaded. 391