复合功能设备方案
概述
USB 复合设备(Composite Device)规范定义了通过单一物理 USB 接口承载多种独立功能类(如音频、HID、存储、串口等)的设备架构与枚举标准。
Ameba 基于 USB-IF 官方发布的 USB 规范,实现了灵活的复合设备功能框架,支持通过接口描述符(Interface Descriptor)或接口关联描述符(IAD)聚合多个功能接口,提供多逻辑设备在主机端的并行枚举、独立驱动加载及协同工作能力。
特性
支持以下功能组合
CDC ACM + HID
CDC ACM + MSC
CDC ACM + UAC
HID + UAC
支持热插拔
支持描述符全定制
支持配置传输缓存大小、速度模式等参数
应用场景
作为 USB 复合设备,Ameba 可通过单个 USB 物理接口同时枚举多种设备类,实现数据传输与控制交互的并行处理,适用于多种复杂的应用场景,例如:
带线控的 USB 音频设备 (UAC + HID):Ameba 在提供 USB 音频输入/输出功能(UAC)的同时,利用 HID 接口实现媒体控制。用户既可以获得高品质的音频流体验(如耳机听音、麦克风录音),又能通过 HID 通道实现音量调节、静音、切歌或 RGB 灯效控制等交互功能。
智能工业与 3D 打印控制 (MSC + CDC ACM):Ameba 结合了 MSC 大容量存储与 CDC 虚拟串口功能。在 3D 打印机或数据记录仪场景中,MSC 接口可模拟为 U 盘用于存储 G-code 切片文件或传感器历史数据,而 CDC 接口则同时作为控制台,供上位机实时发送 AT 指令、监控温度或校准参数。
自动化测试与辅助输入 (HID Mouse + CDC ACM):Ameba 组合了 HID 鼠标与 CDC 串口功能。在此场景下,CDC 接口负责接收来自后台脚本或传感器的原始数据(如坐标指令、头部追踪数据),HID 接口则根据这些指令模拟光标移动和点击动作,广泛应用于硬件自动化测试工具或残障辅助输入设备。
协议简介
USB 复合设备 (USB Composite Device) 规范定义了在 USB 规范框架下,通过单一物理接口同时承载多个独立功能接口的设备架构。 该机制允许主机将单一物理设备识别并枚举为多个逻辑功能的集合,实现不同功能类(如 HID、MSC、CDC 等)的并行处理与独立控制。 遵循该架构的常见设备包括无线键鼠接收器、带声卡的 USB 耳机及集成了存储与调试功能的工业设备等。
复合驱动仅负责顶层管理,具体子功能(如 HID 的报文格式、CDC 的通信协议)的数据处理需遵守其 对应的类协议规范,请参阅相关章节。
描述符结构
复合设备在遵循标准 USB 描述符(设备描述符、配置描述符)的基础上,通过在配置描述符集合中聚合多个接口描述符来实现多功能的定义。
单接口功能类
如果一个接口就代表了一个独立的功能,复合设备在聚合这种功能类的时候直接拼接使用。典型的单接口功能类有 HID 和 MSC。
以 HID 键盘 + HID 鼠标 复合设备为例,其描述符拓扑结构如下所示:
Device Descriptor
| bDeviceClass: 0xEF (Miscellaneous)
| bDeviceSubClass: 0x02 (Common Class)
| bDeviceProtocol: 0x01 (Interface Association Descriptor)
│
└── Configuration Descriptor
| bNumInterfaces: 2 (2 Interfaces)
│ ...
├── Interface Descriptor 0 (HID Keyboard)
│ bInterfaceNumber: 0
│ bInterfaceClass: 0x03 (HID)
│ bInterfaceSubClass: 0x01 (Boot Interface)
│ bInterfaceProtocol: 0x01 (Keyboard)
│
└── Interface Descriptor 1 (HID Mouse)
bInterfaceNumber: 1
bInterfaceClass: 0x03 (HID)
bInterfaceSubClass: 0x01 (Boot Interface)
bInterfaceProtocol: 0x02 (Mouse)
HID 键盘 + HID 鼠标 复合设备和单独的键盘/鼠标设备对比,描述符特征如下:
描述符层级 |
普通设备(Single Function) |
复合设备(Composite Device) |
|---|---|---|
设备描述符 |
|
|
配置描述符 |
1 个配置 |
1 个配置 |
接口描述符 |
1 个接口 |
有 2 个接口 |
端点描述符 |
归属于该接口 |
每个接口拥有独立的端点 |
备注
bDeviceClass = 0xEF:这是复合设备的标准标志,会触发主机驱动解析 IAD (可选)和配置描述符中的多个接口描述符,拆分出不同的设备功能,并创建这些逻辑子设备。
然后分别为 Interface 0 加载键盘驱动,为 Interface 1 加载鼠标驱动。
多接口功能类
如果一个逻辑功能需要占用多个接口才能完成,在使用这种功能类的时候必须加入 接口关联描述符 (Interface Association Descriptor, IAD) 将这些接口关联起来。
典型的多接口功能类
CDC (通信设备类): 通常需要 1 个控制接口 (CCI) + 1 个数据接口 (DCI)。
UVC (USB 视频类): 需要 1 个视频控制接口 (VC) + 1 个或多个视频流接口 (VS)。
UAC (USB 音频类): 需要 1 个音频控制接口 (AC) + 1 个或多个音频流接口 (AS)。
接口关联描述符(IAD)
IAD 向主机声明紧随其后的一组连续接口属于同一个功能,应由同一个驱动程序加载和管理。如果不加 IAD,主机有时候会把它们识别为两个独立的设备,或者驱动加载失败。
Interface Association Descriptor (IAD)
├── bLength : 1 byte → 0x08 (Fixed Length)
├── bDescriptorType : 1 byte → 0x0B (IAD type code)
├── bFirstInterface : 1 byte → First Interface Number
├── bInterfaceCount : 1 bytes → Count of associated interfaces
├── bFunctionClass : 1 byte → Function Class Code
├── bFunctionSubClass : 1 byte → Function SubClass Code
├── bFunctionProtocol : 1 byte → Function Protocol Code
└── iFunction : 1 byte → Function String Descriptor Index
IAD 使用示例
功能 1:设备类占用两个接口,为了让主机将其识别为单一的逻辑功能,必须使用 IAD 将这两个接口进行关联。
功能 2:设备类使用一个独立的接口,不需要 IAD 关联。
类特定请求
USB 协议规范中并没有定义专属的“复合类请求”,其核心逻辑在于通过 USB 标准请求中的寻址机制,将 类特定请求 (Class-Specific Requests) 精确指向指定的接口。
在 SETUP 包的 bmRequestType 字段中,低 5 位(Bits 0..4)表示 Recipient(接收者)。
普通单功能设备:控制请求通常是发给“整个设备”的,即将 Recipient 设置为
Device (00000)。复合设备:大量的控制请求必须精确地发给“特定的接口”,即将 Recipient 设置为
Interface (00001)。
以下是复合设备在控制请求处理上最显著的几个关键点:
字段 |
值 |
含义 |
复合设备中的体现 |
|---|---|---|---|
bmRequestType |
0x21 / 0xA1 |
Class Request, Recipient=Interface |
最常见。例如 CDC 设置波特率、HID 点亮键盘灯 |
wIndex |
Interface Number |
接口编号 |
当 Recipient 是接口时,wIndex 必须填入具体的接口号(如 0, 1, 2), 驱动必须根据这个值把请求分发给对应接口功能驱动处理 |
类驱动
本节详细分析如何设计并实现一个 USB 复合设备类驱动。复合类驱动充当“父类”角色,负责管理多个“子类”(如 CDC ACM、HID、MSC 等)的资源调度、请求分发和数据处理。
描述符结构
为了让主机正确识别复合设备及其包含的多种功能,驱动程序必须在运行时动态在组装一套完整、精确的描述符。在生成设备描述符的时候需要注意下面几点:
设备描述符
bDeviceClass:通常为 0xEF (Miscellaneous) 或 0x00 (由接口定义)。配置描述符
这是一个动态生成的“集合体”,包含了所有子功能的描述符。
bNumInterfaces:必须是所有子功能接口数量的总和。例如,一个 CDC 功能(占用 2 个接口)和一个 MSC 功能(占用 1 个接口)组成的复合设备,此值应为 3。wTotalLength:必须是所有描述符(配置、IAD、接口、端点)长度的总和。这个值需要在运行时精确计算。接口关联描述符 (IAD): 如果某个子功能包含多个接口(如 CDC ACM),必须使用 IAD 将这些接口“捆绑”在一起,声明它们同属于一个功能。
端点描述符
端点的配置必须根据芯片的硬件能力来配置,请参考 硬件配置 。
端点选择: 必须根据功能需求(IN/OUT)和硬件支持来选择可用的端点。
最大包长 (MPS): 需考虑硬件限制。尤其在使用专用发送缓存时,要确保 IN 端点的发送缓存区大小至少能容纳一个最大数据包。
CDC ACM + MSC 示例
下面以 CDC ACM + MSC 为例介绍复合设备的描述符拓扑结构,这些结构体对应于 USB 协议规范中的标准描述符定义。
CDC ACM(虚拟串口):占用两个接口,为了让主机将其识别为单一的逻辑功能,必须使用 IAD 将这两个接口进行关联。
MSC(大容量存储):是一个独立的接口,不需要 IAD 关联。
该复合设备共使用 5 个非零端点(不包含默认控制端点 EP0):
接口编号 |
接口类 |
端点 |
说明 |
|---|---|---|---|
Interface 0 |
CDC Control (ACM) |
1x Interrupt IN |
用于通知串口状态(Serial State)与管理命令。 |
Interface 1 |
CDC Data |
1x Bulk OUT, 1x Bulk IN |
负责虚拟串口数据的发送(OUT)与接收(IN)。 |
Interface 2 |
MSC (Mass Storage) |
1x Bulk OUT, 1x Bulk IN |
负责大容量存储设备的数据读写(SCSI 命令/数据)。 |
驱动中一般将各个描述符定义为数组,在获得配置描述符时,按顺序调用每个子功能类驱动的 get_descriptor 回调函数,将它们聚合在一起。
/* USB Standard Device Descriptor */
static const u8 usbd_composite_dev_desc[USB_LEN_DEV_DESC] = {
//...
0xEF, /* bDeviceClass: Miscellaneous */
0x02, /* bDeviceSubClass: Common Class */
0x01, /* bDeviceProtocol: Interface Association Descriptor */
//...
};
配置描述符不是固定数组,而是由框架在枚举时根据每个已注册子功能的描述符动态组装,直接写入 EP0 控制传输缓冲区:
配置描述符
├── 配置描述符头 (在此填写 bNumInterfaces、wTotalLength)
├── 子功能 1 <-- 由第一个 usbd_composite_xxx_init() 提供
│ ├── IAD(多接口时)
│ ├── 接口描述符
│ └── 端点描述符
├── 子功能 2 <-- 由下一个 usbd_composite_xxx_init() 提供
└── ...
这一设计带来三点影响:
wTotalLength和bNumInterfaces由框架自动计算,无需手动填写。usbd_composite_xxx_init()的调用顺序决定了主机看到的接口编号。组装后的描述符不能被截断,因此
usbd_config_t的ctrl_xfer_buf_len必须能容纳所有支持速率下的描述符总长度;若不足,枚举将直接失败,而不会返回一个被截短的描述符。
拥有多个接口的子功能(如 CDC ECM)会额外提供接口关联描述符(IAD),使主机将这些接口识别为同一个功能,框架也会将其接口计入 bNumInterfaces。
完整的设备描述符拓扑结构如下:
Device Descriptor
| bDeviceClass: 0xEF (Miscellaneous)
| bDeviceSubClass: 0x02 (Common Class)
| bDeviceProtocol: 0x01 (Interface Association Descriptor)
|
└── Configuration descriptor
| bNumInterfaces: 3 (3 Interfaces)
|
| /* Function 1: CDC ACM */
|
├── Interface Association Descriptor (IAD)
| bFirstInterface: 0
| bInterfaceCount: 2 (Associate Interface 0 with Interface 1)
| bFunctionClass: 0x02 (CDC Control)
| bFunctionSubClass: 0x02 (ACM)
|
├── Interface Descriptor 0 (CDC Control Interface)
| | bInterfaceNumber: 0
| | bInterfaceClass: 0x02 (CDC Control)
| | bInterfaceSubClass: 0x02 (ACM)
| | ...
| ├── CDC Class Specific Descriptors (Header, Call Mgmt, ACM...)
| └── Endpoint Descriptor (Interrupt IN)
|
├── Interface Descriptor 1 (CDC Data Interface)
| | bInterfaceNumber: 1
| | bInterfaceClass: 0x0A (CDC Data)
| | ...
| ├── Endpoint Descriptor (Bulk OUT)
| └── Endpoint Descriptor (Bulk IN)
|
| /* Function 2: MSC */
|
└── Interface Descriptor 2 (MSC Interface)
| bInterfaceNumber: 2
| bInterfaceClass: 0x08 (Mass Storage)
| bInterfaceSubClass: 0x06 (SCSI Transparent Command Set)
| bInterfaceProtocol: 0x50 (Bulk-Only Transport / BBB)
| ...
├── Endpoint Descriptor (Bulk OUT)
└── Endpoint Descriptor (Bulk IN)
备注
CDC ACM 描述符详细结构请参考: CDC ACM 协议简介
MSC 描述符详细结构请参考: MSC 协议简介
类驱动实现
复合设备由两部分组成:子功能类驱动(本身是普通类驱动),以及 usbd_composite.c 中的一个小框架,由它负责描述符组装和事件分发。应用层 不需要自己编写复合类驱动。
子功能类驱动
每个子功能(如 CDC、MSC、HID)都是一个独立的类驱动,详细请参考子功能方案的对应章节。
独立的驱动结构:每个子驱动定义一个标准的
usbd_class_driver_t结构体,实现自己的业务逻辑。独立的资源管理:每个子驱动负责管理自己的端点、数据缓冲区以及数据收发处理等。
复合能力:除独立的
usbd_xxx_init()外,每个类还提供usbd_composite_xxx_init()变体。该变体依据调用者传入的类配置结构体(usbd_cdc_acm_config_t、usbd_msc_config_t等)生成类配置,并通过usbd_composite_register_driver()把类驱动注册到复合框架中。
复合框架
复合层的
usbd_class_driver_t由框架持有,而非应用层。框架作为唯一的类驱动注册到 USB Core,并向各子功能分发:get_descriptor:由所有已注册子功能组装配置描述符,直接写入 EP0 控制传输缓冲区。set_config/clear_config:初始化或释放所有子功能的端点与资源。setup、ep0_data_out、ep0_data_in、ep_data_in、ep_data_out:按被寻址的接口或端点,把请求或传输路由给对应的子功能。sof/status_changed:转发给每个子功能。
子功能数量上限由
USBD_COMP_MAX_FUNCS决定,当前为 4。复合设备实例
框架内部维护一个
usbd_composite_dev_t实例,保存已注册的驱动数组、从描述符解析出的接口计数以及当前请求状态。应用层不会接触该实例,只需向usbd_composite_init()传入可选的usbd_composite_cb_t(目前仅含status_changed一个回调)。
CDC ACM + MSC 示例
下面以 CDC ACM + MSC 为例介绍应用层如何组装一个复合设备:
/*
* The composite framework owns the composite-level class driver. The
* sub-function drivers are registered into it, one per class, and the
* framework dispatches descriptor assembly, endpoint setup and every
* transfer to the sub-function that owns the interface or endpoint.
*/
/********************** Function 1: CDC ACM class *********************/
static const usbd_cdc_acm_config_t cdc_acm_class_cfg = {
.bulk_in_addr = COMP_CDC_BULK_IN_EP,
.bulk_out_addr = COMP_CDC_BULK_OUT_EP,
.intr_in_addr = COMP_CDC_INTR_IN_EP,
.bulk_in_xfer_size = CDC_BULK_IN_XFER_SIZE,
.bulk_out_xfer_size = CDC_BULK_OUT_XFER_SIZE,
.notify_en = 1,
};
static const usbd_cdc_acm_cb_t composite_cdc_acm_usr_cb = {
.init = composite_cdc_acm_cb_init,
.deinit = composite_cdc_acm_cb_deinit,
.setup = composite_cdc_acm_cb_setup,
.received = composite_cdc_acm_cb_received,
};
/********************** Function 2: MSC class *********************/
static const usbd_msc_config_t msc_class_cfg = {
.bulk_in_addr = COMP_MSC_BULK_IN_EP,
.bulk_out_addr = COMP_MSC_BULK_OUT_EP,
};
static const usbd_msc_cb_t composite_msc_usr_cb = {
.status_changed = NULL,
};
/********************** Register both sub-functions *********************/
/*
* Each usbd_composite_xxx_init() registers its class driver with the
* composite framework via usbd_composite_register_driver(), so there is no
* composite class driver to write by hand.
*/
ret = usbd_composite_cdc_acm_init(&composite_cdc_acm_usr_cb, &cdc_acm_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "CDC ACM init failed\r\n");
goto exit_usbd_init;
}
ret = usbd_composite_msc_init(&composite_msc_usr_cb, &msc_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "MSC init failed\r\n");
goto exit_cdc_acm_init;
}
/* Start the framework only once every sub-function is registered: the
configuration descriptor is assembled from them here. */
ret = usbd_composite_init(&composite_usr_cb);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "Composite init failed\r\n");
goto exit_msc_init;
}
复合框架内部对各子功能的分发机制:
复合层 usbd_class_driver_t 由框架自身实现,应用层无需编写任何回调。下表列出的回调都位于 usbd_composite.c 中,作用是遍历已注册的子功能;了解它们有助于排查枚举问题,但开发者并不需要实现它们。
回调 |
框架在其上的处理 |
|---|---|
|
把所有已注册子功能的配置描述符依次拼接到 EP0 传输缓冲区。拼接结果不会被截断:若长度超出 |
|
按注册顺序对每个子功能调用 |
|
按注册的逆序对每个子功能调用 |
|
查找拥有 |
|
把控制传输的数据阶段拆到两次中断中处理,使类驱动拿到的是完整的 OUT 载荷或完整的 IN 结果,而不是半包。 |
|
按 |
|
把连接状态传播给每个子功能,并通过 |
排查问题时有一点值得留意:由于描述符是由已注册的子功能集合组装而成,usbd_composite_xxx_init() 的调用顺序决定了主机看到的接口编号。
应用层回调 API
驱动为应用层提供了回调函数接口,以便应用代码能响应 USB 事件并处理业务逻辑。回调分为两级,分别传入。
Composite 应用层回调 API
usbd_composite_cb_t用于上报整个复合设备的状态,只包含一个status_changed回调。无论注册了多少个子功能,USB 连接状态变化时它只触发一次。子功能类应用层回调 API
每个子功能保留自己的回调类型,与独立模式完全相同:
usbd_cdc_acm_cb_t、usbd_msc_cb_t、usbd_hid_usr_cb_t、usbd_uac_cb_t等。将其传给该类的usbd_composite_xxx_init()即可,不会合并成一个复合结构体。各类支持的回调集合略有差异,请查阅对应章节。多数类共有的成员如下:
API
描述
init
在类驱动初始化时被调用,用于初始化应用相关的资源
deinit
在类驱动注销时被调用,用于释放应用相关的资源
setup
在控制传输 setup 或 data 阶段被调用,用于处理应用相关的控制请求
set_config
在类被配置时调用,通知应用该类已就绪,可以开始传输
status_changed
在 USB 连接状态改变时被调用,用于处理热插拔事件
transmitted
在 IN 传输完成时被调用,用于异步获取 IN 传输状态
received
在 OUT 传输完成时被调用,用于异步获取 OUT 传输状态
各类只实现自己实际拥有的回调:例如 MSC 除可选的
status_changed外基本为空,而 CDC ACM 与 HID 则实现了上表中的大部分。
CDC ACM + MSC 示例
下面以 CDC ACM + MSC 为例展示两级回调的传入方式(MSC 使用默认回调,留空即可):
/* Composite level: one callback for the whole device */
static const usbd_composite_cb_t composite_usr_cb = {
.status_changed = composite_cb_status_changed,
};
/* Sub-function level: each class keeps its own callback type */
static const usbd_cdc_acm_cb_t composite_cdc_acm_usr_cb = {
.init = composite_cdc_acm_cb_init, /* Application resource setup */
.deinit = composite_cdc_acm_cb_deinit, /* Application resource cleanup */
.setup = composite_cdc_acm_cb_setup, /* Class-specific control requests */
.received = composite_cdc_acm_cb_received, /* Data arrived on the BULK OUT endpoint */
};
/* MSC needs no application callbacks beyond the optional status change */
static const usbd_msc_cb_t composite_msc_usr_cb = {
.status_changed = NULL,
};
复合层回调在 usbd_composite_init() 中传入,每次连接状态变化只触发一次。各类回调则分别传给自己的 usbd_composite_xxx_init(),与独立模式完全一致——框架只保存各自的指针,并把事件路由给所属的类。
面向应用层 API
应用层按以下三步依序拉起复合设备,拆除时按相反顺序进行:
启动 Core:调用一次
usbd_init(),其usbd_config_t的ctrl_xfer_buf_len需覆盖所有子功能组装后的配置描述符长度。初始化各子功能:调用每个类的
usbd_composite_xxx_init()变体(例如usbd_composite_cdc_acm_init())。每个函数接收该类自己的回调集与类配置,并把对应的类驱动注册到复合框架中。usbd_composite_init():在所有类都初始化完成后启动复合框架,接收可选的复合层用户回调。此时所有类驱动必须已注册完毕,因为配置描述符正是在此处由它们组装而成。
卸载时按同样的顺序反向进行:先调用 usbd_composite_deinit() ,再逐个调用各类的 usbd_xxx_deinit(),最后调用 usbd_deinit() 。
两个卸载接口有同一个约束:必须在 任务上下文中调用。usbd_composite_deinit() 会屏蔽 USB 中断并清除所有已注册子功能的配置;usbd_unregister_class() (由各类的 deinit 内部调用)在中断上下文中会被拒绝,否则类在释放资源期间仍然可以被 ISR 访问。在中断上下文中调用二者都返回 -RTK_ERR_BADARG 且不做任何改动,此时调用者不应释放任何资源。同理,复合设备仍处于注册状态时调用类 deinit 不会产生任何效果,这就是必须先完成复合层卸载的原因。
CDC ACM + MSC 示例
下面以 CDC ACM + MSC 为例介绍复合设备类驱动面向应用层 API 实现:
/**
* @brief Init composite stack: core -> each class -> composite framework
* @return Status
*/
int composite_init_stack(void)
{
int ret;
/* Step 1: Initialize storage disk (must be done before usbd_init) */
ret = usbd_msc_disk_init();
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "MSC disk init failed\r\n");
return ret;
}
/* Step 2: Start USB device stack */
ret = usbd_init(&composite_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "usbd_init failed\r\n");
goto exit_disk_init;
}
/* Step 3: Initialize each class driver with its own callback set and EP config.
Each composite_init registers its class driver with the composite framework. */
ret = usbd_composite_cdc_acm_init(&composite_cdc_acm_usr_cb, &cdc_acm_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "CDC ACM init failed\r\n");
goto exit_usbd_init;
}
ret = usbd_composite_msc_init(&composite_msc_usr_cb, &msc_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "MSC init failed\r\n");
goto exit_cdc_acm_init;
}
/* Step 4: Start composite framework (drivers already registered in step 3) */
ret = usbd_composite_init(COMP_CB);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "Composite init failed\r\n");
goto exit_msc_init;
}
return RTK_SUCCESS;
exit_msc_init:
usbd_msc_deinit();
exit_cdc_acm_init:
usbd_cdc_acm_deinit();
exit_usbd_init:
usbd_deinit();
exit_disk_init:
usbd_msc_disk_deinit();
return ret;
}
/**
* @brief DeInit composite stack, in the reverse order: framework -> classes -> core
* @param void
* @return Status
*/
void composite_deinit_stack(void)
{
usbd_composite_deinit();
usbd_msc_deinit();
usbd_cdc_acm_deinit();
usbd_deinit();
usbd_msc_disk_deinit();
}
备注
详细类驱动说明请参考: 自定义设备方案
API 说明
应用示例
本节以 USB Composite (CDC ACM + MSC) 为例,介绍完整的应用实现和运行测试的方式。
应用设计
本节详细介绍复合设备驱动的完整开发设计流程,涵盖加载驱动、热插拔管理以及资源释放。
加载驱动
复合设备初始化过程需要依次加载 USB 核心初始化及 Composite 类驱动。定义配置结构体并注册用户回调函数是必要步骤。
步骤说明:
硬件配置:配置 USB 速度模式及中断优先级等。
回调注册:定义用户回调结构体
usbd_composite_cb_t和usbd_composite_fucntion_xx_usr_cb,挂载各个阶段的处理函数。加载核心驱动:调用
usbd_init()加载 USB 核心驱动。加载类驱动:调用
usbd_composite_init()加载复合类驱动。
下面以 CDC ACM + MSC 为例介绍加载复合设备驱动实现:
其中 MSC 功能大部分交互由协议栈自动处理,应用层主要关注磁盘的初始化与去初始化。 在 USB 初始化之前,必须先确保存储介质(如 SD 卡或 Flash)已就绪,并调用磁盘初始化接口。
static usbd_config_t composite_cfg = {
.speed = CONFIG_USBD_COMPOSITE_SPEED,
.isr_priority = CONFIG_USBD_COMPOSITE_ISR_THREAD_PRIORITY,
.intr_use_ptx_fifo = 0U,
};
/* CDC ACM class configuration: endpoint addresses and transfer sizing */
static const usbd_cdc_acm_config_t cdc_acm_class_cfg = {
.bulk_in_addr = COMP_CDC_BULK_IN_EP,
.bulk_out_addr = COMP_CDC_BULK_OUT_EP,
.intr_in_addr = COMP_CDC_INTR_IN_EP,
.bulk_in_xfer_size = CDC_BULK_IN_XFER_SIZE,
.bulk_out_xfer_size = CDC_BULK_OUT_XFER_SIZE,
.notify_en = 1,
.bulk_in_zero_copy = 0,
};
/* MSC class configuration */
static const usbd_msc_config_t msc_class_cfg = {
.bulk_in_addr = COMP_MSC_BULK_IN_EP,
.bulk_out_addr = COMP_MSC_BULK_OUT_EP,
};
/* Per-class user callbacks */
static const usbd_cdc_acm_cb_t composite_cdc_acm_usr_cb = {
.init = composite_cdc_acm_cb_init,
.deinit = composite_cdc_acm_cb_deinit,
.setup = composite_cdc_acm_cb_setup,
.received = composite_cdc_acm_cb_received,
};
static const usbd_msc_cb_t composite_msc_usr_cb = {
.status_changed = NULL,
};
/* Composite-level callback, optional */
static const usbd_composite_cb_t composite_usr_cb = {
.status_changed = composite_cb_status_changed,
};
int ret = 0;
/* Step 1: Initializes the underlying storage disk (must precede usbd_init). */
ret = usbd_msc_disk_init();
if (ret != RTK_SUCCESS) {
return;
}
/* Step 2: Initialize USB device core driver with configuration. */
ret = usbd_init(&composite_cfg);
if (ret != RTK_SUCCESS) {
usbd_msc_disk_deinit();
return;
}
/* Step 3: Initialize each class driver. Each registers itself with the composite framework. */
ret = usbd_composite_cdc_acm_init(&composite_cdc_acm_usr_cb, &cdc_acm_class_cfg);
if (ret != RTK_SUCCESS) {
usbd_deinit();
usbd_msc_disk_deinit();
return;
}
ret = usbd_composite_msc_init(&composite_msc_usr_cb, &msc_class_cfg);
if (ret != RTK_SUCCESS) {
usbd_cdc_acm_deinit();
usbd_deinit();
usbd_msc_disk_deinit();
return;
}
/* Step 4: Start the composite framework, after all classes are registered. */
ret = usbd_composite_init(&composite_usr_cb);
if (ret != RTK_SUCCESS) {
usbd_msc_deinit();
usbd_cdc_acm_deinit();
usbd_deinit();
usbd_msc_disk_deinit();
return;
}
热插拔事件处理
通过注册 status_changed 回调函数来监听 USB 连接状态变化(连接/断开)。
参考 设备连接状态检测 , 获取更多细节。
备注
建议使用信号量(Semaphore)通知专用任务线程进行处理,避免在中断上下文中执行耗时操作。
下面以 CDC ACM + MSC 为例介绍复合设备驱动热插拔事件处理:
static u8 composite_attach_status;
static rtos_sema_t composite_attach_status_changed_sema;
/* Composite-level USB status change callback */
static const usbd_composite_cb_t composite_usr_cb = {
.status_changed = composite_cb_status_changed,
};
/* Callback executed in ISR context */
static void composite_cb_status_changed(u8 old_status, u8 status)
{
composite_attach_status = status;
rtos_sema_give(composite_attach_status_changed_sema);
}
/* Thread Context: Handle the state machine */
static void composite_hotplug_thread(void *param)
{
UNUSED(param);
for (;;) {
/* Wait for status change signal */
if (rtos_sema_take(composite_attach_status_changed_sema, RTOS_SEMA_MAX_COUNT) == RTK_SUCCESS) {
if (composite_attach_status == USBD_ATTACH_STATUS_DETACHED) {
RTK_LOGS(TAG, RTK_LOG_INFO, "DETACHED\n");
/* 1. Tear the whole stack down, framework first */
composite_deinit_stack();
/* 2. Rebuild it for the next connection */
if (composite_init_stack() != RTK_SUCCESS) {
break;
}
} else if (composite_attach_status == USBD_ATTACH_STATUS_ATTACHED) {
RTK_LOGS(TAG, RTK_LOG_INFO, "ATTACHED\n");
} else {
RTK_LOGS(TAG, RTK_LOG_INFO, "INIT\n");
}
}
}
RTK_LOGS(TAG, RTK_LOG_ERROR, "Hotplug thread fail\n");
rtos_task_delete(NULL);
}
卸载驱动
在不再需要 USB 功能或系统关机时,需按加载的反序释放资源。 下面以 CDC ACM + MSC 为例介绍复合设备驱动卸载实现:
/* Tear down in the reverse order of composite_init_stack():
framework -> classes -> core -> disk */
usbd_composite_deinit();
usbd_msc_deinit();
usbd_cdc_acm_deinit();
usbd_deinit();
usbd_msc_disk_deinit();
运行方式
该示例演示了如何通过复合设备协议栈,将 Ameba 开发板配置为同时具备 CDC ACM(虚拟串口) 和 MSC(大容量存储) 功能的设备。
当开发板连接至 USB 主机(如 PC)时,系统将识别出两个独立的逻辑设备。用户既可以通过串口工具与开发板进行通信,也可以像操作普通 U 盘一样读写板载 SD 卡中的文件。
该示例路径: {SDK}/example/usb/usbd_composite_cdc_acm_msc ,可为开发者设计自定义 Composite 产品提供完整的参考方案。
配置与编译
编译与烧录
在 SDK 根目录下执行以下命令以配置环境,选择目标 SoC,编译工程,然后将生成的
Image文件烧录至开发板。# Initialize environment (required for every new terminal) source env.sh or env.bat(Windows system) # Select Target SoC (replace xxx with your specific SoCs) ameba.py soc xxx ameba.py build -a usbd_composite_cdc_acm_msc -p
Menuconfig 配置确认
若编译失败,请执行
ameba.py menuconfig,确认已勾选Composite function enable,并在 USB Device Class Selection 下同时选中CDC ACM与MSC。- Choose `CONFIG USB --->`: [*] Enable USB USB Mode (Device) ---> *** USB Device Global Settings *** [*] Composite function enable *** USB Device Class Selection *** [*] CDC ACM [*] MSC Select storage media (SD card, SDIO mode) --->Composite function enable是开启复合框架的开关。其下勾选的每个功能都会被加入同一个设备描述符。存储介质是单选,默认为 SD card, SDIO mode:
菜单项
对应符号
说明
FLASH (on-chip)
USBD_MSC_FLASH片内主 Flash,通过 VFS FATFS 挂载。
Second FLASH (NOR)
USBD_MSC_SECOND_FLASH外挂 SPI NOR。不支持 NAND:必须保持
CONFIG_VFS_SECOND_FLASH_NAND未选中,否则编译失败。SD card, SDIO mode
USBD_MSC_SD_CARD默认选项。需要板上的 SDIOH 插槽中有 SD 卡。
SD card, SPI mode
USBD_MSC_SD_SPI通过通用 SPI 主机连接的 SD 卡或 SD NAND。
RAM disk
USBD_MSC_RAMSRAM 或 PSRAM 中的 VFS RAM 盘。内容不持久:每次接入都会格式化为空盘。
FLASH与RAM通过 VFS 挂载 FATFS 卷;其余介质由 MSC 类通过ll_diskio_drv直接访问。使用FLASH介质时,example_usbd_composite_cdc_acm_msc.c中的COMP_MSC_FLASH_VFS_REGION决定所用区域(VFS1 或 VFS2,默认 VFS2)。
结果验证
启动设备
重启开发板,观察串口日志,应显示如下启动信息:
[COMP-I] USBD ACM+MSC comp demo start [MSC-I] Disk init [USBD-A] INIT [MSC-I] Init [COMP-I] ATTACHED
连接主机
用 USB 线缆将开发板连接到 PC。
当该设备连接至 Windows 主机时,设备管理器将呈现如下层级结构:
通用串行总线控制器下出现:USB Composite Device (由 usbccgp.sys 驱动)。通用串行总线控制器下出现:USB 大容量存储设备 (对应 MSC 功能)。端口 (COM 和 LPT)下出现:USB 串行设备 (COMx) (对应 CDC ACM 功能)。
功能验证 1:CDC ACM (虚拟串口)
在 PC 端打开串口调试工具(如 Realtek Trace Tool)。
选择 Ameba 枚举出的虚拟串口号。
发送任意字符,开发板将原样回传接收到的数据,验证通信正常。
功能验证 2:MSC (大容量存储)
PC 端文件管理器中应自动弹出一个新的可移动磁盘盘符。用户可以双击打开该盘符,对插入的 SD 卡进行文件读写操作。
备注
本示例使用 SD 卡作为 MSC 的底层存储介质,请确保开发板板载 SDIOH 插槽 中已插入一张格式化好的 SD 卡。 请避免在数据读写过程中拔出 SD 卡或断开 USB 连接,以免造成文件系统损坏。