4. URB（USB Request Block）结构体详解

URB（USB Request Block）是 USB 设备驱动与主机控制器之间进行数据交互的核心载体。每个 URB 代表一次完整的 USB 传输请求，包含传输类型、目标端点、数据缓冲区、回调函数等关键信息。理解 struct urb 的成员、标志位和回调机制，是编写稳定 USB 驱动的基石。

4.1 struct urb 核心成员

struct urb 定义在 <linux/usb.h> 中，包含数十个成员。以下按功能分类列出最常用的核心成员：

4.2 URB 标志位详解

transfer_flags 控制 URB 的传输行为，常用标志位如下：

4.3 回调函数机制

URB 的回调函数是异步传输完成后的通知入口，在软中断上下文中执行。回调函数原型如下：

typedef void (*usb_complete_t)(struct urb *urb);

回调函数通过 urb->context 获取驱动私有数据，通过 urb->status 判断传输结果。典型回调处理流程：

1. 检查状态：判断 urb->status 是否为 0，非 0 则记录错误并可能重提交。
2. 处理数据：读取 urb->actual_length 获取实际数据长度，从 urb->transfer_buffer 提取数据。
3. 重新提交（可选）：对于连续中断传输，在回调中重新填充并提交 URB。
4. 清理资源：如果不再使用，调用 usb_free_urb() 释放 URB。

4.4 URB 生命周期与状态机

下图展示了 URB 从创建到完成的完整状态转换：

4.5 中断 URB 的典型代码模式

以下代码展示了中断传输 URB 的创建、提交和回调处理的标准模式：

/* 中断 URB 回调函数 */
static void intr_urb_complete(struct urb *urb)
{
    struct my_driver_data *priv = urb->context;

    if (urb->status == 0) {
        /* 传输成功，处理数据 */
        process_received_data(priv, urb->transfer_buffer,
                              urb->actual_length);
    } else if (urb->status == -ENOENT) {
        /* URB 被主动取消，正常退出 */
        return;
    } else if (urb->status == -ECONNRESET) {
        /* 设备断开 */
        dev_err(&priv->intf->dev, "device disconnected\n");
        return;
    } else {
        /* 其他错误，尝试重新提交 */
        dev_dbg(&priv->intf->dev, "URB error %d, resubmitting\n",
                urb->status);
    }

    /* 重新提交 URB 以接收下一个中断 */
    retval = usb_submit_urb(urb, GFP_ATOMIC);
    if (retval)
        dev_err(&priv->intf->dev, "resubmit failed: %d\n", retval);
}

/* 初始化并提交中断 URB */
static int setup_intr_urb(struct usb_device *udev,
                          struct my_driver_data *priv)
{
    struct urb *urb;
    unsigned int pipe;
    int retval;

    /* 1. 分配 URB */
    urb = usb_alloc_urb(0, GFP_KERNEL);
    if (!urb)
        return -ENOMEM;

    /* 2. 获取中断输入管道 */
    pipe = usb_rcvintpipe(udev, priv->ep_addr);

    /* 3. 填充 URB */
    usb_fill_int_urb(urb, udev, pipe,
                     priv->buffer,          /* 数据缓冲区 */
                     priv->buffer_size,     /* 缓冲区长度 */
                     intr_urb_complete,     /* 回调函数 */
                     priv,                  /* 上下文指针 */
                     priv->interval);       /* 轮询间隔 */

    /* 4. 设置标志位：短包视为错误 */
    urb->transfer_flags |= URB_SHORT_NOT_OK;

    /* 5. 提交 URB */
    retval = usb_submit_urb(urb, GFP_KERNEL);
    if (retval) {
        usb_free_urb(urb);
        return retval;
    }

    priv->intr_urb = urb;
    return 0;
}

4.6 URB 状态码速查表

回调函数中 urb->status 的常见值及其含义：

4.7 URB 分配与释放 API

内核提供了一组辅助函数简化 URB 的管理：

4.8 中断 URB 的故障排查清单

当中断 URB 传输异常时，按以下清单逐项排查：

1. 检查端点描述符：确认 bEndpointAddress 方向正确，bInterval 值合理（全速设备 1-255 ms，高速设备 1-16 微帧）。
2. 验证管道创建：使用 usb_rcvintpipe() 或 usb_sndintpipe() 创建管道，确保端点号与描述符一致。
3. 检查缓冲区对齐：中断传输的缓冲区不需要特殊对齐，但 DMA 缓冲区建议使用 usb_alloc_coherent() 分配。
4. 确认回调上下文：回调中不能睡眠，检查是否有隐式阻塞调用（如 printk 在特定配置下可能阻塞）。
5. 监控状态码：在回调中打印 urb->status，对照 4.6 节速查表定位问题。
6. 检查 USB 带宽：中断传输占用固定的 USB 帧时间，带宽不足时 usb_submit_urb() 返回 -ENOSPC。
7. 验证设备电源状态：设备进入挂起状态后，URB 提交会失败，需先唤醒设备。