2. URB数据结构深度解析：struct urb关键成员及其生命周期

URB（USB Request Block）是USB设备驱动与主机控制器之间的核心通信单元。理解 struct urb 的每个关键成员及其生命周期，是排查URB泄漏、优化传输性能的基础。本章将从数据结构定义出发，逐一剖析核心字段的作用、使用约束与生命周期管理要点。

2.1 struct urb 核心成员一览

以下表格列出了 struct urb 中最关键的成员，以及它们在驱动开发中的典型用途和注意事项。

2.2 pipe 成员：端点通信的编码器

pipe 是一个位编码的整数，它包含了USB通信所需的全部路由信息。内核提供了一组宏来构建和解析 pipe 值。

// 构建 pipe 的典型宏
unsigned int pipe = usb_sndctrlpipe(dev, 0);   // 控制输出端点0
unsigned int pipe = usb_rcvbulkpipe(dev, 1);   // 批量输入端点1
unsigned int pipe = usb_sndintpipe(dev, 2);    // 中断输出端点2
unsigned int pipe = usb_rcvisocpipe(dev, 3);   // 等时输入端点3

// 从 pipe 中提取信息（调试时常用）
unsigned int epnum = usb_pipeendpoint(pipe);
unsigned int dir    = usb_pipeout(pipe) ? USB_DIR_OUT : USB_DIR_IN;
unsigned int type   = usb_pipetype(pipe);      // PIPE_ISOCHRONOUS / PIPE_INTERRUPT / PIPE_CONTROL / PIPE_BULK

2.3 transfer_buffer 与 DMA 安全

transfer_buffer 指向的数据缓冲区必须满足DMA一致性要求。对于批量/中断传输，推荐使用 usb_alloc_coherent 或 kmalloc 配合 GFP_KERNEL 标志。栈上分配的缓冲区（局部数组）绝对不能用于URB传输。

// 正确分配方式示例
struct urb *urb;
void *buf;

urb = usb_alloc_urb(0, GFP_KERNEL);
buf = kmalloc(size, GFP_KERNEL);   // 或 usb_alloc_coherent(dev, size, GFP_KERNEL, &urb->transfer_dma);

urb->transfer_buffer = buf;
urb->transfer_buffer_length = size;
urb->transfer_flags |= URB_NO_TRANSFER_DMA_MAP;  // 如果使用DMA地址

2.4 complete 与 context：回调机制的核心

complete 回调函数在URB传输完成（成功、失败或被取消）时被调用。回调运行在中断上下文或软中断上下文，因此不能执行阻塞操作。context 指针允许驱动将私有数据传递给回调函数，通常指向一个完成量（completion）或请求描述符。

// 典型的 complete 回调实现
static void my_urb_complete(struct urb *urb)
{
    struct my_device *mydev = (struct my_device *)urb->context;

    if (urb->status == 0) {
        // 传输成功，处理 urb->actual_length 字节数据
        process_received_data(mydev, urb->transfer_buffer, urb->actual_length);
    } else if (urb->status == -ECONNRESET) {
        // 被 usb_unlink_urb 取消，正常清理
    } else {
        // 其他错误，可能需要重试
        dev_err(&mydev->interface->dev, "URB failed with status %d\n", urb->status);
    }

    // 在回调中重新提交（循环URB）或释放
    if (mydev->running) {
        usb_submit_urb(urb, GFP_ATOMIC);
    } else {
        usb_free_urb(urb);
    }
}

2.5 URB 生命周期状态机

下图展示了URB从创建到销毁的完整状态转换。理解这个状态机是定位泄漏的关键：任何停留在“已提交”或“已取消但未释放”状态的URB都是潜在泄漏点。

2.6 生命周期管理最佳实践

1. 分配与初始化配对：每个 usb_alloc_urb 必须对应一个 usb_free_urb。推荐在驱动探测时分配，在断开时释放。
2. 提交前检查：调用 usb_submit_urb 前，确保 pipe、transfer_buffer、complete、context 均已正确赋值。
3. 回调中释放：对于一次性URB，在 complete 回调中调用 usb_free_urb。对于循环URB，在驱动停止时先 usb_unlink_urb 再释放。
4. 取消后的清理：usb_unlink_urb 返回后，URB 的 complete 回调仍可能被调用。必须在回调中处理 -ECONNRESET 状态，并最终释放URB。
5. 缓冲区生命周期：transfer_buffer 指向的内存必须在URB完全释放（所有引用计数归零）后才能释放。使用 usb_free_coherent 或 kfree 时注意时序。

2.7 关键成员生命周期对比表

下表总结了不同成员在URB生命周期各阶段的有效性和责任方。