USB 概述

简介

支持的芯片[ RTL8721Dx ][ RTL8730E ][ RTL8721F ][RTL8735C]

USB（Universal Serial Bus）是一种通用的串行总线接口，用于连接主机和外部设备。

USB 技术规范可以从网站 http://www.usb.org/developers 获取。

特性

  • 兼容性：兼容 USB2.0 高速（High-speed 480 Mbps）和全速（Full-speed 12 Mbps）模式

  • 支持以下 USB 主机解决方案：

    • CDC ACM：支持数据双向透传，适用于串口通信、数据采集及自定义通信协议等应用

    • CDC ECM：可挂载以太网模组作为网络接口（NIC），或作为桥接器实现模组与路由器的网络通信

    • MSC：支持大容量存储设备（如 U 盘、读卡器），适用于智能音箱、数据记录及 OTA 固件升级等应用

    • UAC：支持 Type-C 耳机等数字音频设备，提供音频输出与音量控制功能

    • UVC：支持 USB 摄像头，支持 MJPEG、H264、YUV 格式图像截取和视频流转发，适用于智能门锁、安防监控及图像采集等应用

    • 支持多种类型的复合主机：

      • CDC ACM + CDC ECM：支持 4G 蜂窝模组，适用于物联网网关及移动热点等应用

      • HID + UAC：同时支持人机交互与音频录放，实现按键线控与音频录放的一体化控制

    • Vendor (自定义类)：支持非标准主机类的定制化开发，满足特殊应用场景的个性化需求

  • 支持以下 USB 设备解决方案：

    • CDC ACM：支持数据双向透传，适用于串口通信、数据采集及自定义通信协议等应用

    • HID：模拟键盘、鼠标等 HID 外设，实现丰富的人机交互控制

    • MSC：支持 SD 卡、Flash 作为存储媒介, 实现数据存储功能

    • UAC：作为 USB 音频设备端，接收并处理音频流

    • 支持多种类型的复合设备 (Composite Device)：

      • CDC ACM + HID：同时支持透传通信与交互控制

      • CDC ACM + MSC：同时支持透传通信与数据存储

      • CDC ACM + UAC：同时支持透传通信与音频播放

      • HID + UAC：同时支持交互控制与音频录放

    • Vendor：支持非标准设备类的定制化开发，满足特殊应用场景的个性化需求

  • 高级特性：

    • 双角色切换（DRD）：支持 USB 主机和设备双角色动态切换

    • 设备模式高度可定制：支持描述符全定制，包括 VID/PID、字符串描述符及端点映射

    • 主机模式灵活枚举：支持自定义设备匹配策略（如基于 VID/PID 或 Class/Protocol 匹配）、描述符自动解析及自适应速度协商

    • 核心驱动参数可配置：允许开发者灵活配置速度模式、数据缓存 (DFIFO) 深度（仅限专用 FIFO 模式），以及 USB ISR 与核心线程的调度优先级

备注

RTL8721Dx 仅支持全速设备模式

硬件配置

RTL8721Dx:

  • 支持设备模式

  • 支持 USB 2.0 全速（12 Mbps）模式

  • 支持 DMA 传输模式

  • 设备模式下的端点配置如下：

    • EP0：INOUT，仅用于控制传输

    • EP1：IN

    • EP2：OUT

    • EP3：IN

    • EP4：OUT

    • EP5：INOUT

备注

其中，最多仅支持一个周期性 IN 端点。

  • 共享缓存模式，缓存深度（单位 DWORD）配置如下：

    • 总缓存：最大 768

    • 共享接收缓存：最大 472

    • 共享非周期性发送缓存：最大 32

    • 专用周期性发送缓存：最大 256

备注

DMA 模式下，缓存需要为 DMA 寄存器预留 8 个 DWORD。

软件协议栈概述

软件架构

协议栈架构如图所示：

RTL8721Dx:
../../_images/usb_freertos_device_only_arch_zh.svg

各软件模块的功能如下:

  • USB 硬件抽象层: 实现电源管理、PHY 参数校准等 SoC 相关的硬件驱动，为上层 USB 核心驱动提供统一的硬件抽象层接口

  • USB 主机/设备核心驱动：包含 USB IP 相关的硬件驱动、主机/设备控制器驱动、总线枚举和传输调度等核心控制逻辑，为上层 USB 主机/设备类驱动提供统一的核心驱动接口

  • USB 主机/设备类驱动: 兼容 USB2.0 规范的主机/设备类驱动，基于类驱动 API，开发者可快速实现基于标准类的 USB 解决方案

  • USB 主机/设备解决方案示例: 为开发者提供 USB 主机/设备解决方案的设计参考

USB 硬件抽象层驱动

硬件抽象层驱动提供了 SoC 相关的 USB 电源管理、中断处理和 PHY 校准接口，并定义了上层 USB 核心驱动所需的系统常量。

../../_images/usb_hal_api_zh.svg

备注

  • 硬件抽象层默认编入 USB 主机/设备/DRD 核心库文件，不允许开发者修改

  • USB PHY 校准数据在 SoC 出厂前确定，原则上不需要开发者修改，如遇疑似校准导致的兼容性问题（如枚举失败、反复断线重连），请联系 Realtek FAE

USB 设备核心驱动

../../_images/usb_device_api_zh.svg

USB 主机核心驱动

../../_images/usb_host_api_zh.svg

文件目录结构

USB 路径别名

为简化描述，下文使用如下路径别名。

别名

指代路径

SDK_USB_HAL

{SDK}/component/soc/amebaxxx/fwlib/include

SDK_USB

{SDK}/component/usb

SDK_USB_DEV

{SDK}/component/usb/device

SDK_USB_HOST

{SDK}/component/usb/host

SDK_USB_EXAMPLE

{SDK}/example/usb

SDK_USB_LIB

{SDK}/component/soc/amebaxxx/project/project_xxx/lib/application

USB 硬件抽象层

路径

说明

{SDK_USB_HAL}/ameba_usb.h

USB硬件抽象层API定义头文件

USB 核心驱动

RTL8721Dx:

路径

说明

{SDK_USB}/common/

USB通用核心驱动API定义头文件

{SDK_USB_DEV}/core/usbd.h

USB设备核心驱动API定义头文件

{SDK_USB_LIB}/lib_usbd.a

USB设备核心驱动库文件，用于设备类驱动和应用开发

USB 类驱动

路径

说明

{SDK_USB_DEV}/cdc_acm/

CDC ACM设备类驱动

{SDK_USB_DEV}/composite/

复合功能设备类驱动

{SDK_USB_DEV}/hid/

HID设备类驱动

{SDK_USB_DEV}/inic/

INIC设备类驱动（非标）

{SDK_USB_DEV}/msc/

MSC设备类驱动

{SDK_USB_DEV}/uac/

UAC设备类驱动

{SDK_USB_HOST}/cdc_acm/

CDC ACM主机类驱动

{SDK_USB_HOST}/cdc_ecm/

CDC ECM主机类驱动

{SDK_USB_HOST}/msc/

MSC主机类驱动

{SDK_USB_HOST}/uvc/

UVC主机类驱动

USB 解决方案示例

路径

说明

{SDK_USB_EXAMPLE}/usbd_cdc_acm/

基于CDC ACM的透传设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_cdc_acm_hid/

基于CDC ACM和HID的复合功能设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_cdc_acm_uac/

基于CDC ACM和UAC的复合功能设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_uac_hid/

基于HID和UAC的复合功能设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_hid/

HID设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_inic/

INIC设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_msc/

基于MSC的存储设备解决方案示例

{SDK_USB_EXAMPLE}/usbd_uac/

基于UAC的音频设备解决方案示例

{SDK_USB_EXAMPLE}/usbh_cdc_acm/

基于CDC ACM的透传主机解决方案示例

{SDK_USB_EXAMPLE}/usbh_cdc_ecm/

基于CDC ECM的网络通信主机解决方案示例

{SDK_USB_EXAMPLE}/usbh_msc/

基于MSC的存储主机解决方案示例

{SDK_USB_EXAMPLE}/usbh_uvc/

基于UVC的多媒体主机解决方案示例

{SDK_USB_EXAMPLE}/usbh_wifi_bridge/

基于CDC ECM的网络通信bridge解决方案示例

{SDK_USB_EXAMPLE}/usb_drd/

基于MSC主机和MSC设备的DRD解决方案示例

Host 解决方案，参考 Host 解决方案

Device 解决方案，参考 Device 解决方案

USB 认证

USB 认证一般指 USB-IF 认证，即通过 USB-IF 官方的电气、协议和功能测试，确保设备符合 USB 规范， 以保障设备间的互操作性、安全性和可靠性，认证通过后即可合法使用 USB 标志（如 USB Logo）。

USB-IF 认证非强制性过程，但以下情况必须对 USB 产品进行认证：

  • 产品需要使用 USB 标志

  • 产品宣传资料中宣称符合 USB 规范或提及 USB 认证

关于 USB-IF 认证的具体流程和要求，请查阅 https://www.usb.org 相关文档或联系 USB-IF 授权测试实验室。

与 USB 设备相关的其它认证还有：

  • 在欧美市场销售 USB 设备需要通过 FCC、CE 等认证，否则可能面临法律风险

  • 车载 USB 设备需要通过 ISO 26262 车载电子系统的功能安全认证

  • 为确保 USB 设备与 Windows 系统兼容，或需要在产品包装和宣传材料中使用“Certified for Windows”徽标，需要通过 Windows 徽标认证

  • 苹果专用 USB 设备需要通过 MFi 认证

电气一致性测试

概述

USB 电气一致性测试（USB Electrical Compliance Test）是 USB-IF 定义的认证测试标准（Compliance Test Suite，CTS），用于验证 USB 设备、主机或集线器的电气特性是否符合规范要求。 眼图测试 是其中的一项核心测试项目，旨在评估物理层信号质量，包括信号抖动、眼图张开度、上升/下降时间、电压电平及 SE0 等关键指标。

重要

本文档仅介绍眼图测试流程，包括测试固件编译方法和操作指令。完整 CTS 认证测试（含协议测试、电气测试等全部项目）需参考 USB-IF 官方规范及测试方案。

官方测试规范请参考：https://www.usb.org/usb2

使用范围

本测试方案适用于 Ameba 系列全平台（包括 Linux、RTOS、Zephyr 等）。验证产品是否满足 USB 眼图测试要求，可使用以下测试固件与指令集。

编译测试固件

用户可通过 SDK 自行编译 USB 眼图测试固件。请根据测试模式选择以下编译步骤：

Device:

可使用项目自身的代码，或 SDK 中的 example，来编译眼图测试固件。此处以 CDC ACM 为例：

  1. 修改源码，关闭 hotplug 功能：

    打开 example/usb/usbd_cdc_acm/example_usbd_cdc_acm.c，确认 CONFIG_USBD_CDC_ACM_HOTPLUG 定义为 0 （眼图测试需关闭 hotplug，避免中断影响测试）：

    #define CONFIG_USBD_CDC_ACM_HOTPLUG               0

  2. 编译 CDC ACM example：

    ameba.py build -a usbd_cdc_acm -p

    编译环境配置请参考 SDK 使用指南 。

  3. 编译完成后，将生成的固件烧录至目标设备。烧录方法请参考 Flash 烧写指南 。

  4. 在测试对端准备一台支持 CDC ACM 的主机（如 Windows 11），作为测试设备。

  5. 重启开发板后，即可开始眼图测试。

测试指令

烧录测试固件后，通过串口终端向开发板发送以下测试命令。根据测试模式（Device / Host）选择对应的指令表：

Device:

类型

命令

描述

RESET

AT+RST

重启测试板

所有测试用例执行前的必要步骤，清除残留状态，确保系统处于确定的初始环境。

技术支持

如在测试过程中遇到问题，请联系 技术支持 获取专业协助。