USB 硬件验证程序 (USB3HWVerifierAnalyzer.exe)
本文介绍用于测试和调试特定硬件事件的 USB 硬件验证程序工具 (USB3HWVerifierAnalyzer.exe)。
大多数硬件问题会以导致最终用户体验不佳的方式出现，且通常很难确定确切的故障。 USB 硬件验证程序旨在捕获设备、端口、中心、控制器或其组合中出现的硬件故障。
USB 硬件验证程序可执行以下任务：
- 实时捕获硬件事件并显示信息。
- 生成包含所有事件相关信息的跟踪文件。
- 分析现有跟踪文件以获取事件信息。
本文包含以下各节：
获取 USB 硬件验证程序分析器工具
USB 硬件验证程序工具包含在 MUTT 软件包中，而此包可通过 MUTT 软件包中的工具进行下载。
此工具包包含多个用于执行压力与传输测试（包括电源转换）和 SuperSpeed 测试的工具。 该包还有一个自述文档（可供单独下载）。 本文档简要概述了 MUTT 硬件的各个类型。 其中提供了有关应运行的各种测试的分步指南，并为控制器、中心、设备与 BIOS/UEFI 测试推荐了相关拓扑。
如何使用 USB 硬件验证程序来捕获事件
若要使用硬件验证程序来捕获事件，请执行以下步骤：
通过在提升的命令提示符处运行此命令来启动会话。
USB3HWVerifierAnalyzer.exe该工具支持以下选项：
选项 说明 -v <VendorID> 记录指定 VendorID 的所有硬件验证程序事件。 -p <ProductID> 记录指定 ProductID 的所有硬件验证程序事件。 -f <ETL 文件> 分析指定的 ETL 文件。 不支持实时分析。 借助此选项，该工具可脱机分析文件。 /v output 向控制台显示所有事件。 运行要为其捕获硬件事件的测试场景。
会话期间，USB 硬件验证程序会在出现硬件事件时捕获其相关信息。 如果要筛选针对特定硬件的事件，则请指定该硬件的 VendorId 和 ProductId。 该工具可能不会捕获对此设备进行完全枚举之前所出现事件的某些相关信息（如 VID/PID）。 会话结束时生成的详细报告中提供了缺少的信息（稍后讨论）。
注意
AllEvents ETL 文件始终包含所有设备的所有 ETW 事件。 它不受 -v 和 -p 开关的影响。
按 VendorId 和 ProductId 进行筛选的命令行如下：
USB3HWVerifierAnalyzer.exe -v 0781 -p 5595硬件验证程序工具的示例输出如下：
Session Name : TraceSessionFriJan271351112023 Attempting to start session TraceSessionFriJan271351112023... Trace Session created...Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 13319329877.425596: (UsbHub3/179) Event Message: Client Initiated Recovery Action VendorID/ProductID: 0x5e3/0x612 DeviceInterfacePath: \??\USB#VID_05E3&PID_0612#6&130491ac&0&4#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic SuperSpeed USB Hub PortPath: 0x12, 0x4, 0x0, 0x0, 0x0, 0x0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Session Stopped...Status : 0按 Ctrl+C 可停止会话。
会话结束时，会向当前目录添加一个名为 AllEvents.etl 的文件。 此文件包含有关会话期间所捕获全部事件的跟踪信息。
除 AllEvents.etl 之外，此命令窗口还会显示一个报表。 此报告包含实时输出中缺失的某些信息。 以下输出显示了上述会话的对应示例测试报告。 此报告显示了 USB 硬件验证程序遇到的所有事件。
Record #1 (Key = 0x57ff0de4858) VendorID/ProductID: 0x451/0x2077 DeviceInterfacePath: \??\USB#VID_0451&PID_2077#6&c4be011&0&2#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic USB Hub PortPath: 0x2, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationError20HubPortPwrCtrlMaskZero #2: (UsbHub3/179): Client Initiated Recovery Action #3: (UsbHub3/179): Client Initiated Recovery Action #4: (UsbHub3/179): Client Initiated Recovery Action #5: (UsbHub3/179): Client Initiated Recovery Action #6: (UsbHub3/179): Client Initiated Recovery Action #7: (UsbHub3/179): Client Initiated Recovery Action #8: (UsbHub3/179): Client Initiated Recovery Action #9: (UsbHub3/179): Client Initiated Recovery Action #10: (UsbHub3/179): Client Initiated Recovery Action #11: (UsbHub3/179): Client Initiated Recovery Action #12: (UsbHub3/179): Client Initiated Recovery Action #13: (UsbHub3/179): Client Initiated Recovery Action #14: (UsbHub3/179): Client Initiated Recovery Action Record #2 (Key = 0x57ff62a36a8) VendorID/ProductID: 0x1058/0x740 DeviceInterfacePath: \??\USB#VID_1058&PID_0740#57583931453631414E5A3331#{a5dcbf10-6530-11d2-901f-00c04fb951ed} DeviceDescription: USB Mass Storage Device PortPath: 0x2, 0x4, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/173): SuperSpeed Device is Connected on the 2.0 Bus Record #3 (Key = 0x57ff79fd4e8) VendorID/ProductID: 0x1edb/0xbd3b PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #2: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #3: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #4: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #5: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #6: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #7: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLength #8: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLength在前面的示例报告中，记下每个记录的 Key 字段值。 此报表会按这些 Key 值对信息进行分类，以便进行阅读。 AllEvents.etl 中捕获的事件使用相同的 Key 值。
运行以下命令，将 AllEvents.etl 转换为文本格式：
USB3HWVerifierAnalyzer.exe -f AllEvents.etl /v > Output.txt在输出文件中，搜索前面记录的 Key 值。 这些值与以下字段之一关联：fid_UcxController、fid_HubDevice和 fid_UsbDevice。
在 Netmon 中打开 AllEvents.etl，然后选择添加 <field_name> 以显示筛选器，以便按控制器、中心和设备来筛选事件。 有关详细信息，请参阅如何安装 Netmon 和 USB ETW 分析程序。
USB 硬件验证程序标志
| 标记 | 表示...... |
|---|---|
| DeviceHwVerifierClientInitiatedResetPipe | 客户端驱动程序通过重置特定管道来响应 I/O 故障，从而启动恢复操作。 在其他情况下，某些客户端驱动程序可能会执行错误恢复。 |
| DeviceHwVerifierClientInitiatedResetPort | 客户端驱动程序通过重置设备来响应 I/O 故障，从而启动恢复操作。 在其他情况下，某些客户端驱动程序可能会执行错误恢复。 |
| DeviceHwVerifierClientInitiatedCyclePort | 客户端驱动程序通过循环此端口来启动恢复操作。 此标志会导致即插即用管理器重新枚举该设备。 |
| DeviceHwVerifierSetIsochDelayFailure | USB 3.0 设备未能完成 SET_ISOCH_DELAY 请求。 此设备可能无法完成该请求，因为驱动程序不需要请求信息或出现暂时性错误。 但是，驱动程序无法区分这些原因。 报表中未捕获此错误。 |
| DeviceHwVerifierSetSelFailure | USB 3.0 设备未能完成 SET_SEL 请求。 此设备会将该请求信息用于链接电源管理 (LPM)。 此设备可能无法完成该请求，因为驱动程序不需要请求信息或出现暂时性错误。 但是，驱动程序无法区分这些原因。 报表中未捕获此错误。 |
| DeviceHwVerifierSerialNumberMismatchOnRenumeration | 此设备在重新枚举期间报告了其他序列号，而不是它在初始枚举期间所报告的序列号。 由于重置端口或系统恢复操作，可能会出现重新枚举。 |
| DeviceHwVerifierSuperSpeedDeviceWorkingAtLowerSpeed | USB 3.0 设备运行的总线速度低于 SuperSpeed。 |
| DeviceHwVerifierControlTransferFailure | 无法将控制传输发送到设备的默认终结点。 由于设备或控制器错误，此传输可能会失败。 中心日志会指出传输失败的对应 USBD 状态代码。 此标志不含 SET_SEL 和 SET_ISOCH_DELAY 控制传输失败。 这些类型的请求将由 DeviceHwVerifierSetIsochDelayFailure 和 DeviceHwVerifierSetSelFailure 标志包含。 |
| DeviceHwVerifierDescriptorValidationFailure | 设备返回的描述符不符合 USB 规范。 中心日志会指出确切错误。 |
| DeviceHwVerifierInterfaceWakeCapabilityMismatch | RemoteWake 位未在设备中正确设置。 支持远程唤醒的 USB 3.0 设备还须支持功能唤醒。 设备可通过两种方式来表明其对功能唤醒的支持。 第一种方法是通过配置描述符的 bmAttributes 字段，第二种则是响应针对该接口的 GET_STATUS 请求。 对于非复合设备，RemoteWake 位值必须与针对接口 0 的 GET_STATUS 请求所返回的值相匹配。 对于复合设备，RemoteWake 位针对至少一个功能必须为 1。 否则，此标志表示该设备在此处报告了相互矛盾的值。 |
| DeviceHwVerifierBusRenumeration | 设备会通过总线重新进行枚举。 由于重置端口或系统恢复操作，可能会出现重新枚举。 当设备处于已禁用/已启用或已停止/已启动状态时，也会重新枚举。 |
| HubHwVerifierTooManyResets | 中心在短时间内经历了过多重置操作。 即使这些重置成功，中心也不会处理请求，且会出现重复的错误。 |
| HubHwVerifierControlTransferFailure | 针对中心的默认终结点的控制传输失败。 由于设备或控制器错误，此传输可能会失败。 中心日志会指出该失败的对应 USBD 状态代码。 |
| HubHwVerifierInterruptTransferFailure | 针对中心的中断终结点的数据传输失败。 由于设备或控制器错误，此传输可能会失败。 中心日志会指出该失败的对应 USBD 状态代码。 如果传输因请求被取消而失败，则不会捕获该失败。 |
| HubHwVerifierNoSelectiveSuspendSupport | RemoteWake 位未在中心的配置描述符中设为 1。 |
| HubHwVerifierPortResetTimeout | 枚举或重新枚举设备时，端口重置操作会超时。未收到端口更改通知，从而表示端口重置已完成。 |
| HubHwVerifierInvalidPortStatus | 根据 USB 规范，目标端口的端口状态无效。 某些设备可能会导致中心报告无效状态。 |
| HubHwVerifierPortLinkStateSSInactive | 目标端口与下游设备之间的链接处于错误状态。 |
| HubHwVerifierPortLinkStateCompliance | 目标端口与下游设备之间的链接处于符合性模式。 在涉及系统休眠-恢复的某些场景中，可能会出现符合性模式错误；在这些情况下，则不会捕获该失败。 |
| HubHwVerifierPortDeviceDisconnected | 目标端口上的下游设备不再连接到总线。 |
| HubHwVerifierPortOverCurrent | 下游端口报告过流状态。 |
| HubHwVerifierControllerOperationFailure | 针对连接到目标端口的设备，某一控制器操作（例如启用设备、配置终结点）失败。 不会捕获来自 SET_ADDRESS 和重置终结点请求的失败。 |