4. URB（USB Request Block）结构详解：urb结构体成员、标志位与生命周期

URB（USB Request Block）是 Linux USB 子系统中最核心的数据结构，它是主机控制器驱动与 USB 设备驱动之间进行数据交换的载体。每一个 USB 数据传输请求，无论方向是 IN 还是 OUT，都会被封装为一个 URB 实例，通过内核的 USB 核心层提交到主机控制器硬件。理解 URB 的结构、标志位及其生命周期，是进行 USB 驱动故障排查的必备基础。

4.1 urb 结构体核心成员

struct urb 定义在 <linux/usb.h> 中，包含数十个成员。对于驱动开发和故障排查，以下成员最为关键：

4.2 URB 标志位详解

URB 结构体中的 transfer_flags 字段控制 URB 的行为模式。这些标志位在 URB 提交前设置，影响内核如何处理缓冲区、DMA 映射以及传输完成后的动作。

4.3 URB 生命周期与状态机

一个 URB 从创建到销毁，经历一系列明确的状态转换。理解这一生命周期对于调试“URB 提交失败”、“URB 挂起”或“URB 泄漏”问题至关重要。

4.4 各阶段详细说明

4.4.1 创建与填充

URB 通过 usb_alloc_urb() 分配，该函数接受等时包数量参数（非等时传输传 0）。填充阶段使用辅助函数简化操作：

/* 中断传输 URB 填充示例 */
struct urb *urb;
urb = usb_alloc_urb(0, GFP_KERNEL);
if (!urb)
    return -ENOMEM;

usb_fill_int_urb(urb, dev, usb_rcvintpipe(dev, 0x81),
                 buffer, size, complete_callback, context, interval);

/* 批量传输 URB 填充示例 */
usb_fill_bulk_urb(urb, dev, usb_sndbulkpipe(dev, 0x02),
                  buffer, size, complete_callback, context);

4.4.2 提交与调度

usb_submit_urb() 是 URB 生命周期的关键转折点。提交后，URB 进入 USB 核心的内部队列，等待主机控制器驱动程序（HCD）调度。提交可能失败的原因包括：

• -ENODEV： 设备已断开连接。
• -ENOMEM： 内存分配失败（如 DMA 映射失败）。
• -ESHUTDOWN： 主机控制器已关闭（通常发生在系统挂起或复位时）。
• -EPIPE： 端点被 STALL 握手信号停止（端点错误）。
• -EINVAL： 参数无效（如缓冲区未对齐、端点号错误）。

4.4.3 完成回调与回收

URB 完成回调函数在中断上下文或软中断上下文中执行，必须遵守以下规则：

• 不可睡眠： 不能调用 msleep()、wait_event() 等可能导致阻塞的函数。
• 不可提交新 URB： 虽然技术上可行，但容易导致递归或死锁。推荐使用工作队列（workqueue）延迟提交。
• 检查 status： 回调第一件事应检查 urb->status，根据错误码决定处理策略。
• 及时回收： 回调结束后应调用 usb_free_urb() 释放 URB 内存，除非 URB 被设计为重用（通过 usb_submit_urb() 重新提交）。

/* 典型的 URB 完成回调实现 */
static void my_urb_complete(struct urb *urb)
{
    struct my_context *ctx = urb->context;

    if (urb->status == 0) {
        /* 传输成功，处理 urb->transfer_buffer 中的数据 */
        pr_info("URB completed, actual length: %d\n", urb->actual_length);
        process_received_data(urb->transfer_buffer, urb->actual_length);
    } else if (urb->status == -ENOENT) {
        /* URB 被 usb_kill_urb() 取消，正常退出 */
    } else if (urb->status == -ECONNRESET) {
        /* URB 被 usb_unlink_urb() 取消 */
    } else {
        /* 其他错误，记录日志 */
        dev_err(&urb->dev->dev, "URB error: %d\n", urb->status);
    }

    /* 释放 URB 及其缓冲区 */
    usb_free_urb(urb);
}

4.5 URB 重用与取消

在高速数据流场景（如视频采集、批量传输），频繁分配和释放 URB 会导致性能下降。内核支持 URB 重用机制：

• 重用流程： 在完成回调中不调用 usb_free_urb()，而是重新填充 transfer_buffer 和 context，然后再次调用 usb_submit_urb()。
• 取消 URB： usb_kill_urb() 同步取消 URB，等待回调执行完毕；usb_unlink_urb() 异步取消，立即返回。
• 注意事项： 重用 URB 时，必须确保前一次传输已完成（回调已执行），否则会导致 URB 状态混乱。

4.6 故障排查清单

当遇到 URB 相关问题时，按以下清单逐项检查：