主机解决方案

在 USB 主机模式下，USB OTG 可以枚举已连接的 USB 设备并启动 USB 传输。

更多主机类信息参见 usb v5.4 或 usb v6.18。

透传主机方案

配置

在基础的 USB 配置之外，还需要额外的配置来支持 USB CDC ACM 类驱动程序，可将其配置为内置功能或独立的内核模块。

以下配置提供了支持典型 CDC ACM 设备（如 USB 串口）的示例。

根据需要调整配置。

内置配置:

进入 USB support 菜单，输入 Y 选择：

Device Drivers  --->
    USB support  --->
        [*] USB Modem (CDC ACM) support
        [*] USB Serial Converter support

模块配置:

进入 USB support 菜单，输入 M 选择：

Device Drivers  --->
    USB support  --->
        [M] USB Modem (CDC ACM) support
        [M] USB Serial Converter support

在加载常用 USB 主机模块后，加载 CDC ACM 类的内核模块。

insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/serial/usbserial.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/class/cdc-acm.ko

应用 APIs

CDC ACM 设备以 Linux 串口（/dev/ttyACM*）的形式暴露。可使用标准 Linux 串口工具及 termios API。更多信息请参阅 Linux 串口驱动。

使用示例

一旦配置为 CDC ACM 主机，SoC 将识别连接的 CDC ACM 设备为 TTY 设备，并能够通过 TTY 接口与 CDC ACM 设备进行通信。

将 CDC ACM 设备通过 USB 电缆连接到 SoC，控制台上将打印以下日志：

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 2 using dwc2
dwc2 40080000.usb: Set speed to high-speed
cdc_acm 1-1:1.0: ttyACM0: USB ACM device

通过设备节点 /dev/ttyACM0 与 CDC ACM 设备通信，例如：
1. 向 CDC ACM 设备发送数据：
```
echo helloworld > /dev/ttyACM0
```
2. 从 CDC ACM 设备接收数据：
```
cat /dev/ttyACM0
```

CDC ACM 主机完整演示参见 <sdk>/tests/usbh_cdc_acm。

存储主机方案

配置

在基础的 USB 配置外，还需要额外的配置来支持 USB MSC 类驱动程序，可将其配置为内置功能或独立的内核模块。

以下配置提供了一个示例来支持典型的 MSC 设备：使用瑞昱读卡器解决方案的 UDISK，并格式化为 FAT32 文件系统。

USB MSC 类驱动程序所需的常见配置：

SCSI 设备支持：

Device Drivers  --->
    SCSI device support  --->
        [*] SCSI device support
        [*] SCSI disk support

VFAT 文件系统支持：

File systems  --->
    DOS/FAT/NT Filesystems  --->
        [*] VFAT (Windows-95) fs support

本地语言支持：

File systems  --->
    Native language support  --->
        [*] Codepage 437(United States, Canada)
        [*] NLS ISO 8859-1 (Latin 1; Western European Languages)

USB Mass Storage 支持：

Device Drivers  --->
    USB support  --->
        [*] USB Mass Storage support
        [*] Realtek Card Reader support

根据需要调整配置。

内置配置:

进入 USB support 菜单，输入 Y 选择：

Device Drivers  --->
    USB support  --->
        [*] USB Mass Storage support
        [*] Realtek Card Reader support

模块配置:

进入 USB support 菜单，输入 M 选择：

Device Drivers  --->
    USB support  --->
        [M] USB Mass Storage support
        [M] Realtek Card Reader support

在加载通用 USB 主机模块后，加载 MSC 类的内核模块。

insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/storage/usb-storage.ko

应用 APIs

请参考 usb guide x498 。

使用示例

以下是使用支持的 UDISK 测试 USB 主机 MSC 驱动程序的示例。

前置条件：

准备一个已格式化为 FAT32 文件系统的 UDisk。

将 UDisk 连接到 SoC，控制台将输出以下日志：

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 3 using dwc2
dwc2 40080000.usb: Set speed to high-speed
usb-storage 1-1:1.0: USB Mass Storage device detected
scsi host0: usb-storage 1-1:1.0
scsi 0:0:0:0: Direct-Access TOSHIBA USB FLASH DRIVE PMAP PQ: 0 ANSI: 6
sd 0:0:0:0: [sda] 30253056 512-byte logical blocks: (15.5 GB/14.4 GiB)
sd 0:0:0:0: [sda] Write Protect is off
sd 0:0:0:0: [sda] Write cache: disabled, read cache: enabled, does not support DPO or FUA
sda: sda1
sd 0:0:0:0: [sda] Attached SCSI removable disk

出现 [sda] Attached SCSI removable disk 表示枚举成功。

挂载 UDisk 设备：

mkdir /mnt/udisk
mount -t vfat /dev/sda1 /mnt/udisk

验证挂载：
```
df -h | grep sda1
```
预期输出显示 /dev/sda1 挂载在 /mnt/udisk。
访问 UDisk 设备。创建一个文件并进行读写操作：
```
cd /mnt/udisk
echo hello >> test.txt
cat test.txt
hello
```
卸载 UDisk 设备：
```
umount /mnt/udisk
```
断开 UDisk 后，控制台预期输出以下日志：
```
usb 1-1: USB disconnect, device number 3
```
测试通过的条件：UDisk 被识别、挂载成功、写入的数据可正确读取。

视频主机方案

配置

在基础的 USB 配置之基础上，支持 USB UVC 类驱动程序需要额外的配置，并且可将其配置为内置功能或独立的内核模块。

以下配置提供了一个支持典型 UVC 设备（如 UVC 摄像头）的示例。

UVC 摄像头所需的常见配置，在 SDK 中默认选中：

启用 Multimedia support：

Device Drivers  --->
    [*] Multimedia support

选择多媒体选项：

Device Drivers  --->
    Multimedia support  --->
        [*] Cameras/video grabbers support
        [*] Media Controller API
        [*] V4L2 sub-device userspace API
        [*] Media USB Adapters

内置配置:

进入 Media USB Adapters 输入 Y 选择：

Device Drivers  --->
    Multimedia support  --->
        Media USB Adapters  --->
            [*] USB Video Class (UVC)

模块配置:

进入 Media USB Adapters 输入 M 选择：

Device Drivers  --->
    Multimedia support  --->
        Media USB Adapters  --->
            [M] USB Video Class (UVC)

在加载常见的 USB 主机模块后，加载 UVC 类的内核模块。

insmod /lib/modules/<kernel_ver>/kernel/drivers/media/mc/mc.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/media/v4l2-core/videodev.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/media/usb/uvc/uvcvideo.ko

应用 APIs

它将 UVC 设备视为 V4L2 设备。请参阅 linux video 以获取有关 V4L2 API 的更多信息。

使用示例

以下步骤演示使用典型 UVC 摄像头测试 USB 主机 UVC 驱动程序。

前置条件：

SD 卡已插入并挂载（测试将捕获的图像保存到 SD 卡）。
UVC 摄像头已通过 USB 线缆连接到开发板。

连接 UVC 摄像头后，控制台将打印以下日志：

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 2 using dwc2
dwc2 40080000.usb: Set speed to high-speed
uvcvideo: Found UVC 1.00 device USB Camera (0bda:5842)
input: USB Camera: USB Camera as /devices/platform/ocp/40080000.usb/usb1/1-1/1-1:1.0/input/input1

出现 uvcvideo: Found UVC ... 表示枚举成功。

确认视频设备节点：
```
ls /dev/video0
```
运行 UVC 主机测试程序以捕获图像：
```
rtk_usbh_uvc_test /dev/video0
```
测试以 1024x768 MJPEG 格式捕获图像并保存到已挂载的 SD 卡。
验证 SD 卡上的捕获图像：
```
ls /mnt/sd/
```
存在捕获的图像文件即确认 UVC 主机驱动工作正常。

备注

rtk_usbh_uvc_test 二进制文件包含在 packagegroup-rtk-test 包中，该包在 rtk-fwk-full 发行版中可用。对于自定义固件，需在 IMAGE_INSTALL 中添加 rtk-app-usbh-uvc-test。该测试的源代码位于 <sdk>/tests/usbh_uvc。

人机交互主机方案

在 USB 主机模式下，SoC 可以枚举并与 USB HID 设备（如鼠标和键盘）进行交互。

配置

在基础的 USB 配置外，还需要额外的配置来支持 USB HID 类驱动程序，可将其配置为内置功能或独立的内核模块。

以下配置提供了支持典型 HID 设备（如 USB 鼠标或键盘）的示例。

根据需要调整配置。

内置配置:

进入 HID support 菜单，输入 Y 选择：

Device Drivers  --->
    HID support  --->
        [*] USB HID support

模块配置:

进入 HID support 菜单，输入 M 选择：

Device Drivers  --->
    HID support  --->
        [M] USB HID support

在加载通用 USB 主机模块后，加载 HID 类的内核模块。

insmod /lib/modules/<kernel_ver>/kernel/drivers/hid/usbhid/usbhid.ko

应用 APIs

HID 设备被暴露为 Linux 输入设备。有关输入 API 的更多信息，请参阅 Linux 输入子系统。对于原始 HID 访问，/sys/class/hidraw/ 接口也可用。

使用示例

以下步骤演示使用 USB 鼠标或键盘测试 USB 主机 HID 驱动程序。

前置条件：

准备一个 USB 鼠标或键盘。

将 USB 鼠标或键盘连接到 SoC，控制台上将打印以下日志：

dwc2 40080000.usb: Set speed to full-speed
usb 1-1: new full-speed USB device number 2 using dwc2
hid-generic 0003:0BDA:5842.0001: hiddev0,hidraw0: USB HID v1.11 Device [USB Camera: USB Camera] on usb-40080000.usb-1/input0

出现 hid-generic ... 或 usbhid: USB HID v1.11 Device ... 表示枚举成功。

确认输入设备节点：

ls /dev/input/event*
ls /sys/class/hidraw/

测试 HID 设备：
- 鼠标：移动鼠标，通过 evtest /dev/input/eventX 观察 HID 事件（将 X 替换为实际的事件编号）。
- 键盘：按下按键，通过 evtest /dev/input/eventX 观察 HID 事件。
```
evtest /dev/input/event1
```
备注

evtest 由 kmodtool 或 util-linux 包提供。确保将其包含在 Yocto 固件中。
测试通过的条件：HID 设备被识别（dmesg 显示枚举成功）、/dev/input/event* 节点已创建、输入事件可正确捕获。

音频主机方案

在基础的 USB 配置之上，SoC 可以枚举并与 USB 音频设备（UAC 1.0/2.0）进行交互，通过连接的 USB 音频接口实现音频播放和录音。

Linux 内核的 snd-usb-audio 驱动负责完整的 UAC 协议栈处理，包括设备枚举、音频描述符解析、ALSA 声卡注册和等时数据传输。USB 音频设备被抽象为标准 ALSA 声卡，应用程序可通过通用的 ALSA API 进行音频操作。

配置

以下配置提供了支持典型 USB 音频设备的示例。

根据需要调整配置。

内置配置:

进入 Sound card support 菜单，输入 Y 选择：

Device Drivers  --->
    Sound card support  --->
        USB sound devices  --->
            [*] USB Audio/MIDI drivers

模块配置:

进入 Sound card support 菜单，输入 M 选择：

Device Drivers  --->
    Sound card support  --->
        USB sound devices  --->
            [M] USB Audio/MIDI drivers

在加载通用 USB 主机模块后，加载 USB 音频类的内核模块。

insmod /lib/modules/<kernel_ver>/kernel/sound/core/snd-hwdep.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/core/snd-rawmidi.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/usb/snd-usbmidi-lib.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/usb/snd-usb-audio.ko

应用 APIs

USB 音频设备被暴露为 ALSA 声卡。以下标准 ALSA 工具可用：

``arecord``：从录音设备采集音频。
``aplay``：向回放设备播放音频。
``amixer``：控制混音器设置（音量、静音）。
``alsamixer``：交互式混音器控制（终端界面）。

更多详情请参考 Linux ALSA 文档。

使用示例

以下步骤演示使用 USB 音频设备测试 USB 主机 UAC 驱动程序。

前置条件：

准备一个 USB 音频设备（如 USB 声卡、USB 麦克风或 USB 耳机）。

将 USB 音频设备连接到 SoC，控制台上将打印以下日志：

dwc2 40080000.usb: Set speed to full-speed
usb 1-1: new full-speed USB device number 2 using dwc2
usbcore: registered new interface driver snd-usb-audio

出现 snd-usb-audio 表示驱动绑定成功。

确认 ALSA 声卡：
```
cat /proc/asound/cards
aplay -l
arecord -l
```
预期输出中，USB 音频设备会作为额外的声卡显示（如 card 1）。

备注

板载音频编解码器通常占用 card 0。USB 音频设备会被分配下一个可用的声卡编号。
测试音频录音：
```
arecord -D plughw:CARD=1,DEV=0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/usb_audio_test.wav
```
参数说明：
- -D plughw:CARD=1,DEV=0：使用 ALSA 插件设备，Card 1（USB 音频设备）、Device 0。plughw 自动做格式转换，比 hw 兼容性好。
- -f S16_LE：采样格式，16-bit 有符号小端。
- -r 48000：采样率 48000 Hz（UAC 标准采样率）。
- -c 2：通道数 2（立体声）。
- -d 5：录制时长 5 秒。
录音完成后，验证文件大小：
```
ls -lh /tmp/usb_audio_test.wav
```
5 秒立体声 48 kHz 16-bit WAV 文件大小应约为 960 KB（不含 WAV 头部）。
测试音频回放（播放刚录制的文件）：
```
aplay -D plughw:CARD=1,DEV=0 /tmp/usb_audio_test.wav
```
参数说明：
- -D plughw:CARD=1,DEV=0：使用 ALSA 插件设备，Card 1（USB 音频设备）、Device 0。
- /tmp/usb_audio_test.wav：待播放的 WAV 文件路径。
确认设备上有声音输出。如果 aplay 报 underrun 错误，可将 plughw 改为 hw 重试，或检查 amixer -c 1 contents 确认音量设置。
音量和静音控制：
```
amixer -c 1 contents
amixer -c 1 cset name=PCM Playback Volume 80
amixer -c 1 cset name=PCM Playback Switch off
amixer -c 1 cset name=PCM Playback Switch on
```
参数说明：
- amixer -c 1 contents：列出 card 1 的所有混音器控制项。
- amixer -c 1 cset name=PCM Playback Volume 80：设置回放音量为 80，音量范围通常为 0-100。
- amixer -c 1 cset name=PCM Playback Switch off：将回放开关置为 off（静音）。
- amixer -c 1 cset name=PCM Playback Switch on：将回放开关置为 on（取消静音）。
备注

混音器控制项名称因 USB 音频设备而异。使用 amixer -c 1 contents 查看设备的精确控制项名称。
测试通过的条件：USB 音频设备被识别、arecord 录音成功（文件大小非零）、aplay 回放有声音输出。

自定义主机方案

Vendor 类支持开发自定义的 USB 主机类。

配置

在基础的 USB 配置外，还需要额外的配置来支持 USB Vendor 类驱动程序，可将其配置为内置功能或独立的内核模块。

内置配置:

进入 USB support 菜单，输入 Y 选择：

Device Drivers  --->
    USB support  --->
        [*] USB testing driver

模块配置:

进入 USB support 菜单，输入 M 选择：

Device Drivers  --->
    USB support  --->
        [M] USB testing driver

在加载常见的 USB 主机模块后，加载 Vendor 类的内核模块。
```
insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/misc/usbtest.ko
```

应用 APIs

无。

使用示例

本示例演示使用 USB vendor 驱动测试自定义 USB 设备。

前置条件：

准备一个 USB vendor 设备连接到开发板。

编译测试程序：

SDK 提供 <sdk>/tests/usbh_vendor/ 下的测试源码 testusb.c。在 SDK 根目录下编译：

cd <sdk>/tests/usbh_vendor
make

编译产物为 rtk_usbh_vendor_test。

运行测试：

Loopback 测试（case 30）：

rtk_usbh_vendor_test -a -c1 -t30 -s256 -g32 -v1

Sourcesink 测试（其他 case）：

testusb -a

参数说明：

-t30：选择 Loopback 测试用例。
-s256：传输数据块大小 256 字节。
-g32：循环次数 32。
-v1：输出详细信息。
-a：自动枚举设备。

复合主机方案

Linux USB 主机枚举复合 USB 设备时，自动为每个接口绑定对应的 class driver，无需专用的复合主机驱动。

配置

复合主机方案复用各功能类的内核配置，无需额外选项。以 HID + USB 音频组合为例，需同时启用以下两个功能类（参考各自的配置章节）：

内置配置:

Device Drivers  --->
    HID support  --->
        USB HID support  --->
            [*] USB HID transport layer
    Sound card support  --->
        USB sound devices  --->
            [*] USB Audio/MIDI drivers

模块配置:

配置以下选项：

Device Drivers  --->
    HID support  --->
        USB HID support  --->
            [M] USB HID transport layer
    Sound card support  --->
        USB sound devices  --->
            [M] USB Audio/MIDI drivers

在加载通用 USB 主机模块后，加载各功能类的内核模块：

insmod /lib/modules/$(uname -r)/kernel/drivers/hid/usbhid/usbhid.ko
insmod /lib/modules/$(uname -r)/kernel/sound/core/snd-hwdep.ko
insmod /lib/modules/$(uname -r)/kernel/sound/core/snd-rawmidi.ko
insmod /lib/modules/$(uname -r)/kernel/sound/usb/snd-usbmidi-lib.ko
insmod /lib/modules/$(uname -r)/kernel/sound/usb/snd-usb-audio.ko

应用 APIs

无。

使用示例

Linux USB 主机可自动处理复合 USB 设备——枚举时为每个接口分别绑定对应的 class driver，无需额外配置。本示例以带媒体控制键的 USB 耳机（HID + UAC 复合设备）为例。

将复合 USB 设备（如 USB 耳机）连接到 SoC，控制台将打印各接口的枚举日志：

usb 1-1: new full-speed USB device number 2 using dwc2
hid-generic 0003:xxxx:xxxx.0001: hiddev0,hidraw0: USB HID v1.11 Device on usb-40080000.usb-1/input3
usbcore: registered new interface driver snd-usb-audio

两个 class driver 各自独立绑定，互不干扰。

确认 HID 接口：
```
ls /dev/input/event*
```
确认 UAC 音频接口：
```
cat /proc/asound/cards
aplay -l
arecord -l
```
USB 音频设备会显示为独立的声卡（如 card 1）。
测试 HID 功能（以媒体键为例）：
```
evtest /dev/input/event1
```
按下设备上的音量键，应可观察到对应的 HID 输入事件。

测试 UAC 音频功能：

arecord -D plughw:CARD=1,DEV=0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/test.wav
aplay -D plughw:CARD=1,DEV=0 /tmp/test.wav

测试通过的条件：复合 USB 设备枚举成功，HID 接口（/dev/input/event*）和 UAC 音频接口（ALSA 声卡）同时可用，各自功能独立正常。