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