2. URB数据结构深度解析：struct urb成员详解、传输标志位、回调函数机制

URB（USB Request Block）是USB主机控制器与设备驱动程序之间交换数据的核心载体。每个URB实例封装了一次USB传输所需的所有信息：目标端点、数据缓冲区、传输长度、标志位以及完成回调函数。理解struct urb的每个成员，是编写可靠USB驱动的第一步。

2.1 struct urb 核心成员一览

内核头文件 <linux/usb.h> 中定义了 struct urb，其成员按功能可分为：目标定位、传输控制、数据缓冲区、完成回调、状态反馈五大类。下表列出了最常用的成员：

2.2 传输标志位（transfer_flags）详解

transfer_flags 是一个位掩码字段，控制URB在提交、映射和完成阶段的行为。以下是最常用的标志位：

下面的SVG图展示了URB从创建、填充标志位、提交到完成回调的完整生命周期，重点标注了transfer_flags在提交阶段的作用：

2.3 回调函数机制（complete callback）

URB的完成回调函数是异步通知的核心机制。当USB主机控制器完成一次数据传输（无论成功、失败还是被取消），内核都会在软中断上下文中调用驱动注册的complete函数。回调函数的原型如下：

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

回调函数接收一个参数——指向已完成URB的指针。驱动通过检查urb->status判断传输结果，通过urb->actual_length获取实际传输字节数。

2.3.1 回调函数执行上下文

2.3.2 回调函数典型实现模板

static void my_bulk_complete(struct urb *urb)
{
    struct my_device *dev = urb->context;

    /* 检查传输状态 */
    if (urb->status == 0) {
        /* 传输成功，处理 urb->actual_length 字节数据 */
        dev_info(&dev->interface->dev,
                 "Bulk transfer succeeded, %d bytes received\n",
                 urb->actual_length);
        /* 将数据从 urb->transfer_buffer 拷贝到驱动缓冲区 */
        memcpy(dev->data_buf, urb->transfer_buffer,
               min(urb->actual_length, dev->buf_size));
    } else if (urb->status == -ENOENT) {
        /* URB被 usb_kill_urb() 取消，正常退出 */
        dev_dbg(&dev->interface->dev, "URB killed\n");
    } else if (urb->status == -ECONNRESET) {
        /* URB被 usb_unlink_urb() 取消 */
        dev_dbg(&dev->interface->dev, "URB unlinked\n");
    } else {
        /* 其他错误，如 -EPIPE（端点停止）、-ETIMEDOUT（超时） */
        dev_err(&dev->interface->dev,
                "Bulk transfer failed: %d\n", urb->status);
    }

    /* 唤醒等待队列，通知上层数据已到达 */
    complete(&dev->transfer_done);
}

2.3.3 回调函数中的status值速查

下面的SVG图展示了回调函数内部的状态判断流程，以及驱动在不同status下的典型处理路径：

2.4 URB内存管理关键函数

与URB数据结构配套的内存管理函数，驱动开发者必须掌握：

2.5 批量传输URB填充示例

以下代码展示了如何分配、填充并提交一个批量IN传输的URB：

struct urb *urb;
struct my_device *dev;
int ret;

/* 1. 分配URB（批量传输，iso_packets = 0） */
urb = usb_alloc_urb(0, GFP_KERNEL);
if (!urb) {
    dev_err(&dev->interface->dev, "Failed to allocate URB\n");
    return -ENOMEM;
}

/* 2. 分配数据缓冲区 */
dev->buf = kmalloc(BUF_SIZE, GFP_KERNEL);
if (!dev->buf) {
    usb_free_urb(urb);
    return -ENOMEM;
}

/* 3. 使用辅助函数填充URB */
usb_fill_bulk_urb(urb,                     /* URB指针 */
                  dev->udev,               /* USB设备 */
                  usb_rcvbulkpipe(dev->udev, 0x01), /* 批量IN管道，端点1 */
                  dev->buf,                /* 数据缓冲区 */
                  BUF_SIZE,                /* 缓冲区长度 */
                  my_bulk_complete,        /* 回调函数 */
                  dev);                    /* context上下文 */

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

/* 5. 提交URB */
ret = usb_submit_urb(urb, GFP_KERNEL);
if (ret) {
    dev_err(&dev->interface->dev,
            "Failed to submit URB: %d\n", ret);
    kfree(dev->buf);
    usb_free_urb(urb);
    return ret;
}

/* URB已提交，等待回调执行 */