blob: 8ec2a67c39b7c6a1114e75563fd980717155103f [file] [log] [blame]
Andrzej Pietrasiewicz5e654a42013-06-13 10:37:25 +02001
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.