2. Linux USB Gadget框架：软件架构与核心数据结构

Linux USB Gadget 框架是内核中实现设备端（Device Side）USB 功能的核心软件层。它向上为各类 Gadget 功能驱动（如 ECM、UVC、Mass Storage）提供统一的编程接口，向下通过 UDC（USB Device Controller）驱动直接操作硬件寄存器。理解其软件架构与核心数据结构，是进行硬件适配与移植的基础。

2.1 软件架构分层

整个框架采用分层设计，从底至上依次为：UDC 驱动层、Gadget 核心层、功能驱动层。各层职责清晰，通过标准 API 交互。

2.2 核心数据结构

Gadget 框架围绕三个核心数据结构构建：usb_gadget、usb_ep、usb_request。它们分别代表 USB 设备整体、端点（Endpoint）和传输请求（Request）。

2.2.1 usb_gadget：设备抽象

struct usb_gadget 是 USB 设备控制器的软件抽象，代表一个完整的 USB 设备实例。它包含设备状态、速度、电源管理、UDC 操作函数集等信息。

// include/linux/usb/gadget.h
struct usb_gadget {
    struct device          dev;           // 内核设备模型
    const struct usb_gadget_ops *ops;     // UDC 操作函数集
    struct usb_ep         *ep0;           // 控制端点 ep0
    enum usb_device_state  state;         // 设备状态 (USB_STATE_*)
    enum usb_device_speed  speed;         // 当前连接速度
    unsigned               is_otg:1;      // 是否支持 OTG
    unsigned               is_a_peripheral:1; // 是否作为 A 设备
    unsigned               b_hnp_enable:1; // HNP 使能
    unsigned               a_hnp_support:1;
    unsigned               a_alt_hnp_support:1;
    unsigned               quirk_ep_out_aligned_size:1; // 硬件 quirks
    // ... 其他字段
};

2.2.2 usb_ep：端点抽象

struct usb_ep 代表一个 USB 端点（Endpoint），包括端点号、方向、类型、最大包大小等属性。每个 UDC 驱动需要为所有可用端点创建对应的 usb_ep 实例。

// include/linux/usb/gadget.h
struct usb_ep {
    void                    *driver_data;  // 驱动私有数据
    const char              *name;         // 端点名称 (如 "ep1in")
    const struct usb_ep_ops *ops;          // 端点操作函数集
    struct list_head         ep_list;      // 链表节点
    unsigned                 maxpacket:16; // 最大包大小
    unsigned                 max_streams:16; // 批量流数量
    unsigned                 mult:2;       // 高带宽模式倍数
    unsigned                 maxburst:5;   // 突发传输长度
    unsigned                 address:8;    // 端点地址 (含方向位)
    const struct usb_endpoint_descriptor *desc; // 描述符指针
};

2.2.3 usb_request：传输请求抽象

struct usb_request 描述一次 USB 数据传输请求，包含数据缓冲区、长度、完成回调等。它是 Gadget 框架中数据流动的基本单元。

// include/linux/usb/gadget.h
struct usb_request {
    void          *buf;           // 数据缓冲区
    unsigned       length;        // 缓冲区长度
    dma_addr_t     dma;           // DMA 地址 (若使用 DMA)
    unsigned       no_interrupt:1; // 是否不产生中断
    unsigned       zero:1;        // 是否发送零长度包
    unsigned       short_not_ok:1; // 是否不允许短包
    unsigned       stream_id:16;  // 批量流 ID
    void          *context;       // 回调上下文
    void (*complete)(struct usb_ep *ep, struct usb_request *req); // 完成回调
    struct list_head list;        // 链表节点
};

2.3 数据结构关系图

以下 SVG 图展示了三个核心数据结构之间的关联关系，以及它们如何与 UDC 硬件交互。

2.4 数据流与回调链

一次典型的 USB 数据传输流程如下：

1. 功能驱动调用 usb_ep_queue() 提交 usb_request 到某个端点。
2. Gadget 核心层将请求传递给 UDC 驱动的 ep->ops->queue() 回调。
3. UDC 驱动将请求写入硬件（DMA 或 FIFO），启动传输。
4. 硬件传输完成后触发中断，UDC 驱动在中断处理中调用 req->complete() 回调。
5. 功能驱动在回调中处理数据，可能再次提交新请求。

2.5 硬件适配接口清单

在移植 UDC 驱动时，必须实现以下核心接口：