Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/Documentation/usb/gadget_configfs.txt

  1 
  2 
  3 
  4 
  5                 Linux USB gadget configured through configfs
  6 
  7 
  8                              25th April 2013
  9 
 10 
 11 
 12 
 13 Overview
 14 ========
 15 
 16 A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can
 17 be connected to a USB Host to extend it with additional functions like a serial
 18 port or a mass storage capability.
 19 
 20 A gadget is seen by its host as a set of configurations, each of which contains
 21 a number of interfaces which, from the gadget's perspective, are known as
 22 functions, each function representing e.g. a serial connection or a SCSI disk.
 23 
 24 Linux provides a number of functions for gadgets to use.
 25 
 26 Creating a gadget means deciding what configurations there will be
 27 and which functions each configuration will provide.
 28 
 29 Configfs (please see Documentation/filesystems/configfs/*) lends itself nicely
 30 for the purpose of telling the kernel about the above mentioned decision.
 31 This document is about how to do it.
 32 
 33 It also describes how configfs integration into gadget is designed.
 34 
 35 
 36 
 37 
 38 Requirements
 39 ============
 40 
 41 In 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 
 47 Usage
 48 =====
 49 
 50 (The original post describing the first function
 51 made available through configfs can be seen here:
 52 http://www.spinics.net/lists/linux-usb/msg76388.html)
 53 
 54 $ modprobe libcomposite
 55 $ mount none $CONFIGFS_HOME -t configfs
 56 
 57 where CONFIGFS_HOME is the mount point for configfs
 58 
 59 1. Creating the gadgets
 60 -----------------------
 61 
 62 For each gadget to be created its corresponding directory must be created:
 63 
 64 $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>
 65 
 66 e.g.:
 67 
 68 $ mkdir $CONFIGFS_HOME/usb_gadget/g1
 69 
 70 ...
 71 ...
 72 ...
 73 
 74 $ cd $CONFIGFS_HOME/usb_gadget/g1
 75 
 76 Each gadget needs to have its vendor id <VID> and product id <PID> specified:
 77 
 78 $ echo <VID> > idVendor
 79 $ echo <PID> > idProduct
 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
 83 for each language, e.g.:
 84 
 85 $ mkdir strings/0x409
 86 
 87 Then 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 
 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
102 <number> is the configuration's number, e.g.:
103 
104 $ mkdir configs/c.1
105 
106 ...
107 ...
108 ...
109 
110 Each configuration also needs its strings, so a subdirectory must be created
111 for each language, e.g.:
112 
113 $ mkdir configs/c.1/strings/0x409
114 
115 Then the configuration string can be specified:
116 
117 $ echo <configuration> > configs/c.1/strings/0x409/configuration
118 
119 Some attributes can also be set for a configuration, e.g.:
120 
121 $ echo 120 > configs/c.1/MaxPower
122 
123 3. Creating the functions
124 -------------------------
125 
126 The gadget will provide some functions, for each function its corresponding
127 directory must be created:
128 
129 $ mkdir functions/<name>.<instance name>
130 
131 where <name> corresponds to one of allowed function names and instance name
132 is 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 
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
152 creating symbolic links:
153 
154 $ ln -s functions/<name>.<instance name> configs/<name>.<number>
155 
156 e.g.:
157 
158 $ ln -s functions/ncm.usb0 configs/c.1
159 
160 ...
161 ...
162 ...
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 
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
201 
202 
203 Such a gadget must be finally enabled so that the USB host can enumerate it.
204 In order to enable the gadget it must be bound to a UDC (USB Device Controller).
205 
206 $ echo <udc name> > UDC
207 
208 where <udc name> is one of those found in /sys/class/udc/*
209 e.g.:
210 
211 $ echo s3c-hsotg > UDC
212 
213 
214 6. Disabling the gadget
215 -----------------------
216 
217 $ echo "" > UDC
218 
219 7. Cleaning up
220 --------------
221 
222 Remove functions from configurations:
223 
224 $ rm configs/<config name>.<number>/<function>
225 
226 where <config name>.<number> specify the configuration and <function> is
227 a symlink to a function being removed from the configuration, e.g.:
228 
229 $ rm configfs/c.1/ncm.usb0
230 
231 ...
232 ...
233 ...
234 
235 Remove strings directories in configurations
236 
237 $ rmdir configs/<config name>.<number>/strings/<lang>
238 
239 e.g.:
240 
241 $ rmdir configs/c.1/strings/0x409
242 
243 ...
244 ...
245 ...
246 
247 and remove the configurations
248 
249 $ rmdir configs/<config name>.<number>
250 
251 e.g.:
252 
253 rmdir configs/c.1
254 
255 ...
256 ...
257 ...
258 
259 Remove functions (function modules are not unloaded, though)
260 
261 $ rmdir functions/<name>.<instance name>
262 
263 e.g.:
264 
265 $ rmdir functions/ncm.usb0
266 
267 ...
268 ...
269 ...
270 
271 Remove strings directories in the gadget
272 
273 $ rmdir strings/<lang>
274 
275 e.g.:
276 
277 $ rmdir strings/0x409
278 
279 and finally remove the gadget:
280 
281 $ cd ..
282 $ rmdir <gadget name>
283 
284 e.g.:
285 
286 $ rmdir g1
287 
288 
289 
290 
291 Implementation design
292 =====================
293 
294 Below the idea of how configfs works is presented.
295 In configfs there are items and groups, both represented as directories.
296 The difference between an item and a group is that a group can contain
297 other groups. In the picture below only an item is shown.
298 Both items and groups can have attributes, which are represented as files.
299 The user can create and remove directories, but cannot remove files,
300 which can be read-only or read-write, depending on what they represent.
301 
302 The filesystem part of configfs operates on config_items/groups and
303 configfs_attributes which are generic and of the same type for all
304 configured elements. However, they are embedded in usage-specific
305 larger structures. In the picture below there is a "cs" which contains
306 a config_item and an "sa" which contains a configfs_attribute.
307 
308 The filesystem view would be like this:
309 
310 ./
311 ./cs        (directory)
312    |
313    +--sa    (file)
314    |
315    .
316    .
317    .
318 
319 Whenever a user reads/writes the "sa" file, a function is called
320 which accepts a struct config_item and a struct configfs_attribute.
321 In the said function the "cs" and "sa" are retrieved using the well
322 known container_of technique and an appropriate sa's function (show or
323 store) is called and passed the "cs" and a character buffer. The "show"
324 is for displaying the file's contents (copy data from the cs to the
325 buffer), while the "store" is for modifying the file's contents (copy data
326 from the buffer to the cs), but it is up to the implementer of the
327 two functions to decide what they actually do.
328 
329 typedef struct configured_structure cs;
330 typedef struct 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 
346 The file names are decided by the config item/group designer, while
347 the directories in general can be named at will. A group can have
348 a number of its default sub-groups created automatically.
349 
350 For more information on configfs please see
351 Documentation/filesystems/configfs/*.
352 
353 The concepts described above translate to USB gadgets like this:
354 
355 1. A gadget has its config group, which has some attributes (idVendor,
356 idProduct etc) and default sub-groups (configs, functions, strings).
357 Writing to the attributes causes the information to be stored in
358 appropriate locations. In the configs, functions and strings sub-groups
359 a user can create their sub-groups to represent configurations, functions,
360 and groups of strings in a given language.
361 
362 2. The user creates configurations and functions, in the configurations
363 creates symbolic links to functions. This information is used when the
364 gadget's UDC attribute is written to, which means binding the gadget
365 to the UDC. The code in drivers/usb/gadget/configfs.c iterates over
366 all configurations, and in each configuration it iterates over all
367 functions and binds them. This way the whole gadget is bound.
368 
369 3. 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 
375 4. Each USB function naturally has its own view of what it wants
376 configured, so config_groups for particular functions are defined
377 in the functions implementation files drivers/usb/gadget/f_*.c.
378 
379 5. Function's code is written in such a way that it uses
380 
381 usb_get_function_instance(), which, in turn, calls request_module.
382 So, provided that modprobe works, modules for particular functions
383 are loaded automatically. Please note that the converse is not true:
384 after a gadget is disabled and torn down, the modules remain loaded.

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us