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外设核心驱动库文件，用于外设类驱动和应用开发

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应用示例对应的类驱动。

硬件抽象层驱动

概述

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

../../_images/usb_hal_api_cn.svg

硬件抽象层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

主机核心驱动

主机驱动软件架构

../../_images/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

描述

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，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的Ameba SoC，

具体参考 硬件配置

nptx_fifo_depth

USB主机共享非周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的

Ameba SoC，具体参考 硬件配置

ptx_fifo_depth

USB主机共享周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的Ameba

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不得超过硬件支持的最大总缓存深度，具体参考 硬件配置 。

外设核心驱动

外设驱动软件架构

../../_images/usb_device_api_cn.svg

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

面向类驱动层的API

API

描述

usbd_register_class

注册外设类驱动，外设类驱动类型为usbd_class_driver_t,

具体参考 类驱动层回调函数

usbd_unregister_class

注销外设类驱动

usbd_ep_init

初始化端点

usbd_ep_deinit

注销端点

usbd_ep_transmit

通过指定端点发送数据

usbd_ep_receive

准备从指定端点接受数据

usbd_ep_set_stall

将指定端点状态设置为STALL

usbd_ep_clear_stall

清除指定端点的STALL状态

usbd_ep_is_stall

检查指定端点是否处于STALL状态

usbd_ep0_set_stall

将端点0的状态设置为STALL

usbd_ep0_transmit

通过端点0发送数据，用于在控制IN传输的Data阶段发送数据

usbd_ep0_receive

准备从端点0接受数据，用于在控制OUT传输的Data阶段接收数据

usbd_ep0_transmit_status

通过端点0发送ZLP，用于在控制OUT传输的Status阶段发送ZLP

usbd_ep0_receive_status

准备通过端点0接收ZLP，用于在控制IN传输的Status阶段接收ZLP

usbd_get_str_desc

用于将ASCII编码的字符串转换为USB字符串描述符所需要的UNICODE 16字节流

类驱动层回调函数

外设核心驱动层提供了类型 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描述符

set_config

在外设核心驱动在ADDRESSED状态下收到SET_CONFIGURATION控制请求时被调用，用于类驱动层初始化端点资源

clear_config

在外设核心驱动在CONFIGURED状态下收到SET_CONFIGURATION控制请求切到新的配置时被调用，用于class层注销端点资源

setup

在控制IN/OUT传输的Setup阶段完成时被调用，用于class层处理与class相关的控制请求

ep_data_in

在批量/中断/等时IN传输的Data阶段完成时被调用，用于指示class层批量/中断/等时IN数据传输已完成

ep_data_out

在批量/中断/等时OUT传输的Data阶段完成时被调用，用于class层处理接收到的批量/中断/等时OUT数据

ep0_data_in

在控制IN传输的Data阶段完成时被调用，用于指示class层控制IN数据传输已完成

ep0_data_out

在控制OUT传输的Data阶段完成时被调用，用于class层处理接收到的控制OUT数据

sof

在SOF中断发生时被调用，一般用于class层处理与时序相关的事务

suspend

在suspend中断发生时被调用, 用于class层在suspend发生时做资源挂起处理

resume

在resume中断发生时被调用, 用于class层在resume发生时做资源恢复处理

status_changed

在USB连接状态改变时被调用，用于class层处理热插拔事件

面向应用层的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外设配置参数

外设核心驱动层提供了类型 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支持的最大缓存深度，具体参考 硬件配置 。

主机解决方案

透传主机方案

TODO

网络通信主机方案

TODO

存储主机方案

TODO

视频主机方案

TODO

外设解决方案

音频外设方案

概述

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

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

../../_images/usb_uac_overview.png

协议栈提供了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

在类驱动初始化（usbd_cdc_acm_init）时被调用，用于初始化应用相关的资源

deinit

在类驱动注销（usbd_cdc_acm_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

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

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热插拔事件

应用示例

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

设备描述符定制

TODO

DRD解决方案

TODO

USB认证

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

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

  • 产品使用​USB标志、宣传资料中宣称符合USB规范或提及USB认证

  • 需要无缝兼容主流操作系统（如 Windows、macOS、Linux）

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

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