4. Linux USB Gadget 框架核心数据结构详解

USB Gadget 框架的核心在于三个相互关联的数据结构：usb_gadget（控制器抽象）、usb_ep（端点抽象）和 usb_request（请求抽象）。它们是驱动开发者与硬件交互的基石，理解其内部字段与生命周期是进行批量传输性能优化的前提。

4.1 usb_gadget：控制器实例

usb_gadget 结构体代表一个 USB 设备控制器（UDC）实例。它封装了硬件能力、电源状态、连接状态以及指向端点列表的指针。每个 UDC 驱动在 probe 阶段都会分配并注册一个 usb_gadget 对象。

4.2 usb_ep：端点抽象

usb_ep 是对硬件端点的软件抽象。每个端点都有方向（IN/OUT）、类型（批量/中断/等时）、最大包大小和当前状态。Gadget 函数驱动通过 usb_ep_autoconfig 从 ep_list 中匹配可用端点。

4.3 usb_request：I/O 请求单元

usb_request 是数据传输的最小工作单元。函数驱动分配请求、填充缓冲区，然后通过 usb_ep_queue 提交给 UDC 硬件。完成时，complete 回调被触发。批量传输性能优化的核心就在于如何高效地管理这些请求的生命周期。

struct usb_request {
    void            *buf;           // 数据缓冲区指针
    unsigned        length;         // 缓冲区长度（字节）
    dma_addr_t      dma;            // DMA 地址（若使用 DMA）
    unsigned        sg_nents;       // 分散/聚集表项数
    struct scatterlist *sg;         // 分散/聚集表指针
    unsigned        num_sgs;        // SG 表项数量
    unsigned        stream_id;      // 批量流 ID（USB 3.0 批量流）
    void            (*complete)(struct usb_ep *ep,
                                struct usb_request *req); // 完成回调
    void            *context;       // 回调上下文
    int             status;         // 传输状态（0 成功，负值错误码）
    unsigned        actual;         // 实际传输字节数
    unsigned        no_interrupt;   // 是否禁止完成中断
    unsigned        zero;           // 是否发送 ZLP（零长度包）
    unsigned        short_not_ok;   // 是否不允许短包
    struct list_head list;          // 用于挂入请求队列
};

4.4 三者协作关系

在 Gadget 函数驱动中，这三个结构体通过以下方式协作：

1. 初始化阶段： 通过 gadget->ep_list 遍历，使用 usb_ep_autoconfig 匹配 usb_ep，并调用 usb_ep_enable 激活端点。
2. 传输阶段： 分配 usb_request，填充 buf 和 length，调用 usb_ep_queue 提交到 UDC。
3. 完成阶段： UDC 硬件完成传输后，调用 usb_request->complete 回调，驱动在回调中检查 status 和 actual，然后回收请求。