3. xHCI Trace 工具介绍

调试 xHCI 枚举，光看代码和寄存器肯定不够。你得能看到总线上到底发生了什么。

这就是 Trace 工具的价值——它记录 USB 总线上的所有通信细节。

我这些年用过的工具不少，从最简单的 Bus Hound 到厂商专用方案，每个都有它的脾气。这一章我把它们掰开了讲清楚。

3.1 常用通用 Trace 工具

3.1.1 USBlyzer

USBlyzer 算是 Windows 平台上的老牌工具了。它的界面做得不错，能看到设备描述符、配置描述符这些结构化数据。

我用它最多的时候是看描述符请求的响应。比如你请求设备描述符，返回的 18 字节是不是符合规范，USBlyzer 能帮你解析得明明白白。

不过，USBlyzer 有个局限——它工作在协议层，看不到 xHCI 控制器内部的寄存器状态。你只知道总线上有 Setup 包、Data 包、握手包，但不知道 xHCI 什么时候把 TRB 写入 Event Ring。

3.1.2 Bus Hound

Bus Hound 和 USBlyzer 不太一样。它更原始，但信息更全。每一帧数据都能以十六进制形式呈现。

Bus Hound 的强项在于底层捕获。我曾经遇到一个设备枚举失败案例，USBlyzer 显示一切正常，但设备就是不被识别。后来用 Bus Hound 的底层模式，发现主机发的 包时序有问题。

但话说回来，你要是想看清每个 USB 包的细节，Bus Hound 是个不错的选择。

3.1.3 对比分析

说白了，这两个工具看的是同一个东西——USB 总线上的包。但它们的视角不同。USBlyzer 给你翻译好的版本，Bus Hound 给你原材料。

3.2 xHCI 专用 Trace 捕获

通用工具有它们的位置。但如果你想弄明白 xHCI 为什么出错，就得用专用工具了。

我个人觉得最有价值的是 xHCI Event Ring Trace。它记录的是 xHCI 控制器上报给驱动的事件——比如端口状态变化、传输完成、错误中断等。

3.2.1 什么是事件 TRB？

xHCI 规范里定义了多种 Event TRB。常见的有：

• Transfer Event TRB：传输完成或出错时产生
• Port Status Change Event TRB：设备插入/拔出时产生
• Command Completion Event TRB：驱动发的命令执行完毕
• Host Controller Event TRB：控制器本身的状态变化

你想想看，如果设备枚举到第 3 步崩了，你只知道总线上没数据了。但 xHCI Event Ring 能告诉你——是 Transfer Event 返回了错误码，还是 Port Status 根本没变。

3.2.2 怎么捕获 Event Ring？

捕获 Event Ring 不那么简单。它不像 USB 包那样直接挂在总线上。Event Ring 在 xHCI 控制器的内存里，驱动通过 Doorbell 机制触发后，控制器才会写 Event Ring。

我的做法有两种：

1. 软件注入：修改 xHCI 驱动，在 Event Ring 读取点加 Hook。Windows 上可以用 WDF 或 KMDF 的调试接口。Linux 上可以直接改 xhci-hcd 驱动，加 printk。
2. 硬件 Trace：某些厂商的 xHCI IP 支持内部 Trace 输出，通过 JTAG 或专用引脚导出 Event Ring 数据。Intel 的 xHCI 控制器就有这功能。

3.2.3 Windows 上的 ETW Trace

Windows 自带的 Event Tracing for Windows (ETW) 也能捕获 xHCI 事件。你只需要启用 Microsoft-Windows-USB-UCX 和 Microsoft-Windows-USB-XHCI 这两个 Provider。

命令很简单：

xperf -start USBTrace -on "Microsoft-Windows-USB-UCX:0xFF:0x5,Microsoft-Windows-USB-XHCI:0xFF:0x5" -f usbtrace.etl

跑完枚举之后停止：

xperf -stop USBTrace

然后用 USB ETW Viewer 或 Xperf 打开 .etl 文件。

3.3 安装与配置

工具装不上或者配不对，你再懂协议也没用。这里我总结一下常用的配置方法。

3.3.1 USBlyzer 安装

• 最新版本支持 Win10/Win11
• 安装过程中会装驱动，需要以管理员身份运行
• 安装完后重启，设备管理器里能看到 USBlyzer 设备
• 启动后默认监听所有 USB 端口

你可能遇到的坑：杀毒软件会拦截它的驱动安装。我建议装之前关掉实时防护。

3.3.2 Bus Hound 配置

• 打开 Bus Hound，选 Devices 标签页
• 勾选你要监控的设备（通常是 USB 控制器）
• 在 Settings 里把 Buffer Size 调大，默认可能不够用
• 记得开 Phase 模式，不然看不到 Setup/In/Out 包的区别

我建议把 Bus Hound 装成服务，这样系统启动时就能自动开始捕获。

3.3.3 xHCI Event Ring 捕获配置

软件 Hook 方式需要改驱动代码：

// Linux xhci-hcd 驱动示例
// 在 xhci_handle_event() 函数中加入 Trace
static void handle_event(struct xhci_hcd *xhci, union xhci_trb *event) {
    trace_xhci_event(event);
    // 原有处理逻辑
}

硬件 Trace 方式则需参考厂商文档，配置对应的 Trace 寄存器。

3.4 本章知识图谱

这张图我画的是工具选择的决策逻辑。很多人一上来就打开 Bus Hound，结果抓了一堆包却找不到问题。我建议先判断问题属于哪个层次——是协议层、控制器内部还是物理层，然后选对工具。