Commit | Line | Data |
---|---|---|
d80b5005 MCC |
1 | ============================================ |
2 | Linux USB gadget configured through configfs | |
3 | ============================================ | |
5e654a46 AP |
4 | |
5 | ||
d80b5005 | 6 | 25th April 2013 |
5e654a46 AP |
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 | ||
98264991 | 27 | Configfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely |
5e654a46 AP |
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 | ||
d80b5005 MCC |
52 | :: |
53 | ||
54 | $ modprobe libcomposite | |
55 | $ mount none $CONFIGFS_HOME -t configfs | |
5e654a46 AP |
56 | |
57 | where CONFIGFS_HOME is the mount point for configfs | |
58 | ||
59 | 1. Creating the gadgets | |
60 | ----------------------- | |
61 | ||
d80b5005 | 62 | For each gadget to be created its corresponding directory must be created:: |
5e654a46 | 63 | |
d80b5005 | 64 | $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> |
5e654a46 | 65 | |
d80b5005 | 66 | e.g.:: |
5e654a46 | 67 | |
d80b5005 | 68 | $ mkdir $CONFIGFS_HOME/usb_gadget/g1 |
5e654a46 | 69 | |
d80b5005 MCC |
70 | ... |
71 | ... | |
72 | ... | |
5e654a46 | 73 | |
d80b5005 | 74 | $ cd $CONFIGFS_HOME/usb_gadget/g1 |
5e654a46 | 75 | |
d80b5005 | 76 | Each gadget needs to have its vendor id <VID> and product id <PID> specified:: |
5e654a46 | 77 | |
d80b5005 MCC |
78 | $ echo <VID> > idVendor |
79 | $ echo <PID> > idProduct | |
5e654a46 AP |
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 | |
d80b5005 | 83 | for each language, e.g.:: |
5e654a46 | 84 | |
d80b5005 | 85 | $ mkdir strings/0x409 |
5e654a46 | 86 | |
d80b5005 | 87 | Then the strings can be specified:: |
5e654a46 | 88 | |
d80b5005 MCC |
89 | $ echo <serial number> > strings/0x409/serialnumber |
90 | $ echo <manufacturer> > strings/0x409/manufacturer | |
91 | $ echo <product> > strings/0x409/product | |
5e654a46 AP |
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 | |
d80b5005 | 102 | <number> is the configuration's number, e.g.:: |
5e654a46 | 103 | |
d80b5005 | 104 | $ mkdir configs/c.1 |
5e654a46 | 105 | |
d80b5005 MCC |
106 | ... |
107 | ... | |
108 | ... | |
5e654a46 AP |
109 | |
110 | Each configuration also needs its strings, so a subdirectory must be created | |
d80b5005 | 111 | for each language, e.g.:: |
5e654a46 | 112 | |
d80b5005 | 113 | $ mkdir configs/c.1/strings/0x409 |
5e654a46 | 114 | |
d80b5005 | 115 | Then the configuration string can be specified:: |
5e654a46 | 116 | |
d80b5005 | 117 | $ echo <configuration> > configs/c.1/strings/0x409/configuration |
5e654a46 | 118 | |
d80b5005 | 119 | Some attributes can also be set for a configuration, e.g.:: |
5e654a46 | 120 | |
d80b5005 | 121 | $ echo 120 > configs/c.1/MaxPower |
5e654a46 AP |
122 | |
123 | 3. Creating the functions | |
124 | ------------------------- | |
125 | ||
126 | The gadget will provide some functions, for each function its corresponding | |
d80b5005 | 127 | directory must be created:: |
5e654a46 | 128 | |
d80b5005 | 129 | $ mkdir functions/<name>.<instance name> |
5e654a46 AP |
130 | |
131 | where <name> corresponds to one of allowed function names and instance name | |
d80b5005 | 132 | is an arbitrary string allowed in a filesystem, e.g.:: |
5e654a46 | 133 | |
d80b5005 | 134 | $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() |
5e654a46 | 135 | |
d80b5005 MCC |
136 | ... |
137 | ... | |
138 | ... | |
5e654a46 AP |
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 | |
d80b5005 | 152 | creating symbolic links:: |
5e654a46 | 153 | |
d80b5005 | 154 | $ ln -s functions/<name>.<instance name> configs/<name>.<number> |
5e654a46 | 155 | |
d80b5005 | 156 | e.g.:: |
5e654a46 | 157 | |
d80b5005 | 158 | $ ln -s functions/ncm.usb0 configs/c.1 |
5e654a46 | 159 | |
d80b5005 MCC |
160 | ... |
161 | ... | |
162 | ... | |
5e654a46 AP |
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 | ||
d80b5005 MCC |
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 | |
5e654a46 AP |
201 | |
202 | ||
203 | Such a gadget must be finally enabled so that the USB host can enumerate it. | |
5e654a46 | 204 | |
d80b5005 MCC |
205 | In order to enable the gadget it must be bound to a UDC (USB Device |
206 | Controller):: | |
207 | ||
208 | $ echo <udc name> > UDC | |
5e654a46 AP |
209 | |
210 | where <udc name> is one of those found in /sys/class/udc/* | |
d80b5005 | 211 | e.g.:: |
5e654a46 | 212 | |
d80b5005 | 213 | $ echo s3c-hsotg > UDC |
5e654a46 AP |
214 | |
215 | ||
216 | 6. Disabling the gadget | |
217 | ----------------------- | |
218 | ||
d80b5005 MCC |
219 | :: |
220 | ||
221 | $ echo "" > UDC | |
5e654a46 AP |
222 | |
223 | 7. Cleaning up | |
224 | -------------- | |
225 | ||
d80b5005 | 226 | Remove functions from configurations:: |
5e654a46 | 227 | |
d80b5005 | 228 | $ rm configs/<config name>.<number>/<function> |
5e654a46 AP |
229 | |
230 | where <config name>.<number> specify the configuration and <function> is | |
d80b5005 | 231 | a symlink to a function being removed from the configuration, e.g.:: |
5e654a46 | 232 | |
d80b5005 | 233 | $ rm configs/c.1/ncm.usb0 |
5e654a46 | 234 | |
d80b5005 MCC |
235 | ... |
236 | ... | |
237 | ... | |
5e654a46 | 238 | |
d80b5005 | 239 | Remove strings directories in configurations: |
5e654a46 | 240 | |
d80b5005 | 241 | $ rmdir configs/<config name>.<number>/strings/<lang> |
5e654a46 | 242 | |
d80b5005 | 243 | e.g.:: |
5e654a46 | 244 | |
d80b5005 | 245 | $ rmdir configs/c.1/strings/0x409 |
5e654a46 | 246 | |
d80b5005 MCC |
247 | ... |
248 | ... | |
249 | ... | |
5e654a46 | 250 | |
d80b5005 | 251 | and remove the configurations:: |
5e654a46 | 252 | |
d80b5005 | 253 | $ rmdir configs/<config name>.<number> |
5e654a46 | 254 | |
d80b5005 | 255 | e.g.:: |
5e654a46 | 256 | |
d80b5005 | 257 | rmdir configs/c.1 |
5e654a46 | 258 | |
d80b5005 MCC |
259 | ... |
260 | ... | |
261 | ... | |
5e654a46 | 262 | |
d80b5005 | 263 | Remove functions (function modules are not unloaded, though): |
5e654a46 | 264 | |
d80b5005 | 265 | $ rmdir functions/<name>.<instance name> |
5e654a46 | 266 | |
d80b5005 | 267 | e.g.:: |
5e654a46 | 268 | |
d80b5005 | 269 | $ rmdir functions/ncm.usb0 |
5e654a46 | 270 | |
d80b5005 MCC |
271 | ... |
272 | ... | |
273 | ... | |
5e654a46 | 274 | |
d80b5005 | 275 | Remove strings directories in the gadget:: |
5e654a46 | 276 | |
d80b5005 | 277 | $ rmdir strings/<lang> |
5e654a46 | 278 | |
d80b5005 | 279 | e.g.:: |
5e654a46 | 280 | |
d80b5005 | 281 | $ rmdir strings/0x409 |
5e654a46 | 282 | |
d80b5005 | 283 | and finally remove the gadget:: |
5e654a46 | 284 | |
d80b5005 MCC |
285 | $ cd .. |
286 | $ rmdir <gadget name> | |
5e654a46 | 287 | |
d80b5005 | 288 | e.g.:: |
5e654a46 | 289 | |
d80b5005 | 290 | $ rmdir g1 |
5e654a46 AP |
291 | |
292 | ||
293 | ||
294 | ||
295 | Implementation design | |
296 | ===================== | |
297 | ||
298 | Below the idea of how configfs works is presented. | |
299 | In configfs there are items and groups, both represented as directories. | |
300 | The difference between an item and a group is that a group can contain | |
301 | other groups. In the picture below only an item is shown. | |
302 | Both items and groups can have attributes, which are represented as files. | |
303 | The user can create and remove directories, but cannot remove files, | |
304 | which can be read-only or read-write, depending on what they represent. | |
305 | ||
306 | The filesystem part of configfs operates on config_items/groups and | |
307 | configfs_attributes which are generic and of the same type for all | |
308 | configured elements. However, they are embedded in usage-specific | |
309 | larger structures. In the picture below there is a "cs" which contains | |
310 | a config_item and an "sa" which contains a configfs_attribute. | |
311 | ||
d80b5005 | 312 | The filesystem view would be like this:: |
5e654a46 | 313 | |
d80b5005 MCC |
314 | ./ |
315 | ./cs (directory) | |
316 | | | |
317 | +--sa (file) | |
318 | | | |
319 | . | |
320 | . | |
321 | . | |
5e654a46 AP |
322 | |
323 | Whenever a user reads/writes the "sa" file, a function is called | |
324 | which accepts a struct config_item and a struct configfs_attribute. | |
325 | In the said function the "cs" and "sa" are retrieved using the well | |
326 | known container_of technique and an appropriate sa's function (show or | |
327 | store) is called and passed the "cs" and a character buffer. The "show" | |
328 | is for displaying the file's contents (copy data from the cs to the | |
329 | buffer), while the "store" is for modifying the file's contents (copy data | |
330 | from the buffer to the cs), but it is up to the implementer of the | |
331 | two functions to decide what they actually do. | |
332 | ||
d80b5005 MCC |
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 | +-----------------+ . | |
5e654a46 AP |
351 | |
352 | The file names are decided by the config item/group designer, while | |
353 | the directories in general can be named at will. A group can have | |
354 | a number of its default sub-groups created automatically. | |
355 | ||
356 | For more information on configfs please see | |
98264991 | 357 | `Documentation/filesystems/configfs.rst`. |
5e654a46 AP |
358 | |
359 | The concepts described above translate to USB gadgets like this: | |
360 | ||
361 | 1. A gadget has its config group, which has some attributes (idVendor, | |
362 | idProduct etc) and default sub-groups (configs, functions, strings). | |
363 | Writing to the attributes causes the information to be stored in | |
364 | appropriate locations. In the configs, functions and strings sub-groups | |
365 | a user can create their sub-groups to represent configurations, functions, | |
366 | and groups of strings in a given language. | |
367 | ||
368 | 2. The user creates configurations and functions, in the configurations | |
369 | creates symbolic links to functions. This information is used when the | |
370 | gadget's UDC attribute is written to, which means binding the gadget | |
371 | to the UDC. The code in drivers/usb/gadget/configfs.c iterates over | |
372 | all configurations, and in each configuration it iterates over all | |
373 | functions and binds them. This way the whole gadget is bound. | |
374 | ||
375 | 3. 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 | ||
381 | 4. Each USB function naturally has its own view of what it wants | |
382 | configured, so config_groups for particular functions are defined | |
383 | in the functions implementation files drivers/usb/gadget/f_*.c. | |
384 | ||
720a8d36 | 385 | 5. Function's code is written in such a way that it uses |
5e654a46 AP |
386 | |
387 | usb_get_function_instance(), which, in turn, calls request_module. | |
388 | So, provided that modprobe works, modules for particular functions | |
389 | are loaded automatically. Please note that the converse is not true: | |
390 | after a gadget is disabled and torn down, the modules remain loaded. |