gadget_configfs.rst 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390
  1. ============================================
  2. Linux USB gadget configured through configfs
  3. ============================================
  4. 25th April 2013
  5. Overview
  6. ========
  7. A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can
  8. be connected to a USB Host to extend it with additional functions like a serial
  9. port or a mass storage capability.
  10. A gadget is seen by its host as a set of configurations, each of which contains
  11. a number of interfaces which, from the gadget's perspective, are known as
  12. functions, each function representing e.g. a serial connection or a SCSI disk.
  13. Linux provides a number of functions for gadgets to use.
  14. Creating a gadget means deciding what configurations there will be
  15. and which functions each configuration will provide.
  16. Configfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely
  17. for the purpose of telling the kernel about the above mentioned decision.
  18. This document is about how to do it.
  19. It also describes how configfs integration into gadget is designed.
  20. Requirements
  21. ============
  22. In order for this to work configfs must be available, so CONFIGFS_FS must be
  23. 'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.
  24. Usage
  25. =====
  26. (The original post describing the first function
  27. made available through configfs can be seen here:
  28. http://www.spinics.net/lists/linux-usb/msg76388.html)
  29. ::
  30. $ modprobe libcomposite
  31. $ mount none $CONFIGFS_HOME -t configfs
  32. where CONFIGFS_HOME is the mount point for configfs
  33. 1. Creating the gadgets
  34. -----------------------
  35. For each gadget to be created its corresponding directory must be created::
  36. $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>
  37. e.g.::
  38. $ mkdir $CONFIGFS_HOME/usb_gadget/g1
  39. ...
  40. ...
  41. ...
  42. $ cd $CONFIGFS_HOME/usb_gadget/g1
  43. Each gadget needs to have its vendor id <VID> and product id <PID> specified::
  44. $ echo <VID> > idVendor
  45. $ echo <PID> > idProduct
  46. A gadget also needs its serial number, manufacturer and product strings.
  47. In order to have a place to store them, a strings subdirectory must be created
  48. for each language, e.g.::
  49. $ mkdir strings/0x409
  50. Then the strings can be specified::
  51. $ echo <serial number> > strings/0x409/serialnumber
  52. $ echo <manufacturer> > strings/0x409/manufacturer
  53. $ echo <product> > strings/0x409/product
  54. 2. Creating the configurations
  55. ------------------------------
  56. Each gadget will consist of a number of configurations, their corresponding
  57. directories must be created:
  58. $ mkdir configs/<name>.<number>
  59. where <name> can be any string which is legal in a filesystem and the
  60. <number> is the configuration's number, e.g.::
  61. $ mkdir configs/c.1
  62. ...
  63. ...
  64. ...
  65. Each configuration also needs its strings, so a subdirectory must be created
  66. for each language, e.g.::
  67. $ mkdir configs/c.1/strings/0x409
  68. Then the configuration string can be specified::
  69. $ echo <configuration> > configs/c.1/strings/0x409/configuration
  70. Some attributes can also be set for a configuration, e.g.::
  71. $ echo 120 > configs/c.1/MaxPower
  72. 3. Creating the functions
  73. -------------------------
  74. The gadget will provide some functions, for each function its corresponding
  75. directory must be created::
  76. $ mkdir functions/<name>.<instance name>
  77. where <name> corresponds to one of allowed function names and instance name
  78. is an arbitrary string allowed in a filesystem, e.g.::
  79. $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module()
  80. ...
  81. ...
  82. ...
  83. Each function provides its specific set of attributes, with either read-only
  84. or read-write access. Where applicable they need to be written to as
  85. appropriate.
  86. Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information.
  87. 4. Associating the functions with their configurations
  88. ------------------------------------------------------
  89. At this moment a number of gadgets is created, each of which has a number of
  90. configurations specified and a number of functions available. What remains
  91. is specifying which function is available in which configuration (the same
  92. function can be used in multiple configurations). This is achieved with
  93. creating symbolic links::
  94. $ ln -s functions/<name>.<instance name> configs/<name>.<number>
  95. e.g.::
  96. $ ln -s functions/ncm.usb0 configs/c.1
  97. ...
  98. ...
  99. ...
  100. 5. Enabling the gadget
  101. ----------------------
  102. All the above steps serve the purpose of composing the gadget of
  103. configurations and functions.
  104. An example directory structure might look like this::
  105. .
  106. ./strings
  107. ./strings/0x409
  108. ./strings/0x409/serialnumber
  109. ./strings/0x409/product
  110. ./strings/0x409/manufacturer
  111. ./configs
  112. ./configs/c.1
  113. ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0
  114. ./configs/c.1/strings
  115. ./configs/c.1/strings/0x409
  116. ./configs/c.1/strings/0x409/configuration
  117. ./configs/c.1/bmAttributes
  118. ./configs/c.1/MaxPower
  119. ./functions
  120. ./functions/ncm.usb0
  121. ./functions/ncm.usb0/ifname
  122. ./functions/ncm.usb0/qmult
  123. ./functions/ncm.usb0/host_addr
  124. ./functions/ncm.usb0/dev_addr
  125. ./UDC
  126. ./bcdUSB
  127. ./bcdDevice
  128. ./idProduct
  129. ./idVendor
  130. ./bMaxPacketSize0
  131. ./bDeviceProtocol
  132. ./bDeviceSubClass
  133. ./bDeviceClass
  134. Such a gadget must be finally enabled so that the USB host can enumerate it.
  135. In order to enable the gadget it must be bound to a UDC (USB Device
  136. Controller)::
  137. $ echo <udc name> > UDC
  138. where <udc name> is one of those found in /sys/class/udc/*
  139. e.g.::
  140. $ echo s3c-hsotg > UDC
  141. 6. Disabling the gadget
  142. -----------------------
  143. ::
  144. $ echo "" > UDC
  145. 7. Cleaning up
  146. --------------
  147. Remove functions from configurations::
  148. $ rm configs/<config name>.<number>/<function>
  149. where <config name>.<number> specify the configuration and <function> is
  150. a symlink to a function being removed from the configuration, e.g.::
  151. $ rm configs/c.1/ncm.usb0
  152. ...
  153. ...
  154. ...
  155. Remove strings directories in configurations:
  156. $ rmdir configs/<config name>.<number>/strings/<lang>
  157. e.g.::
  158. $ rmdir configs/c.1/strings/0x409
  159. ...
  160. ...
  161. ...
  162. and remove the configurations::
  163. $ rmdir configs/<config name>.<number>
  164. e.g.::
  165. rmdir configs/c.1
  166. ...
  167. ...
  168. ...
  169. Remove functions (function modules are not unloaded, though):
  170. $ rmdir functions/<name>.<instance name>
  171. e.g.::
  172. $ rmdir functions/ncm.usb0
  173. ...
  174. ...
  175. ...
  176. Remove strings directories in the gadget::
  177. $ rmdir strings/<lang>
  178. e.g.::
  179. $ rmdir strings/0x409
  180. and finally remove the gadget::
  181. $ cd ..
  182. $ rmdir <gadget name>
  183. e.g.::
  184. $ rmdir g1
  185. Implementation design
  186. =====================
  187. Below the idea of how configfs works is presented.
  188. In configfs there are items and groups, both represented as directories.
  189. The difference between an item and a group is that a group can contain
  190. other groups. In the picture below only an item is shown.
  191. Both items and groups can have attributes, which are represented as files.
  192. The user can create and remove directories, but cannot remove files,
  193. which can be read-only or read-write, depending on what they represent.
  194. The filesystem part of configfs operates on config_items/groups and
  195. configfs_attributes which are generic and of the same type for all
  196. configured elements. However, they are embedded in usage-specific
  197. larger structures. In the picture below there is a "cs" which contains
  198. a config_item and an "sa" which contains a configfs_attribute.
  199. The filesystem view would be like this::
  200. ./
  201. ./cs (directory)
  202. |
  203. +--sa (file)
  204. |
  205. .
  206. .
  207. .
  208. Whenever a user reads/writes the "sa" file, a function is called
  209. which accepts a struct config_item and a struct configfs_attribute.
  210. In the said function the "cs" and "sa" are retrieved using the well
  211. known container_of technique and an appropriate sa's function (show or
  212. store) is called and passed the "cs" and a character buffer. The "show"
  213. is for displaying the file's contents (copy data from the cs to the
  214. buffer), while the "store" is for modifying the file's contents (copy data
  215. from the buffer to the cs), but it is up to the implementer of the
  216. two functions to decide what they actually do.
  217. ::
  218. typedef struct configured_structure cs;
  219. typedef struct specific_attribute sa;
  220. sa
  221. +----------------------------------+
  222. cs | (*show)(cs *, buffer); |
  223. +-----------------+ | (*store)(cs *, buffer, length); |
  224. | | | |
  225. | +-------------+ | | +------------------+ |
  226. | | struct |-|----|------>|struct | |
  227. | | config_item | | | |configfs_attribute| |
  228. | +-------------+ | | +------------------+ |
  229. | | +----------------------------------+
  230. | data to be set | .
  231. | | .
  232. +-----------------+ .
  233. The file names are decided by the config item/group designer, while
  234. the directories in general can be named at will. A group can have
  235. a number of its default sub-groups created automatically.
  236. For more information on configfs please see
  237. `Documentation/filesystems/configfs.rst`.
  238. The concepts described above translate to USB gadgets like this:
  239. 1. A gadget has its config group, which has some attributes (idVendor,
  240. idProduct etc) and default sub-groups (configs, functions, strings).
  241. Writing to the attributes causes the information to be stored in
  242. appropriate locations. In the configs, functions and strings sub-groups
  243. a user can create their sub-groups to represent configurations, functions,
  244. and groups of strings in a given language.
  245. 2. The user creates configurations and functions, in the configurations
  246. creates symbolic links to functions. This information is used when the
  247. gadget's UDC attribute is written to, which means binding the gadget
  248. to the UDC. The code in drivers/usb/gadget/configfs.c iterates over
  249. all configurations, and in each configuration it iterates over all
  250. functions and binds them. This way the whole gadget is bound.
  251. 3. The file drivers/usb/gadget/configfs.c contains code for
  252. - gadget's config_group
  253. - gadget's default groups (configs, functions, strings)
  254. - associating functions with configurations (symlinks)
  255. 4. Each USB function naturally has its own view of what it wants
  256. configured, so config_groups for particular functions are defined
  257. in the functions implementation files drivers/usb/gadget/f_*.c.
  258. 5. Function's code is written in such a way that it uses
  259. usb_get_function_instance(), which, in turn, calls request_module.
  260. So, provided that modprobe works, modules for particular functions
  261. are loaded automatically. Please note that the converse is not true:
  262. after a gadget is disabled and torn down, the modules remain loaded.