USB 概述

简介

支持的芯片[ RTL8721Dx ][ RTL8721F ]

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

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

备注

由于 zephyr 官方 USB 协议栈当前未完善，仅支持设备模式，因此我们选择不使用官方源码，而是提供功能更强大的 Realtek USB 协议栈。本章节简要介绍 Realtek USB 协议栈，以及如何编译和运行应用示例。

特性

兼容 USB2.0 高速（High-speed 480 Mbps）和全速（Full-speed 12 Mbps）模式
支持以下 USB 主机解决方案：
- CDC ACM：实现数据双向透传功能，适用于串口通信、数据采集等应用场景
- UAC：支持音频播放功能，可连接 USB 音频设备进行音频输出
- HID + UAC 复合主机：同时支持人机交互与音频播放，实现按键线控与音频播放的一体化控制
- Vendor：突破标准主机类限制的定制化解决方案，满足特殊应用场景的个性化需求
支持以下 USB 设备解决方案：
- CDC ACM：支持数据双向透传，可作为虚拟串口使用
- HID：模拟 USB 键盘、鼠标等标准 HID 外设，实现丰富的人机交互功能
- MSC：作为 USB 存储设备，实现数据存储与读写功能
- UAC：作为 USB 音频设备，支持音频播放功能
- CDC ACM + HID 复合设备：同时支持透传通信与交互控制
- CDC ACM + MSC 复合设备：同时支持透传通信与数据存储
- CDC ACM + UAC 复合设备：同时支持透传通信与音频播放
- HID + UAC 复合设备：同时支持交互控制与音频播放
- Vendor：突破标准设备类限制的定制化方案，满足特殊应用场景的个性化需求
设备模式下支持描述符全定制
- VID 和 PID
- 字符串描述符
- 端点映射
主机模式下支持灵活匹配设备
- 指定设备匹配策略（如匹配 VID/PID，或匹配特定类协议等）
- 自动解析描述符
- 自适应速度模式
核心驱动参数可配置
- 速度模式
- DFIFO 深度（仅适用于专用 FIFO 模式）
- 核心 ISR/线程的优先级

硬件配置

支持设备模式
支持 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。

软件协议栈概述

协议栈架构

各软件模块的功能如下:

USB 硬件抽象层： 实现电源管理、PHY 参数校准等 SoC 相关的硬件驱动，为上层 USB 核心驱动提供统一的硬件抽象层接口
USB 设备核心驱动： 包含 USB IP 相关的硬件驱动、设备控制器驱动、总线枚举和传输调度等核心控制逻辑，为上层 USB 设备类驱动提供统一的核心驱动接口
USB 设备类驱动： 兼容 USB2.0 规范的设备类驱动，基于类驱动 API，开发者可快速实现基于标准类的 USB 解决方案
USB 设备解决方案示例： 为开发者提供 USB 设备解决方案的设计参考

Zephyr USB API 和 FreeRTOS USB API 一致，详见 USB API

文件目录结构

SDK/modules/hal/realtek
├── ameba/common/usb/source
│   ├── common
│   │   ├── usb_cdc_acm.h
│   │   ├── usb_ch9.h
│   │   ├── usb_msc.h
│   │   ├── usb_os.h
│   │   ├── usb_ringbuf.h
│   │   ├── usb_scsi.h
│   │   ├── usb_uac1.h
│   │   └── usb_uac2.h
│   │
│   └── device
│       ├── cdc_acm
│       ├── composite
│       ├── hid
│       ├── inic_dplus
│       ├── msc
│       ├── uac
│       ├── vendor
│       └── core
│           └── usbd.h
│
└── zephyr/blobs/amebadplus/lib
    └── lib_usbd.a

SDK/modules/hal/realtek
├── ameba/common/usb/source
│   ├── common
│   │   ├── usb_cdc_acm.h
│   │   ├── usb_ch9.h
│   │   ├── usb_msc.h
│   │   ├── usb_os.h
│   │   ├── usb_ringbuf.h
│   │   ├── usb_scsi.h
│   │   ├── usb_uac1.h
│   │   └── usb_uac2.h
│   │
│   ├── device
│   │   ├── cdc_acm
│   │   ├── composite
│   │   ├── hid
│   │   ├── inic
│   │   ├── msc
│   │   ├── uac
│   │   ├── vendor
│   │   └── core
│   │      └── usbd.h
│   │
│   └── host
│       ├── cdc_acm
│       ├── composite
│       ├── uac
│       ├── vendor
│       └── core
│           └── usbh.h
│
└── zephyr/blobs/amebaG2/lib
    ├── lib_usbh.a
    └── lib_usbd.a

配置和编译

USB DTS 和 Binding：

USB 设备 DTS 定义文件: {sdk}/zephyr/dts/arm/realtek/amebadplus/amebadplus.dtsi
USB 设备 binding 定义文件: {sdk}/zephyr/dts/bindings/usb/realtek,ameba-usb.yaml
在 overlay 或 board 级 dts 中使能 USB 节点：

&usb {
   status = "okay";
};

USB menuconfig：

在路径 {sdk} 下，执行以下命令

west build -t menuconfig 或者 ./nuwa.py config

进入 Modules 下的 hal_realtek，然后选择需要使能的 USB 类驱动:

[*] RealTek Ameba Zephyr USB stack
   Select USB Mode (Device)  --->
   [ ]  CDC ACM device
   [ ]  HID device
   [ ]  MSC device
   [ ]  Composite device
   [ ]  Vendor device

保存并退出。

编译命令：

在路径 {sdk} 下，执行以下命令：

./nuwa.py build -a applications/usb/xxx -d rtl872xda_evb -p

详细参考： Zephyr SDK 编译和烧录

USB DTS 和 Binding：

USB 设备 DTS 定义文件: {sdk}/zephyr/dts/arm/realtek/amebaG2/amebaG2.dtsi
USB 设备 binding 定义文件: {sdk}/zephyr/dts/bindings/usb/realtek,ameba-usb.yaml
在 overlay 或 board 级 dts 中使能 USB 节点：

&usb {
   status = "okay";
};

USB menuconfig：

在路径 {sdk} 下，执行以下命令：

west build -t menuconfig 或者 ./nuwa.py config

进入 Modules 下的 hal_realtek，然后选择需要使能的 USB 类驱动:

[*] RealTek Ameba Zephyr USB stack
   Select USB Mode (Device)  --->
   [ ]  CDC ACM device
   [ ]  HID device
   [ ]  MSC device
   [ ]  Composite device
   [ ]  Vendor device

保存并退出。

编译命令：

在路径 {sdk} 下，执行以下命令：

./nuwa.py build -a applications/usb/xxx -d rtl8721f_evb -p

详细参考： Zephyr SDK 编译和烧录

USB 认证

请参考 FreeRTOS USB 编程指南中关于 USB 认证的介绍： USB 认证