IC:

支持的芯片

Ameba SoC	RTL8721Dx	RTL8720E	RTL8726E	RTL8713E	RTL8730E	RTL8721F
支持状态	Y	N	N	N	Y	Y

USB 概述

USB（Universal Serial Bus）是一种通用的串行总线接口，用于连接主机和外部设备，其主要特点如下：

即插即用：无需重启系统即可连接和断开设备。
统一标准：定义了统一的电气接口和协议，使设备间能够兼容互通。
多功能支持：支持多种类型的设备。
供电能力：可为设备供电，无需额外的电源适配器。

USB IF（USB Implementers Forum）负责制定 USB 技术规范，提供兼容性测试工具，并提供 USB 设备认证服务。

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

硬件配置

支持设备模式
支持 USB 2.0 全速（12 Mbps）模式
支持 DMA 和 slave 模式
设备模式下的端点配置如下：
- EP0：INOUT，仅用于控制传输
- EP1：IN
- EP2：OUT
- EP3：IN
- EP4：OUT
- EP5：INOUT

备注

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

共享缓存模式，缓存深度（单位 DWORD）配置如下：
- 总缓存：最大 768
- 共享接收缓存：最大 472
- 共享非周期性发送缓存：最大 32
- 专用周期性发送缓存：最大 256

备注

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

软件协议栈概述

软件特性

兼容 USB2.0 全速设备模式
支持 DMA 和 slave 模式
模块化分层设计，上下层之间通过异步回调式 API 通信，有效降低 MCU 负载
支持 CDC ACM、HID、UAC 等 USB IF 标准设备类驱动
提供透传、HID、音频、复合功能设备等设备解决方案示例
支持设备描述符全定制
设备核心驱动参数可配置

软件架构

协议栈架构如图所示：

../../rst_rtos/7_usb/figures/usb_stack_architecture_device_cn.svg

各软件模块的功能如下:

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

文件目录结构

USB 硬件抽象层

路径	说明
`{SDK}/component/soc/amebaxxx/fwlib/include/ameba_usb.h`	USB硬件抽象层API定义头文件

USB 核心驱动

路径	说明
`{SDK}/component/component/usb/common/`	USB通用核心驱动API定义头文件
`{SDK}/component/component/usb/device/core/usbd.h`	USB设备核心驱动API定义头文件
`{SDK}/amebadplus_gcc_project/project_km4/asdk/lib/application/lib_usbd.a`	USB设备核心驱动库文件，用于设备类驱动和应用开发

路径	说明
`{SDK}/component/component/usb/common/`	USB通用核心驱动API定义头文件
`{SDK}/component/component/usb/device/core/usbd.h`	USB设备核心驱动API定义头文件
`{SDK}/component/component/usb/host/core/usbh.h`	USB主机核心驱动API定义头文件
`{SDK}/amebasmart_gcc_project/project_ap/asdk/lib/application/lib_usb.a`	USB综合核心驱动库文件，用于DRD类驱动和应用开发
`{SDK}/amebasmart_gcc_project/project_ap/asdk/lib/application/lib_usbd.a`	USB设备核心驱动库文件，用于设备类驱动和应用开发
`{SDK}/amebasmart_gcc_project/project_ap/asdk/lib/application/lib_usbh.a`	USB主机核心驱动库文件，用于主机类驱动和应用开发

路径	说明
`{SDK}/component/component/usb/common/`	USB通用核心驱动API定义头文件
`{SDK}/component/component/usb/device/core/usbd.h`	USB设备核心驱动API定义头文件
`{SDK}/component/component/usb/host/core/usbh.h`	USB主机核心驱动API定义头文件
`{SDK}/amebagreen2_gcc_project/project_km4tz/asdk/lib/application/lib_usb.a`	USB综合核心驱动库文件，用于DRD类驱动和应用开发
`{SDK}/amebagreen2_gcc_project/project_km4tz/asdk/lib/application/lib_usbd.a`	USB设备核心驱动库文件，用于设备类驱动和应用开发
`{SDK}/amebagreen2_gcc_project/project_km4tz/asdk/lib/application/lib_usbh.a`	USB主机核心驱动库文件，用于主机类驱动和应用开发

USB 类驱动

路径	说明
`{SDK}/component/component/usb/device/cdc_acm/`	CDC ACM设备类驱动
`{SDK}/component/component/usb/device/composite/`	复合功能设备类驱动
`{SDK}/component/component/usb/device/hid/`	HID设备类驱动
`{SDK}/component/component/usb/device/inic/`	INIC设备类驱动（非标）
`{SDK}/component/component/usb/device/msc/`	MSC设备类驱动
`{SDK}/component/component/usb/device/uac/`	UAC设备类驱动
`{SDK}/component/component/usb/host/cdc_acm/`	CDC ACM主机类驱动
`{SDK}/component/component/usb/host/cdc_ecm/`	CDC ECM主机类驱动
`{SDK}/component/component/usb/host/msc/`	MSC主机类驱动
`{SDK}/component/component/usb/host/uvc/`	UVC主机类驱动

USB 解决方案示例

路径	说明
`{SDK}/component/component/example/usb/usbh_cdc_acm/`	基于CDC ACM的透传主机解决方案示例
`{SDK}/component/component/example/usb/usbh_cdc_ecm/`	基于CDC ECM的网络通信主机解决方案示例
`{SDK}/component/component/example/usb/usbh_msc/`	基于MSC的存储主机解决方案示例
`{SDK}/component/component/example/usb/usbh_uvc/`	基于UVC的多媒体主机解决方案示例
`{SDK}/component/component/example/usb/usbh_wifi_bridge/`	基于CDC ECM的网络通信bridge解决方案示例
`{SDK}/component/component/example/usb/usbd_cdc_acm/`	基于CDC ACM的透传设备解决方案示例
`{SDK}/component/component/example/usb/usbd_cdc_acm_hid/`	基于CDC ACM和HID的复合功能设备解决方案示例
`{SDK}/component/component/example/usb/usbd_cdc_acm_uac/`	基于CDC ACM和UAC的复合功能设备解决方案示例
`{SDK}/component/component/example/usb/usbd_uac_hid/`	基于HID和UAC的复合功能设备解决方案示例
`{SDK}/component/component/example/usb/usbd_hid/`	HID设备解决方案示例
`{SDK}/component/component/example/usb/usbd_inic/`	INIC设备解决方案示例
`{SDK}/component/component/example/usb/usbd_msc/`	基于MSC的存储设备解决方案示例
`{SDK}/component/component/example/usb/usbd_uac/`	基于UAC的音频设备解决方案示例
`{SDK}/component/component/example/usb/usb_drd/`	基于MSC主机和MSC设备的DRD解决方案示例

配置和编译

配置 USB

在 {SDK}/amebaxxx_gcc_project 下执行命令 ./menuconfig.py , 在 CONFIG USB 下选择 Enable USB 使能 USB，然后选择需要使能的 USB 类驱动:

[*] Enable USB
        USB Mode (Device)  --->
[ ] CDC ACM
[ ] Composite
[ ] HID
[ ] MSC
[ ] UAC

保存并退出。

编译 USB

在 {SDK}/amebaxxx_gcc_project 下执行命令 ./build.py -a <example> 编译指定的 USB 应用示例。

备注

上述命令中 <example> 为 component/example/usb 下的 USB 应用示例文件夹名, 且需要在配置 USB 时使能 USB 应用示例对应的类驱动。

硬件抽象层驱动

概述

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

硬件抽象层 API

硬件抽象层驱动提供了类型为 usb_hal_driver_t 的回调函数集:

typedef struct {
   int(* init)(u8 mode);
   int(* deinit)(void);
   void(* enable_interrupt)(u8 priority);
   void(* disable_interrupt)(void);
   void(* register_irq_handler)(void *handler, u8 priority);
   void(* unregister_irq_handler)(void);
   usb_cal_data_t *(* get_cal_data)(u8 mode);
   void (*cg)(u32 ms);
} usb_hal_driver_t;

API	描述
init	SoC相关的硬件（电源、时钟、使能）初始化
deinit	SoC相关的硬件（电源、时钟、使能）去初始化
enable_interrupt	使能USB中断
disable_interrupt	失能USB中断
register_irq_handler	注册USB中断处理函数
unregister_irq_handler	注销USB中断处理函数
get_cal_data	获取SoC相关的USB PHY校准数据
cg	USB CG 功耗测试

另外，硬件抽象层驱动还提供了如下 USB 相关的宏定义：

宏定义	描述
USB_REG_BASE	USB寄存器基地址
USB_ADDON_REG_BASE	USB AddOn寄存器基地址
USB_MAX_ENDPOINTS	USB设备模式下支持的最大端点数量
USB_MAX_PIPES	USB主机模式下支持的最大通道数量
USB_VID	Realtek USB VID
USB_PID	Realtek USB PID

备注

硬件抽象层默认编入 USB 主机/设备/DRD 核心库文件，不允许开发者修改
USB PHY 校准数据在 SoC 出厂前确定，原则上不需要开发者修改，如遇疑似校准导致的兼容性问题（如枚举失败、反复断线重连），请联系 Realtek FAE

主机核心驱动

主机驱动软件架构

../../rst_rtos/7_usb/figures/usb_host_api_cn.svg

主机核心驱动层 API 定义头文件: {SDK}/component/usb/host/core/usbh.h

面向 Class 层的 API

API	描述
usbh_register_class	注册主机类驱动，主机类驱动类型为usbh_class_driver_t, 具体参考 Class层回调函数
usbh_unregister_class	注销主机类驱动
usbh_alloc_pipe	初始化通道
usbh_free_pipe	注销通道
usbh_open_pipe	打开通道
usbh_close_pipe	关闭通道
usbh_reactivate_pipe	重新激活指定通道中的传输请求
usbh_get_configuration	获取指定subclass对应的配置索引
usbh_set_configuration	设定配置索引
usbh_get_interface	获取指定class、subclass和protocol的interface索引
usbh_set_interface	设定当前的interface索引
usbh_get_interface_descriptor	获取指定interface索引和alternate setting对应的解析后的interface描述符
usbh_get_raw_configuration_descriptor	获取未解析的配置描述符
usbh_get_device_descriptor	获取解析后的设备描述符
usbh_get_interval	获取bInterval对应的物理值
usbh_set_toggle	设置指定通道的PID翻转
usbh_get_toggle	获取指定通道的当前PID翻转设置
usbh_get_ep_type	获取指定通道对应的设备端点类型
usbh_get_urb_state	获取指定通道当前URB状态
usbh_notify_class_state_change	向核心驱动层发送事件，指示类驱动层状态有变更
usbh_notify_urb_state_change	向核心驱动层发送事件，指示URB状态有变更
usbh_ctrl_set_interface	向设备发送SET_INTERFACE标准请求
usbh_ctrl_set_feature	向设备发送SET_FEATURE标准请求
usbh_ctrl_clear_feature	向设备发送CLEAR_FEATURE标准请求
usbh_ctrl_request	向设备发送自定义控制请求
usbh_bulk_receive_data	发起批量传输，从设备接收数据
usbh_bulk_send_data	发起批量传输，向设备发送数据
usbh_intr_receive_data	发起中断传输，从设备接收数据
usbh_intr_send_data	发起中断传输，向设备发送数据
usbh_isoc_receive_data	发起等时传输，从设备接收数据
usbh_isoc_send_data	发起等时传输，向设备发送数据
usbh_get_current_frame	获取当前的帧号
usbh_get_last_transfer_size	获取指定通道上一次传输的数据长度
usbh_enter_suspend	进入或退出suspend状态
usbh_port_test_ctrl	发送端口测试指令，用于CTS测试

Class 层回调函数

主机核心驱动层提供了类型 usbh_class_driver_t 用于定义主机类驱动:

typedef struct {
        u8 class_code;
        u8(*attach)(struct _usb_host_t *host);
        u8(*detach)(struct _usb_host_t *host);
        u8(*setup)(struct _usb_host_t *host);
        u8(*process)(struct _usb_host_t *host);
        u8(*sof)(struct _usb_host_t *host);
        u8(*nak)(struct _usb_host_t *host, u8 pipe_num);
} usbh_class_driver_t;

具体定义如下:

API	描述
class_code	USB IF定义的类代码
attach	在SET_CONFIGURATION请求成功执行后被调用
detach	在设备连接断开时被调用
setup	在attach回调执行成功后被调用，用于处理类驱动相关的控制请求
process	在setup回调执行成功后被消息驱动循环调用，用于处理类驱动相关的消息
sof	在SOF中断发生时被调用，一般用于class层处理与时序相关的事务
nak	在指定通道发生NAK中断时被调用

面向应用层的 API

API	描述
usbh_init	初始化USB主机核心驱动，配置信息通过类型为 `usbh_config_t` 的参数指定，具体参考 USB主机核心驱动配置参数
usbh_deinit	注销USB主机核心驱动
usbh_get_status	获取设备连接状态，0 - 断开，1 - 连接
usbh_reenumerate	重新枚举

USB 主机核心驱动配置参数

主机核心驱动层提供了类型 usbh_config_t 用于定义 USB 主机协议栈配置参数:

typedef struct {
        u32 ext_intr_en;
        u16 rx_fifo_depth;
        u16 nptx_fifo_depth;
        u16 ptx_fifo_depth;
        u8 main_task_priority;
        u8 isr_task_priority;
        u8 alt_max;
        u8 speed : 2;
        u8 dma_enable : 1;
        u8 sof_tick_en : 1;
} usbd_config_t;

具体定义如下:

参数	描述
ext_intr_en	使能可选的USB中断，设定值为0时不开任何可选中断，可根据应用设计需要，设定为以下宏定义值（支持按位组合）： USBH_SOF_INTR：SOF中断（GINTSTS.Sof），当Class层需要使能sof回调函数时开启，用于处理与时序相关的事务
rx_fifo_depth	USB主机共享接收缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC，具体参考硬件配置
nptx_fifo_depth	USB主机共享非周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC，具体参考硬件配置
ptx_fifo_depth	USB主机共享周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC，具体参考硬件配置
main_task_priority	USB主机核心驱动主消息处理任务的优先级
isr_task_priority	USB主机核心驱动中断处理任务的优先级
alt_max	Interface描述符中支持的最大的alternate setting数量
speed	USB主机速度，有效值： USB_SPEED_HIGH：高速模式，适用于支持高速USB的Ameba SoC USB_SPEED_HIGH_IN_FULL：全速模式，适用于支持高速USB的Ameba SoC，用于连接全速UAC等对带宽要求不高的设备 USB_SPEED_FULL：全速模式，适用于仅支持全速USB的Ameba SoC
dma_enable	使能DMA模式
sof_tick_en	设置USB主机核心驱动的计时方式，该计时用于根据设备端点描述符bInterval来触发周期性传输，以及传输超时检测： 0：利用系统时钟（如SysTick、DebugTimer，因SoC而异）计时，不需要响应额外的中断，CPU占用率较低，但与SOF 计数可能会有偏差。适用于要求低CPU占用率、或者对传输周期要求不苛刻的应用场景。 1：利用SOF中断计时，需要配合USBH_SOF_INTR可选中断使用，因为需要周期性响应SOF中断，CPU占用率较高，计时精度与SOF计数精度匹配

备注

配置的缓存总深度 rx_fifo_depth + nptx_fifo_depth + ptx_fifo_depth 不得超过硬件支持的最大总缓存深度，具体参考硬件配置。

设备核心驱动

设备驱动软件架构

../../rst_rtos/7_usb/figures/usb_device_api_cn.svg

设备核心驱动层 API 定义头文件: {SDK}/component/usb/device/core/usbd.h

面向类驱动层的 API

API	描述
usbd_register_class	注册设备类驱动，在设备类驱动初始化函数中调用, 类驱动定义参考类驱动层回调函数。
usbd_unregister_class	注销设备类驱动，在设备类驱动注销函数中调用。
usbd_ep_init	初始化端点，一般会在以下场景中被调用：设备类驱动set_config回调函数中设备类驱动setup回调函数中，收到SET_INTERFACE之类的需要重新初始化端点的特定请求时
usbd_ep_deinit	注销端点，一般会在以下场景中被调用：设备类驱动clear_config回调函数中设备类驱动setup回调函数中，收到SET_INTERFACE之类的需要注销端点的特定请求时
usbd_ep_transmit	通过指定端点向USB主机发送数据，即发起IN传输。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_in/ep0_data_in回调函数中获取传输执行状态。设备核心驱动会根据需要自动补发ZLP，类驱动层和应用层不需要处理。
usbd_ep_receive	准备从指定端点从USB主机接受数据，即发起OUT传输。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_out/ep0_data_out回调函数中获取传输完成的数据。
usbd_ep_set_stall	将指定端点状态设置为STALL，根据USB协议或者应用设计需求调用。
usbd_ep_clear_stall	清除指定端点的STALL状态，根据USB协议或者应用设计需求调用。
usbd_ep_is_stall	检查指定端点是否处于STALL状态。
usbd_get_str_desc	用于将ASCII编码的字符串转换为UNICODE 16编码的USB字符串描述符。注意目标字符串缓存的大小为源字符串大小的两倍再加两个字节，多出的两个字节为USB字符串描述符长度和描述符类型标识。

类驱动层回调函数

设备核心驱动层提供了类型 usbd_class_driver_t 用于定义设备类驱动:

typedef struct _usbd_class_driver_t {
   u16*(*get_descriptor)( usb_dev_t *dev, usb_setup_req_t *req, u8 *buf);
   u8(*set_config)(usb_dev_t *dev, u8 config);
   u8(*clear_config)(usb_dev_t *dev, u8 config);
   u8(*setup)(usb_dev_t *dev, usb_setup_req_t  *req);
   u8(*sof)(usb_dev_t *dev);
   u8(*suspend)(usb_dev_t *dev);
   u8(*resume)(usb_dev_t *dev);
   u8(*ep0_data_in)(usb_dev_t *dev, u8 status);
   u8(*ep0_data_out)(usb_dev_t *dev);
   u8(*ep_data_in)(usb_dev_t *dev, u8 ep_addr, u8 status);
   u8(*ep_data_out)(usb_dev_t *dev, u8 ep_addr, u16 len);
   void (*status_changed)(usb_dev_t *dev, u8 old_status, u8 status);
} usbd_class_driver_t;

具体定义如下:

API	是否必须	描述
get_descriptor	是	在设备核心驱动枚举阶段收到USB主机获取USB描述符请求时被调用，所有类型的描述符统一通过该回调函数获取。设备类驱动需要在该回调函数中，根据Setup请求wValue字段定义的描述符类型，返回对应的描述符数组指针和数组长度信息： USB_DESC_TYPE_DEVICE：设备描述符，必须支持 USB_DESC_TYPE_CONFIGURATION：配置描述符，必须支持 USB_DESC_TYPE_DEVICE_QUALIFIER：设备限定描述符，对于需要同时支持全速与高速的设备，必须支持 USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION：其它速率配置描述符，对于需要同时支持全速与高速的设备，必须支持 USB_DESC_TYPE_STRING：字符串描述符，具体又包含语言ID、厂商、产品、串号等字符串描述符，可选关于USB描述符的介绍，参考设备描述符定制。
set_config	是	当设备核心驱动在ADDRESSED状态下收到SET_CONFIGURATION控制请求时被调用。类驱动一般需要在该回调函数中初始化端点资源并为OUT传输做好准备：调用usbd_ep_init初始化当前配置对应的所有端点调用usbd_ep_receive准备好进行第一笔OUT传输
clear_config	是	在以下场景中会被调用：设备核心驱动在CONFIGURED状态下收到SET_CONFIGURATION控制请求切到新的配置或切到未配置状态时设备核心驱动在非ADDRESSED/CONFIGURED状态下收到SET_CONFIGURATION控制请求时设备核心驱动处理枚举完成（GINTSTS.EnumDone）中断时设备核心驱动处理会话完成（GOTGINT.SesEndDet）中断时在usbd_deinit被调用时类驱动一般需要在该回调函数中调用usbd_ep_deinit注销端点资源。
setup	是	在控制IN/OUT传输的Setup阶段完成时被调用，用于类驱动层处理与类驱动相关的控制请求：标准接口请求：USB_REQ_SET_INTERFACE、USB_REQ_GET_INTERFACE、USB_REQ_GET_STATUS 类相关请求：具体参考类规范中的相关定义自定义请求：对于用户自定义的非标准类设备，用户可以根据需要自定义控制请求
ep_data_in	否	在批量/中断/等时IN传输的Data阶段完成时被调用，用于指示IN传输的完成状态。类驱动可在该回调函数中调用应用层回调函数，允许发起新的IN传输或在IN传输失败时进行重传。
ep_data_out	否	在批量/中断/等时OUT传输的Data阶段完成时被调用，用于处理接收到的OUT数据，类驱动可在该回调函数中做如下处理：调用应用层回调函数，由应用层处理接收到的数据调用usbd_ep_receive准备好进行下一笔OUT传输
ep0_data_in	否	在控制IN传输的Data阶段完成时被调用，用于指示控制IN传输的完成状态，允许发起新的控制IN传输或在控制 IN传输失败时进行重传
ep0_data_out	否	在控制OUT传输的Data阶段完成时被调用，用于处理接收到的控制OUT数据。注意EP0的OUT传输使能在设备核心驱动层自动完成，类驱动层不需要处理。
sof	否	在SOF中断发生时被调用，一般用于处理与时序相关的事务，比如UAC应用可以通过该回调函数做与USB主机的时钟同步
suspend	否	在suspend中断发生时被调用, 用于类驱动层在suspend发生时做资源挂起处理
resume	否	在resume中断发生时被调用, 用于类驱动层在resume发生时做资源恢复处理
status_changed	是	在USB连接状态改变时被调用，类驱动层可通过该回调函数支持USB热插拔。例如可以调用应用层回调函数，让应用层在检测到与USB主机连接/通信断开时注销并重新初始化USB设备。具体参考设备连接状态检测

备注

上述所有设备类驱动回调函数均在中断上下文中被调用，不得在回调函数中执行耗时或阻塞操作。

面向应用层的 API

API	描述
usbd_init	初始化USB设备核心驱动，配置信息通过类型为 `usbd_config_t` 的参数指定，具体参考 USB设备核心驱动配置参数
usbd_deinit	注销USB设备
usbd_get_status	获取USB连接状态，返回值为 `usbd_attach_status_t` 定义的枚举值： USBD_ATTACH_STATUS_INIT = 0U, // 初始化 USBD_ATTACH_STATUS_ATTACHED = 1U, // 连接到USB主机 USBD_ATTACH_STATUS_DETACHED = 2U // 与USB主机断开连接或停止通信
usbd_get_bus_status	获取USB总线状态，当返回值为HAL_OK时，参数status返回有效的USB总线状态信息，取值范围为 `usbd_bus_state_t` 定义的枚举值的按位组合值： USBD_BUS_STATUS_DN = BIT0, // D-线上的逻辑电平 USBD_BUS_STATUS_DP = BIT1, // D+线上的逻辑电平 USBD_BUS_STATUS_SUSPEND = BIT2, // Suspend状态指示
usbd_wake_host	向USB主机发送remote wakeup信号，唤醒USB主机

USB 设备核心驱动配置参数

设备核心驱动层提供了类型 usbd_config_t 用于定义 USB 设备核心驱动配置参数:

typedef struct {
   u32 nptx_max_epmis_cnt;
   u32 ext_intr_en;
   u16 rx_fifo_depth;
   u16 ptx_fifo_depth[USB_MAX_ENDPOINTS - 1];
   u8 speed;
   u8 isr_priority;
   u8 isr_in_critical : 1;
   u8 dma_enable : 1;
   u8 intr_use_ptx_fifo : 1;
} usbd_config_t;

具体定义如下:

参数	描述
nptx_max_epmis_cnt	非周期性IN传输产生EPMis中断的EPMis次数阈值，仅适用于配置了共享缓存的Ameba SoC
ext_intr_en	使能可选的USB中断 USBD_SOF_INTR：SOF中断，一般用于需要通过SOF与USB主机端进行时钟同步的应用场景 USBD_EOPF_INTR：用于等时传输时设定下一帧的奇偶性，仅用于slave模式 USBD_EPMIS_INTR：用于在使能了多个非周期IN端点的应用场景下，发生EPMis中断后重启IN传输，仅适用于配置了共享缓存的Ameba SoC
rx_fifo_depth	接收缓存深度，单位是DWORD，设定值不能超过硬件允许的最大值，仅适用于配置了专用缓存的Ameba SoC，具体参考硬件配置
ptx_fifo_depth	发送缓存深度，单位是DWORD，ptx_fifo_depth[n]对应索引为n+1的发送缓存。设定值不能超过硬件允许的最大值，索引为0的发送缓存深度不允许配置，使用硬件默认值。仅适用于配置了专用缓存的Ameba SoC，具体参考硬件配置。
speed	USB设备速度，有效值： USB_SPEED_HIGH：高速模式，适用于支持高速USB的Ameba SoC USB_SPEED_HIGH_IN_FULL：全速模式，适用于支持高速USB的Ameba SoC，一般用于UAC等对带宽要求不高的应用场景 USB_SPEED_FULL：全速模式，适用于仅支持全速USB的Ameba SoC
isr_priority	USB设备核心驱动中的中断处理事件优先级
isr_in_critical	是否使能将USB设备核心驱动中的中断处理事件在保护区中运行，0-失能, 1-使能
dma_enable	是否使能DMA模式，0-失能, 1-使能
intr_use_ptx_fifo	是否需要使用专用的周期性传输缓存来处理中断IN传输，0-失能, 1-使能，仅适用于配置了共享缓存的Ameba SoC

备注

支持共享缓存的 Ameba SoC 不需要配置缓存深度；
支持专用缓存的 Ameba SoC 在配置缓存深度时，注意 rx_fifo_depth 和所有 ptx_fifo_depth 的设定值之和不能超过 SoC 支持的最大缓存深度。

具体参考硬件配置。

主机解决方案

透传主机方案

概述

CDC ACM 类为通信设备类（Communication Device Class，CDC）的抽象控制模型（Abstract Control Model，ACM）子类，可用于数据透传。

USB 协议栈提供了：

标准的 CDC ACM 主机类驱动，通道配置如下：
- 两个通道用于控制 IN/OUT 传输
- 一个通道用于中断 IN 传输
- 一个通道用于批量 IN 传输
- 一个通道用于批量 OUT 传输
数据透传应用示例，特征如下：
- 支持透传设备方案定义的 CDC ACM 设备
- 支持数据完整性校验测试、寿命测试、性能测试
- 支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/host/cdc_acm

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/cdc_acm/usbh_cdc_acm.h

API	描述
usbh_cdc_acm_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbh_cdc_acm_deinit	注销类驱动
usbh_cdc_acm_set_line_coding	发送CTRL请求，设置USB设备的line coding
usbh_cdc_acm_get_line_coding	发送CTRL请求，获取USB设备的line coding
usbh_cdc_acm_set_control_line_state	发送CTRL请求，设置USB设备的control line state
usbh_cdc_acm_transmit	发送批量OUT数据到USB设备
usbh_cdc_acm_receive	从USB设备读取批量IN数据
usbh_cdc_acm_notify_receive	从USB设备读取中断IN数据
usbh_cdc_acm_get_bulk_ep_mps	获取USB设备批量IN端点的MPS值

应用层回调 API

类驱动提供了类型为 usbh_cdc_acm_cb_t 的应用层回调函数集:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
   int(* notify)(u8 *buf, u32 len);
   int(* receive)(u8 *buf, u32 len);
   int(* transmit)(usbh_urb_state_t state);
   int(* line_coding_changed)(usbh_cdc_acm_line_coding_t *line_coding);
} usbh_cdc_acm_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
attach	在类驱动执行attach回调时被调用，用于应用层处理设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理设备断开事件
setup	在类驱动执行setup回调时被调用，用于指示应用层类驱动已准备好进行批量传输
notify	在类驱动收到中断IN数据时被调用，用于应用层处理设备上报的状态信息
receive	在类驱动收到批量IN数据时被调用，用于应用层处理设备上报的数据
transmit	在类驱动批量OUT数据传输完成时被调用，用于应用层获取批量OUT传输状态
line_coding_changed	在类驱动收到设备上报的line coding数据，并与历史数据进行比对，发现有变更时被调用，用于应用层对line coding的改变作对应处理

应用示例

示例路径: {SDK}/component/example/usb/usbh_cdc_acm

该示例定义了一个 CDC ACM 主机，更多信息，请参考示例路径下的 README.md 文件。

该示例可作为基于 USB 批量传输的透传方案主机端的设计参考。

网络通信主机方案

概述

CDC ECM 类为通信设备类（Communication Device Class，CDC）的以太网控制模型（Ethernet Control Model，ACM）子类，用于通过 USB 实现与网络设备的互联。

USB 协议栈提供了：

标准的 CDC ECM 主机类驱动，通道配置如下：
- 两个通道用于控制 IN/OUT 传输
- 一个通道用于中断 IN 传输
- 一个通道用于批量 IN 传输
- 一个通道用于批量 OUT 传输
CDC ECM 主机应用示例，可识别 CDC ECM 设备并进行基本的通信测试
CDC ECM 桥接器应用示例，可支持 CDC ECM 设备与路由器之间进行网络通信

类驱动

类驱动路径

{SDK}/component/usb/host/cdc_ecm

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/cdc_ecm/usbh_cdc_ecm_hal.h

API	描述
usbh_cdc_ecm_do_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbh_cdc_ecm_do_deinit	注销类驱动
usbh_cdc_ecm_process_mac_str	获取CDC ECM设备的MAC信息
usbh_cdc_ecm_send_data	发送批量OUT数据
usbh_cdc_ecm_get_connect_status	获取CDC ECM设备的连接状态
usbh_cdc_ecm_get_receive_mps	获取CDC ECM设备批量IN端点的MPS值

应用层回调 API

类驱动提供了类型为 usb_report_data 的应用层回调函数:

typedef void (*usb_report_data)(u8 *buf, u32 len);

具体定义如下:

API	描述
usb_report_data	处理接收到的批量IN网络数据

应用示例

SDK 提供了两个 CDC ECM 主机类应用实例：

CDC ECM 主机示例

示例路径: {SDK}/component/example/usb/usbh_cdc_ecm

该示例定义了一个 CDC ECM 主机，可识别 CDC ECM 设备并进行基本的通信测试。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 CDC ECM 主机方案的设计参考。

CDC ECM 桥接器示例

示例路径: {SDK}/component/example/usb/usbh_wifi_bridge

该示例定义了一个 CDC ECM 桥接器，可支持 CDC ECM 设备与路由器之间进行网络通信。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 CDC ECM 桥接器方案的设计参考。

存储主机方案

概述

MSC 主机类提供了对大容量存储设备（Mass Storage Class）的支持，使用 SCSI（Small Computer System Interface）命令集与 MSC 设备通信，实现数据读写。

USB 协议栈提供了：

标准的 MSC 主机类驱动，特征如下：
- 基于 BOT（Bulk-Only Transport）传输协议
- 通道配置：
  - 两个通道用于控制 IN/OUT 传输
  - 一个通道用于批量 IN 传输
  - 一个通道用于批量 OUT 传输
MSC 主机应用示例
- 支持 FAT32 格式的标准 MSC 设备
- 支持基于 FATFS 的数据读写测试

类驱动

类驱动路径

{SDK}/component/usb/host/msc

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/msc/usbh_msc.h

API	描述
usbh_msc_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbh_msc_deinit	注销类驱动

应用层回调 API

类驱动提供了类型为 usbh_msc_cb_t 的应用层回调函数集:

typedef struct {
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
} usbh_msc_cb_t;

具体定义如下:

API	描述
attach	在类驱动执行attach回调时被调用，用于应用层处理MSC设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理MSC设备断开事件
setup	当类驱动完成对MSC设备的初始化时被调用，用于指示应用层类驱动已准备好与MSC设备进行数据传输

FATFS 磁盘驱动 API

类驱动提供了类型为 ll_diskio_drv 的 FATFS 磁盘驱动 USB_disk_Driver，实现了以下 API:

API	描述
disk_initialize	初始化USB磁盘
disk_deinitialize	注销USB磁盘
disk_status	获取USB磁盘状态：RES_OK - 就绪，RES_ERROR - 未就绪
disk_read	从USB磁盘中读取数据
disk_write	将数据写入USB磁盘，仅当FATFS使能_USE_WRITE时有效
disk_ioctl	支持以下FATFS IO控制指令： CTRL_SYNC：强制将缓冲区的数据写入物理存储介质，对于USB磁盘，可认为是写穿透的，不需要SYNC GET_SECTOR_COUNT：获取sector数量 GET_SECTOR_SIZE：获取sector大小 GET_BLOCK_SIZE：获取block大小

应用示例

示例路径: {SDK}/component/example/usb/usbh_msc

该示例定义了一个 MSC 主机，可识别 MSC 设备并基于 FATFS 进行简单的文件读写测试。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 MSC 主机方案的设计参考。

视频主机方案

概述

USB 视频类（USB Video Class, UVC）主机可识别、配置并管理连接的 UVC 设备（如摄像头、网络摄像头、视频采集卡），获取图像或视频流信息，应用于图像采集、视频监控、工业巡检、医疗诊断、视频推流等场景。

USB 协议栈提供了：

标准的 UVC 主机类驱动，特征如下：
- 支持高速或全速的 UVC 1.5 设备
- 支持 MJPEG/YUV/H264 视频流格式
- 支持分辨率、帧率设置
- 最大支持 6MB/s 码率
- 通道配置：
  - 两个通道用于控制 IN/OUT 传输
  - 一个通道用于等时 IN 传输
UVC 主机应用示例，可与标准 UVC 设备进行通信，支持三种应用场景，可通过 CONFIG_USBH_UVC_APP 来切换：
- USBH_UVC_APP_SIMPLE：截取数据帧后只做简单拷贝，用于性能测试
- USBH_UVC_APP_VFS：截取 MJPEG/H264 数据帧后，通过 VFS 以图像文件的形式写入 SD 卡
- USBH_UVC_APP_HTTPC：截取 MJPEG/H264 数据帧后，通过 HTTP 以图像文件的形式上传至 HTTP 服务器

类驱动

类驱动路径

{SDK}/component/usb/host/uvc

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/uvc/usbh_uvc_intf.h

API	描述
usbh_uvc_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbh_uvc_deinit	注销类驱动
usbh_uvc_stream_on	开启视频流
usbh_uvc_stream_off	关闭视频流
usbh_uvc_stream_state	获取视频流状态：STREAMING_OFF - 关闭，STREAMING_ON - 开启
usbh_uvc_set_param	设置视频参数
usbh_uvc_get_frame	从帧缓存的视频流中截取一个数据帧
usbh_uvc_put_frame	将截取的数据帧释放回帧缓存

应用层回调 API

类驱动提供了类型为 usbh_uvc_cb_t 的应用层回调函数集:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* attach)(void);
   int(* detach)(void);
} usbh_uvc_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
attach	在类驱动执行attach回调时被调用，用于应用层处理设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理设备断开事件

应用示例

示例路径: {SDK}/component/example/usb/usbh_uvc

该示例定义了一个 UVC 主机，可与标准 UVC 设备进行通信，更多信息，请参考示例路径下的 README.md 文件。

该示例可作为基于 UVC 的视频方案主机的设计参考。

自定义主机方案

概述

Vendor 类可作为开发者自定义 USB 主机的设计参考。

SDK 提供了：

Vendor 主机类驱动，通道配置如下：
- 两个通道用于控制 IN/OUT 传输
- 两个通道用于批量 IN/OUT 传输
- 两个通道用于中断 IN/OUT 传输
- 两个通道用于等时 IN/OUT 传输
Vendor 主机应用示例，特征如下：
- 支持自定义设备方案定义的 Vendor 设备
- 支持数据完整性校验测试
- 支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/host/vendor

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/vendor/usbh_vendor.h

API	描述
usbh_vendor_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbh_vendor_deinit	注销类驱动
usbh_vendor_bulk_transmit	发送批量OUT数据到USB设备
usbh_vendor_bulk_receive	从USB设备读取批量IN数据
usbh_vendor_intr_transmit	发送中断OUT数据到USB设备
usbh_vendor_intr_receive	从USB设备读取中断IN数据
usbh_vendor_isoc_transmit	发送等时OUT数据到USB设备
usbh_vendor_isoc_receive	从USB设备读取等时IN数据
usbh_vendor_get_bulk_ep_mps	获取USB设备批量IN端点的MPS值
usbh_vendor_get_intr_ep_mps	获取USB设备中断IN端点的MPS值

应用层回调 API

类驱动提供了类型为 usbh_vendor_cb_t 的应用层回调函数集:

typedef struct {
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
   int(* receive)(u8 ep_type, u8 *buf, u32 len);
   int(* transmit)(u8 ep_type);
} usbh_vendor_cb_t;

具体定义如下:

API	描述
attach	在类驱动执行attach回调时被调用，用于应用层处理设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理设备断开事件
setup	在类驱动执行setup回调时被调用，用于指示应用层类驱动已准备好进行数据传输
receive	在类驱动收到IN数据时被调用，用于应用层处理设备上报的数据
transmit	在类驱动OUT数据传输完成时被调用，用于应用层获取OUT传输状态

应用示例

示例路径: {SDK}/component/example/usb/usbh_vendor

该示例定义了一个厂商自定义主机，更多信息，请参考示例路径下的 README.md 文件。

该示例可作为基于 USB 自定义方案主机端的设计参考。

设备解决方案

音频设备方案

概述

UAC（USB Audio Class）设备类定义了 USB 耳机、USB 麦克风、USB 声卡和其它音频设备的功能控制和接口标准。

UAC 各版本支持的音频参数如下：

../../rst_rtos/7_usb/figures/usb_uac_overview.png

协议栈提供了 UAC 设备类驱动和对应的应用示例，特征如下：

支持全速 UAC 1.0 扬声器功能，默认支持以下音频格式，可在应用层灵活配置：

采样率（kHz）	位宽	声道
采样率（kHz）	位宽	2	4	6	8
44.1	16	Y	Y	Y	Y
44.1	24/32	Y	Y
48	16	Y	Y	Y	Y
48	24/32	Y	Y
96	16	Y	Y
96	24/32	Y
192	16	Y
192	24/32

支持高速和全速 UAC 2.0 扬声器功能，默认支持以下音频格式，可在应用层灵活配置：

采样率（kHz）	位宽	声道
采样率（kHz）	位宽	2	4	6	8
44.1	16	Y	Y	Y	Y
44.1	24/32	Y	Y	Y	Y
48	16	Y	Y	Y	Y
48	24/32	Y	Y	Y	Y
96	16	Y	Y
96	24/32	Y	Y
192	16	Y
192	24/32	Y

端点配置如下：
- 一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
- 一个等时 OUT 端点用于从 USB 主机接收音频数据
支持音量、静音控制
支持描述符全定制
支持 USB 热插拔

备注

USB 设备核心驱动目前不支持 UAC2.0 高带宽端点，即每个帧/微帧最多只支持一笔等时传输，传输大小不超过等时 OUT 端点的最大包长
整条音频通路支持的音频格式由 UAC 主机、UAC 设备硬件及软件框架、音频硬件及软件框架、基于 UAC 的音频应用共同决定

类驱动

类驱动路径

{SDK}/component/usb/device/uac

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/uac/usbd_uac.h

API	描述
usbd_uac_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API
usbd_uac_deinit	注销类驱动
usbd_uac_config	配置音频参数
usbd_uac_start_play	开始接收需要播放的音频数据到ring buffer
usbd_uac_stop_play	停止接收音频数据
usbd_uac_read	从ring buffer中读取接收到的音频数据用于播放
usbd_uac_get_read_frame_cnt	获取待播放的帧数量

应用层回调 API

类驱动提供了类型为 usbd_uac_cb_t 的应用层回调函数集:

typedef struct {
        usbd_audio_cfg_t in;
        usbd_audio_cfg_t out;
        void *audio_ctx;
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        void(* status_changed)(u8 old_status, u8 status);
        void(* mute_changed)(u8 mute);
        void(* volume_changed)(u8 volume);
        void(* format_changed)(u32 freq, u8 ch_cnt);
        void(* sof)(void);
} usbd_uac_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层UAC类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件
mute_changed	USB主机静音设置发生变化时被调用，用于应用层处理静音设置
volume_changed	USB主机音量设置发生变化时被调用，用于应用层调节播放音量
format_changed	USB主机的音频参数设置发生变化时被调用，用于应用层调整音频参数
sof	收到SOF中断时被调用，用于应用层处理时钟同步

应用示例

示例路径: {SDK}/component/example/usb/usbd_uac

该示例定义了一个 UAC 扬声器设备，连接到 USB 主机后可被识别为扬声器。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 USB 音频设备方案的设计参考。

透传设备方案

概述

CDC ACM 类为通信设备类（Communication Device Class，CDC）的抽象控制模型（Abstract Control Model，ACM）子类，可用于模拟 COM 端口，实现数据透传。

SDK 提供了：

标准的 CDC ACM 设备类驱动，特征如下：
- 可配置批量 IN/OUT 的传输长度
- 可配置中断 IN 端点是否使能，方便在不需要中断 IN 的应用中节省带宽
- 端点配置如下：
  一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
  
  一个中断 IN 端点用于向 USB 主机发送设备端的状态信息
  
  一个批量 IN 端点用于向 USB 主机发送数据
  
  一个批量 OUT 端点用于从 USB 主机接收数据
基于 CDC ACM 标准设备类驱动的虚拟串口应用示例，特征如下：
- 在主机端可被识别为标准串口设备，支持通用的串口工具，例如 PuTTY/TeraTerm
- 执行数据回显操作，即通过批量 OUT 端点接收主机发送的批量 OUT 数据，并通过批量 IN 端点将数据发送回主机
- 支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/cdc_acm

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/cdc_acm/usbd_cdc_acm.h

API	描述
usbd_cdc_acm_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbd_cdc_acm_deinit	注销类驱动
usbd_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机

应用层回调 API

类驱动提供了类型为 usbd_cdc_acm_cb_t 的应用层回调函数集:

typedef struct {
   u8(* init)(void);
   u8(* deinit)(void);
   u8(* setup)(usb_setup_req_t *req, u8 *buf);
   u8(* received)(u8 *buf, u32 len);
   void(* transmitted)(u8 status);
   void (*status_changed)(u8 old_status, u8 status);
} usbd_cdc_acm_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据
transmitted	在批量IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

应用示例

示例路径: {SDK}/component/example/usb/usbd_cdc_acm

该示例定义了一个虚拟串口设备，USB 主机端可以用通用的串口工具与之通信，设备端会返回任何主机端下发的数据。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为基于 USB 批量传输的透传方案的设计参考。

HID 设备方案

概述

HID 设备类定义了标准化的人机接口设备（Human Interface Device），通过报表描述符定义的数据格式，使用控制或中断传输方式与 HID 主机进行通信。

USB 协议栈提供了：

HID 键盘和鼠标设备类驱动
- HID 键盘设备类驱动的端点配置如下：
  - 一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
  - 一个中断 IN 端点用于向 USB 主机发送按键信息
  - 一个中断 OUT 端点用于从 USB 主机接收控制指令
- HID 鼠标设备类驱动的端点配置如下：
  - 一个控制端点用于处理 USB 主机发送的控制请求
  - 一个中断 IN 端点用于向 USB 主机发送按键信息
- 支持描述符全定制
HID 键盘和鼠标应用示例，特征如下：
- 支持基本的键盘和鼠标事件模拟
- 支持 USB 热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/hid

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/hid/usbd_hid.h

API	描述
usbd_hid_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API
usbd_hid_deinit	注销类驱动
usbd_hid_send_data	发送HID数据

应用层回调 API

类驱动提供了类型为 usbd_hid_usr_cb_t 的应用层回调函数集:

typedef struct {
        void(* init)(void);
        void(* deinit)(void);
        void(* setup)(void);
        void(* transmitted)(u8 status);
        void(* received)(u8 *buf, u32 len);
        void (*status_changed)(u8 old_status, u8 status);
} usbd_hid_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
received	在中断OUT传输完成时被调用，用于应用层处理接收到的数据，仅对键盘应用有效
transmitted	在中断IN传输完成时被调用，用于应用层以异步的方式获取中断IN传输状态
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

应用示例

示例路径: {SDK}/component/example/usb/usbd_hid

该示例定义了一个 HID 键盘和鼠标设备，提供了与主机通信的简单测试示例。

更多信息，请参考示例路径下的 README.md 文件。

其中，HID 键盘示例可作为 USB HID 双向通信设备方案的设计参考，HID 鼠标示例可作为 USB HID 单向通信设备方案的设计参考。

存储设备方案

概述

MSC 设备类定义了标准化的大容量存储设备（Mass Storage Class），使用 SCSI（Small Computer System Interface）命令集与主机交互，支持对存储媒介的读写、擦除、查询等操作。

USB 协议栈提供了：

标准的 MSC 设备类驱动，特征如下：
- 基于 BOT（Bulk-Only Transport）传输协议
- 支持 SD 卡和 RAM 两种存储媒介
- 端点配置如下：
  - 一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
  - 一个批量 IN 端点用于向 USB 主机发送数据
  - 一个批量 OUT 端点用于从 USB 主机接收数据
- 支持描述符全定制
MSC 设备应用示例，特征如下：
- 支持 USB 热插拔
- 支持 SD 卡热插拔

备注

慎用 SD 卡热插拔功能，在传输过程中热插拔，有造成文件系统损坏、数据丢失的风险。

类驱动

类驱动路径

{SDK}/component/usb/device/msc

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/msc/usbd_msc.h

API	描述
usbd_msc_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbd_msc_deinit	注销类驱动
usbd_msc_disk_init	初始化存储媒介
usbd_msc_disk_deinit	注销存储媒介

应用层回调 API

类驱动提供了类型为 usbd_msc_cb_t 的应用层回调函数集:

typedef struct {
   void (*status_changed)(u8 old_status, u8 status);
} usbd_msc_cb_t;

具体定义如下:

API	描述
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

应用示例

示例路径: {SDK}/component/example/usb/usbd_msc

该示例定义了一个大容量存储设备，USB 主机端可通过 USB 访问设备存储媒介（例如 SD 卡）。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 USB 存储设备方案的设计参考。

FullMAC 设备方案

概述

基于 INIC（Internet Network Interface Controller），可实现基于 USB 的 FullMAC 解决方案，作为网卡通过 USB 与主机连接，为主机提供网络接入能力。

关于 FullMAC，参考支持的芯片。

USB 协议栈提供了：

INIC 设备类驱动，特征如下：
- 支持 WiFi 单功能模式
- 端点配置如下：
  - 一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
  - 一个批量 IN 端点用于向 USB 主机发送数据
  - 两个批量 OUT 端点用于从 USB 主机接收数据
- 支持描述符全定制
基于 INIC 设备类驱动的 FullMAC 应用示例，特征如下：
- 支持定制的 Linux 主机 FullMAC 驱动（联系 Realtek FAE）
- 支持 USB 热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/inic_dplus

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/inic_dplus/usbd_inic.h

API	描述
usbd_inic_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API
usbd_inic_deinit	注销类驱动
usbd_inic_transmit_ctrl_data	发送控制数据
usbd_inic_transmit_data	发送非控制数据
usbd_inic_receive_data	接收非控制数据

应用层回调 API

类驱动提供了类型为 usbd_inic_cb_t 的应用层回调函数集:

typedef struct {
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        int(* clear_config)(void);
        void(* transmitted)(usbd_inic_ep_t *in_ep, u8 status);
        int(* received)(usbd_inic_ep_t *out_ep, u16 len);
        void (*status_changed)(u8 old_status, u8 status);
        void(*suspend)(void);
        void(*resume)(void);
} usbd_uac_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层INIC类驱动已就绪
clear_config	在类驱动clear_config回调中被调用，用于通知应用层INIC类驱动未就绪
transmitted	在非控制端点数据发送完成时被调用，用于应用层异步获取数据发送状态
received	在非控制端点数据接收完成时被调用，用于应用层处理接收到的数据
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件
suspend	在USB发生suspend中断后，类驱动suspend回调执行时被调用，用于应用层处理suspend事件
resume	在USB发生resume中断后，类驱动resume回调执行时被调用，用于应用层处理resume事件

应用示例

示例路径: {SDK}/component/example/usb/usbd_inic

该示例定义了一个 INIC 设备，主机端加载对应的专用设备驱动后可与之通信。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 USB FullMAC 解决方案的设计参考。

复合功能设备方案

概述

USB 复合功能（Composite）设备是一种通过单一物理 USB 接口实现多种独立功能的 USB 设备，它通过将多个独立的 USB 功能单元以接口的形式组合在一起，使 USB 主机将其识别为多个虚拟设备的集合，从而解决了单一物理接口的扩展性问题。

协议栈提供了复合功能设备类驱动及对应的应用示例，特征如下：

支持以下功能组合
- CDC ACM + HID
- CDC ACM + UAC
- HID + UAC
支持描述符全定制
支持 USB 热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/composite

类驱动 API

Composite 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm_hid.h

API

描述

usbd_composite_init

初始化类驱动，初始化时会传入以下应用层回调指针：

CDC ACM应用层回调，参考 CDC ACM应用层回调API
HID应用层回调，参考 HID应用层回调API
Composite应用层回调，参考 Composite应用层回调API

usbd_composite_deinit

注销类驱动

CDC ACM 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm.h

API	描述
usbd_composite_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_composite_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机

HID 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_hid.h

API	描述
usbd_composite_hid_send_data	通过中断IN端点发送HID数据到USB主机

Composite 应用层回调 API

类驱动提供了类型为 usbd_composite_cb_t 的 HID 应用层回调函数集:

typedef struct {
        void (*status_changed)(u8 old_status, u8 status);
        int (* set_config)(void);
} usbd_composite_cb_t;

具体定义如下:

API	描述
set_config	在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

CDC ACM 应用层回调 API

类驱动提供了类型为 usbd_composite_cdc_acm_usr_cb_t 的 CDC ACM 应用层回调函数集:

typedef struct {
        u8(* init)(void);
        u8(* deinit)(void);
        u8(* setup)(usb_setup_req_t *req, u8 *buf);
        u8(* received)(u8 *buf, u32 len);
} usbd_composite_cdc_acm_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据

HID 应用层回调 API

类驱动提供了类型为 usbd_composite_hid_usr_cb_t 的 HID 应用层回调函数集:

typedef struct {
        int(* init)(void);
        void(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        void(* transmitted)(u8 status);
} usbd_composite_hid_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
transmitted	在中断IN传输完成时被调用，用于应用层以异步的方式获取中断IN传输状态

Composite 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm_uac.h

API

描述

usbd_composite_init

初始化类驱动，初始化时会传入以下应用层回调指针：

CDC ACM应用层回调，参考 CDC ACM应用层回调API
UAC应用层回调，参考 UAC应用层回调API
Composite应用层回调，参考 Composite应用层回调API

usbd_composite_deinit

注销类驱动

CDC ACM 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm.h

API	描述
usbd_composite_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_composite_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机

UAC 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_uac.h

API	描述
usbd_composite_uac_config	配置音频参数
usbd_composite_uac_start_play	开始接收需要播放的音频数据到ring buffer
usbd_composite_uac_stop_play	停止接收音频数据
usbd_composite_uac_read	从ring buffer中读取接收到的音频数据用于播放
usbd_composite_uac_get_read_frame_cnt	获取待播放的帧数量
usbd_composite_uac_get_read_frame_time_in_us	获取待播放的帧数量

Composite 应用层回调 API

类驱动提供了类型为 usbd_composite_cb_t 的 HID 应用层回调函数集:

typedef struct {
        void (*status_changed)(u8 old_status, u8 status);
        int (* set_config)(void);
} usbd_composite_cb_t;

具体定义如下:

API	描述
set_config	在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

CDC ACM 应用层回调 API

类驱动提供了类型为 usbd_composite_cdc_acm_usr_cb_t 的 CDC ACM 应用层回调函数集:

typedef struct {
        u8(* init)(void);
        u8(* deinit)(void);
        u8(* setup)(usb_setup_req_t *req, u8 *buf);
        u8(* received)(u8 *buf, u32 len);
} usbd_composite_cdc_acm_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据

UAC 应用层回调 API

类驱动提供了类型为 usbd_composite_uac_usr_cb_t 的 UAC 应用层回调函数集:

typedef struct {
        usbd_audio_cfg_t in;
        usbd_audio_cfg_t out;
        void *audio_ctx;
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        int(* status_changed)(u8 status);
        int(* mute_changed)(u8 mute);
        int(* volume_changed)(u8 volume);
        int(* format_changed)(u32 freq, u8 ch_cnt, u8 byte_width);
        int(* sof)(void);
} usbd_composite_uac_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层UAC类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件
mute_changed	USB主机静音设置发生变化时被调用，用于应用层处理静音设置
volume_changed	USB主机音量设置发生变化时被调用，用于应用层调节播放音量
format_changed	USB主机的音频参数设置发生变化时被调用，用于应用层调整音频参数
sof	收到SOF中断时被调用，用于应用层处理时钟同步

Composite 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_hid_uac.h

API

描述

usbd_composite_init

初始化类驱动，初始化时会传入以下应用层回调指针：

HID应用层回调，参考 HID应用层回调API
UAC应用层回调，参考 UAC应用层回调API
Composite应用层回调，参考 Composite应用层回调API

usbd_composite_deinit

注销类驱动

HID 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_hid_bi_dir.h

API	描述
usbd_composite_hid_send_data	通过中断IN端点发送HID数据到USB主机
usbd_composite_hid_volume_ctrl	通过中断IN端点发送音量控制指令到USB主机
usbd_composite_hid_power_ctrl	通过中断IN端点发送电源控制指令到USB主机
usbd_composite_hid_read	从中断OUT接收缓存中读取指定大小的数据
usbd_composite_hid_get_read_buf_cnt	获取中断OUT接收缓存中的未读数据帧数量
usbd_composite_hid_ring_buf_is_full	检查中断OUT接收缓存是否写满

UAC 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_uac.h

API	描述
usbd_composite_uac_config	配置音频参数
usbd_composite_uac_start_play	开始接收需要播放的音频数据到ring buffer
usbd_composite_uac_stop_play	停止接收音频数据
usbd_composite_uac_read	从ring buffer中读取接收到的音频数据用于播放
usbd_composite_uac_get_read_frame_cnt	获取待播放的帧数量
usbd_composite_uac_get_read_frame_time_in_us	获取待播放的帧数量

Composite 应用层回调 API

类驱动提供了类型为 usbd_composite_cb_t 的 HID 应用层回调函数集:

typedef struct {
        void (*status_changed)(u8 old_status, u8 status);
        int (* set_config)(void);
} usbd_composite_cb_t;

具体定义如下:

API	描述
set_config	在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

HID 应用层回调 API

类驱动提供了类型为 usbd_composite_hid_usr_cb_t 的 HID 应用层回调函数集:

typedef struct {
        int(* init)(void);
        void(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        int(* sof)(void);
        void(* transmitted)(u8 status);
} usbd_composite_hid_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调执行阶段被调用，用于指示应用层类驱动已就绪
sof	在类驱动sof回调执行阶段被调用，用于处理应用层处理与时序相关的事务
transmitted	在中断IN传输完成时被调用，用于应用层以异步的方式获取中断IN传输状态

UAC 应用层回调 API

类驱动提供了类型为 usbd_composite_uac_usr_cb_t 的 UAC 应用层回调函数集:

typedef struct {
        usbd_audio_cfg_t in;
        usbd_audio_cfg_t out;
        void *audio_ctx;
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        int(* status_changed)(u8 status);
        int(* mute_changed)(u8 mute);
        int(* volume_changed)(u8 volume);
        int(* format_changed)(u32 freq, u8 ch_cnt, u8 byte_width);
        int(* sof)(void);
} usbd_composite_uac_usr_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层UAC类驱动已就绪
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件
mute_changed	USB主机静音设置发生变化时被调用，用于应用层处理静音设置
volume_changed	USB主机音量设置发生变化时被调用，用于应用层调节播放音量
format_changed	USB主机的音频参数设置发生变化时被调用，用于应用层调整音频参数
sof	收到SOF中断时被调用，用于应用层处理时钟同步

应用示例

SDK 提供以下 USB Composite 示例:

路径	描述
{SDK}/component/example/usb/usbd_composite_cdc_acm_hid/	CDC ACM虚拟串口和HID鼠标应用示例
{SDK}/component/example/usb/usbd_composite_cdc_acm_uac/	CDC ACM虚拟串口和UAC扬声器应用示例
{SDK}/component/example/usb/usbd_composite_uac_hid/	UAC扬声器和自定义HID应用示例

更多信息，请参考对应示例路径下的 README.md 文件。

上述示例可作为 USB Composite 设备方案的设计参考。

自定义设备方案

概述

Vendor 类可作为开发者自定义 USB 设备的设计参考。

SDK 提供了：

Vendor 设备类驱动，特征如下：
- 支持描述符全定制
- 端点配置如下：
  一个控制 IN/OUT 端点用于处理 USB 主机发送的控制请求
  
  一对批量 IN/OUT 端点用于批量传输测试
  
  一对中断 IN/OUT 端点用于中断传输测试
  
  一对等时 IN/OUT 端点用于等时传输测试
基于 Vendor 设备类驱动的应用示例，特征如下：
- 与 Vendor 主机应用示例适配，具体参考自定义主机方案
- 执行批量/中断/等时传输的数据回显操作
- 支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/vendor

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/vendor/usbd_vendor.h

API	描述
usbd_vendor_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考应用层回调API。
usbd_vendor_deinit	注销类驱动
usbd_vendor_transmit_ctrl_data	发送控制 IN 数据到 USB 主机
usbd_vendor_transmit_bulk_data	发送批量 IN 数据到 USB 主机
usbd_vendor_receive_bulk_data	从USB主机接收批量 OUT 数据
usbd_vendor_transmit_intr_data	发送中断 IN 数据到 USB 主机
usbd_vendor_receive_intr_data	从USB主机接收中断 OUT 数据
usbd_vendor_transmit_isoc_data	发送等时 IN 数据到 USB 主机
usbd_vendor_receive_isoc_data	从USB主机接收等时 OUT 数据

应用层回调 API

类驱动提供了类型为 usbd_vendor_cb_t 的应用层回调函数集:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* setup)(usb_setup_req_t *req, u8 *buf);
   int(* set_config)(void);
   int(* bulk_received)(u8 *buf, u32 len);
   int(* intr_received)(u8 *buf, u32 len);
   int(* isoc_received)(u8 *buf, u32 len);
   void(* bulk_transmitted)(u8 status);
   void(* intr_transmitted)(u8 status);
   void(* isoc_transmitted)(u8 status);
   void (*status_changed)(u8 old_status, u8 status);
} usbd_vendor_cb_t;

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪
bulk_received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据
intr_received	在中断OUT传输完成时被调用，用于应用层处理接收到的数据
isoc_received	在等时OUT传输完成时被调用，用于应用层处理接收到的数据
bulk_transmitted	在批量IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
intr_transmitted	在中断IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
isoc_transmitted	在等时IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

应用示例

示例路径: {SDK}/component/example/usb/usbd_vendor

该示例定义了一个自定义设备，支持批量/中断/等时传输的数据回显。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 USB 厂商自定义方案设备端的设计参考。

设备描述符定制

描述符概述

USB 设备通过描述符定义设备功能，USB 描述符的拓扑结构示例如下图所示：

../../rst_rtos/7_usb/figures/usb_device_descriptors_cn.svg

其中：

一个 USB 设备只有一个设备描述符（Device Descriptor）
一个 USB 设备可以有多个（由设备描述符的 bNumConfigurations 指定）配置描述符（Configuration Descriptor），但同时只允许一个配置描述符生效
一个配置描述符下可以有多个（由配置描述符的 bNumInterfaces 指定）接口描述符（Interface Descriptor），且多个接口描述符可以同时生效
一个接口描述符下可以有多个（由接口描述符的 bNumEndPoints 指定）端点描述符（Endpoint Descriptor），且多个端点描述符可以同时生效

另外，还有其它一些常用的描述符：

设备描述符、配置描述符和接口描述符都有一些相关的功能描述，这些描述定义为字符描述符（String Descriptor）
对于需要同时支持高速和全速模式的设备，还需要同时定义设备限定描述符（Device Qualifier Descriptor）和其它速率配置描述符（Other Speed Configuration Descriptor）
对于复合设备，还需要在多个类接口描述符之前，增加一个接口关联描述符（Interface Association Descriptor，IAD）
某些 USB 设备类需要定义与设备类相关的特定描述符，比如 HID 设备需要定义报表描述符（Report Descriptor）

备注

具体的描述符定义，请参考 USB 规范。

描述符数据结构

一般情况下，USB 主机会按如下顺序获取 USB 设备的描述符信息：

获取设备描述符，USB 设备需要返回设备描述符信息
获取配置描述符，USB 设备需要返回描述符拓扑结构中当前有效的配置描述符及其以下节点（包含接口描述符和端点描述符）的全部描述符信息
获取配置描述符对应的字符串描述符，USB 设备需要根据主机控制请求中的字符串类型信息，返回当前有效配置描述符下对应的字符串描述符信息，包含语言 ID、串号、厂商、产品等字符串信息

另外，USB 主机可能还会尝试获取 USB 设备的以下描述符信息：

获取设备限定描述符，如果 USB 设备有支持，需要返回设备限定描述符信息
获取其它速率配置描述符，如果 USB 设备有支持，需要返回描述符拓扑结构中当前有效的配置描述符对应的其它速率配置描述符及其节点（包含接口描述符和端点描述符）的全部描述符信息
获取其它速率配置描述符对应的字符串描述符，USB 设备需要根据主机控制请求中的字符串类型信息，返回当前有效配置描述符对应的其它速率配置描述符下对应的字符串描述符信息，包含语言 ID、串号、厂商、产品等字符串信息
获取设备类相关的描述符，USB 设备需要根据设备类规范返回相关的描述符信息
获取 USB 主机相关的描述符，比如 Windows 主机会尝试获取索引值为 238（对应 16 进制数字 0xEE）的 Microsoft OS 字符串描述符（Microsoft OS String Descriptor）

备注

如果 USB 设备不支持某些描述符，在收到 USB 主机端相关请求时，需要返回 STALL 状态，复合规范的 STALL 并不会影响 USB 主机与设备间的通信，也不会影响 USB 设备的功能。

鉴于上述 USB 主机获取 USB 设备描述符的行为，建议 USB 设备定义以下几个独立数组用于存储 USB 主机需要获取的描述符信息：

设备描述符，仅包含设备描述符信息
配置描述符，每个配置描述符分别定义，包含其自身及其以下节点（包含接口描述符和端点描述符）的全部描述符信息
字符串描述符，包含语言 ID 在内的每个字符串描述符分别定义
设备限定描述符，仅包含设备限定描述符信息
其它速率配置描述符，每个其它速率配置描述符分别定义，包含其自身及其以下节点（包含接口描述符和端点描述符）的全部描述符信息；为节省存储资源，也可与配置描述符共用一个数组，运行时动态替换描述符类型数据
设备类相关的描述符，按设备类规范定义
USB 主机相关的描述符，按 USB 主机相关规范和应用需求定义

描述符定制项

USB 设备协议栈中定义的所有设备类，其全部描述符信息均开源并允许开发者根据设计需求定制。但为兼容性，对于基于 USB 规范的标准类设备，一般仅建议对以下描述符信息进行定制：

VID 与 PID

开发者可以直接使用 USB 协议栈默认使用的 Realtek VID 和 PID，如需自定义，需要注册成为 USB-IF 成员（参考 https://www.usb.org/members），然后按照 USB-IF 的流程申请 VID 和 PID。开发者如果需要使用 Realtek VID，并自定义 PID，请与 Realtek FAE 联系。

备注

使用 Realtek VID 和 PID, 并不意味着产品符合 USB 规范，仍需要进行 USB 认证。

字符串描述符

设备描述符、配置描述符和接口描述符都有字符串描述符索引字段，可定义非 0 的索引值并定义对应的字符串描述符：

设备描述符
- iManufacturer：厂商字符串
- iProduct：产品字符串
- iSerialNumber：串号字符串
配置描述符
- iConfiguration：配置字符串
接口描述符
- iInterface：配置字符串

备注

USB 规范要求字符串描述符使用 UNICODE 编码，设备核心驱动提供了 usbd_get_str_desc 函数用于将 ASCII 编码的字符串转为 UNICODE 编码的字符串描述符，方便开发者用 ASCII 字符串来维护字符串信息。
协议栈目前仅提供了英文字符串描述符示例，如需支持其它语言类型，请参考 USB 规范定义所需的语言 ID 描述符及对应的字符串描述符

端点描述符

对于一般应用，端点描述符中的以下字段支持自定义：

bEndpointAddress：端点地址
wMaxPacketSize：最大包长，一般建议按 USB 规范定义的最大值（不高于 SoC 硬件支持的最大值）来设定，除非有特别需求，不建议随意修改
bInterval：传输间隔

备注

协议栈保证默认提供的端点配置对所有 SoC 可用，如需调整，请参考硬件配置，务必熟知相关 USB 规范和 SoC 硬件限制后再做谨慎调整，否则可能导致兼容性问题甚至枚举失败。

设备连接状态检测

对于自供电 USB 设备，当 USB 连接状态改变时，设备类驱动及应用层需要及时获悉相关事件并做对应处理，从而达成支持热插拔、降低功耗等目的。

USB 设备核心驱动提供了如下 API 用于设备类驱动及应用层检测 USB 连接状态：

status_changed：用于异步获取设备连接状态改变事件，参考设备类驱动层回调函数
usbd_get_status：用于获取设备当前连接状态，参考设备类核心驱动 API
usbd_get_bus_status：用于获取 USB 总线 DP/DM/suspend 状态，参考设备类核心驱动 API

上述 API 需要在 USB 上电之后，访问 USB 相关寄存器才能获得有效数据，因此需要在 USB 核心驱动初始化之后才能调用。如果要在 USB 未上电时就能获取 USB 状态信息，需要借助外部电路的支持，例如通过 GPIO 中断来检测 VBUS 的上电掉电事件，具体请参考硬件设计手册（Hardware Design Guide）中的 USB 插入检测电路参考设计。

借助上述软硬件检测方案，可以分辨如下 USB 设备连接状态改变事件：

事件	usbd_get_status	status_changed	VBUS GPIO中断	VBUS状态
设备复位（保持与USB主机连接）	USBD_ATTACH_STATUS_ATTACHED	USBD_ATTACH_STATUS_INIT -> USBD_ATTACH_STATUS_ATTACHED	N/A	ON
设备复位（保持USB连接断开）	USBD_ATTACH_STATUS_INIT	N/A	N/A	OFF
设备复位（保持与USB充电器连接）	USBD_ATTACH_STATUS_INIT	N/A	N/A	ON
连接到USB主机	USBD_ATTACH_STATUS_ATTACHED	USBD_ATTACH_STATUS_DETACHED -> USBD_ATTACH_STATUS_ATTACHED	Y (上升沿)	OFF -> ON
从USB主机断开	USBD_ATTACH_STATUS_DETACHED	USBD_ATTACH_STATUS_ATTACHED -> USBD_ATTACH_STATUS_DETACHED	Y (下降沿)	ON -> OFF
连接到USB充电器	USBD_ATTACH_STATUS_INIT or USBD_ATTACH_STATUS_DETACHED	N/A	Y (上升沿)	OFF -> ON
从USB充电器断开	USBD_ATTACH_STATUS_INIT or USBD_ATTACH_STATUS_DETACHED	N/A	Y (下降沿)	ON -> OFF
USB连接挂起（suspend）	USBD_ATTACH_STATUS_DETACHED	USBD_ATTACH_STATUS_ATTACHED -> USBD_ATTACH_STATUS_DETACHED	与主机设置相关	与主机设置相关
USB连接恢复（resume）	USBD_ATTACH_STATUS_ATTACHED	USBD_ATTACH_STATUS_DETACHED -> USBD_ATTACH_STATUS_ATTACHED	与主机设置相关	与主机设置相关

两个典型的应用场景：

基于软件的解决方案

如果对功耗要求不严苛，允许 USB 电源常开，可通过 status_changed，只借助软件的方式获取设备连接状态改变事件，一般用法如下：

检测到与 USB 主机断开连接时，终止通信，注销并重新注册 USB 设备，等待下次与 USB 主机连接
检测到与 USB 主机连接时，恢复通信

具体处理流程参考下图：

../../rst_rtos/7_usb/figures/usb_status_detection_sw_cn.svg

基于硬件辅助的解决方案

如果对功耗要求严苛，希望在 USB 设备与主机未连接时能够关闭 USB 相关电源，可通过 GPIO 中断来检测 VBUS 的上电掉电事件，一般用法如下：

检测到与 USB 主机断开连接或者连接到 USB 充电器时，注销 USB 设备，以达省电目的
检测到与 USB 主机连接时，注册 USB 设备，使能 USB 通信

具体处理流程参考下图：

../../rst_rtos/7_usb/figures/usb_status_detection_hw_cn.svg

DRD 解决方案

概述

DRD 指双角色设备（Dual-Role Device），即支持在主机和设备两个角色之间进行动态切换的 USB 设备。

DRD 提升了设备灵活性，适应多样化的应用场景，例如：

存储设备：作为主机连接 U 盘、打印机，作为设备连接电脑、手机
车载设备：作为 Carplay 设备，与车机系统互联
工业物联网：灵活适配传感器（设备）与控制器（主机）角色

协议栈提供了基于标准 MSC 主机和 MSC 设备类驱动的 DRD 设备应用示例，特征如下：

支持 MSC 设备：
- 基于 BOT（Bulk-Only Transport）传输协议
- 支持 SD 卡作为存储媒介
- 端点配置如下：
  - 一个控制端点用于处理 USB 主机发送的控制请求
  - 一个批量 IN 端点用于向 USB 主机发送数据
  - 一个批量 OUT 端点用于从 USB 主机接收数据
- 支持描述符全定制
支持 MSC 主机：
- 支持 FAT32 格式的 MSC 设备
- 通道配置如下：
  - 两个通道用于控制 IN/OUT 传输
  - 一个通道用于批量 IN 传输
  - 一个通道用于批量 OUT 传输
不支持 SD 卡热插拔
不支持 USB 热插拔

类驱动

关于 MSC 主机类驱动，参考存储主机方案。

关于 MSC 设备类驱动，参考存储设备方案。

应用示例

示例路径: {SDK}/component/example/usb/usb_drd

该示例定义了一个具备大容量存储主机和大容量存储设备的双角色设备，在运行时进行角色切换。

更多信息，请参考示例路径下的 README.md 文件。

该示例可作为 DRD 方案的设计参考。

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 认证

所有产品

通过功能选择芯片

HiFi DSP 系列

HiFi DSP 系列

Cortex-A Linux 系列

Cortex-A Linux 系列

显示系列

显示系列

Audio 系列

Audio 系列

Wi-Fi 6 + BLE 系列

Wi-Fi 6 + BLE 系列

Wi-Fi 2.4G/5G + BLE 系列

Wi-Fi 2.4G/5G + BLE 系列

Wi-Fi + 经典蓝牙系列

Wi-Fi + 经典蓝牙系列

Wi-Fi R-MESH 系列

Wi-Fi R-MESH 系列

通过应用选择芯片

IoT 控制

IoT 控制

应用指南

重要功能开发指南

Wi-Fi 开发指南

Wi-Fi 开发指南

系统安全开发指南

系统安全开发指南

多媒体开发指南

RTOS

LINUX

语音识别

语音识别

SDK

批量生产

工具

Flash 烧写工具

Flash 烧写工具

射频测试工具

射频测试工具

支持的芯片

USB 概述

硬件配置

软件协议栈概述

软件特性

软件架构

文件目录结构

配置和编译

硬件抽象层驱动

主机核心驱动

主机驱动软件架构

面向 Class 层的 API

面向应用层的 API

设备核心驱动

设备驱动软件架构

面向类驱动层的 API

面向应用层的 API

主机解决方案

透传主机方案

概述

类驱动

应用示例

网络通信主机方案

概述

类驱动

应用示例

存储主机方案

概述

类驱动

应用示例

视频主机方案

概述

类驱动

应用示例

自定义主机方案

概述

类驱动

应用示例

设备解决方案

音频设备方案

概述