跳转至

A20OS USB 子系统设计

状态:已实现(HID + Mass Storage + xHCI)。当前共享实现为 kernel/drivers/usb/(core/usb_core.c、host/xhci.c、class/usb_hid.c、class/usb_storage.c)。generic 在 tools/mk/driver-modules.mk 实际列出的 x86_64/aarch64/loongarch64 上通过 xhci.a20drv、usb-hid.a20drv、usb-storage.a20drv 部署;embedded 静态链接这些共享源码。

与原生驱动模型的关系

HCD、hub 和 interface driver 使用同一设备绑定/发布/退出模型;USB 的 URB、slot 和 endpoint 仍是子系统协议,不因 native queue 出现而自动替换。consumer 借用硬件可达 URB/ring 时,先通过 slot abort、endpoint release 或 pre-consumer prepare 确认停止,再允许相应存储交还。通用 execution stop 位于 consumer 解绑之后、call drain 之前,不能代替更早的借用解除。普通 ready 检查也不能代替在途 callback/code/context 的排空。完整共同顺序见核心生命周期。

1. 背景与目标

A20OS 最初的 USB 驱动是窄用途的 kernel/drivers/input/xhci_hid.c(1165 行):硬编码绑定 Intel 8086:1e31 XHCI 控制器,只解析 HID 1.11 boot protocol 键盘/鼠标,轮询工作,单控制器单实例(静态 g_xhci)。它没有 USB 设备树、没有 URB 抽象、不支持存储设备、不支持热插拔。该文件已随通用 USB 子系统落地而移除,HID 事件面迁入 kernel/drivers/usb/class/usb_hid.c(经 /dev/event0 mux kernel/drivers/input/input_mux.c 与 virtio-input 等输入源聚合)。

目标是引入一个通用 USB 子系统,使任意 USB 宿主控制器上的 HID 与 Mass Storage 设备通过统一模型工作,并接入现有输入/块设备类接口。

2. 现状评估(A20OS 已有基础)

已有能力 位置 说明
驱动模型 kernel/drivers/core/ device/driver/bus、publication/protocol、managed failed-probe 与可失败执行停止
总线热插拔钩子 device_hotplug(dev, BUS_EVENT_ADD/REMOVE) USB core 已用于 interface 发布和移除
PCI 枚举 kernel/drivers/bus/pci_bus.c 宿主控制器可作为 PCI 设备绑定
输入类接口 input_dev_ops_t(read/ioctl/poll)+ DEV_CLASS_INPUT HID 接入点,已存在
块类接口 block_dev_ops_t(read/write/flush/capacity/sector_size)+ DEV_CLASS_BLOCK MSC 接入点,已存在
XHCI 底层 历史 xhci_hid.c(已移除) MMIO、TRB/事件环、输入/输出上下文、命令与控制传输、端口枚举、轮询;重构为 kernel/drivers/usb/host/xhci.c 的 usb_hcd_t
内核线程 init_kthread 等 可承载枚举/轮询工作

落地通用 USB 时,既有驱动模型和输入/块类接口可复用,当时需要新增的三部分现在都已实现:

  1. USB 核心子系统:URB 抽象 + 设备/接口/端点模型 + 枚举流程;
  2. HCD(宿主控制器驱动)抽象:把 xhci_hid.c 的控制器逻辑重构为与协议解析解耦的可复用 HCD,暴露 URB 提交 + 根集线器端口管理;
  3. 动态设备生命周期:端口变化检测 → 枚举 → 总线热插拔发布 → 类驱动绑定,以及移除路径。

3. 总体架构

+-------------------------------------------------------------------+
|  VFS / devfs                     input 子系统 (evdev 风格)         |
|  block 层 (virtio_blk 等)  ←block_dev_ops_t        input_dev_ops_t|
+-------------------------------------------------------------------+
   |                                      |
   | class_device publish                 | class_device publish
+-------------------------------------------------------------------+
|                    USB 核心 (kernel/drivers/usb/core)              |
|  · usb_bus_type (bus_type "usb")  +  hotplug(BUS_EVENT_ADD/REMOVE) |
|  · usb_device/usb_interface/usb_endpoint(从描述符构建)            |
|  · URB 抽象(usb_urb_t:端点 + 传输类型 + 缓冲区 + 完成回调)      |
|  · 枚举流程:地址分配 → 配置描述符 → 接口解析 → 类驱动匹配          |
|  · 类驱动注册表:class/subclass/protocol → driver_t                 |
+-------------------------------------------------------------------+
   | URB 提交 / 完成                  | URB 提交 / 完成
+-------------------------------------------------------------------+
|      HCD 层 (kernel/drivers/usb/host)                               |
|  · usb_hcd_t:transfer(urb), poll_ports(), ring/event 队列, DMA     |
|  · xhci_hcd(由 xhci_hid 重构,独立实例 per-controller)             |
|  ·(远期)ehci/uhci/ohci_hcd                                       |
+-------------------------------------------------------------------+
   | PCI / platform 绑定
   bus_type "pci" → 宿主控制器 device_t

关键分层原则(遵循 A20OS 现有约定)

  • HCD 只负责传输,不解析 USB 协议;协议解析(HID/MSC)在类驱动。
  • USB 核心不依赖任何具体 HCD,只依赖 usb_hcd_t 接口。
  • 类驱动通过 device_id_t(vendor=USB class<<16|subclass<<8|protocol)在 usb 总线上匹配,沿用现有 driver_t 生命周期。
  • 当前没有已实现的“设备锁 > URB 锁 > 环锁”三级层级。xHCI 现在有真实生效的 xhci->lock(保护 command/event ring、endpoint 链、事件环游标与同步传输所有权),完成由 controller 自己的 INTx 驱动,USB core 的 process-context poll 保留为热插拔扫描与无 INTx 平台上的回退路径。同步传输靠 xfer_busy 所有权标志串行化而不是排队,HID/storage 各自的 class lock 与 xhci->lock 之间的单向顺序记录在锁顺序契约。仍未建立的是:同一 controller 上多个同步传输的排队、MSI/MSI-X 模式,以及 SMP 下的压力验证(门禁只跑单核)。

4. USB 核心设计

4.1 URB(USB Request Block)

typedef struct usb_urb {
    usb_device_t    *dev;
    usb_endpoint_t  *ep;        /* 目标端点 */
    uint8_t          transfer_type; /* CTRL/INT/BULK/ISO */
    uint8_t          direction;     /* IN/OUT */
    void            *buf;        /* 传输缓冲(DMA 一致或 bounce)*/
    size_t           len;
    int              status;
    void           (*complete)(struct usb_urb *urb);
    void            *ctx;        /* class-driver context */
} usb_urb_t;
  • xHCI endpoint 保存当前 pending URB,HCD 完成它;当前不是通用多项端点待办队列。
  • 中断传输(HID 报告)由 class 驱动重新提交,沿用同一条 event ring 进展路径——由 IRQ handler 驱动,core poll 负责热插拔扫描与回退。
  • 控制传输走核心封装:usb_control_msg()(标准请求 set/get,包 setup + data + status 三个阶段)。

4.2 设备树模型

usb_device_t             /* 逻辑设备:地址、速度、descriptor、配置 */
└─ usb_interface_t[]     /* 每个 interface 发布一个 device_t */
   └─ usb_endpoint_t[]   /* 端点描述符 */
  • 每个 usb_interface_t 发布一个 device_t(bus = "usb",hardware_id = { class, subclass, protocol, interface_number })。
  • 类驱动按 interface 的 class/subclass/protocol 匹配。

4.3 枚举流程

  1. HCD 轮询根集线器端口:XHCI_PORTSC 的 CSC/CCS 变化 → 复位端口。
  2. 新连接:先分配端口清理对象,再复位设备和分配 slot/address,读取 device/config descriptor 并解析 interface/endpoint。xHCI 由 Address Device 命令分配地址,不额外发送第二个 SET_ADDRESS。
  3. 为每个 interface 构建 device_t,调用 device_hotplug(..., BUS_EVENT_ADD),由统一核心注册、匹配并 probe class driver。
  4. 断开或枚举失败时先 offline 已发布 class,再检查 HCD abort_slot;只有停止成功才执行 interface REMOVE 并回收协议存储。任一步失败保留端口、slot/address、接口与 HCD,扫描/注销显式重试。部分发布也遵守这个顺序;slot 已停后不重复 abort。

alloc_slot 非零返回也可能交还非零 usb_slot_t.hcd 清理 token,核心必须保留;零 token 的未知控制器状态仍由 HCD 管理。失败清理无需新的分配,禁止覆盖 pending 端口。扫描只对真实枚举增加计数,扫描对同一连接最多尝试三次,物理断开才重置。整个 xHCI 退出另登记 remove prepare,在核心解绑下游接口前先排空 IRQ、确认控制器停机及 BME 清零,失败保留图。拓扑通过原生生命周期协调器串行保护;锁外 completion 由 controller/slot 计数保留,相关清理返回 -EBUSY 并可重试。同一物理控制器仍有待清理端口时暂停新 slot 分配,避免旧回调误用复用的编号。HID/hub 独立退出已接入 endpoint 释放;storage 的实例保留、活跃调用及 BOT 恢复已接入,其他 transfer 错误仍须分开验证;xHCI bulk 通过独立保留的 DMA 暂存对象解除对调用者存储的访问。详细契约见 原生运行时。 热插拔门禁排除启动报告重放,要求实际拔出后的第二次枚举和 ready;QMP 操作等待匹配命令的回包。

4.4 多控制器

  • 每控制器动态分配独立 xhci_controller_t(由 device_t->drv_priv 持有),USB core 最多登记 32 个 HCD(包括 hub 提供的下游总线)。xHCI 使用 ANY PCI ID 表再由 .match 精确检查 PCI class 0x0C0330。

5. HCD 接口(由 xhci_hid 重构而来)

typedef struct usb_hcd {
    const usb_hcd_ops_t *ops;
    device_t *hcd_dev;
    unsigned max_ports;
    uint8_t *port_state;
    usb_device_t **port_devices;
    void *priv;
} usb_hcd_t;

当前 usb_hcd_ops_t 由 start、poll、端口状态/复位、slot 初始化、EP0 control/descriptor、endpoint 配置、interrupt/bulk 提交、abort_slot 和 release_endpoint 组成;权威声明是 kernel/include/drivers/usb/usb.h,不存在文中旧草案的单一 submit_urb 或 stop 回调。

历史重构要点(已完成):

  • xhci_ring/enqueue/dispatch/wait_event/command/control → HCD 内部;
  • hid_keyboard_report/mouse_report/tablet_report → 移入 usb-hid 类驱动;
  • xhci_parse_hid/configure_hid → 由 usb 核心的 interface 枚举替代,端点/接口信息从描述符读取而非 HID 专属解析;
  • 轮询入口保留(xhci_op_poll,仍是热插拔扫描入口,也是无 INTx 平台和 a20.xhci.poll=1 时的回退);IRQ completion 路径已实现:probe 申领 INTx,xhci_irq_handler() 驱动 event ring 完成。

6. 类驱动

6.1 usb-hid(DEV_CLASS_INPUT)

匹配 class=3(HID)的 interface,产出 input_dev_ops_t,事件经 input class 聚合到 /dev/event0。当前只支持 boot protocol 键盘/鼠标;完整 HID report descriptor 解析仍在计划中。

6.2 usb-storage / BOT(DEV_CLASS_BLOCK)

  • 匹配 class=8(Mass Storage)、subclass=6(SCSI transparent)、protocol=0x50(BOT)。
  • Bulk-only transport:CBW/CSW 包 + bulk-in/out 端点。
  • 转发 SCSI 命令(INQUIRY/READ10/WRITE10/READ_CAPACITY),映射到 block_dev_ops_t(read/write 以 LBA 计)。
  • 复用 VFS block_cache + 现有文件系统(fat32/ext4/ntfs 可挂载)。

6.3 集线器

class/usb_hub.c 已实现 class=9 hub:通过父 HCD 转发 slot/control/abort,发布下游端口并保留相同的部分 slot 交还契约。递归枚举由 HCD 列表扫描推进;QEMU 门禁为 make smoke-usb-hub-x86_64,实体 hub/拓扑边界仍需对应平台证据。

usb_interface_release_endpoints() 供当前 remove 回调在 class drain 后逐项释放非 EP0 endpoint。HCD 的 release_endpoint 返回 0 才交还 URB/buffer 和 ring 所有权,错误保留未完成项并可重试。xHCI 先确认 Stopped,再 Drop Context/确认 Disabled;HID/hub probe/独立退出均使用可失败清理,其他 endpoint 继续工作。hub 另在子设备解绑前执行 prepare 关闭准入,下游退出失败不再枚举/重装状态 URB,存储仍等确认停止后交还。该 HCD 字段始于 ABI 10;URB 增加 actual_length 后当前模块 ABI 为 13,旧模块必须重建。完整契约见 接口独立退出。

同步 bulk 使用每控制器 64 KiB、页对齐的原生 DMA buffer,由 xfer_busy 串行使用;硬件只访问暂存区。完整成功返回 0,短包返回 -EMSGSIZE 并通过 URB actual_length 报告实际字节,IN 只拷回该前缀;STALL 返回 -EPIPE。超限/非法残余计数不交付数据,任意返回后 HCD 不再引用调用者 URB/buffer。对象等 controller 停止及 USB 图清理成功后才释放;actual_length 引入于 ABI 13,跨 64 KiB 边界已接入最多两段的同一 TD,首段短包/错误可匹配并计算实际长度,失败停止仍保留整份存储。make smoke-usb-bulk-x86_64 在专用空白镜像上执行真实读/写/比对/恢复,详见 暂存协议。

7. 线程 / 并发模型

  • 当前没有 per-controller 内核线程。kernel_progress_poll() 调用按约 20 ms(50 Hz)节流的 usb_core_poll(),后者扫描 HCD 端口并推进枚举/移除;input read/poll 还会推进 HID 事件。
  • xHCI 注册自己的共享 INTx handler;可用时由 IRQ 推进完成,未路由时回退轮询,回调在控制器自旋锁外执行。
  • register/scan/enumerate/unregister 由核心生命周期协调器串行保护;普通入口可嵌套但不压制 probe,进度 poll/usb_device_poll() 使用 try,忙时跳过,避免 class drain 死锁。相同 HCD 重入或活动下游期间注销上游返回 -EBUSY;注册容量预留和有界重选扫描允许其他 HCD 的回调增删。同步命令/控制/bulk 由 xfer_busy 串行化,不能在设备自旋锁内等待停止或 remove。完整契约见 拓扑与退役。

8. 内存 / DMA 模型

  • 传输缓冲:HCD 分配 DMA 一致内存(现有 xhci_ring 已用同一套页分配),类驱动经 URB 缓冲拷贝;避免类驱动直接碰 DMA 地址。
  • 描述符解析缓冲为内核堆,校验长度后使用(沿用 xhci_hid 的边界检查风格)。

9. 集成点与 Makefile

  • 共享目录是 kernel/drivers/usb/{core,host,class}/。usb_core.c 显式列入 GENERIC_KERNEL_SERVICE_SRCS;xHCI/HID/storage 显式列入 EMBEDDED_DEVICE_DRIVER_SRCS,generic 则由 tools/mk/driver-modules.mk 的架构包清单构建。不存在递归 wildcard 自动纳入。
  • bus_type "usb" 注册在 driver_core_init 之后(现有总线注册序列)。
  • 类驱动 DRIVER_REGISTER() 自动进入 .driver_init。

10. QEMU 验证矩阵

用例 QEMU 参数 验收
xhci + usb 键盘 -device qemu-xhci -device usb-kbd /dev/event0 出现键盘事件
xhci + usb 鼠标/平板 -device usb-tablet 鼠标事件
xhci + usb 存储 -drive ... -device usb-storage,drive=x 动态块设备 /dev/diskN,可挂载 fat32/ext4
无 HID 控制器 无 usb 设备 正常启动,无 panic
回归 现有 smoke-riscv64 等 不退化

仓库定义了 make smoke-usb-x86_64,但该目标只挂载键盘和鼠标并检查 HID 枚举,不覆盖 storage mount。其他表项是手工或未来扩展矩阵,不能从表格推断已有同名自动目标。

11. 历史里程碑与未来计划

Phase 1(历史计划,已实现):XHCI HCD 重构 + USB 核心 + HID boot。

  • 抽取 xhci_hid.c 控制器逻辑为 usb/host/xhci.c(usb_hcd_t)。
  • 新建 usb/core/:URB、usb_device/interface/endpoint、枚举、usb 总线、控制传输封装。
  • 新建 usb/class/usb_hid.c:boot 键盘/鼠标 → input_dev_ops_t。
  • QEMU usb-kbd/usb-tablet 通过;现有 xhci_hid 行为不回归。
  • 预计:~2500–3500 行(重构 + 新增)。

现状:Phase 1 与 Phase 2 已实现。kernel/drivers/usb/host/xhci.c、kernel/drivers/usb/core/usb_core.c、kernel/drivers/usb/class/usb_hid.c、kernel/drivers/usb/class/usb_storage.c 均已落地,xhci_hid.c 已删除;drvmod 侧 xhci.c/usb_hid.c/usb_storage.c 以模块形式提供(smoke-usb-x86_64)。

Phase 2(历史计划,已实现):BOT 存储。

  • usb/class/usb_storage.c:BOT + SCSI 子集 → block_dev_ops_t。
  • QEMU usb-storage 可挂载文件系统。
  • 预计:~1200–1800 行。

Phase 3:hub 已实现,其它 HCD 仍待开发。

  • 通用 hub 驱动和递归枚举见 §6.3。
  • EHCI/UHCI/OHCI(净室,参考规范)。可选。

12. 风险

  • xHCI 规范复杂:槽/端点上下文与 TRB 状态机。从 xhci_hid 重构时必须保持传输语义不变,否则键盘立即失效;重构后跑 smoke-* 兜底。
  • 热插拔竞态:设备移除与 URB 提交并发时,URB 队列与 class_device 生命周期需严格配对(沿用 class_device online 标记)。
  • 锁现状:xhci->lock 由 HCD 的 ops 与 IRQ handler 实际获取,同步传输由 xfer_busy 串行化;HID completion 自己取 h->lock,HCD 只在锁外回调;USB storage 的每实例锁已是 sleepable mutex,跨同步 bulk wait 持有它是合规的。拔出时 abort_slot() 先 Disable Slot 再释放端点 ring,smoke-usb-hotplug-x86_64 验证地址/slot 归还与重插。详见锁顺序契约。
  • 硬件覆盖有限:当前按 PCI xHCI class 0x0c0330 匹配,并在 QEMU/VirtualBox 模拟控制器上验证;真实控制器的固件、IOMMU、cache coherency 和错误恢复仍需单独验证。
  • BOT 已接入串行 reset recovery、endpoint halt 清理、数据短包/STALL 后的 CSW 收取及首次 CSW STALL 的单次重试;错误恢复失败阻止新 CBW,不自动重放写入。probe 保留 REQUEST SENSE/就绪重试,块 I/O 不把短数据当成成功。实际控制器/支持配置的验收仍按发布条件执行。

13. 与"设计原则"的一致性

  • 分层薄接口、无 ABI 互相包装依赖(USB core 不碰 Linux/native ABI)。
  • 不引入 POSIX 异步信号;HID 完成由 controller 的 INTx 驱动,class 回调仍走同步的 read/poll 路径,不新增异步完成回调接口。
  • 能力/权限、时间约束等 native 概念不进入 USB core。