4. USB Gadget框架解析

USB Gadget框架是Linux内核中用于实现设备端（Device/Peripheral）USB功能的软件抽象层。与主机侧（Host）的USB核心框架相对应，Gadget框架允许嵌入式设备（如开发板、手机、工业控制器）模拟成各种USB外设——从简单的串口（ACM）、网卡（ECM/RNDIS），到复杂的MTP、ADB、UVC摄像头等。理解Gadget框架的核心在于把握三个层次：UDC（USB Device Controller）驱动（硬件相关）、usb_gadget_driver（功能逻辑相关）以及UDC Core（中间调度层）。本章将深入解析这三者的关系、数据结构与工作流程，帮助开发者从“调用API”进阶到“理解机制”。

上图展示了Gadget框架的三层协作关系。功能层通过usb_gadget_driver描述“设备是什么”（如串口、网卡），UDC驱动层通过usb_gadget_ops控制“硬件怎么做”（如收发端点数据），而UDC Core则负责将两者动态绑定。下面我们逐一拆解每个模块的核心原理与实战要点。

4.1 gadget驱动模型：从主机视角到设备视角的转换

4.1.1 核心原理：为什么需要Gadget框架？

在传统主机侧USB驱动中，开发者面对的是usb_device、usb_interface等结构，内核USB核心负责枚举、配置、带宽管理等。但在设备侧，硬件角色完全反转：设备需要被动响应主机的控制请求，并主动提供端点（Endpoint）能力。Gadget框架的本质是将设备侧硬件能力抽象为可编程的端点集合，并提供一个类似主机侧usb_driver的注册机制，让功能驱动（如g_serial、g_ether）无需关心具体UDC硬件差异。

关键设计思想包括：

• 端点抽象：struct usb_ep代表一个物理端点，支持usb_ep_queue()提交请求、usb_ep_dequeue()取消请求。
• 请求对象：struct usb_request封装数据缓冲区、长度、完成回调，类似于主机侧的URB。
• 回调驱动：功能驱动通过注册setup()回调处理标准请求（如GET_DESCRIPTOR、SET_CONFIGURATION），通过bind()完成端点分配和初始化。

4.1.2 判断方法：如何区分UDC驱动与Gadget功能驱动？

初学者常混淆这两个概念。判断标准如下：

一个简单判断方法：如果代码中出现了readl/writel或访问struct dwc2_hsotg等私有数据，则属于UDC驱动；如果只调用usb_ep_queue()和usb_gadget_ops，则属于功能驱动。

4.1.3 案例拆解：一个最小gadget功能驱动的骨架

假设我们要实现一个自定义的vendor-specific gadget设备（不依赖现有function模块），核心代码如下：

static int my_bind(struct usb_gadget *gadget) {
    struct usb_ep *ep;
    /* 1. 获取端点 */
    ep = usb_ep_autoconfig(gadget, &my_hs_ep_desc);
    if (!ep) return -ENODEV;
    /* 2. 分配请求 */
    req = usb_ep_alloc_request(ep, GFP_KERNEL);
    /* 3. 准备数据缓冲区 */
    req->buf = kmalloc(MAX_PACKET_SIZE, GFP_KERNEL);
    req->complete = my_complete;
    return 0;
}

static struct usb_gadget_driver my_driver = {
    .function = "my_custom_gadget",
    .bind = my_bind,
    .unbind = my_unbind,
    .setup = my_setup,
    .disconnect = my_disconnect,
    .max_speed = USB_SPEED_HIGH,
};

int my_init(void) {
    return usb_gadget_probe_driver(&my_driver);
}

该案例展示了功能驱动的最小骨架：bind()中自动配置端点并分配请求，setup()中处理控制传输。实际项目中，my_setup()需要解析usb_ctrlrequest，根据bRequest类型返回描述符或执行类请求。

4.2 UDC驱动：硬件与内核的桥梁

4.2.1 核心原理：UDC驱动的职责边界

UDC驱动是Gadget框架中最接近硬件的部分。它需要完成以下任务：

1. 硬件初始化：使能时钟、配置PHY、复位控制器、初始化端点FIFO。
2. 中断处理：处理EP0事件（SETUP、DATA、STATUS）、端点完成中断、总线复位/挂起事件。
3. 端点管理：实现struct usb_ep_ops中的enable/disable/queue/dequeue等操作。
4. VBUS检测：通过GPIO或控制器内部寄存器监测VBUS状态，调用usb_gadget_vbus_connect()通知上层。

UDC驱动通过struct usb_gadget_ops向上层暴露能力：

struct usb_gadget_ops {
    int (*get_frame)(struct usb_gadget *);
    int (*wakeup)(struct usb_gadget *);
    int (*set_selfpowered)(struct usb_gadget *, int);
    int (*vbus_session)(struct usb_gadget *, int);
    int (*vbus_draw)(struct usb_gadget *, unsigned mA);
    int (*pullup)(struct usb_gadget *, int);
    int (*udc_start)(struct usb_gadget *, struct usb_gadget_driver *);
    int (*udc_stop)(struct usb_gadget *);
};

4.2.2 操作流程：从注册到运行的完整链路

以DWC2控制器为例，UDC驱动的生命周期如下：

• 平台驱动探测：dwc2_driver_probe()获取资源、初始化硬件，然后调用usb_add_gadget_udc()注册struct usb_gadget。
• 功能驱动绑定：当用户加载g_serial.ko时，UDC Core调用udc_start()，将usb_gadget_driver绑定到usb_gadget。
• 枚举开始：主机发送复位信号，UDC驱动检测到后调用usb_gadget_udc_reset()，随后进入EP0 SETUP处理循环。
• 数据传输：功能驱动调用usb_ep_queue()，UDC驱动将请求翻译为DMA描述符或FIFO写入操作。

4.2.3 实战场景：调试UDC中断风暴

背景：某平台使用DWC3控制器，在插入USB线时系统卡死，日志显示dwc3_interrupt频繁触发。
分析：通过/proc/interrupts查看中断计数，发现每秒增长数万次。使用perf top定位到dwc3_ep0_interrupt。
根因：PHY未正确配置，导致设备反复进入复位状态。检查设备树中snps,dis_u2_susphy_quirk和snps,dis_u3_susphy_quirk属性，发现未禁用USB2/3 Suspend PHY，导致链路不稳定。
解决：在设备树中添加：

&usb0 {
    snps,dis_u2_susphy_quirk;
    snps,dis_u3_susphy_quirk;
    status = "okay";
};

结果：中断频率降至正常水平，枚举成功。
复盘：UDC中断风暴通常与PHY电源管理、时钟稳定性和VBUS去抖有关。建议在调试时先使用lsusb -v确认主机侧是否识别设备，再通过echo 0 > /sys/kernel/debug/dwc3/.../link_state检查链路状态。

4.3 usb_gadget_driver结构：功能驱动的“身份证”

4.3.1 核心原理：结构体成员与回调时机

struct usb_gadget_driver是功能驱动注册到UDC Core的入口，其定义如下（以Linux 6.x为例）：

struct usb_gadget_driver {
    const char *function;       // 功能名称，用于sysfs显示
    enum usb_device_speed max_speed;  // 支持的最大速度
    int (*bind)(struct usb_gadget *); // 绑定UDC时调用，分配端点
    void (*unbind)(struct usb_gadget *);
    int (*setup)(struct usb_gadget *, const struct usb_ctrlrequest *);
    void (*disconnect)(struct usb_gadget *);
    void (*suspend)(struct usb_gadget *);
    void (*resume)(struct usb_gadget *);
    struct device_driver driver;  // 内嵌标准驱动模型
};

各回调的触发时机：

4.3.2 判断方法：如何选择bind()中的端点配置策略？

在bind()中，开发者需要根据设备描述符中的端点需求，从UDC提供的端点池中选择合适的端点。推荐策略：

1. 使用usb_ep_autoconfig()自动匹配，它根据usb_endpoint_descriptor的bmAttributes和bEndpointAddress自动选择。
2. 对于高速设备，优先选择双缓冲（double-buffered）端点以提高吞吐。
3. 如果UDC支持DMA，确保请求缓冲区按DMA_ALIGNMENT对齐。

示例：为批量端点选择FIFO大小为512字节的端点：

struct usb_ep *ep;
ep = usb_ep_autoconfig(gadget, &bulk_in_desc);
if (!ep) {
    dev_err(&gadget->dev, "no suitable bulk IN ep\n");
    return -ENODEV;
}
/* 手动调整FIFO大小（部分UDC支持） */
if (gadget->ops->ep_fifo_cfg)
    gadget->ops->ep_fifo_cfg(ep, 512);

4.3.3 案例拆解：composite框架下的多function绑定

现代内核推荐使用composite框架，它允许一个gadget设备同时实现多个功能（如ADB+MTP）。其核心是struct usb_composite_driver，内部包含多个usb_function实例。关键点：

• usb_add_function()将功能添加到配置中。
• 每个usb_function有自己的bind()，但共享同一个usb_gadget_driver。
• 通过configfs（/sys/kernel/config/usb_gadget/）可以动态组合功能，无需重新编译内核。

实际部署时，使用configfs创建gadget的流程：

# 创建gadget目录
mkdir /sys/kernel/config/usb_gadget/g1
cd /sys/kernel/config/usb_gadget/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

该流程避免了编写内核模块，适合产品快速原型验证。