Documentation/usb/gadget_configfs.txt

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/*) 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 　　#它选中了configfs模块
$ mount none $CONFIGFS_HOME -t configfs　　 #挂载，$CONFIGFS_HOME是内核中指定的变量吗？

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>　　 #<name>表示gadget设备名，可以是任意字符串

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 　　# 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()
#执行request_module()时加载usb_f_ncm.ko，应该也是通过“ncm”名字进行匹配的

...
...
...

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 　　#将function和configuration进行关联
------------------------------------------------------

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> 　　#Android中创建符号链接使用的不是ln

==><number>是唯一的，这岂不是每个配置只能有1个function了？可以多个function链接到同一个cofigure中吗？

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　　#将UDC设置为空表示disable这个gadget

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 configfs/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)
|
.
.
.
===> config_item 和 config_group可用于表示目录，config_group里面还可以包含子目录。configfs_attribute表示属性文件。

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/*.

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 ==>当gadget's UDC attribute文件被写入时表示gadget与UDC进行绑定
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. ==>也是调用用户空间的modprobe加载的
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. ==>会自动加载function模块，但是不会自动卸载function模块

Documentation/ABI/testing/configfs-usb-gadget：

What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property>
Date: May 2014
KernelVersion: 3.16
Description:
This group contains "Extended Property Descriptors" specific for one
gadget's USB interface or one interface group described
by an IAD.

The attributes:

type - value 1..7 for interpreting the data
　　1: unicode string
　　2: unicode string with environment variable
　　3: binary
　　4: little-endian 32-bit
　　5: big-endian 32-bit
　　6: unicode string with a symbolic link
　　7: multiple unicode strings
data - blob of data to be interpreted depending on type

Documentation/usb/gadget-testing.txt：

========================

10. NCM function
================

The function is provided by usb_f_ncm.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "ncm".
The NCM function provides these attributes in its function directory:

ifname - network device interface name associated with this function instance
qmult - queue length multiplier for high and super speed
host_addr - MAC address of host's end of this Ethernet over USB link
dev_addr - MAC address of device's end of this Ethernet over USB link

and after creating the functions/ncm.<instance name> they contain default
values: qmult is 5, dev_addr and host_addr are randomly selected.
Except for ifname they can be written to until the function is linked to a
configuration. The ifname is read-only and contains the name of the interface
which was assigned by the net core, e. g. usb0.

Testing the NCM function
------------------------

Configure IP addresses of the device and the host. Then:

On the device: ping <host's IP> 通过ping测试ncm功能是否OK
On the host: ping <device's IP>