Rockchip Linux USB Gadget Quick Start

:::info 文档信息

文档标识：RK-JC-YF-316　·　发布版本：V1.0.0　·　页数：14　·　语言：英文

原始文档：Rockchip_Quick_Start_Linux_USB_Gadget_EN.pdf

:::

章节大纲

Rockchip Linux USB Gadget Quick Start（P1）
- Linux-USB Gadget API Framework（P4）
  - Kernel Configuration（P5）
  - USB configfs（P6）
- USB Gadget Usage（P6）
  - USB Management Process（P6）
  - Function Configuration（P7）
    - ADB (Android Debug Bridge)（P8）
    - UAC (USB Audio Class)（P8）
    - RNDIS (Remote Network Driver Interface Specification)（P10）
    - MTP (Media Transfer Protocol)（P11）
    - UMS (USB Mass Storage)（P11）
    - ACM (CDC - ACM: Communication Device Class - Abstract Control Model)（P12）
    - UVC (USB Video Class)（P13）
  - USB Composite Device（P14）

在线预览

若预览无法显示，请直接下载 PDF 后用本地阅读器打开。

1. Linux-USB Gadget API Framework

USB Gadget is a system running inside a USB peripheral normally has at least three layers inside the kernel to handle USB protocol processing, and may have additional layers in user space code. The gadget API is used by the middle layer to interact with the lowest level (which directly handles hardware).

In Linux, from the bottom up, these layers are:

USB Controller: This is the lowest software level. It is the only layer that talks to hardware. That hardware is exposed through endpoint objects, which accept streams of IN/OUT buffers, and through callbacks that interact with gadget drivers. USB Gadget: The lower boundary of this driver implements hardware-neutral USB functions, using calls to the controller driver. For example, setup a function by using ep0 protocol response including class-specific functionality, and managing IN and OUT transfers on all currently enabled endpoints. Upper Level: Most gadget drivers have an upper boundary that connects to some Linux driver or framework in Linux. Through that boundary flows the data which the gadget driver produces and/or consumes through protocol transfers over USB. Additional Layers: Other layers may exist. These could include kernel layers, such as network protocol stacks, as well as user mode applications building on standard POSIX system call APIs such as open() , close() , read() and write() . NOTE: reference documents: https://www.kernel.org/doc/htmldocs/gadget/intro.html

1.1 Kernel Configuration

USB Gadget function is configured in menuconfig as follows:

Location:
-> Device Drivers
-> USB support
-> USB Gadget Support
-> USB Gadget Drivers

There is a set of automatic configuration scripts under RK Linux, to achieve the following automatic configuration functions:

CONFIG_USB_CONFIGFS_ACM
CONFIG_USB_CONFIGFS_RNDIS
CONFIG_USB_CONFIGFS_MASS_STORAGE
CONFIG_USB_CONFIGFS_F_FS
CONFIG_USB_CONFIGFS_F_MTP
CONFIG_USB_CONFIGFS_F_UAC1
CONFIG_USB_CONFIGFS_F_UAC2
CONFIG_USB_CONFIGFS_F_UVC

1.2 USB configfs

configfs is a ram-based filesystem that provides the converse of sysfs's functionality. Where sysfs is a filesystem- based view of kernel objects, configfs is a filesystem-based manager of kernel objects, or config_items.

With sysfs, an object is created in kernel (for example, when a device is discovered) and it is registered with sysfs. Its attributes then appear in sysfs, allowing userspace to read the attributes via readdir/read. It may allow some attributes to be modified via write. The important point is that the object is created and destroyed in kernel, the kernel controls the lifecycle of the sysfs representation, and sysfs is merely a window on all this.

A configfs config_item is created via an explicit userspace operation: mkdir. It is destroyed via rmdir. The attributes appear at mkdir time, and can be read or modified via read and write. As with sysfs, readdir queries the list of items and/or attributes. symlink can be used to group item together. Unlike sysfs, the lifetime of the representation is completely driven by userspace. The kernel modules backing the items must respond to this.

2. USB Gadget Usage

2.1 USB Management Process

There are three USB related files in RKScript package：

S50usbdevice # /etc/init.d/ works with .usb_config in the same directory
usbdevice # /usr/bin/
61-usbdevice.rules # /lib/udev/rules.d/
#There are two related files that need to be built or modified by users
.usb_config # /etc/init.d/
/tmp/.usb_config # S50usbdevice generates automaticlly

You can directly modify .usb_config and execute S50usbdevce script to configure USB function when needed.

After USB function is configured successfully, the following log will be showed to indicate USB is ready:

[   66.178517] android_work: sent uevent USB_STATE=CONNECTED
[   66.179977] configfs-gadget gadget: high-speed config #1: b
[   66.180663] android_work: sent uevent USB_STATE=CONFIGURED

2.2 Function Configuration

USB function configuration is written in /etc/init.d/.usb_config . You can change USB function by modifying /tmp/.usb_config and run /etc/init.d/S50usbdevice restart during running state.

Currently USB Gadget auto-configuration supports the following options for .usb_config :

usb_adb_en
usb_uac1_en
usb_uac2_en
usb_rndis_en
usb_mtp_en
usb_ums_en
usb_acm_en
usb_uvc_en

Differences between /etc/init.d/.usb_config and /tmp/.usb_config ：

/etc/init.d/.usb_config is the default configuration, sometimes your system may be a read-only system, and the file is unable to modify. Therefore, it is not recommended to modify this file in running state except for special cases. /tmp/.usb_config is a copy file of /etc/init.d/.usb_config . After booting, S50usbdevice will copy the /etc/init.d/.usb_config to /tmp which is a ram space and could be modified at any time. When you need to modify USB function in the running state, you can modify this file and reset USB function by

/etc/init.d/S50usbdevice restart .

2.2.1 ADB (Android Debug Bridge)

ADB is a versatile command line debugging tool that can be used for file transfer, Unix Shell login and other

functions.

ADB will be start properly by upper-layer application  adbd , and the  adbd compilation switch needs to be

turned on in Buildroot.

BR2_PACKAGE_ANDROID_TOOLS_ADBD

After ensuring there is an adbd running in your system, run the following command and connect to PC:

echo usb_adb_en > /tmp/.usb_config

Run adb devices , you can get devices on PC.

Note: If not find the device by adb device under Linux, run the following command:

adb kill-server
sudo adb devices

In Windows system, ADB driver need to be installed, adb devices need to run as an administrator if necessary.

2.2.2 UAC (USB Audio Class)

UAC implements the function of audio transmission between Device and Host for Host devices through USB virtual standard PCM interface.

UAC has two versions, UAC1 and UAC2. The differences between UAC2 and UAC1 follows:

The bandwidth of UAC2 is higher than UAC1 (the implementation of each platform is slightly different depends on actual testing) Windows 7 and some Windows 10 systems do not support UAC2 by default. You need to install the driver manually, but they all support UAC1.

You can enable UAC by running the following command:

echo usb_uac1_en > /tmp/.usb_config # or usb_uac2_en

UAC testing requires a third-party open-source library ALSA. Use aplay -l or arecord -l to find supported sound cards used to playing or recording:

# aplay -l
card 2: rk3xxx [rk3xxx], device 0: USB Audio [USB Audio]
Subdevices: 1/1
Subdevice #0: subdevice #0
# Specify the device setting by using: -D "hw:${card},${device}" (the above
information can be written as -D "hw:2,0")

UAC test process needs to build a loopback of audio data stream to test UAC Playback and Capture functions at the same time:

(1) PC plays audio to Device

Linux:

aplay -D "plughw:2,0" -f S16_LE -r 48000 -c 2 /userdata/test.wav
# plughw: if the audio sampling rate does not match the setting, alsa will
resample the audio to ensure that the output audio sampling rate is consistent
with the setting

Windows:

Right-click the sound icon at the bottom right corner-> Open Sound Settings -> Select output device and select the device (generally its name is Source/Sink which is related to Windows version), and then open the player to play music.

(2) Device will redirect the audio from UAC Playback to Capture

arecord -D "hw:3,0" -f S16_LE -r 48000 -c 2 -t raw -N |  aplay -D "hw:3,0" -f
S16_LE -r 48000 -c 2 -t raw -N

(3) PC will redirect the audio from UAC Capture to normal speakers

Linux

arecord -D "hw:2,0" -f S16_LE -r 44100 -c 2 -t raw -N | aplay -D "hw:1,0" -f
S16_LE -r 44100 -c 2 -t raw -N

Windows:

Right-click the sound icon at the lower right corner-> "Open Sound Settings"-> Select the input device and select the device (generally its name is Source/Sink which is related to Windows version)

Click on Device properties->Additional device properties , select item Listen and Listen to this device ,click on Play through this device to select the original playback device of PC.

In this way you will hear the test audio from the speaker of your PC.

2.2.3 RNDIS (Remote Network Driver Interface Specification)

RNDIS provides network interface specifications based on USB. Data interaction between Device and Host can be done by network commands (like SSH, etc.).

Run the following commands to enable RNDIS function:

echo usb_rndis_en > /tmp/.usb_config

You can find a new network card on both Host and Device by ifconfig:

# Host Linux
ifconfig
enp0s20u3u4u4 Link encap:Ethernet  HWaddr d6:11:03:17:c3:97
inet6 addr: fe80::3fa6:da84:77bd:122a/64 Scope:Link
UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
RX packets:61 errors:0 dropped:0 overruns:0 frame:0
TX packets:187 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:7198 (7.1 KB)  TX bytes:41844 (41.8 KB)
# Device
ifconfig
usb0      Link encap:Ethernet  HWaddr 46:26:71:47:E3:9F
inet addr:169.254.216.27  Bcast:169.254.255.255  Mask:255.255.0.0
inet6 addr: fe80::9e72:7f20:cc68:4a34/64 Scope:Link
UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
RX packets:606 errors:606 dropped:0 overruns:0 frame:606
TX packets:125 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:100024 (97.6 KiB)  TX bytes:30346 (29.6 KiB)

Host did not assign an IPv4 address which can be specified by ifconfig command manually:

#RNDIS address is fixed 169.254.216.1
ifconfig enp0s20u3u4u4 down
ifconfig enp0s20u3u4u4 169.254.216.1
ifconfig enp0s20u3u4u4 up

Now, you can use ping command on Device or Host to communicate with each other.

Note: IPV4 address is assigned automatically and successfully without manual assignment under Windows.

2.2.4 MTP (Media Transfer Protocol)

MTP is a media file transfer protocol proposed by Microsoft, which can conveniently share media files between Device and Host.

MTP could start normally depended on mtp-server of upper-layer application. and the mtp-server compilation switch in Buildroot should be enabled.

BR2_PACKAGE_MTP

After making sure there is a mtp-server in the system, run the following command and connect to PC:

echo usb_mtp_en > /tmp/.usb_config

Then you will see the "--- MODEL ---" device on the PC, which is the same in Linux and Windows.

Note: The MTP attribute name can be modified in buildroot/package/rockchip/mtp, please refer to the patch. The /userdata directory is shared by default.

2.2.5 UMS (USB Mass Storage)

UMS provides large-capacity external storage for Host devices.

Differences between UMS and MTP follows:

UMS works in blocks, but MTP works in files.

When UMS works, target block works exclusively, if multi-user operate the same block will cause errors; but MTP supports multi-user operation.

Run the following command to enable UMS:

echo usb_ums_en > /tmp/.usb_config
echo "ums_block=/dev/block/by-name/userdata" >> /tmp/.usb_config # it could be
replaced with an image file,for example /userdata/ums_shared.img

You will see a new USB drive on your PC.

As UMS Block works exclusively, S50usbdevice provides a new property that enables UMS Block to be uninstalled from the device when it is connected to a PC to prevent the device from operating incorrectly; when the PC is disconnected, it will be remounted to /mnt/ums .

You can enable the following properties in .usb_config:

echo "ums_block_auto_mount=on" >> /tmp/.usb_config

If you don't want to use a logical partition to load UMS, you can use an image file instead of a logical partition. image can be generated by yourself or automatically generated by S50usbdevice script.

#To generate a fat format with 8M size image file automatically, and enable UMS
to mount automatically
echo usb_ums_en > /tmp/.usb_config
echo "ums_block=/userdata/ums_shared.img" >> /tmp/.usb_config
echo "ums_block_size=8" >> /tmp/.usb_config #Unit M
echo "ums_block_type=fat" >> /tmp/.usb_config
echo "ums_block_auto_mount=on" >> /tmp/.usb_config

All above operations can be configured in Buildroot in this path: Target packages-> Rockchip BSP packages-> rockchip usb mass storage. After configuration, rebuild RKscript to generate /etc/init.d/.usb_config automatically.

2.2.6 ACM (CDC - ACM: Communication Device Class - Abstract Control Model)

It can be understood as a USB virtual serial port, and generates TTY devices both in Device and Host.

Run the following command to enable ACM:

echo usb_acm_en > /tmp/.usb_config

After enabling ACM, the /dev/ttyGS0 device will be found on the Device and the /dev/ttyACM0 device will be found on the PC.

#Run the following command on PC:
echo test > /dev/ttyACM0
#Run the following command on Device
cat /dev/ttyGS0 #to get test output

2.2.7 UVC (USB Video Class)

UVC function requires UVC application to start normally. A test demo ( uvc_app ) is provided in Buildroot, and the corresponding compilation switch needs to be turned on in Buildroot.

BR2_PACKAGE_UVC_APP

To manually modify S50usbdevice script and add:

- # Add uvc app here with start-stop-daemon
+ if [ $UVC_EN = on ];then
+               start-stop-daemon --start --quiet --background --exec
/usr/bin/uvc_app -- 640 480
+ fi

Use the following command to enable UVC:

echo usb_uvc_en > /tmp/.usb_config # Output is 640x480 format image by default

Checking tool on the Host: it recommends to use guvcview in Linux and amcap in Windows, select

Device-> UVC Camera / Options-> Preview

The bottom left corner shows the frame rate.

Note: uvc_app is just a test demo, not an formal application. It displays 4 solid-color stripes. Users can modify the application according to this demo. UVC application is needed when using UVC function; otherwise, starting UVC function directly will cause abnormal USB functions. If your system is a read-only file system, S50usbdevice should be modified in advance before the system is packaged UVC is not friendly support hot plug. Once USB Gadget completes unbind action, UVC will not be used normally, which is caused by V4L2 registration mechanism.

2.3 USB Composite Device

If conditions of port and bandwidth permits, The composite function of USB Gadget can be used to combine multiple USB Gadegt functions into one USB Port.

For example: combine ADB + RNDIS:

echo usb_mtp_en > /tmp/.usb_config
echo usb_adb_en >> /tmp/.usb_config

章节大纲​

在线预览​

1. Linux-USB Gadget API Framework​

1.1 Kernel Configuration​

1.2 USB configfs​

2. USB Gadget Usage​

2.1 USB Management Process​

2.2 Function Configuration​

2.2.1 ADB (Android Debug Bridge)​

2.2.2 UAC (USB Audio Class)​

2.2.3 RNDIS (Remote Network Driver Interface Specification)​

2.2.4 MTP (Media Transfer Protocol)​

2.2.5 UMS (USB Mass Storage)​

2.2.6 ACM (CDC - ACM: Communication Device Class - Abstract Control Model)​

2.2.7 UVC (USB Video Class)​

2.3 USB Composite Device​