Linux USB gadget configured through configfs

Overview

USB Linux 小工具是一种具有 UDC（USB 设备控制器）的设备，可连接到 USB 主机，以扩展其附加功能，如串行端口或大容量存储功能。

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.

主机将gadget视为一组配置，每个配置都包含若干接口，从gadget的角度看，这些接口被称为功能，每个功能代表一个串行连接或 SCSI 磁盘等。

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 为gadget提供了许多功能。

Linux provides a number of functions for gadgets to use.

创建gadget意味着要决定有哪些配置，以及每个配置将提供哪些功能。

Creating a gadget means deciding what configurations there will be and which functions each configuration will provide.

Configfs（请参阅 Configfs - 用户空间驱动的内核对象配置）可以很好地将上述决定告知内核。本文档将介绍如何做到这一点。 (Configfs - Userspace-driven Kernel Object Configuration — The Linux Kernel documentation)

Configfs (please see Configfs - Userspace-driven Kernel Object Configuration) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it.

Configfs（请参阅 Configfs - 用户空间驱动的内核对象配置）可以很好地将上述决定告知内核。本文档将介绍如何做到这一点。

本文还将介绍如何将 configfs 集成到gadget中。

It also describes how configfs integration into gadget is designed.

Requirements

为使其正常工作，configfs 必须可用，因此 .config 中的 CONFIGFS_FS 必须为 "y "或 "m"。目前，USB_LIBCOMPOSITE 选择 CONFIGFS_FS。

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

描述通过 configfs 提供第一个功能的原始帖子可在此处查看：

The original post describing the first function made available through configfs can be seen here:

  [PATCH 30/30] usb/gadget: the start of the configfs interface — Linux USB 

$ modprobe libcomposite

$ mount none $CONFIGFS_HOME -t configfs

其中 CONFIGFS_HOME变量 是 configfs 的挂载点 (一个文件夹路径)。

where CONFIGFS_HOME is the mount point for configfs.

1. Creating the gadgets [创建Gadget]

必须为每个要创建的小工具创建相应的目录：

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

每个小工具都需要指定供应商 ID <VID> 和产品 ID <PID>：

Each gadget needs to have its vendor id <VID> and product id <PID> specified:

$ echo <VID> > idVendor

$ echo <PID> > idProduct

当执行上面第一行语句后，在此gadget目录中，就会自动创建出一系列文件及文件夹。

Gadget还需要序列号、制造商和产品字符串。为了存放这些字符串，必须为每种语言创建一个字符串子目录，如:

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   # 0x409表示英文

然后就可以指定字符串了：

Then the strings can be specified:

$ echo <serial number> > strings/0x409/serialnumber

$ echo <manufacturer> > strings/0x409/manufacturer

$ echo <product> > strings/0x409/product

此外，还可以在语言目录中创建自定义字符串描述符目录，并将字符串文本写入字符串目录中的 "s "属性：

Further custom string descriptors can be created as directories within the language's directory, with the string text being written to the "s" attribute within the string's directory:

$ mkdir strings/0x409/xu.0 

$ echo <string text> > strings/0x409/xu.0/s

在函数驱动程序支持的情况下，函数可以允许这些自定义字符串描述符的符号链接，以便将这些字符串与类描述符关联起来。

Where function drivers support it, functions may allow symlinks to these custom string descriptors to associate those strings with class descriptors.

2. Creating the configurations [创建配置]

每个gadget都将包含多个配置，必须创建相应的目录：

Each gadget will consist of a number of configurations, their corresponding directories must be created:

$ mkdir configs/<name>.<number>

其中 <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 [创建功能]

gadget将提供一些功能，必须为每个功能创建相应的目录：

The gadget will provide some functions, for each function its corresponding directory must be created:

$ mkdir functions/<name>.<instance name>

其中 <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()

...

...

...

每个函数都提供其特定的属性集，具有只读或读写访问权限。在适用的情况下，需要对它们进行适当的写入。更多信息请参阅 Documentation/ABI/testing/configfs-usb-gadget。

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/testing/configfs-usb-gadget for more information.

4. Associating the functions with their configurations [将功能和配置进行关联]

此时会创建许多gadget，每个gadget都有指定的配置和可用的功能。剩下的工作就是指定哪个功能在哪个配置中可用（同一个功能可以在多个配置中使用）。这可以通过创建符号链接来实现：

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 [使能Gadget]

上述所有步骤都是为了将配置和功能组成一个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

需要最后使能这个Gadget，以便 USB 主机能对其进行枚举。

为了启用Gadget，必须将其绑定到 UDC（USB 设备控制器）上：

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

其中 <udc 名称> 是在 /sys/class/udc/* 中找到的名称之一，例如

where <udc name> is one of those found in /sys/class/udc/* e.g.:

$ echo s3c-hsotg > UDC

6. Disabling the gadge [停止Gadget]

$ echo "" > UDC

7. Cleaning up [移除]

从配置中删除功能：

Remove functions from configurations:

$ rm configs/<config name>.<number>/<function>

其中 <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

参考：

Linux USB gadget configured through configfs — The Linux Kernel documentation