linux/Documentation/usb/gadget_configfs.txt
<<
>>
Prefs
   1
   2
   3
   4
   5                Linux USB gadget configured through configfs
   6
   7
   8                             25th April 2013
   9
  10
  11
  12
  13Overview
  14========
  15
  16A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can
  17be connected to a USB Host to extend it with additional functions like a serial
  18port or a mass storage capability.
  19
  20A gadget is seen by its host as a set of configurations, each of which contains
  21a number of interfaces which, from the gadget's perspective, are known as
  22functions, each function representing e.g. a serial connection or a SCSI disk.
  23
  24Linux provides a number of functions for gadgets to use.
  25
  26Creating a gadget means deciding what configurations there will be
  27and which functions each configuration will provide.
  28
  29Configfs (please see Documentation/filesystems/configfs/*) lends itslef nicely
  30for the purpose of telling the kernel about the above mentioned decision.
  31This document is about how to do it.
  32
  33It also describes how configfs integration into gadget is designed.
  34
  35
  36
  37
  38Requirements
  39============
  40
  41In 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
  47Usage
  48=====
  49
  50(The original post describing the first function
  51made available through configfs can be seen here:
  52http://www.spinics.net/lists/linux-usb/msg76388.html)
  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<numebr> 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.
 204In order to enable the gadget it must be bound to a UDC (USB Device Controller).
 205
 206$ echo <udc name> > UDC
 207
 208where <udc name> is one of those found in /sys/class/udc/*
 209e.g.:
 210
 211$ echo s3c-hsotg > UDC
 212
 213
 2146. Disabling the gadget
 215-----------------------
 216
 217$ echo "" > UDC
 218
 2197. Cleaning up
 220--------------
 221
 222Remove functions from configurations:
 223
 224$ rm configs/<config name>.<number>/<function>
 225
 226where <config name>.<number> specify the configuration and <function> is
 227a symlink to a function being removed from the configuration, e.g.:
 228
 229$ rm configfs/c.1/ncm.usb0
 230
 231...
 232...
 233...
 234
 235Remove strings directories in configurations
 236
 237$ rmdir configs/<config name>.<number>/strings/<lang>
 238
 239e.g.:
 240
 241$ rmdir configs/c.1/strings/0x409
 242
 243...
 244...
 245...
 246
 247and remove the configurations
 248
 249$ rmdir configs/<config name>.<number>
 250
 251e.g.:
 252
 253rmdir configs/c.1
 254
 255...
 256...
 257...
 258
 259Remove functions (function modules are not unloaded, though)
 260
 261$ rmdir functions/<name>.<instance name>
 262
 263e.g.:
 264
 265$ rmdir functions/ncm.usb0
 266
 267...
 268...
 269...
 270
 271Remove strings directories in the gadget
 272
 273$ rmdir strings/<lang>
 274
 275e.g.:
 276
 277$ rmdir strings/0x409
 278
 279and finally remove the gadget:
 280
 281$ cd ..
 282$ rmdir <gadget name>
 283
 284e.g.:
 285
 286$ rmdir g1
 287
 288
 289
 290
 291Implementation design
 292=====================
 293
 294Below the idea of how configfs works is presented.
 295In configfs there are items and groups, both represented as directories.
 296The difference between an item and a group is that a group can contain
 297other groups. In the picture below only an item is shown.
 298Both items and groups can have attributes, which are represented as files.
 299The user can create and remove directories, but cannot remove files,
 300which can be read-only or read-write, depending on what they represent.
 301
 302The filesystem part of configfs operates on config_items/groups and
 303configfs_attributes which are generic and of the same type for all
 304configured elements. However, they are embedded in usage-specific
 305larger structures. In the picture below there is a "cs" which contains
 306a config_item and an "sa" which contains a configfs_attribute.
 307
 308The filesystem view would be like this:
 309
 310./
 311./cs        (directory)
 312   |
 313   +--sa    (file)
 314   |
 315   .
 316   .
 317   .
 318
 319Whenever a user reads/writes the "sa" file, a function is called
 320which accepts a struct config_item and a struct configfs_attribute.
 321In the said function the "cs" and "sa" are retrieved using the well
 322known container_of technique and an appropriate sa's function (show or
 323store) is called and passed the "cs" and a character buffer. The "show"
 324is for displaying the file's contents (copy data from the cs to the
 325buffer), while the "store" is for modifying the file's contents (copy data
 326from the buffer to the cs), but it is up to the implementer of the
 327two functions to decide what they actually do.
 328
 329typedef struct configured_structure cs;
 330typedef struc 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
 346The file names are decided by the config item/group designer, while
 347the directories in general can be named at will. A group can have
 348a number of its default sub-groups created automatically.
 349
 350For more information on configfs please see
 351Documentation/filesystems/configfs/*.
 352
 353The concepts described above translate to USB gadgets like this:
 354
 3551. A gadget has its config group, which has some attributes (idVendor,
 356idProduct etc) and default sub-groups (configs, functions, strings).
 357Writing to the attributes causes the information to be stored in
 358appropriate locations. In the configs, functions and strings sub-groups
 359a user can create their sub-groups to represent configurations, functions,
 360and groups of strings in a given language.
 361
 3622. The user creates configurations and functions, in the configurations
 363creates symbolic links to functions. This information is used when the
 364gadget's UDC attribute is written to, which means binding the gadget
 365to the UDC. The code in drivers/usb/gadget/configfs.c iterates over
 366all configurations, and in each configuration it iterates over all
 367functions and binds them. This way the whole gadget is bound.
 368
 3693. 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
 3754. Each USB function naturally has its own view of what it wants
 376configured, so config_groups for particular functions are defined
 377in the functions implementation files drivers/usb/gadget/f_*.c.
 378
 3795. Funciton's code is written in such a way that it uses
 380
 381usb_get_function_instance(), which, in turn, calls request_module.
 382So, provided that modprobe works, modules for particular functions
 383are loaded automatically. Please note that the converse is not true:
 384after a gadget is disabled and torn down, the modules remain loaded.
 385
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.