forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
390 lines
10 KiB
390 lines
10 KiB
============================================ |
|
Linux USB gadget configured through configfs |
|
============================================ |
|
|
|
|
|
25th April 2013 |
|
|
|
|
|
|
|
|
|
Overview |
|
======== |
|
|
|
A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can |
|
be connected to a USB Host to extend it with additional functions like a serial |
|
port or a mass storage capability. |
|
|
|
A gadget is seen by its host as a set of configurations, each of which contains |
|
a number of interfaces which, from the gadget's perspective, are known as |
|
functions, each function representing e.g. a serial connection or a SCSI disk. |
|
|
|
Linux provides a number of functions for gadgets to use. |
|
|
|
Creating a gadget means deciding what configurations there will be |
|
and which functions each configuration will provide. |
|
|
|
Configfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely |
|
for the purpose of telling the kernel about the above mentioned decision. |
|
This document is about how to do it. |
|
|
|
It also describes how configfs integration into gadget is designed. |
|
|
|
|
|
|
|
|
|
Requirements |
|
============ |
|
|
|
In order for this to work configfs must be available, so CONFIGFS_FS must be |
|
'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. |
|
|
|
|
|
|
|
|
|
Usage |
|
===== |
|
|
|
(The original post describing the first function |
|
made available through configfs can be seen here: |
|
http://www.spinics.net/lists/linux-usb/msg76388.html) |
|
|
|
:: |
|
|
|
$ modprobe libcomposite |
|
$ mount none $CONFIGFS_HOME -t configfs |
|
|
|
where CONFIGFS_HOME is the mount point for configfs |
|
|
|
1. Creating the gadgets |
|
----------------------- |
|
|
|
For each gadget to be created its corresponding directory must be created:: |
|
|
|
$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> |
|
|
|
e.g.:: |
|
|
|
$ mkdir $CONFIGFS_HOME/usb_gadget/g1 |
|
|
|
... |
|
... |
|
... |
|
|
|
$ cd $CONFIGFS_HOME/usb_gadget/g1 |
|
|
|
Each gadget needs to have its vendor id <VID> and product id <PID> specified:: |
|
|
|
$ echo <VID> > idVendor |
|
$ echo <PID> > idProduct |
|
|
|
A gadget also needs its serial number, manufacturer and product strings. |
|
In order to have a place to store them, a strings subdirectory must be created |
|
for each language, e.g.:: |
|
|
|
$ mkdir strings/0x409 |
|
|
|
Then the strings can be specified:: |
|
|
|
$ echo <serial number> > strings/0x409/serialnumber |
|
$ echo <manufacturer> > strings/0x409/manufacturer |
|
$ echo <product> > strings/0x409/product |
|
|
|
2. Creating the configurations |
|
------------------------------ |
|
|
|
Each gadget will consist of a number of configurations, their corresponding |
|
directories must be created: |
|
|
|
$ mkdir configs/<name>.<number> |
|
|
|
where <name> can be any string which is legal in a filesystem and the |
|
<number> is the configuration's number, e.g.:: |
|
|
|
$ mkdir configs/c.1 |
|
|
|
... |
|
... |
|
... |
|
|
|
Each configuration also needs its strings, so a subdirectory must be created |
|
for each language, e.g.:: |
|
|
|
$ mkdir configs/c.1/strings/0x409 |
|
|
|
Then the configuration string can be specified:: |
|
|
|
$ echo <configuration> > configs/c.1/strings/0x409/configuration |
|
|
|
Some attributes can also be set for a configuration, e.g.:: |
|
|
|
$ echo 120 > configs/c.1/MaxPower |
|
|
|
3. Creating the functions |
|
------------------------- |
|
|
|
The gadget will provide some functions, for each function its corresponding |
|
directory must be created:: |
|
|
|
$ mkdir functions/<name>.<instance name> |
|
|
|
where <name> corresponds to one of allowed function names and instance name |
|
is an arbitrary string allowed in a filesystem, e.g.:: |
|
|
|
$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() |
|
|
|
... |
|
... |
|
... |
|
|
|
Each function provides its specific set of attributes, with either read-only |
|
or read-write access. Where applicable they need to be written to as |
|
appropriate. |
|
Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. |
|
|
|
4. Associating the functions with their configurations |
|
------------------------------------------------------ |
|
|
|
At this moment a number of gadgets is created, each of which has a number of |
|
configurations specified and a number of functions available. What remains |
|
is specifying which function is available in which configuration (the same |
|
function can be used in multiple configurations). This is achieved with |
|
creating symbolic links:: |
|
|
|
$ ln -s functions/<name>.<instance name> configs/<name>.<number> |
|
|
|
e.g.:: |
|
|
|
$ ln -s functions/ncm.usb0 configs/c.1 |
|
|
|
... |
|
... |
|
... |
|
|
|
5. Enabling the gadget |
|
---------------------- |
|
|
|
All the above steps serve the purpose of composing the gadget of |
|
configurations and functions. |
|
|
|
An example directory structure might look like this:: |
|
|
|
. |
|
./strings |
|
./strings/0x409 |
|
./strings/0x409/serialnumber |
|
./strings/0x409/product |
|
./strings/0x409/manufacturer |
|
./configs |
|
./configs/c.1 |
|
./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 |
|
./configs/c.1/strings |
|
./configs/c.1/strings/0x409 |
|
./configs/c.1/strings/0x409/configuration |
|
./configs/c.1/bmAttributes |
|
./configs/c.1/MaxPower |
|
./functions |
|
./functions/ncm.usb0 |
|
./functions/ncm.usb0/ifname |
|
./functions/ncm.usb0/qmult |
|
./functions/ncm.usb0/host_addr |
|
./functions/ncm.usb0/dev_addr |
|
./UDC |
|
./bcdUSB |
|
./bcdDevice |
|
./idProduct |
|
./idVendor |
|
./bMaxPacketSize0 |
|
./bDeviceProtocol |
|
./bDeviceSubClass |
|
./bDeviceClass |
|
|
|
|
|
Such a gadget must be finally enabled so that the USB host can enumerate it. |
|
|
|
In order to enable the gadget it must be bound to a UDC (USB Device |
|
Controller):: |
|
|
|
$ echo <udc name> > UDC |
|
|
|
where <udc name> is one of those found in /sys/class/udc/* |
|
e.g.:: |
|
|
|
$ echo s3c-hsotg > UDC |
|
|
|
|
|
6. Disabling the gadget |
|
----------------------- |
|
|
|
:: |
|
|
|
$ echo "" > UDC |
|
|
|
7. Cleaning up |
|
-------------- |
|
|
|
Remove functions from configurations:: |
|
|
|
$ rm configs/<config name>.<number>/<function> |
|
|
|
where <config name>.<number> specify the configuration and <function> is |
|
a symlink to a function being removed from the configuration, e.g.:: |
|
|
|
$ rm configs/c.1/ncm.usb0 |
|
|
|
... |
|
... |
|
... |
|
|
|
Remove strings directories in configurations: |
|
|
|
$ rmdir configs/<config name>.<number>/strings/<lang> |
|
|
|
e.g.:: |
|
|
|
$ rmdir configs/c.1/strings/0x409 |
|
|
|
... |
|
... |
|
... |
|
|
|
and remove the configurations:: |
|
|
|
$ rmdir configs/<config name>.<number> |
|
|
|
e.g.:: |
|
|
|
rmdir configs/c.1 |
|
|
|
... |
|
... |
|
... |
|
|
|
Remove functions (function modules are not unloaded, though): |
|
|
|
$ rmdir functions/<name>.<instance name> |
|
|
|
e.g.:: |
|
|
|
$ rmdir functions/ncm.usb0 |
|
|
|
... |
|
... |
|
... |
|
|
|
Remove strings directories in the gadget:: |
|
|
|
$ rmdir strings/<lang> |
|
|
|
e.g.:: |
|
|
|
$ rmdir strings/0x409 |
|
|
|
and finally remove the gadget:: |
|
|
|
$ cd .. |
|
$ rmdir <gadget name> |
|
|
|
e.g.:: |
|
|
|
$ rmdir g1 |
|
|
|
|
|
|
|
|
|
Implementation design |
|
===================== |
|
|
|
Below the idea of how configfs works is presented. |
|
In configfs there are items and groups, both represented as directories. |
|
The difference between an item and a group is that a group can contain |
|
other groups. In the picture below only an item is shown. |
|
Both items and groups can have attributes, which are represented as files. |
|
The user can create and remove directories, but cannot remove files, |
|
which can be read-only or read-write, depending on what they represent. |
|
|
|
The filesystem part of configfs operates on config_items/groups and |
|
configfs_attributes which are generic and of the same type for all |
|
configured elements. However, they are embedded in usage-specific |
|
larger structures. In the picture below there is a "cs" which contains |
|
a config_item and an "sa" which contains a configfs_attribute. |
|
|
|
The filesystem view would be like this:: |
|
|
|
./ |
|
./cs (directory) |
|
| |
|
+--sa (file) |
|
| |
|
. |
|
. |
|
. |
|
|
|
Whenever a user reads/writes the "sa" file, a function is called |
|
which accepts a struct config_item and a struct configfs_attribute. |
|
In the said function the "cs" and "sa" are retrieved using the well |
|
known container_of technique and an appropriate sa's function (show or |
|
store) is called and passed the "cs" and a character buffer. The "show" |
|
is for displaying the file's contents (copy data from the cs to the |
|
buffer), while the "store" is for modifying the file's contents (copy data |
|
from the buffer to the cs), but it is up to the implementer of the |
|
two functions to decide what they actually do. |
|
|
|
:: |
|
|
|
typedef struct configured_structure cs; |
|
typedef struct specific_attribute sa; |
|
|
|
sa |
|
+----------------------------------+ |
|
cs | (*show)(cs *, buffer); | |
|
+-----------------+ | (*store)(cs *, buffer, length); | |
|
| | | | |
|
| +-------------+ | | +------------------+ | |
|
| | struct |-|----|------>|struct | | |
|
| | config_item | | | |configfs_attribute| | |
|
| +-------------+ | | +------------------+ | |
|
| | +----------------------------------+ |
|
| data to be set | . |
|
| | . |
|
+-----------------+ . |
|
|
|
The file names are decided by the config item/group designer, while |
|
the directories in general can be named at will. A group can have |
|
a number of its default sub-groups created automatically. |
|
|
|
For more information on configfs please see |
|
`Documentation/filesystems/configfs.rst`. |
|
|
|
The concepts described above translate to USB gadgets like this: |
|
|
|
1. A gadget has its config group, which has some attributes (idVendor, |
|
idProduct etc) and default sub-groups (configs, functions, strings). |
|
Writing to the attributes causes the information to be stored in |
|
appropriate locations. In the configs, functions and strings sub-groups |
|
a user can create their sub-groups to represent configurations, functions, |
|
and groups of strings in a given language. |
|
|
|
2. The user creates configurations and functions, in the configurations |
|
creates symbolic links to functions. This information is used when the |
|
gadget's UDC attribute is written to, which means binding the gadget |
|
to the UDC. The code in drivers/usb/gadget/configfs.c iterates over |
|
all configurations, and in each configuration it iterates over all |
|
functions and binds them. This way the whole gadget is bound. |
|
|
|
3. The file drivers/usb/gadget/configfs.c contains code for |
|
|
|
- gadget's config_group |
|
- gadget's default groups (configs, functions, strings) |
|
- associating functions with configurations (symlinks) |
|
|
|
4. Each USB function naturally has its own view of what it wants |
|
configured, so config_groups for particular functions are defined |
|
in the functions implementation files drivers/usb/gadget/f_*.c. |
|
|
|
5. Function's code is written in such a way that it uses |
|
|
|
usb_get_function_instance(), which, in turn, calls request_module. |
|
So, provided that modprobe works, modules for particular functions |
|
are loaded automatically. Please note that the converse is not true: |
|
after a gadget is disabled and torn down, the modules remain loaded.
|
|
|