URB 结构深度解析：核心字段与批量传输中的作用

USB Request Block (URB) 是 USB 设备驱动与主机控制器之间的核心通信载体。在批量传输场景下，URB 的字段配置直接决定了数据传输的正确性、吞吐量和延迟。本章深入剖析 URB 的四个关键字段：transfer_buffer、transfer_flags、status 和 actual_length，并阐明它们在批量传输中的具体作用。

2.1 URB 核心字段总览

URB 结构体定义在 <linux/usb.h> 中，包含数十个字段。对于批量传输驱动开发者，以下四个字段是性能调优和错误处理的核心关注点：

字段名	类型	方向	批量传输中的核心作用
transfer_buffer	void *	驱动→URB	指向数据缓冲区的指针，驱动在此准备发送数据或接收数据
transfer_flags	unsigned long	驱动→URB	控制 URB 行为（如 DMA 映射、短包处理、中断上下文）
status	int	URB→驱动	URB 完成后的状态码，指示成功、错误或取消
actual_length	int	URB→驱动	实际传输的字节数，用于处理短包和流控

2.2 transfer_buffer：数据搬运的“货舱”

transfer_buffer 是 URB 中指向实际数据内存区域的指针。在批量传输中，它承担着驱动与 USB 设备之间数据搬运的“货舱”角色。

2.2.1 分配与生命周期

• 分配方式：通常使用 kmalloc()、usb_alloc_coherent() 或 dma_alloc_coherent() 分配。
• 对齐要求：批量传输建议 512 字节对齐，以匹配 USB 2.0 批量端点最大包大小。
• 生命周期：缓冲区必须在 URB 生命周期内有效，直到 URB 完成回调被调用。

2.2.2 批量传输中的典型用法

/* 批量 OUT 传输：发送数据到设备 */
urb->transfer_buffer = kmalloc(urb->transfer_buffer_length, GFP_KERNEL);
memcpy(urb->transfer_buffer, data_to_send, data_len);
urb->transfer_buffer_length = data_len;

/* 批量 IN 传输：从设备接收数据 */
urb->transfer_buffer = usb_alloc_coherent(dev, BULK_BUF_SIZE, GFP_KERNEL, &urb->transfer_dma);
urb->transfer_flags |= URB_NO_TRANSFER_DMA_MAP;  /* 使用预分配的 DMA 地址 */

2.3 transfer_flags：URB 行为的“控制面板”

transfer_flags 是一个位掩码字段，控制 URB 的传输行为。在批量传输中，以下标志位最为关键：

标志位	值	批量传输中的作用
URB_NO_TRANSFER_DMA_MAP	0x0001	告知内核已手动设置 DMA 地址，跳过自动映射，减少开销
URB_SHORT_NOT_OK	0x0002	批量 IN 传输中，如果收到短包（小于请求长度），将 status 设为 -EREMOTEIO
URB_FREE_BUFFER	0x0004	URB 完成时自动释放 transfer_buffer，简化内存管理
URB_NO_INTERRUPT	0x0008	批量传输中禁止中断触发，适用于轮询模式
URB_ZERO_PACKET	0x0040	批量 OUT 传输中，如果数据长度是端点最大包大小的整数倍，自动发送零长度包

2.4 status：传输结果的“判决书”

status 字段在 URB 完成回调中被内核填充，指示传输的最终结果。对于批量传输，常见的 status 值包括：

status 值	含义	批量传输中的处理建议
0	传输成功	检查 actual_length 确认数据完整性
-EINPROGRESS	URB 正在处理中	不应在回调中看到此值
-EREMOTEIO	短包错误（设置了 URB_SHORT_NOT_OK）	重新提交 URB 或调整缓冲区大小
-EPIPE	端点被 STALL（停止）	需要发送 CLEAR_FEATURE 清除 halt 状态
-ENODEV	设备已断开	停止所有 URB 提交，释放资源
-ESHUTDOWN	主机控制器已关闭	驱动应进入错误恢复流程

2.5 actual_length：实际传输的“计量器”

actual_length 记录 URB 完成时实际传输的字节数。在批量传输中，这个字段对于处理短包和流控至关重要。

2.5.1 短包处理

批量 IN 传输中，设备可能返回少于请求长度的数据（短包）。短包通常表示：

• 数据流结束（如批量读取完成）
• 设备端缓冲区未满
• USB 帧时间限制导致提前终止

/* 批量 IN 回调中的短包处理示例 */
static void bulk_in_callback(struct urb *urb)
{
    if (urb->status == 0) {
        /* 成功接收数据 */
        if (urb->actual_length < urb->transfer_buffer_length) {
            /* 短包：可能表示数据流结束 */
            dev_info(dev, "短包接收: 请求 %d 字节, 实际 %d 字节\n",
                     urb->transfer_buffer_length, urb->actual_length);
            /* 处理已接收的数据 */
            process_data(urb->transfer_buffer, urb->actual_length);
            /* 根据协议决定是否继续提交新的 URB */
        } else {
            /* 完整包：继续提交下一个 URB 以维持流水线 */
            submit_next_urb(urb->context);
        }
    }
}

2.5.2 性能调优中的 actual_length 监控

在批量传输性能调优中，持续监控 actual_length 与 transfer_buffer_length 的比值可以帮助诊断问题：

观测现象	可能原因	调优方向
actual_length 频繁小于请求长度	设备端吞吐不足、USB 帧时间限制	增大 URB 缓冲区大小、增加并发 URB 数量
actual_length 始终等于请求长度	传输正常，但可能未充分利用带宽	尝试增大 transfer_buffer_length 以提升单次传输效率
actual_length 为 0 且 status 为 0	设备返回了零长度包（ZLP）	检查协议是否期望 ZLP，或调整 URB_ZERO_PACKET 标志

2.6 四个字段的协同工作

在批量传输的完整生命周期中，四个字段协同工作：

1. 提交阶段：驱动设置 transfer_buffer（数据来源/目的地）和 transfer_flags（行为控制）。
2. 传输阶段：主机控制器根据 transfer_buffer 和 transfer_flags 执行 DMA 操作。
3. 完成阶段：内核填充 status（传输结果）和 actual_length（实际字节数）。
4. 解析阶段：驱动在回调中根据 status 判断成功与否，根据 actual_length 确定有效数据量。

2.7 本章小结

• transfer_buffer：数据缓冲区指针，优先使用 DMA 一致性分配以提升批量传输性能。
• transfer_flags：行为控制位掩码，批量 OUT 传输务必设置 URB_ZERO_PACKET。
• status：传输结果状态码，-EPIPE 需要特殊处理（清除 halt）。
• actual_length：实际传输字节数，用于短包检测和吞吐量统计。
• 四个字段在 URB 生命周期中协同工作，理解它们的交互是批量传输驱动开发和性能调优的基础。