Zephyr RTOS 与 USB 协议栈

roboto_usb2can 固件并非传统的裸机轮询程序，而是构建在 Zephyr RTOS 之上的事件驱动型嵌入式应用。本章面向已具备 Zephyr 基础的开发者，深入剖析其 RTOS 集成策略、USB 协议栈的选型演进、GS-USB 类的描述符体系，以及从设备树到应用代码的完整硬件抽象链路。理解这些设计决策，是后续分析 CAN 监控机制与 LED 状态系统的前提。

Zephyr 工作区架构与依赖管理

项目采用 Zephyr 标准的 west manifest 工作流管理多仓库依赖。west.yml 声明了两个核心上游：zephyrproject-rtos/zephyr 提供 RTOS 内核与驱动框架，CANnectivity/cannectivity 提供 GS-USB 设备类实现与协议兼容层。这种分离策略使得 USB2CAN 协议逻辑可以独立于内核版本演进，同时通过 import: true 自动继承 Zephyr 的子模块依赖图。在 CI 流程中，构建环境通过 west init -m 将本仓库挂载为 samples/roboto_usb2can，再执行 west update 拉取完整工作区，最终调用 Zephyr SDK 完成交叉编译。CMakeLists.txt 设置了 BOARD_ROOT 指向项目根目录，使自定义板级定义无需侵入 Zephyr 源码树即可被构建系统识别。

Sources: west.yml, zephyr-build.yml, CMakeLists.txt

板级支持包与设备树抽象

固件运行在一块基于 STM32G431CBT6 的定制硬件上，Zephyr 通过**设备树（DeviceTree）**完成全部硬件抽象。boards/roboto_usb2can/ 目录下包含完整的板级支持包（BSP），其中 roboto_usb2can.dts 是理解硬件绑定的核心文件。该 DTS 引入 stm32g431X8.dtsi 获取 SoC 级外设定义，并在此基础上实例化三个关键节点：

首先是 UDC（USB Device Controller）节点 zephyr_udc0，它通过 &usb 引用使能 STM32 内置的 USB FS 外设，绑定 PA11/PA12 为 DM/DP 引脚，并选择 HSI48 作为 48 MHz 的 USB 时钟源。其次是 GS-USB 设备节点 gs_usb0，其 compatible 为 "gs_usb"，这个字符串是 CANnectivity 驱动在 Zephyr 设备模型中注册的标识符，应用层通过 DT_NODELABEL(gs_usb0) 获取设备句柄。最后是 CANnectivity 通道聚合节点 cannectivity，它将 fdcan1 CAN 控制器与 counters2 时间戳计数器关联为逻辑通道 channel0，实现了物理 CAN 外设到 GS-USB 协议通道的映射。

graph TD
    A[Application Layer] -->|DEVICE_DT_GET| B[gs_usb0<br/>compatible: gs_usb]
    B -->|gs_usb_register| C[cannectivity<br/>channel0]
    C -->|can-controller| D[fdcan1<br/>STM32 FDCAN]
    C -->|timestamp-counter| E[counters2<br/>TIM2 Counter]
    B -->|zephyr_udc0| F[STM32 USB FS<br/>PA11/PA12]
    style B fill:#e1f5fe
    style C fill:#fff3e0

板级 YAML 文件进一步声明了硬件能力签名（supported: can, gpio, usb_device, usbd），使 Zephyr 的测试框架与构建系统能够自动验证板级配置的完备性。

Sources: roboto_usb2can.dts, roboto_usb2can.yaml, Kconfig.roboto_usb2can

USB 协议栈演进：从 Legacy 到 Stack-NEXT

本项目最显著的架构决策之一，是完全弃用 Zephyr Legacy USB 设备栈，全面迁移至 USB Device Stack-NEXT。在 prj.conf 中，所有以 CONFIG_USB_DEVICE_ 为前缀的 Legacy GS-USB 选项均被注释，取而代之的是 CONFIG_USB_DEVICE_STACK_NEXT=y 及其配套的 CONFIG_USBD_GS_USB 新栈配置。这一迁移并非简单的 API 替换，而是架构范式的转变：

Legacy 栈采用静态描述符表和全局回调注册机制，配置分散在 Kconfig 与代码宏之间；而 Stack-NEXT 引入了显式的 USBD Context 模型，描述符、配置、接口类均作为独立对象在运行时通过 usbd_add_descriptor()、usbd_register_class() 等 API 挂载到上下文对象上。这种对象化设计使得多配置、多速度、多接口的复杂设备描述符管理变得可组合、可测试。main.c 中的宏 USBD_DEVICE_DEFINE(usbd, ...) 即是在编译期实例化该上下文，并绑定到设备树中的 zephyr_udc0 控制器。

维度	Legacy Stack	Stack-NEXT (Current)
启用宏	`CONFIG_USB_DEVICE_STACK`	`CONFIG_USB_DEVICE_STACK_NEXT`
GS-USB 类	`CONFIG_USB_DEVICE_GS_USB`	`CONFIG_USBD_GS_USB`
描述符管理	静态数组/Kconfig 拼接	运行时对象挂载 (`usbd_add_*`)
设备上下文	隐式全局	显式 `struct usbd_context`
多配置支持	有限	原生支持
初始化模式	`usb_enable(NULL)`	`usbd_init()` + `usbd_enable()`

为保持与旧版 Linux gs_usb 驱动的兼容性，新栈同时启用了 CONFIG_USBD_GS_USB_COMPATIBILITY_MODE=y，这确保了描述符布局与请求处理行为在协议层面与 candleLight 等主流实现保持一致。

Sources: prj.conf, main.c

GS-USB 设备类与描述符体系

GS-USB（Geschwister Schneider USB）是 Linux 内核原生支持的 CAN 适配器 USB 类协议，本项目通过 CANnectivity 模块实现了完整的设备端协议栈。固件在 USB 层面的身份标识为 VID 0x1D50 / PID 0x606F，制造商字符串 "wentywenty"，产品字符串 "roboto_usb2can"。

标准描述符链

在 main() 的初始化序列中，应用层按严格时序向 USBD Context 注册描述符：语言描述符 → 厂商字符串 → 产品字符串 → 序列号 → 全速配置描述符 → GS-USB 类实例。usbd_device_set_code_triple() 将接口类、子类、协议码全部置零，这是 GS-USB 协议的惯例（使用 Vendor-Specific 类），避免操作系统误加载内置驱动。usbd_device_set_bcd_usb() 被显式设为 USB_SRN_2_0_1（0x0201），这是触发 Windows 读取 BOS 描述符的关键前提。

BOS 与 MSOS 2.0：免驱设计的核心

为实现 Windows 8.1+ 的即插即用免驱体验，固件实现了 Microsoft OS 2.0 Descriptors 体系。roboto_usb2can.h 中定义了三个层次的描述符结构：

MSOS 2.0 描述符集 (msos2_desc)：包含兼容 ID（WINUSB）与设备接口 GUID，GUID 采用 candleLight 兼容值 {c6e515a2-8dc6-4fc4-a03c-9325555d68e6}，确保上位机工具与现有生态兼容。
BOS Platform Capability (bos_cap_msosv2)：通过 UUID DF60DDD8-8945-C74C-9CD2-659D9E648A9F 向主机宣告 MSOS 2.0 支持，并携带供应商请求码 0x01。
供应商请求处理器 (msos_vendor_handler)：当主机通过 bRequest=0x01、wIndex=MS_OS_20_DESCRIPTOR_INDEX 发起控制传输时，该处理器将 msos2_desc 复制到响应缓冲区，完成 WinUSB 驱动绑定。

sequenceDiagram
    participant Host as Windows Host
    participant UDC as STM32 USB FS
    participant App as Application (main.c)

    Host->>UDC: GET_DESCRIPTOR (BOS)
    UDC->>Host: BOS + MSOSv2 Platform Cap
    Host->>UDC: Vendor Request 0x01<br/>(wIndex = 0x07)
    UDC->>App: msos_vendor_handler()
    App->>UDC: Return msos2_desc<br/>(CompatibleID=WINUSB + GUID)
    UDC->>Host: MSOS 2.0 Descriptor Set
    Host->>Host: Bind WinUSB driver<br/>(Plug & Play)

Sources: main.c, main.c, roboto_usb2can.h

内存、线程与实时性配置

作为一款 USB-CAN 协议转换适配器，固件需要在有限的 144 KB SRAM 内同时承载 USB DMA 缓冲区、协议栈工作队列、CAN 帧缓冲与 RTOS 内核对象。prj.conf 中的资源分配体现了明显的空间优化导向：

UDC 缓冲区池：CONFIG_UDC_BUF_COUNT=48 与 CONFIG_UDC_BUF_POOL_SIZE=4096 构成了 USB 控制器端的固定块内存池，用于端点 FIFO 与 DMA 描述符。48 个 buffer 对于单通道全速 USB 的批量传输场景足够覆盖主机调度延迟。
GS-USB 专用池：CONFIG_USBD_GS_USB_POOL_SIZE=64 为 CANnectivity 协议层提供对象池，避免在帧收发路径上发生堆分配。
线程栈：RX/TX 线程各分配 2048 bytes 栈空间，优先级设为 -1（即 Cooperative 优先级，仅低于中断）。这种设计保证了 CAN 帧在 USB 总线上的传输时序不会因其他内核线程抢占而抖动。
系统级裁剪：CONFIG_SERIAL=n、CONFIG_CONSOLE=n、CONFIG_LOG=n 关闭了所有调试输出通道；CONFIG_SIZE_OPTIMIZATIONS=y 启用 -Os；CONFIG_ASSERT=n 移除断言检查。对于量产固件，这些裁剪将 Flash 占用压缩到极致，使 128 KB 的 Flash 在容纳 Bootloader、RTOS、USB 栈、CAN 驱动与应用逻辑后仍有余量。

Sources: prj.conf

初始化时序与事件驱动模型

main.c 的初始化流程严格遵循先外设后协议、先注册后使能的原则，其顺序直接决定了系统的稳定性：

LED 子系统初始化 (status_led_init())：最先完成，确保后续任何错误状态均可通过视觉反馈呈现。
CAN 错误监控注册：遍历 can_devices 数组，为每个物理 CAN 控制器挂载 can_state_change_callback。该回调实现了错误帧洪水检测与强制 Bus-Off 保护逻辑。
GS-USB 协议注册：调用 gs_usb_register()，将 gs_usb0 设备句柄、fdcan1 通道数组与 ops 回调结构体（含 status_led_event）绑定到 CANnectivity 协议栈。
USB 描述符与类注册（Stack-NEXT 路径）：依次挂载字符串、配置、GS-USB 类、BOS 描述符，随后调用 usbd_init() 进行协议层状态机初始化，最后 usbd_enable() 使能 UDC 中断与端点。
就绪宣告：设置蓝灯为 LED_USB_READY，主线程退出，系统完全转入中断与 work queue 驱动的事件循环。

在整个生命周期中，CAN 状态变更与 GS-USB 事件构成了两条主要的事件流。CAN 状态回调运行在中断上下文，直接操作 can_error_monitor 状态机；GS-USB 事件（如 GS_USB_EVENT_CHANNEL_ACTIVITY_RX）则通过 status_led_event 回调触发 LED 状态更新，两者通过 k_work_delayable 与 k_timer 安全地将事件递送到系统工作队列执行。

Sources: main.c, led.c

下一步阅读指引

Zephyr RTOS 与 USB 协议栈为整个适配器提供了操作系统基底与主机通信能力。在此基础上，CAN 总线侧的错误监控与保护机制构成了可靠性核心，而 LED 控制系统则将这些内部状态翻译为人类可感知的视觉信号。建议按以下顺序继续深入：

如需理解 CAN 总线侧的错误帧洪水检测、Bus-Off 自动保护与状态恢复逻辑，请参阅 CAN 总线监控与错误保护机制。
如需分析三灯状态机的实现细节、Zephyr work queue 的时序设计，以及 GS-USB 事件到 LED 模式的映射关系，请参阅状态指示与 LED 控制系统。
如需了解上位机工具如何基于 WinUSB/libusb 与固件交互，请参阅上位机工具开发。