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