3. Linux USB子系统概览
Linux USB子系统是操作系统中最复杂的设备管理框架之一，它既要支持主机侧（Host）的成千上万种USB外设，又要支持设备侧（Device/Gadget）的USB外设功能模拟。对于USB Gadget驱动开发者而言，理解整个子系统的分层架构、数据流路径以及各层之间的接口约定，是编写高质量驱动的前提。本章将从全局视角拆解Linux USB子系统的四大核心模块：USB Core、HCD（Host Controller Driver）、Gadget Framework以及用户空间接口，并重点剖析Gadget框架在其中的位置与作用。
上图展示了Linux USB子系统的整体分层架构。从纵向看，系统分为用户空间、内核核心层、控制器驱动层和硬件层。Gadget框架位于内核核心层与设备控制器驱动之间，它向下屏蔽了不同UDC（USB Device Controller）硬件的差异，向上提供了统一的usb_gadget、usb_ep等抽象接口。理解这个分层关系，是后续编写Gadget驱动的第一块基石。
3.1 USB Core：主机侧与设备侧的中枢
USB Core是Linux内核中管理USB总线所有公共逻辑的模块，它不直接操作硬件，而是为HCD和Gadget框架提供基础设施服务。在主机侧，USB Core负责总线枚举、设备配置、电源管理、带宽分配等；在设备侧，USB Core通过udc-core.c管理UDC驱动的注册与注销，并维护Gadget设备的状态机。
USB Core的核心数据结构包括：
- struct usb_device：代表一个USB设备，包含设备描述符、配置列表、端点信息等。
- struct usb_interface：代表一个接口（Interface），是驱动绑定的基本单位。
- struct usb_gadget：代表设备侧的USB设备，由UDC驱动创建并注册到USB Core。
- struct usb_ep：代表一个端点（Endpoint），Gadget驱动通过它进行数据传输。
对于Gadget开发者，USB Core提供的usb_add_gadget()和usb_del_gadget()是注册与注销Gadget设备的入口。此外，composite.c实现了复合设备框架，允许将多个功能（如ACM串口、RNDIS网卡、Mass Storage）组合成一个物理设备，这是现代USB Gadget开发最常用的方式。
核心原理：USB Core在设备侧并不直接处理端点数据，而是通过usb_gadget_ops回调函数（如ep_enable、ep_queue）将请求转发给UDC驱动。这种设计使得Gadget功能驱动（如f_serial.c）可以完全与硬件无关，只需调用标准API即可。
3.2 HCD与Gadget框架：两条独立的数据通路
HCD和Gadget框架虽然都位于USB Core之下，但它们服务完全不同的角色。HCD驱动主机控制器（如Intel xHCI、Synopsys DWC3的Host模式），负责管理连接到下行端口的设备；而Gadget框架驱动设备控制器（如DWC3的Device模式、ChipIdea），让SoC本身作为一个USB外设出现在主机面前。
两条通路的关键差异如下表所示：
| 对比维度 | HCD (Host侧) | Gadget框架 (Device侧) |
|---|---|---|
| 数据对象 | URB (USB Request Block) | usb_request |
| 核心结构 | struct usb_hcd, struct urb | struct usb_gadget, struct usb_ep |
| 端点方向 | 从主机视角看设备端点 | 从设备视角看自身端点 |
| 典型驱动 | ehci-pci, xhci-hcd | dwc3, chipidea, renesas_usb3 |
| 枚举角色 | 主动发送SETUP令牌 | 被动响应主机请求 |
在Gadget框架内部，udc-core.c负责管理UDC驱动的生命周期。每个UDC驱动需要实现usb_gadget_ops结构体中的回调，包括udc_start、udc_stop、pullup等。当Gadget功能驱动需要发送数据时，它通过usb_ep_queue()将一个usb_request挂到端点上，UDC驱动负责将其转化为硬件DMA操作。
3.3 用户空间接口：从内核到应用的桥梁
用户空间接口是Gadget驱动与应用程序交互的窗口。Linux提供了多种机制让用户程序控制和使用Gadget功能：
- ConfigFS (usb_gadget)：通过
/sys/kernel/config/usb_gadget/目录动态创建和配置Gadget设备，无需编写内核代码即可组合功能。 - FunctionFS (FFS)：允许用户空间程序直接实现USB功能，通过
/dev/ffs-*文件描述符进行端点读写。 - Legacy Gadget接口：如
/dev/ttyGS0（串口）、/dev/loopX（存储），由内核中的功能驱动创建的标准设备节点。 - sysfs属性：用于查询UDC状态、当前连接速度、VBUS状态等。
- 先向UDC写入空字符串，断开设备：
echo "" > UDC - 删除旧功能链接：
rm configs/c.1/acm.usb0 - 创建新功能并链接：
mkdir functions/rndis.usb0 && ln -s functions/rndis.usb0 configs/c.1 - 重新绑定UDC：
echo "dwc3.0" > UDC - 混淆HCD与Gadget的端点概念：HCD的端点是从主机视角描述的，而Gadget的端点是从设备自身视角描述的。同一个物理端点，在两侧的编号和方向定义可能不同。
- 忽略UDC驱动的状态管理：UDC驱动不仅仅是数据通道，还负责VBUS检测、远程唤醒、挂起/恢复等电源管理事件。Gadget功能驱动必须正确处理这些事件，否则设备可能无法进入低功耗模式。
- 过度依赖ConfigFS而忽视内核编程：ConfigFS适合快速原型验证，但对于需要高性能或特殊控制逻辑的场景（如批量端点上的零拷贝传输），仍需编写内核态Gadget驱动。
- 未区分USB 2.0与USB 3.0的端点特性：在USB 3.0中，批量端点支持突发传输（Burst），且新增了Streams功能。Gadget驱动需要根据UDC能力选择合适的数据传输方式。
以ConfigFS为例，创建一个ACM串口Gadget的典型流程如下：
# 挂载configfs
mount -t configfs none /sys/kernel/config
cd /sys/kernel/config/usb_gadget
# 创建gadget实例
mkdir g1 && cd g1
# 设置VID/PID
echo 0x1d6b > idVendor
echo 0x0104 > idProduct
# 创建配置和功能
mkdir configs/c.1
mkdir functions/acm.usb0
ln -s functions/acm.usb0 configs/c.1
# 绑定UDC
echo "musb-hdrc.0" > UDC上述命令执行后，主机侧将枚举出一个CDC ACM设备，用户空间通过/dev/ttyACM0即可通信。整个过程无需编写任何内核代码，体现了ConfigFS的灵活性。
经验提醒：在开发初期，建议优先使用ConfigFS验证硬件和UDC驱动是否正常，再考虑编写自定义Gadget功能驱动。这可以快速区分硬件问题与软件逻辑问题。
3.4 实战案例：基于DWC3的Gadget功能切换
某嵌入式平台使用Synopsys DWC3控制器，同时支持Host和Device模式。产品需求是：设备在启动时作为USB串口（ACM）与PC通信，运行特定命令后切换为USB网卡（RNDIS）模式。我们通过ConfigFS和UDC的pullup控制实现动态切换。
初始现象与约束：DWC3驱动已正确加载，/sys/class/udc/下可以看到dwc3.0节点。但直接切换功能时，主机侧无法正确重新枚举，需要手动断开VBUS。
分析过程：通过dmesg查看内核日志，发现切换时UDC驱动没有执行usb_gadget_disconnect()，导致主机侧仍认为设备在线。进一步检查ConfigFS操作，发现直接删除功能链接后，Gadget设备并未完全停止。
操作步骤：
结果对比：按照上述顺序操作后，主机侧能够正确识别RNDIS设备，网络接口正常出现。切换时间从原来的3秒缩短到1秒以内。
复盘经验：Gadget功能切换的核心是确保UDC先断开连接，再修改配置，最后重新连接。任何在连接状态下修改配置的操作都可能导致枚举失败。此外，DWC3的pullup回调会控制D+线路的上拉电阻，这是物理层断开的标志。
风险提示：在切换过程中，如果主机侧正在通过当前Gadget接口传输数据（如串口正在输出日志），强制断开可能导致主机驱动异常。生产环境中应设计应用层协议，先通知主机端准备断开，再执行切换。
3.5 常见误区与总结复盘
在理解Linux USB子系统的过程中，开发者常陷入以下误区：
总结来看，Linux USB子系统的设计精髓在于分层与抽象。USB Core提供了统一的设备模型，HCD和Gadget框架分别服务主机侧和设备侧，而用户空间接口则让应用层能够灵活控制Gadget功能。对于Gadget驱动开发者，重点应放在理解usb_gadget、usb_ep、usb_request这三个核心对象的关系，以及它们如何与UDC硬件交互。下一阶段的学习应围绕具体UDC驱动（如DWC3、ChipIdea）的源代码展开，结合硬件手册深入理解端点调度、DMA描述符管理等底层细节。