4. USB请求块（URB）

USB请求块（USB Request Block，URB）是Linux USB子系统中最核心的数据结构之一，它充当了USB设备驱动与主机控制器硬件之间的通信载体。每个URB描述一次完整的USB数据传输事务，包括传输类型、目标端点、数据缓冲区、传输长度以及完成后的回调函数。理解URB的结构、生命周期以及提交/回调机制，是编写正确、高效的USB设备驱动的关键前提。

4.1 URB结构体详解

URB结构体定义在<linux/usb.h>头文件中，是驱动与USB核心层交互的主要数据结构。下面列出其关键字段及其作用：

4.2 URB生命周期

一个URB从创建到销毁经历完整的生命周期，驱动必须遵循以下阶段操作URB：

1. 创建（Allocation）：使用usb_alloc_urb()分配URB实例，传入等时包数量（非等时传输传0）。
2. 初始化（Initialization）：填充URB的关键字段，包括pipe、dev、transfer_buffer、complete回调等。对于批量/中断/控制传输，可使用辅助函数如usb_fill_bulk_urb()简化初始化。
3. 提交（Submission）：调用usb_submit_urb()将URB提交给USB核心层。提交后URB进入待处理状态，驱动不能再修改其关键字段。
4. 处理（Processing）：USB核心层将URB传递给主机控制器驱动（HCD），HCD执行实际的USB总线事务。此阶段URB处于不可用状态。
5. 完成（Completion）：传输完成后，USB核心层调用驱动注册的complete回调函数，并更新status和actual_length字段。驱动在回调中处理数据或错误。
6. 回收（Reclamation）：驱动在回调中或之后调用usb_free_urb()释放URB内存。如果URB需要复用，可调用usb_unlink_urb()取消未完成的URB后再重新初始化。

4.3 URB提交与回调机制

URB的提交和回调是驱动与USB核心层交互的核心接口。驱动通过usb_submit_urb()将URB提交给核心层，核心层在传输完成后调用complete回调通知驱动。理解这两个接口的语义和约束，是编写可靠USB驱动的必要条件。

4.3.1 URB提交：usb_submit_urb()

usb_submit_urb()是异步非阻塞函数，调用后立即返回。其原型如下：

int usb_submit_urb(struct urb *urb, gfp_t mem_flags);

参数说明：

• urb：已初始化完成的URB指针。
• mem_flags：内存分配标志，在中断上下文中必须使用GFP_ATOMIC，在进程上下文中可使用GFP_KERNEL。

返回值：0表示成功提交；负值表示错误，常见错误码包括：

4.3.2 回调函数：complete 回调

回调函数的类型定义为：

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

回调函数在URB传输完成后被调用，驱动在此函数中：

• 检查urb->status判断传输是否成功。
• 读取urb->actual_length获取实际传输字节数。
• 处理接收到的数据（对于IN传输）或确认发送完成（对于OUT传输）。
• 决定是否重新提交URB以继续传输（如批量流式传输）。
• 调用usb_free_urb()释放URB，或将其归还给URB池。

回调函数执行在中断上下文（或软中断上下文）中，因此必须遵守以下约束：

• 不能调用可能睡眠的函数（如wait_event()、mutex_lock()、kmalloc(GFP_KERNEL)）。
• 不能执行长时间运行的操作——应尽快返回，将耗时工作推迟到工作队列或tasklet中。
• 可以安全地调用usb_submit_urb()重新提交URB（使用GFP_ATOMIC标志）。

4.3.3 典型URB提交代码示例

以下代码展示了一个完整的批量OUT传输URB的创建、初始化和提交流程：

#include <linux/usb.h>

/* 批量传输完成回调 */
static void bulk_write_complete(struct urb *urb)
{
    struct my_device *dev = urb->context;
    
    if (urb->status == 0) {
        /* 传输成功，urb->actual_length 为实际发送字节数 */
        dev_dbg(&dev->interface->dev, "Bulk write OK, %d bytes sent\n",
                urb->actual_length);
    } else if (urb->status == -ENOENT) {
        /* URB被 usb_kill_urb() 取消，正常关闭路径 */
    } else {
        dev_err(&dev->interface->dev, "Bulk write failed: %d\n",
                urb->status);
    }
    
    /* 通知等待的进程（如果有） */
    complete(&dev->write_done);
}

/* 提交批量写URB */
int submit_bulk_write(struct my_device *dev, u8 *data, int len)
{
    struct urb *urb;
    int ret;
    
    /* 1. 分配URB */
    urb = usb_alloc_urb(0, GFP_KERNEL);
    if (!urb)
        return -ENOMEM;
    
    /* 2. 初始化URB */
    usb_fill_bulk_urb(urb, dev->udev,
                      usb_sndbulkpipe(dev->udev, dev->bulk_out_endpoint),
                      data, len,
                      bulk_write_complete, dev);
    
    /* 3. 提交URB */
    ret = usb_submit_urb(urb, GFP_KERNEL);
    if (ret) {
        dev_err(&dev->interface->dev,
                "Failed to submit bulk URB: %d\n", ret);
        usb_free_urb(urb);
        return ret;
    }
    
    /* URB已提交，不要释放——回调中会处理 */
    return 0;
}

4.4 URB传输类型与回调行为对比

不同的USB传输类型在URB提交和回调行为上存在差异，驱动开发者需要根据传输类型选择合适的处理策略：