3、xHCI数据结构：设备上下文、端点上下文、传输描述符（TRB）归纳总结
好，咱们进入第3章。前两章我们把xHCI的架构和寄存器摸了一遍，现在该碰碰核心的数据结构了。这章我把设备上下文、端点上下文和TRB这三个东西串起来讲，说白了，它们是xHCI调度器的“三驾马车”。你要是搞不懂它们怎么协同，追Trace的时候会非常痛苦——我早期调试PD协议时就吃过这个亏。
3.1 设备上下文——每个USB设备的“户口本”
设备上下文，英文叫Device Context。它长啥样？就是一块32字节对齐的内存区域，每个槽位（Slot）对应一个。xHCI最多支持255个设备上下文，每个大小是1024字节（32个DWORD）。
核心作用：记录设备的状态、端点配置、以及挂载在哪个端口上。
项目中我见过最坑的bug是设备上下文地址写错了，结果DMA读到一堆垃圾数据，导致设备枚举一直失败。后来我习惯在初始化时先往设备上下文里写个固定pattern，然后让Host Controller读回来校验，这对定位内存一致性问题特别有效。
| 字段 | 偏移（DWORD） | 说明 |
|---|---|---|
| Slot Context | 0-7 | 包含设备地址、端口号、路由字符串、状态等 |
| Endpoint 0 Context | 8-15 | 控制端点0的配置 |
| Endpoint 1-15 Context | 16-31 | 非控制端点的配置，每个占8个DWORD |
有个细节值得提——设备上下文的第一个DWORD是Slot Context的入口控制字。它决定了当前槽位是否有效、以及上下文的状态机走到哪一步。我记得有次调试PD协议里针对电源角色的切换，就是靠监控这个状态字的变化，才抓住驱动层没有及时回应Set Configuration的命令。
3.2 端点上下文——每个管道的“交通规则”
端点上下文好比是给每个管道定规矩。它决定了这个管道怎么传数据、传多大、差错控制怎么做。每个端点上下午文占16个DWORD（64字节），对齐到64字节边界。
这里我画了张图，帮你梳理三者的关系。
说白了，设备上下文是你的一级目录，端点上下文是二级目录，TRB才是真正干活的数据描述符。
端点上下文的关键字段：
- EP State：端点状态机（Disabled, Running, Halted, Error等）。我从Trace里抓过一次状态跑飞，发现是驱动在Set TR Dequeue Pointer之前没把端点的Doorbell敲响。
- Mult, MaxPStreams：多包、流控相关的参数。在PD协议里，BOS描述符经常用到Mult字段，调错时得多留意。
- Interval：微帧调度间隔，直接影响带宽分配。
- CERR：错误计数逻辑（Error Count）。我建议调试阶段把CERR设大一点，避免触碰到重试上限导致设备断开。
技巧：解析Trace时，重点关注Endpoint Context的Dword 0（状态与控制字）和Dword 3（TR Dequeue Pointer）。它们能直接告诉你这个端点当前在哪、下一个TRB该从哪取。
3.3 传输描述符（TRB）——真正的“干活指令”
TRB全称Transfer Request Block，是xHCI和系统内存之间的最小传输单元。它的长度固定为16字节（4个DWORD）。Host Controller通过轮询TRB环来发起数据传输、事件通知以及链路管理等操作。
我习惯把TRB分成三大类：
- 传输类TRB（Normal, Isoch, Control Data/Status等）——真正搬数据的。
- 命令类TRB（Address Device, Configure Endpoint,等等）——用来操作设备上下文和端点上下文。
- 事件类TRB（Transfer Event, Command Completion Event等）——由Host Controller写回内存，通知驱动
TRB内部结构（以Normal TRB为例）：
| Dword | 位域 | 说明 |
|---|---|---|
| 0-1（低64位） | Data Buffer Pointer | 指向实际数据缓冲区的物理地址（64位） |
| 2 | TRB Transfer Length / TD Size / Interrupter Target | 要传输的字节数、剩余TD大小、中断目标 |
| 3 | Cycle bit, Chain bit, IOC bit, TRB Type等 | 控制位域，决定TRB的行为 |
注意：Cycle bit（循环位）是TRB环的关键——Host Controller每轮转一圈就会翻转它。如果你在Trace里发现连续多个TRB都是同一个Cycle值，那很可能是Dequeue和Enqueue指针不同步，属于典型的软硬件握手漏了。
说到这个，我想起之前的一个案例：PD协议里传输BOS描述符时，驱动构造了一组Normal TRB，但忘记设置Chain bit来标识同一个TD内的多段TRB。结果Host Controller以为第一段TRB就是整个传输，提前给了一个Short Packet事件，导致驱动误判BOS长度。后来我们加了Chain bit检查，问题就消失了。
3.4 三者的协同关系：从设备上下文到TRB的链路
嗯，我们来理一下xHCI的数据流向：
- Host Controller收到Doorbell寄存器写操作（或者端口事件），知道哪个设备有活要干。
- 它通过设备上下文基地址数组（DCBAA）找到对应槽位的Device Context。
- Device Context里存着每个有效端点的端点上下文指针（或者内嵌结构）。
- 从端点上下文里取出TR Dequeue Pointer，指向当前该端点要执行的TRB环。
- 开始逐个消耗TRB，直到遇到Chain bit结束或遇到IOC中断请求。
这个链路在调试PD协议时特别重要。比方说，你想定位为什么设备没有响应Set Configuration——你得从Trace里找到对应的Configure Endpoint命令完成事件，回查端点上下文的状态字是否变成了Running。如果状态还是Disabled，那就是上下文没写进去。
我以前犯过一个低级错误：在DDR里分配设备上下文时，忘记将它们对齐到64字节边界。结果Host Controller读到的上下文全是错的，DMA写回的状态也不对。这让我抓了两天头皮，最后还是靠逻辑分析仪对比物理地址才发现的。所以我现在写分配代码时，都会用__attribute__((aligned(64)))或者cacheline对齐宏。
3.5 一个避坑案例
给你讲个真事。去年我带团队调一个PD充电器的兼容性问题，问题现象是设备插上后随机掉枚举。我们用xHCI Trace抓了一大把数据，发现每次出问题时，Device Context的Slot Context状态字段都显示“Preset Error”（预设错误）。
再深入看端点上下文，发现EP0的最大包大小（Max Packet Size）字段被填成了512字节（应该是64）。问题根源是驱动在初始化时，直接从USB 2.0 Description里取了bMaxPacketSize0的值，但没有判断设备是否工作在SuperSpeed模式。对于USB 2.0设备，这个值可能是512；但对于相同描述符的PD设备，必须限制在64字节以内。
修起来很简单——在构造端点上下文之前，先判断设备速度，然后强制EP0的Max Packet Size为64。从那以后，这个随机掉枚举的问题就再也没出现过。
这个小案例说明，数据结构里的每个字段都有其物理含义，调Trace的时候要多问自己一句“这个值合理吗？”