Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
1 2 3 4 5 Linux USB gadget configured through configfs 6 7 8 25th April 2013 9 10 11 12 13 Overview 14 ======== 15 16 A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can 17 be connected to a USB Host to extend it with additional functions like a serial 18 port or a mass storage capability. 19 20 A gadget is seen by its host as a set of configurations, each of which contains 21 a number of interfaces which, from the gadget's perspective, are known as 22 functions, each function representing e.g. a serial connection or a SCSI disk. 23 24 Linux provides a number of functions for gadgets to use. 25 26 Creating a gadget means deciding what configurations there will be 27 and which functions each configuration will provide. 28 29 Configfs (please see Documentation/filesystems/configfs/*) lends itself nicely 30 for the purpose of telling the kernel about the above mentioned decision. 31 This document is about how to do it. 32 33 It also describes how configfs integration into gadget is designed. 34 35 36 37 38 Requirements 39 ============ 40 41 In order for this to work configfs must be available, so CONFIGFS_FS must be 42 'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. 43 44 45 46 47 Usage 48 ===== 49 50 (The original post describing the first function 51 made available through configfs can be seen here: 52 http://www.spinics.net/lists/linux-usb/msg76388.html) 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 2. Creating the configurations 94 ------------------------------ 95 96 Each gadget will consist of a number of configurations, their corresponding 97 directories must be created: 98 99 $ mkdir configs/<name>.<number> 100 101 where <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 110 Each configuration also needs its strings, so a subdirectory must be created 111 for each language, e.g.: 112 113 $ mkdir configs/c.1/strings/0x409 114 115 Then the configuration string can be specified: 116 117 $ echo <configuration> > configs/c.1/strings/0x409/configuration 118 119 Some attributes can also be set for a configuration, e.g.: 120 121 $ echo 120 > configs/c.1/MaxPower 122 123 3. Creating the functions 124 ------------------------- 125 126 The gadget will provide some functions, for each function its corresponding 127 directory must be created: 128 129 $ mkdir functions/<name>.<instance name> 130 131 where <name> corresponds to one of allowed function names and instance name 132 is 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 140 Each function provides its specific set of attributes, with either read-only 141 or read-write access. Where applicable they need to be written to as 142 appropriate. 143 Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. 144 145 4. Associating the functions with their configurations 146 ------------------------------------------------------ 147 148 At this moment a number of gadgets is created, each of which has a number of 149 configurations specified and a number of functions available. What remains 150 is specifying which function is available in which configuration (the same 151 function can be used in multiple configurations). This is achieved with 152 creating symbolic links: 153 154 $ ln -s functions/<name>.<instance name> configs/<name>.<number> 155 156 e.g.: 157 158 $ ln -s functions/ncm.usb0 configs/c.1 159 160 ... 161 ... 162 ... 163 164 5. Enabling the gadget 165 ---------------------- 166 167 All the above steps serve the purpose of composing the gadget of 168 configurations and functions. 169 170 An 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 203 Such a gadget must be finally enabled so that the USB host can enumerate it. 204 In order to enable the gadget it must be bound to a UDC (USB Device Controller). 205 206 $ echo <udc name> > UDC 207 208 where <udc name> is one of those found in /sys/class/udc/* 209 e.g.: 210 211 $ echo s3c-hsotg > UDC 212 213 214 6. Disabling the gadget 215 ----------------------- 216 217 $ echo "" > UDC 218 219 7. Cleaning up 220 -------------- 221 222 Remove functions from configurations: 223 224 $ rm configs/<config name>.<number>/<function> 225 226 where <config name>.<number> specify the configuration and <function> is 227 a symlink to a function being removed from the configuration, e.g.: 228 229 $ rm configfs/c.1/ncm.usb0 230 231 ... 232 ... 233 ... 234 235 Remove strings directories in configurations 236 237 $ rmdir configs/<config name>.<number>/strings/<lang> 238 239 e.g.: 240 241 $ rmdir configs/c.1/strings/0x409 242 243 ... 244 ... 245 ... 246 247 and remove the configurations 248 249 $ rmdir configs/<config name>.<number> 250 251 e.g.: 252 253 rmdir configs/c.1 254 255 ... 256 ... 257 ... 258 259 Remove functions (function modules are not unloaded, though) 260 261 $ rmdir functions/<name>.<instance name> 262 263 e.g.: 264 265 $ rmdir functions/ncm.usb0 266 267 ... 268 ... 269 ... 270 271 Remove strings directories in the gadget 272 273 $ rmdir strings/<lang> 274 275 e.g.: 276 277 $ rmdir strings/0x409 278 279 and finally remove the gadget: 280 281 $ cd .. 282 $ rmdir <gadget name> 283 284 e.g.: 285 286 $ rmdir g1 287 288 289 290 291 Implementation design 292 ===================== 293 294 Below the idea of how configfs works is presented. 295 In configfs there are items and groups, both represented as directories. 296 The difference between an item and a group is that a group can contain 297 other groups. In the picture below only an item is shown. 298 Both items and groups can have attributes, which are represented as files. 299 The user can create and remove directories, but cannot remove files, 300 which can be read-only or read-write, depending on what they represent. 301 302 The filesystem part of configfs operates on config_items/groups and 303 configfs_attributes which are generic and of the same type for all 304 configured elements. However, they are embedded in usage-specific 305 larger structures. In the picture below there is a "cs" which contains 306 a config_item and an "sa" which contains a configfs_attribute. 307 308 The filesystem view would be like this: 309 310 ./ 311 ./cs (directory) 312 | 313 +--sa (file) 314 | 315 . 316 . 317 . 318 319 Whenever a user reads/writes the "sa" file, a function is called 320 which accepts a struct config_item and a struct configfs_attribute. 321 In the said function the "cs" and "sa" are retrieved using the well 322 known container_of technique and an appropriate sa's function (show or 323 store) is called and passed the "cs" and a character buffer. The "show" 324 is for displaying the file's contents (copy data from the cs to the 325 buffer), while the "store" is for modifying the file's contents (copy data 326 from the buffer to the cs), but it is up to the implementer of the 327 two functions to decide what they actually do. 328 329 typedef struct configured_structure cs; 330 typedef struct specific_attribute sa; 331 332 sa 333 +----------------------------------+ 334 cs | (*show)(cs *, buffer); | 335 +-----------------+ | (*store)(cs *, buffer, length); | 336 | | | | 337 | +-------------+ | | +------------------+ | 338 | | struct |-|----|------>|struct | | 339 | | config_item | | | |configfs_attribute| | 340 | +-------------+ | | +------------------+ | 341 | | +----------------------------------+ 342 | data to be set | . 343 | | . 344 +-----------------+ . 345 346 The file names are decided by the config item/group designer, while 347 the directories in general can be named at will. A group can have 348 a number of its default sub-groups created automatically. 349 350 For more information on configfs please see 351 Documentation/filesystems/configfs/*. 352 353 The concepts described above translate to USB gadgets like this: 354 355 1. A gadget has its config group, which has some attributes (idVendor, 356 idProduct etc) and default sub-groups (configs, functions, strings). 357 Writing to the attributes causes the information to be stored in 358 appropriate locations. In the configs, functions and strings sub-groups 359 a user can create their sub-groups to represent configurations, functions, 360 and groups of strings in a given language. 361 362 2. The user creates configurations and functions, in the configurations 363 creates symbolic links to functions. This information is used when the 364 gadget's UDC attribute is written to, which means binding the gadget 365 to the UDC. The code in drivers/usb/gadget/configfs.c iterates over 366 all configurations, and in each configuration it iterates over all 367 functions and binds them. This way the whole gadget is bound. 368 369 3. The file drivers/usb/gadget/configfs.c contains code for 370 371 - gadget's config_group 372 - gadget's default groups (configs, functions, strings) 373 - associating functions with configurations (symlinks) 374 375 4. Each USB function naturally has its own view of what it wants 376 configured, so config_groups for particular functions are defined 377 in the functions implementation files drivers/usb/gadget/f_*.c. 378 379 5. Function's code is written in such a way that it uses 380 381 usb_get_function_instance(), which, in turn, calls request_module. 382 So, provided that modprobe works, modules for particular functions 383 are loaded automatically. Please note that the converse is not true: 384 after a gadget is disabled and torn down, the modules remain loaded.