IC:

支持的芯片

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

USB概述

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

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

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

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

硬件配置

支持设备模式
支持全速模式
设备模式下的端点配置如下：
- EP0：INOUT
- EP1：IN
- EP2：OUT
- EP3：IN
- EP4：OUT
- EP5：INOUT
其中，EP0仅用于控制传输，仅支持一个周期性IN端点。
共享缓存模式，缓存深度（单位DWORD）配置如下：
- 总缓存：最大1016
- 共享接收缓存：最大512
- 共享非周期性发送缓存：最大256
- 专用周期性发送缓存：最大256
内置PHY

软件协议栈概述

软件特性

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

软件架构

协议栈架构如图所示：

../../_images/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主机核心驱动库文件，用于主机类驱动和应用开发

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/`	UAC2.0设备类驱动
`{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和UAC2.0的复合功能设备解决方案示例
`{SDK}/component/component/example/usb/usbd_uac_hid/`	基于HID和UAC2.0的复合功能设备解决方案示例
`{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/`	基于UAC2.0的音频设备解决方案示例
`{SDK}/component/component/example/usb/usb_drd/`	基于MSC主机和MSC设备的DRD解决方案示例

配置和编译

配置USB

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

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

保存并退出。

编译USB

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

备注

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

配置USB

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

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

保存并退出。

编译USB

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

备注

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

硬件抽象层驱动

概述

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

硬件抽象层API

API	描述
`usb_chip_init`	SoC相关的硬件（电源、时钟、使能）初始化
`usb_chip_deinit`	SoC相关的硬件（电源、时钟、使能）去初始化
`usb_chip_get_cal_data`	获取SoC相关的USB PHY校准数据

备注

硬件抽象层默认编入USB主机/设备/DRD核心库文件，不允许开发者修改
USB PHY校准数据在SoC出厂前确定，原则上不需要开发者修改，如确实有必要修改，请联系Realtek FAE

主机核心驱动

主机驱动软件架构

主机核心驱动层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	描述
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不得超过硬件支持的最大总缓存深度，具体参考硬件配置。

设备核心驱动

设备驱动软件架构

设备核心驱动层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	通过指定非EP0端点向USB主机发送数据，即发起IN传输。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_in回调函数中获取传输执行状态
usbd_ep_receive	准备从指定非EP0端点从USB主机接受数据，即发起OUT传输。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_out回调函数中获取传输完成的数据
usbd_ep_set_stall	将指定端点状态设置为STALL，根据USB协议或者应用设计需求调用
usbd_ep_clear_stall	清除指定端点的STALL状态，根据USB协议或者应用设计需求调用
usbd_ep_is_stall	检查指定端点是否处于STALL状态
usbd_ep0_set_stall	将端点0的状态设置为STALL，根据USB协议或者应用设计需求调用
usbd_ep0_transmit	通过端点0发送数据，用于在控制IN传输的Data阶段向USB主机发送数据。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep0_data_in回调函数中获取传输执行状态
usbd_ep0_receive	准备从端点0接受数据，用于在控制OUT传输的Data阶段从USB主机接收数据。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep0_data_out回调函数中获取传输完成的数据
usbd_ep0_transmit_status	通过端点0发送ZLP，用于在控制OUT传输的Status阶段发送ZLP。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep0_data_in回调函数中获取传输执行状态
usbd_ep0_receive_status	准备通过端点0接收ZLP，用于在控制IN传输的Status阶段接收ZLP。传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep0_data_out回调函数中获取传输完成的数据
usbd_get_str_desc	用于将ASCII编码的字符串转换为UNICODE 16编码的USB字符串描述符，注意目标字符串缓存的大小为源字符串大小的两倍再加两个字节，多出的两个字节为USB字符串描述符长度和描述符类型标识

类驱动层回调函数

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

typedef struct _usbd_class_driver_t {
   u8 *(*get_descriptor)( usb_dev_t *dev, usb_setup_req_t *req,
   usb_speed_type_t speed, u16 *len);
   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 status);
} usbd_class_driver_t;

具体定义如下:

API	是否必须	描述
get_descriptor	是	在设备核心驱动枚举阶段收到USB主机获取USB描述符请求时被调用，所有类型的描述符统一通过该回调函数获取。设备类驱动需要在该回调函数中，根据Setup请求wValue字段定义的描述符类型，返回对应的描述符数组指针和数组长度信息： i 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传输，如果上一笔传输的数据长度为端点描述符中wMaxPacketSize的倍数，发送ZLP包将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_err_cnt[USB_MAX_ENDPOINTS];
   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_err_cnt	非周期性IN传输允许出现的最大错误次数
nptx_max_epmis_cnt	非周期性IN传输产生EPMis中断的EPMis次数阈值
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）子类，可用于数据透传。

协议栈提供了标准的CDC ACM主机类驱动和基于该主机类驱动的数据透传应用示例，特征如下：

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

类驱动

类驱动路径

{SDK}/component/usb/host/cdc_acm

类驱动API

类驱动API定义头文件：{SDK}/component/usb/host/usbh_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 codi ng的改变作对应处理

应用示例

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

该示例定义了一个CDC ACM主机，可与:ref:usb_device_cdc_acm 定义的CDC ACM设备进行通信。

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

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

网络通信主机方案

概述

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

SDK提供了标准的CDC ECM主机类驱动和基于该主机类驱动的数据透传应用示例，特征如下：

支持标准CDC ECM设备
通道配置如下：
- 两个通道用于控制IN/OUT传输
- 一个通道用于中断IN传输
- 一个通道用于批量IN传输
- 一个通道用于批量OUT传输
支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/host/cdc_ecm

类驱动API

类驱动API定义头文件：{SDK}/component/usb/host/usbh_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设备并进行DHCP测试。

更多信息，请参考示例路径下的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设备通信，实现数据读写。

SDK提供了标准的MSC主机类驱动和基于该主机类驱动的数据读写测试应用示例，特征如下：

支持FAT32格式的、基于BOT（Bulk-Only Transport）传输协议的MSC设备
通道配置如下：
- 两个通道用于控制IN/OUT传输
- 一个通道用于批量IN传输
- 一个通道用于批量OUT传输

类驱动

类驱动路径

{SDK}/component/usb/host/msc

类驱动API

类驱动API定义头文件：{SDK}/component/usb/host/usbh_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设备（如摄像头、网络摄像头、视频采集卡），获取图像或视频流信息，应用于图像采集、视频监控、工业巡检、医疗诊断、视频推流等场景。

协议栈提供了标准的UVC主机类驱动，特征如下：

支持高速或全速的UVC 1.5设备
支持MJPEG/YUV/H264视频流格式
支持分辨率、帧率设置
最大支持6MB/s码率
通道配置如下：
- 两个通道用于控制IN/OUT传输
- 一个通道用于等时IN传输

类驱动

类驱动路径

{SDK}/component/usb/host/uvc

类驱动API

类驱动API定义头文件：{SDK}/component/usb/host/usbh_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设备进行通信，示例支持三种应用场景，可通过CONFIG_USBH_UVC_APP来切换：

USBH_UVC_APP_SIMPLE：截取数据帧后只做简单拷贝，用于性能测试
USBH_UVC_APP_VFS：截取MJPEG/H264数据帧后，通过VFS以图像文件的形式写入SD卡
USBH_UVC_APP_HTTPC：截取MJPEG/H264数据帧后，通过HTTP以图像文件的形式上传至HTTP服务器

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

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

设备解决方案

音频设备方案

概述

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

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

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

支持UAC 2.0扬声器功能
支持高速和全速模式
支持多种音频格式，可在应用层灵活配置，例如：
- 44.1kHz，16/24/32位，2/4/6/8声道
- 48kHz，16/24/32位，2/4/6/8声道
- 96kHz，16/24/32位，2/4声道
- 192kHz，16/24/32位，2声道
端点配置如下：
- 一个控制端点用于处理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 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

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

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

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

透传设备方案

概述

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

协议栈提供了标准的CDC ACM设备类驱动和基于该设备类驱动的虚拟串口应用示例，特征如下：

可配置批量IN/OUT的传输长度
可配置中断IN端点是否使能，方便在不需要中断IN的应用中节省带宽
端点配置如下：
- 一个控制端点用于处理USB主机发送的控制请求
- 一个中断IN端点用于向USB主机发送设备端的状态信息
- 一个批量IN端点用于向USB主机发送数据
- 一个批量OUT端点用于从USB主机接收数据
支持热插拔

类驱动

类驱动路径

{SDK}/component/usb/device/cdc_acm

类驱动API

类驱动API定义头文件：{SDK}/component/usb/device/usbd_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 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主机进行通信。

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

支持基于双向中断传输的键盘应用，端点配置如下：
- 一个控制端点用于处理USB主机发送的控制请求
- 一个中断IN端点用于向USB主机发送按键信息
- 一个中断OUT端点用于从USB主机接收控制指令
支持基于中断IN的鼠标应用，端点配置如下：
- 一个控制端点用于处理USB主机发送的控制请求
- 一个批量IN端点用于向USB主机发送按键信息
支持描述符全定制
支持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

注销存储媒介

应用层回调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 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文件。

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

存储设备方案

概述

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

协议栈提供了标准的MSC设备类驱动和基于该设备类驱动的大容量存储设备应用示例，特征如下：

基于BOT（Bulk-Only Transport）传输协议
支持SD卡和RAM两种存储媒介
端点配置如下：
- 一个控制端点用于处理USB主机发送的控制请求
- 一个批量IN端点用于向USB主机发送数据
- 一个批量OUT端点用于从USB主机接收数据
支持描述符全定制
支持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 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，参考支持的芯片。

协议栈提供了INIC设备类驱动，特征如下：

支持WiFi单功能模式
端点配置如下：
- 一个控制端点用于处理USB主机发送的控制请求
- 一个批量IN端点用于向USB主机发送数据
- 两个批量OUT端点用于从USB主机接收数据
支持描述符全定制
支持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 *ep, u8 status);
        int(* received)(usbd_inic_ep_t *ep, u16 len);
        void (*status_changed)(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

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

面向应用层的API

API	描述
usbd_composite_init	初始化类驱动，初始化时会传入以下应用层回调指针： CDC ACM应用层回调，参考 CDC ACM应用层回调API HID应用层回调，参考 HID应用层回调API Composite应用层回调，参考 Composite应用层回调API
usbd_composite_deinit	注销类驱动
usbd_composite_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_composite_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机
usbd_composite_hid_send_data	注销存储媒介

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

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

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

具体定义如下:

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

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

面向应用层的API

API	描述
usbd_composite_init	初始化类驱动，初始化时会传入以下应用层回调指针： CDC ACM应用层回调，参考 CDC ACM应用层回调API UAC应用层回调，参考 UAC应用层回调API Composite应用层回调，参考 Composite应用层回调API
usbd_composite_deinit	注销类驱动
usbd_composite_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_composite_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机
usbd_composite_hid_send_data	注销存储媒介

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

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

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

具体定义如下:

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

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

面向应用层的API

API	描述
usbd_composite_init	初始化类驱动，初始化时会传入以下应用层回调指针： HID应用层回调，参考 HID应用层回调API UAC应用层回调，参考 UAC应用层回调API Composite应用层回调，参考 Composite应用层回调API
usbd_composite_deinit	注销类驱动
usbd_composite_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_composite_cdc_acm_notify_serial_state	通过中断IN端点发送状态数据到USB主机
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接收缓存是否写满

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中断时被调用，用于应用层处理时钟同步

Composite应用层回调API

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

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

具体定义如下:

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

应用示例

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 2.0扬声器应用示例
{SDK}/component/example/usb/usbd_composite_uac_hid/	UAC 2.0扬声器和自定义HID应用示例

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

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

热插拔检测

TODO

设备描述符定制

描述符概述

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

../../_images/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硬件限制后再做谨慎调整，否则可能导致兼容性问题甚至枚举失败。

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