3. Gadget API 核心数据结构：struct usb_gadget、struct usb_ep、struct usb_request

在 Linux USB Gadget 驱动框架中，struct usb_gadget、struct usb_ep 和 struct usb_request 是三个最核心的数据结构。它们分别抽象了 Gadget 设备、端点 和 USB 请求，构成了驱动与硬件交互的基石。理解这三个结构体的作用与关键字段，是编写 Gadget 功能驱动的第一步。

3.1 struct usb_gadget：Gadget 设备抽象

struct usb_gadget 是 USB Gadget 设备在驱动层的核心表示，它封装了硬件控制器（UDC）的通用属性和操作接口。每个 UDC 硬件对应一个 usb_gadget 实例。

关键字段解析

3.2 struct usb_ep：端点抽象

struct usb_ep 代表一个 USB 端点（Endpoint），是数据传输的通道。每个端点都有方向（IN/OUT）、类型（控制/批量/中断/等时）和编号。端点 0 由 UDC 核心管理，其他端点由功能驱动申请使用。

关键字段解析

端点操作流程

1. 申请端点：通过 usb_ep_autoconfig() 或直接遍历 gadget->ep_list 匹配端点能力。
2. 使能端点：调用 usb_ep_enable()，传入端点描述符配置最大包长等参数。
3. 分配请求：调用 usb_ep_alloc_request() 创建 usb_request 实例。
4. 提交请求：调用 usb_ep_queue() 启动数据传输。
5. 完成回调：请求完成后，UDC 调用 usb_request->complete 回调通知驱动。
6. 释放资源：传输结束后调用 usb_ep_free_request() 和 usb_ep_disable()。

3.3 struct usb_request：USB 请求抽象

struct usb_request 是数据传输的基本单元，封装了一次 USB 传输所需的缓冲区、长度、方向和完成状态。功能驱动通过提交请求来触发 UDC 硬件进行实际的数据收发。

关键字段解析

3.4 三者协作示例：虚拟网卡发送数据

以虚拟网卡驱动发送一个网络数据包为例，展示三个结构体的协作流程：

/* 伪代码：虚拟网卡发送一个 skb 数据包 */
static int eth_send_packet(struct usb_function *f, struct sk_buff *skb)
{
    struct f_eth *eth = func_to_eth(f);
    struct usb_request *req;
    struct usb_ep *ep_in = eth->in_ep;  /* 从 usb_gadget 获取的 IN 端点 */
    int ret;

    /* 1. 从端点池获取一个空闲请求 */
    req = usb_ep_alloc_request(ep_in, GFP_ATOMIC);
    if (!req)
        return -ENOMEM;

    /* 2. 设置请求参数 */
    req->buf      = skb->data;
    req->length   = skb->len;
    req->complete = eth_tx_complete;  /* 发送完成回调 */
    req->context  = skb;              /* 传递 skb 给回调 */
    req->zero     = 1;                /* 自动补零长度包 */

    /* 3. 提交请求到端点 */
    ret = usb_ep_queue(ep_in, req, GFP_ATOMIC);
    if (ret) {
        usb_ep_free_request(ep_in, req);
        dev_kfree_skb_any(skb);
        return ret;
    }

    return 0;
}

/* 发送完成回调 */
static void eth_tx_complete(struct usb_ep *ep, struct usb_request *req)
{
    struct sk_buff *skb = req->context;

    if (req->status != 0) {
        /* 处理错误 */
        dev_kfree_skb_any(skb);
    } else {
        /* 发送成功，释放 skb */
        dev_kfree_skb_any(skb);
    }

    /* 释放请求，归还端点 */
    usb_ep_free_request(ep, req);
}

3.5 数据结构对比速查表