windows USB 设备驱动开发-USB 客户端驱动程序验证程序

USB 客户端驱动程序验证程序是 USB 3.0 驱动程序堆栈的一项功能，包含在 Windows 8 中。 启用验证程序后，USB 驱动程序堆栈会失败或修改客户端驱动程序执行的某些操作。 这些失败模拟的错误条件，否则可能难以找到，并可能导致以后产生不良结果。 模拟故障使你有机会确保驱动程序能够正常处理故障。 客户端可以通过错误处理代码处理错误或执行不同的代码路径。

例如，客户端驱动程序通过批量终结点的静态流支持 I/O 操作。 通过使用验证程序，可以确保驱动程序的流逻辑正常工作，而不考虑各种主机控制器支持的流数。 若要模拟该场景，可以使用 usbVerifierStaticStreamCountOverride 设置稍后讨论。 每次驱动程序调用 USBD_QueryUsbCapability 以确定主机控制器支持的最大静态流数时，例程将返回不同的值。

 重要 USB 客户端驱动程序验证程序仅针对各种 xHCI 控制器测试驱动程序。 它模拟某些固有的 2.0 控制器行为，例如缺少链接式 MDL 支持。 但是，我们建议你必须使用 USB 2.0 控制器测试客户端驱动程序，而不是使用此工具来替代相同。

Windows 硬件实验室工具包 (HLK) 测试可用于系统、USB 主机控制器、集线器和设备的其他测试。 这些测试涵盖基本设备功能、可靠性和与 Windows 的兼容性。 有关详细信息，请参阅 Windows Hardware Lab Kit (HLK) USB 测试。

如何启用 USB 客户端驱动程序验证程序

若要使用 USB 客户端驱动程序验证程序，请在运行 Windows 8的目标计算机上启用它。 目标计算机必须具有 USB 设备连接到的 xHCI 控制器。

为客户端驱动程序启用驱动程序验证程序时，将自动启用 USB 客户端驱动程序 验证程序 。 或者，可以通过设置此注册表项来启用验证程序。

启用 Windows Driver Foundation (WDF) 验证程序控制应用程序 (WdfVerifier.exe) 不会自动启用 USB 客户端驱动程序验证程序。

HKEY_LOCAL_MACHINE
   SYSTEM
      CurrentControlSet
         services
            <Client Driver>
               Parameters
                  UsbVerifierEnabled (DWORD)

UsbVerifierEnabled 注册表项采用 DWORD 值。 当 UsbVerifierEnabled 为 1 时，将启用 USB 客户端驱动程序验证程序;0 禁用它。 如果为客户端 驱动程序启用了驱动程序验证程序 ，并且 UsbVerifierEnabled 为 0，则禁用 USB 客户端驱动程序验证程序。

USB 客户端驱动程序验证程序的配置设置

启用验证程序后，USB 驱动程序堆栈通过调用USBD_xxxUrbAllocate例程来跟踪客户端驱动程序分配的 URL 。 如果客户端驱动程序泄露任何 URB，USB 驱动程序堆栈会使用该信息通过 驱动程序验证程序进行 bug 检查。 在这种情况下，请使用 !usbanalyze -v  命令来确定泄漏原因。

此外，还可以根据需要配置 USB 客户端驱动程序验证程序以修改或失败特定例程，并指定例程必须失败的频率。 若要配置验证程序，请设置注册表项，如下所示：

HKEY_LOCAL_MACHINE
   SYSTEM
      CurrentControlSet
         services
            <Client driver>
               Parameters
                  <USB client driver verifier setting> (DWORD)

USB 客户端驱动程序验证程序设置注册表项采用 DWORD 值。 如果添加、修改或删除任何设置，则必须使用系统重新枚举设备以应用设置。

此表显示了 USB 客户端驱动程序验证程序设置的可能值。 这些设置适用于在 Service 密钥下指定的客户端驱动程序。

USB 硬件验证程序 (USB3HWVerifierAnalyzer.exe)

有用于测试和调试特定硬件事件的 USB 硬件验证程序工具 (USB3HWVerifierAnalyzer.exe)。

大多数硬件问题会以导致最终用户体验不佳的方式出现，且通常很难确定确切的故障。 USB 硬件验证程序旨在捕获设备、端口、中心、控制器或其组合中出现的硬件故障。

USB 硬件验证程序可执行以下任务：

• 实时捕获硬件事件并显示信息；
• 生成包含所有事件相关信息的跟踪文件；
• 分析现有跟踪文件以获取事件信息；

获取 USB 硬件验证程序分析器工具

USB 硬件验证程序工具包含在 MUTT 软件包中，而此包可通过 MUTT 软件包中的工具进行下载。

此工具包包含多个用于执行压力与传输测试（包括电源转换）和 SuperSpeed 测试的工具。 该包还有一个自述文档（可供单独下载）。 本文档简要概述了 MUTT 硬件的各个类型。 其中提供了有关应运行的各种测试的分步指南，并为控制器、中心、设备与 BIOS/UEFI 测试推荐了相关拓扑。

如何使用 USB 硬件验证程序来捕获事件

若要使用硬件验证程序来捕获事件，请执行以下步骤：

1.通过在提升的命令提示符处运行此命令来启动会话。

USB3HWVerifierAnalyzer.exe

该工具支持以下选项：

2.运行要为其捕获硬件事件的测试场景。

会话期间，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

3.按 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 值。

4.运行以下命令，将 AllEvents.etl 转换为文本格式：

USB3HWVerifierAnalyzer.exe -f AllEvents.etl /v > Output.txt

5.在输出文件中，搜索前面记录的 Key 值。 这些值与以下字段之一关联：fid_UcxController、fid_HubDevice和 fid_UsbDevice。

在 Netmon 中打开 AllEvents.etl，然后选择添加 <field_name> 以显示筛选器，以便按控制器、中心和设备来筛选事件。

USB 硬件验证程序标志

USBLPM 工具

USBLPM 工具监视 USB 3.0 端口的 U0/U1/U2/U3 电源状态。 它还可用于验证 U0/U1/U2 之间的转换是否正确发生。 此外，该工具还可以在系统中的所有设备上启用或禁用 U1 和/或 U2 状态。

该工具包含在 MUTT 软件包中。

USBLPM

USBLPM 仅适用于Windows 8，适用于 Microsoft USB 3.0 驱动程序堆栈。 该工具不作为此包中的批处理文件和脚本的一部分运行。 该工具适用于控制器、集线器和设备公司，用于监视新的 USB 3.0 电源状态。

USBLPM 在 监视、 测试或 配置 模式下运行。

监视

这是在没有任何参数的情况下运行该工具时的默认模式。 在此模式下，该工具会定期查询每个级别的 USB 3.0 设备，并显示端口的当前 U 状态。 默认情况下，该工具每 500 毫秒运行一次查询。

在监视模式下，可以通过以下命令行选项更改时间段：

usblpm /PollingInterval <*time in milliseconds*>

其中，时间值为 1 到 100000 的整数。 /PollingInterval 选项是可选的。 通常，不应更改时间段。

测试

测试设备或中心：

1. 启动该工具。
2. 将模式从“监视”更改为“测试”。
3. 选择测试设备。
4. 单击“ 启动” 以启动测试运行。

测试在 10 秒内完成，结果会显示给用户。

测试尝试 U0/U1/U2 状态的不同组合，并确保测试设备成功重新进入 U0。 这是通过发送查询 BOS 描述符的控件传输来完成的。

若要测试中心，请删除连接到中心的所有设备并运行测试。 然后，附加一个或多个设备并重新运行测试。 但是，如果其中一个下游设备未正确支持 U1/U2，则中心测试将失败。 因此，在中心上运行测试之前，建议先在中心下游的设备上运行测试，以确保它们通过测试。

运行测试时，请勿更改设备拓扑。 如果动态更改配置，则工具的行为未定义。

配置 U1/U2 状态

可以通过运行以下命令，使用 USBLPM 为系统上的所有 USB 设备启用或禁用 U1 和 U2 状态：

usblpm /enable|/disable U1|U2

例如，此命令禁用 U2： 

usblpm /disable U2

在“配置”模式下，该工具不显示任何窗口。 在运行该工具后，启用或禁用将保留。

USBLPM 的已知问题

在测试 SuperSpeed 集线器的 USBLPM 之前，应执行以下步骤来禁用选择性挂起。

1. 在“设备管理器”中，右键单击“SuperSpeed”中心，然后选择“属性”。
2. 单击“ 电源管理 ”选项卡。
3. 取消选中 “允许计算机关闭此设备以节省电量”。

使用 USBLPM 完成测试后，通过选中 “允许计算机关闭此设备以节省电源以重新启用选择性挂起”，为中心启用选择性挂起。

 备注 USBLPM 当前不测试 USB 2.1 LPM。

USBStress 包

USBStress 是内核模式驱动程序的用户模式应用程序 (usbstress.exe) 和驱动程序安装包的组合，usbstress.sys。

这些文件包含在 MUTT 软件包中。USBStress 是一组测试，侧重于整个 USB 驱动程序堆栈、USB 通用父驱动程序 (Usbccgp.sys) 、控制器及其上游集线器。 USBStress 随机选择测试并配置附加的测试设备。 由于测试的随机性，建议在 24 小时内运行 USBStress，以允许更多的测试组合。

该工具执行与测试设备之间各种传输长度的控制、批量、常时等量数据传输。 对于 SuperMUTT 设备，USBTCD 将数据传输到批量终结点支持的流。

USBStress 驱动程序在很大程度上是自驱动式的，也就是说，大多数 I/O 请求是由驱动程序而不是应用程序生成的。 驱动程序使用计时器和工作项来生成 I/O 并执行其他操作。 驱动程序检查注册表以确定它是否应运行其测试。 外部程序设置该注册表项。 此驱动程序的目标是在各种操作之间创建尽可能多的并发性，以消除争用条件和同步问题。

此列表汇总了 USBStress 执行的测试：

• 使用远程唤醒进行选择性挂起；
• 批量、中断和常时等量终结点上的并发读/写请求以及取消；
• 并发字符串传输请求和取消；
• 批量终结点和取消 上的并发中止管道；
• 随机重置为意外删除和重新枚举；
• 随机重置为意外删除和重新枚举，重新枚举失败；
• 随机选择可用的备用接口 ；
• 随机指示设备每隔 n 个控制传输停止一次；
• 如果已连接，随机指示 MUTT Pack (断开 VBUS 与公开的下游端口的连接；
• 如果已连接，则随机指示 MUTT 包 ，以模拟公开的下游端口 上的过流情况；
• 随机指示 MUTT Pack (是否已连接) ，以在中心上执行硬件重置；

若要为 MUTT 设备安装usbstress.sys驱动程序，请使用 MuttUtil 和 -UpdateDriver 选项：

c:\Program Files (x86)\USBTest\x64>MuttUtil.exe -UpdateDriver usbstress.inf
Return value: 0


c:\Program Files (x86)\USBTest\x64>MuttUtil.exe -list
       :    : HARDWARE ID                    :  PROBLEM CODE  : DRIVER
DEVICE :  0 : USB\VID_045E&PID_078E&REV_8011 :             0  : USBSTRESS
Return value: 1

USBTCD 包

USBTCD 是用户模式应用程序和内核模式驱动程序的组合。 该工具执行读取和写入操作。 它启动与测试设备之间各种传输长度的控制、批量、常时、数据传输。 对于 SuperMUTT 设备，USBTCD 将数据传输到批量终结点支持的流。 它还可以将传输缓冲区作为链接的 MDL 发送。 在这种情况下，可以指定传输缓冲区中的段数。

USBTCD 文件包含在 MUTT 软件包中。

USBTCD

若要使用这些命令，必须加载 USBTCD 驱动程序 (USBTCD.sys) 作为设备的函数驱动程序。 若要加载设备的驱动程序，请运行 MUTTUtil 并指定 USBTCD.inf。 此工具为所有连接的 USB 设备加载 USBTCD.sys 。

c:\Program Files (x86)\USBTest\x64>MuttUtil.exe -UpdateDriver usbtcd.inf
Return value: 0


c:\Program Files (x86)\USBTest\x64>MuttUtil.exe -list
       :    : HARDWARE ID                    :  PROBLEM CODE  : DRIVER
DEVICE :  0 : USB\VID_045E&PID_078E&REV_8011 :             0  : USBTCD
Return value: 1

可以使用以下命令测量与 SuperMUTT 设备的批量终结点之间的传输性能。

Usbtcd –perf –read 1 100 2 10240000 0

Usbtcd –perf –write 1 100 0 10240000 0

在前面的命令中，USBTCD 从管道 2 读取 10240000 字节。 第二个命令中，USBTCD 启动写入操作，其中将 10240000 个字节发送到管道 0。 对于这两个命令，该工具执行操作 100 次，并且不指定超时值。

这些命令用于测量 MUTT 设备的批量终结点的性能。 请注意，在这种情况下，传输大小会减小。

Usbtcd –perf –read 1 100 2 512000 0

Usbtcd –perf –write 1 100 0 512000 0

这些命令测量到 SuperMUTT 设备的批量终结点流的数据传输的性能。 目前，设备固件尝试每毫秒切换一次流，将 ERDY 与新的流编号一起发送到主机。 这是使用设备内部的计时器实现的。

Usbtcd –sread 1 100 7 1 1024 0

Usbtcd –swrite 1 100 6 1 1024 0

在上述命令中，USBTCD 在 SuperMUTT 设备的批量终结点中读取和写入特定流。 在第一个命令中，该工具启动一个工作线程，该线程从与管道 7 关联的流 1 读取 1024 字节。 同样，第二个命令将 1024 字节写入与管道 6 关联的流 1。 对于这两个命令，该工具执行操作 100 次，并且不指定超时值。

若要查看有关 USBTCD 的帮助，请运行以下命令：

usbtcd -?

命令显示有关命令行选项的信息。 可以在命令行上指定传输大小、详细程度、传输超时等。

USB XHCIWMI

XHCIWMI 是用于诊断目的的工具。 此工具仅在Windows 8上运行，并在设备连接到 xHCI 端口和 Windows 加载 Microsoft USB 3.0 驱动程序堆栈时收集信息。

XHCIWMI在提升的命令提示符窗口中运行以下命令：

Xhciwmi.exe

该工具在命令窗口中显示当前固件版本和有关控制器的信息。 运行以下命令，针对已知问题验证控制器和集线器的固件：

Xhciwmi.exe –verify

建议使用 –verify 选项来检查控制器和连接的中心。