📚 课程目录第4章 UHCI队列头（QH）与批量传输

4. UHCI队列头（QH）与批量传输

4.1 队列头（Queue Head）结构详解

在UHCI（Universal Host Controller Interface）中，队列头（QH）是调度传输描述符（TD）的核心数据结构。每个QH代表一个传输端点或一组传输请求的入口点，通过水平链接形成调度链表。批量传输（Bulk Transfer）正是依赖QH的链接机制实现异步调度。

4.1.1 QH数据结构定义

UHCI的QH为32字节对齐结构，包含两个关键字段：队列头指针（Queue Head Pointer）和传输描述符链表指针（TD Pointer）。以下是标准QH的C语言定义：

/* UHCI 队列头结构（32字节对齐） */
struct uhci_qh {
    uint32_t hw_link;          /* 水平链接指针（指向下一个QH或TD） */
    uint32_t element_link;     /* 垂直链接指针（指向第一个TD） */
    /* 以下为软件辅助字段（非硬件必需） */
    struct uhci_td *td_list;   /* 软件维护的TD链表头 */
    uint32_t qh_status;        /* 队列状态标志 */
    uint32_t reserved[4];      /* 保留字段，填充至32字节 */
} __attribute__((aligned(32)));

关键对齐要求：QH必须分配在32字节对齐的物理地址上。如果对齐错误，UHCI控制器将忽略该QH并产生调度错误。驱动开发中常用 kmem_cache_create 配合对齐标志分配QH内存。

4.1.2 QH链接字段解析

字段	位域	描述
hw_link	[31:4] 地址位 [3] QH/TD选择位 [2] 垂直/VF位 [1:0] 终止位	指向下一个调度节点。位3=1表示指向QH，=0表示指向TD；位2=1表示垂直遍历结束；位1:0=11表示链表终止。
element_link	[31:4] 地址位 [3] 保留 [2] VF位 [1:0] 终止位	指向当前QH的第一个TD。如果为终止状态（位1:0=11），表示该QH无待处理TD。

调度规则：UHCI控制器遍历水平链表时，遇到QH则检查其element_link。如果element_link非空，控制器垂直遍历该QH下的TD链表，处理完所有TD后再回到水平链表继续前进。这种“水平遍历QH、垂直遍历TD”的机制是UHCI批量传输调度的基础。

4.2 批量传输（Bulk Transfer）在UHCI中的调度机制

4.2.1 批量传输的调度位置

UHCI将传输分为两类调度帧：

周期性传输（Isochronous/Interrupt）：在帧起始（SOF）后的固定时间槽内调度，优先级最高。
非周期性传输（Control/Bulk）：在周期性传输完成后剩余的帧时间内调度，优先级较低。

批量传输属于非周期性传输，其QH被链接在UHCI帧列表（Frame List）的非周期性队列头指针之后。UHCI控制器在每个帧（1ms）中，先处理完所有周期性传输，再遍历非周期性链表执行批量传输。

带宽抢占风险：如果周期性传输占满整个帧时间（如多个高速中断端点），批量传输可能被无限期延迟。驱动开发中必须通过USB规范规定的带宽预算（Frame Budget）来限制周期性传输的总带宽，通常保留至少10%的帧时间给批量传输。

4.2.2 批量传输调度流程图

下图展示了UHCI控制器在一个帧内处理批量传输的完整流程：

4.2.3 批量传输QH的链接与遍历

批量传输的QH被组织在UHCI的非周期性链表（Non-periodic List）中。该链表以帧列表索引0的QH指针为入口，所有批量QH通过hw_link字段水平串联。UHCI控制器在每个帧中按以下步骤遍历：

获取入口QH：从帧列表的第0项读取非周期性QH指针。
检查element_link：如果当前QH的element_link非终止状态，则垂直遍历其TD链表。
处理TD：执行TD中的传输请求（发送/接收数据），更新TD状态。
垂直遍历结束：当TD链表的VF位被置位或element_link为终止状态时，返回水平链表。
水平前进：通过hw_link移动到下一个QH，重复步骤2-4。
链表终止：当hw_link的终止位为11时，停止遍历，等待下一帧。

驱动调试要点：在批量传输调度中，最常见的错误是QH的element_link未正确初始化导致控制器死循环。调试时应在QH分配后立即将element_link设置为终止状态（0x03），待TD就绪后再更新。使用 udelay(1) 确保内存写入顺序正确。

4.3 批量传输TD与QH的协同工作

4.3.1 TD结构回顾

批量传输的每个数据包对应一个传输描述符（TD）。TD包含令牌（Token）、缓冲区指针（Buffer Pointer）和控制状态字段。以下是批量传输TD的关键字段：

字段	大小	批量传输配置
Link Pointer	32位	指向下一个TD，形成垂直链表
Token	32位	包含端点号（Endpoint）、设备地址（Device Address）、PID（IN/OUT/SETUP）和数据长度
Buffer Pointer	32位	指向数据缓冲区的物理地址（必须4字节对齐）
Status	32位	包含错误位（Bit Stuff Error、CRC Error、Timeout等）和完成状态

4.3.2 QH与TD的链接关系图

下图展示了批量传输中QH与TD的垂直链接关系：

4.4 批量传输调度中的常见问题与调试方法

4.4.1 调度死锁与QH遍历超时

当批量传输QH的element_link指向一个已完成的TD但未更新时，UHCI控制器会反复处理同一个TD，导致调度死锁。调试方法：

检查TD状态位：在中断处理中读取TD的Status字段，确认是否已置位完成位（Bit 23: Active）。
验证element_link更新：使用 print_hex_dump 打印QH的element_link值，确认驱动在TD完成后已将其更新为下一个TD或终止状态。
设置调度超时：在驱动中实现软超时机制，如果某个QH在10ms内未完成，强制重置该QH并报告错误。

硬件Bug规避：某些UHCI控制器（如早期ICH系列）在批量传输QH的element_link为终止状态时，如果hw_link指向自身，会导致无限循环。驱动开发中应避免QH的hw_link自引用，始终确保链表最终指向终止节点。

4.4.2 批量传输数据完整性问题

批量传输的数据完整性依赖于TD的缓冲区指针和长度字段。常见问题包括：

问题现象	可能原因	调试方法
数据错位	缓冲区未4字节对齐	使用 `kmalloc` 的 `GFP_DMA` 标志分配对齐内存
数据丢失	TD长度字段超过64字节	批量传输最大包长为64字节，超过需分多个TD
CRC错误	USB线缆噪声或驱动时序问题	检查UHCI端口状态寄存器，增加重试逻辑
设备无响应	设备地址或端点号配置错误	使用USB分析仪抓取总线数据，验证Token字段

4.4.3 批量传输调度性能优化

在驱动开发中，批量传输的吞吐量受QH链表长度和TD数量影响。优化建议：

合并TD：将多个连续的小数据包合并到一个TD中（不超过64字节），减少QH遍历次数。
预分配QH池：在驱动初始化时预分配一批QH，避免运行时动态分配导致的内存碎片。
使用批量流（Bulk Streams）：如果硬件支持USB 3.0批量流，可并行处理多个批量传输。
调整帧预算：在UHCI的帧列表配置中，为非周期性传输预留更多时间槽。

调试工具推荐：使用 usbmon 工具捕获USB总线数据，结合 ftrace 跟踪UHCI驱动的中断处理函数，可以精确定位批量传输调度中的延迟点。在QH处理前后添加 trace_printk 标记，分析调度时间分布。

4.5 本章小结

UHCI的队列头（QH）是批量传输调度的核心数据结构，通过水平链表组织多个传输端点，通过垂直链表管理每个端点的TD序列。批量传输在帧内的非周期性时间段执行，优先级低于周期性传输。驱动开发中需要重点关注QH的链接正确性、TD的缓冲区对齐以及调度死锁的预防。掌握QH与TD的协同机制，是调试UHCI批量传输性能与稳定性的基础。