APM32 USB Device Library 软件架构、文件体系与核心数据结构

1. 五层架构各模块技术职责拆解

1. Application 应用层：开发者业务代码，接收 USB 上报事件，处理业务逻辑，调用库对外 API。
2. USB Device Library 库层
   • Core 模块：维护 USB 设备完整状态机；Translation 模块处理四种 USB 传输；Request 模块处理 USB Chapter9 标准请求；提供各类中断回调入口。
   • Class 模块：实现各个 USB 设备子类协议，向 Core 注册回调函数，响应主机的类特定请求、数据收发。
3. Device Configuration 配置层：存放设备描述符、字符串描述符、硬件回调函数，完成产品 VID/PID、字符串、端点参数配置。
4. Device Driver 设备驱动层：芯片适配抽象层，屏蔽不同 APM32 系列寄存器差异。
5. USB Driver 硬件驱动层：直接操作 MCU 的 USB 外设寄存器，完成 FIFO、时钟、中断硬件初始化。

资料获取：APM32 USB Device Library应用笔记

2. 库完整文件目录结构说明

库文件存放路径为APM32_USB_Library\Device，分为两大子文件夹：

1. Class 文件夹：各类 USB 设备类实现
   • CDC、CustomHID、HID、MSC、WINUSB 五个子目录，每个目录存放对应类的.c/.h 源文件。
2. Core 文件夹：USB 内核协议栈
   • Inc 子目录：usbd_config.h、usbd_core.h、usbd_dataXfer.h、usbd_stdReq.h
   • Src 子目录：usbd_core.c、usbd_dataXfer.c、usbd_stdReq.c

3. 关键源文件功能解析

Core 内核文件

1. usbd_core.c/h：USB 设备状态机，设备初始化、复位、挂起、恢复、连接断开、SOF 事件处理，对外核心 API USBD_Init / USBD_DeInit。
2. usbd_dataXfer.c/h：端点 0 控制传输收发函数，Setup 请求解析。
3. usbd_stdReq.c/h：实现 USB Chapter‑9 全部标准主机请求（GetDescriptor、SetAddress、SetConfiguration 等）。

Class 设备类文件

• HID：usbd_hid.c/h，实现标准鼠标、键盘 HID；
• CustomHID：usbd_customhid.c/h，自定义报告描述符，支持双向收发；
• MSC：usbd_msc.c/h、usbd_msc_bot.c/h、usbd_msc_scsi.c/h，BOT 批量传输 + SCSI 命令处理；
• CDC：usbd_cdc.c/h虚拟串口实现；
• WinUSB：usbd_winusb.c/h微软免驱协议实现。

用户配置文件

• usbd_board.c/h：USB 硬件配置、硬件初始化、回调函数；
• usb_descriptor.c/h：全部 USB 描述符（设备、配置、字符串）；
• usb_device_user.c/h：用户侧 USB 初始化入口；
• usb_interface.c/h：用户数据接口注册。

4. 四大核心数据结构体详解

1. USBD_REQ_SETUP_T：Setup 包请求解析结构体 用于解析主机下发的 Setup 8 字节请求包，包含bmRequest、bRequest、wValue、wIndex、wLength字段，内核收到控制请求后填充该结构体，交给 Class 层处理。
2. USBD_DESC_T：描述符回调结构体 汇集设备描述符、配置描述符、字符串描述符、BOS 描述符、WinUSB OS 描述符等全部描述符回调函数指针，用户修改描述符即配置该结构体内部回调。
3. USBD_CLASS_T：USB 设备类处理结构体 每一个 USB 设备类对应该结构体实例；包含类名字、初始化 / 反初始化回调、Setup 请求回调、IN/OUT 端点数据收发回调、ISO 同步传输异常回调。Class 驱动向 Core 内核注册该结构体完成挂载。
4. USBD_INFO_T：USB 设备实例总控结构体 保存设备完整运行状态：设备状态、地址、速度、端点状态数组、描述符指针、注册的 Class 数组、Setup 请求缓存、用户回调函数，整个 USB 库运行的核心上下文。

5. 各类 USB Class 底层协议依据