如何使用 Logman 捕获 USB 事件跟踪

  • 项目

本文提供有关使用 Logman 工具捕获 USB ETW 事件跟踪的信息。 Logman 是内置于 Windows 中的跟踪工具。 可以使用 Logman 将事件捕获到事件跟踪日志文件中。

先决条件

事件跟踪日志文件可以很快增长，但较小的日志文件更易于导航和传输。 在开始跟踪之前，请考虑执行以下步骤从日志中排除无关事件，以便可以专注于要检查的设备活动：

  • 断开非相关设备的任何非关键 USB 设备的连接。 设备越少，跟踪越小，更易于阅读和分析。
  • 如果系统具有 USB 键盘或鼠标，请改为使用远程桌面输入跟踪命令。
  • 在相关操作周围尽可能缩小跟踪的开始和结束范围。
  • 如果只对特定类别的 USB 事件感兴趣，可以使用关键字筛选记录的事件。 有关详细信息，请参阅“备注”。

来自 USB 3.0 驱动程序堆栈的事件跟踪类似于 Windows 7 中引入的 USB 2.0 驱动程序堆栈跟踪。 可以在Windows 8计算机上捕获 USB 2.0 驱动程序堆栈中的事件跟踪。 从 USB 2.0 和 USB 3.0 驱动程序堆栈捕获事件跟踪的方式类似。 可以从 USB 2.0 或 USB 3.0 驱动程序堆栈中独立捕获事件。 将 USB 2.0 设备连接到 USB 3.0 主控制器时，可从 USB 3.0 驱动程序堆栈获取事件跟踪。 在这种情况下，你将查看 USB 2.0 设备的新 USB 3.0 驱动程序堆栈事件。

Instructions

收集 USB 跟踪事件

  1. 打开具有管理权限的命令提示符窗口。 为此，请选择“开始”，在搜索框中键入 cmd ，选择并按住 (或右键单击“) cmd.exe”，然后选择“ 以管理员身份运行”。

  2. 在命令提示符窗口中，输入以下命令以启动捕获会话：

    logman create trace -n usbtrace -o %SystemRoot%\Tracing\usbtrace.etl -nb 128 640 -bs 128
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBXHCI (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3 (Default,PartialDataBusTrace)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBPORT
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB
logman update trace -n usbtrace -p Microsoft-Windows-Kernel-IoTrace 0 2
logman start -n usbtrace

    完成上述每个命令后，Logman 会显示 The command completed successfully.

  3. 执行要捕获的操作。 例如，若要捕获设备枚举的事件，可以插入在 设备管理器 中显示为“未知设备”的 U 盘。 使命令提示符窗口保持打开状态。

  4. 完成方案后停止会话。 输入以下命令以结束捕获会话：

    可以通过运行以下命令来停止 USB 集线器和端口事件收集：

    logman stop -n usbtrace
logman delete -n usbtrace
move /Y %SystemRoot%\Tracing\usbtrace_000001.etl %SystemRoot%\Tracing\usbtrace.etl

前面的捕获会话生成名为 usbtrace.etl 的 etl 文件。 跟踪文件存储在 %SystemRoot%\Tracing\usbtrace.etl (C：\Windows\Tracing\usbtrace.etl) 。 将文件移动到另一个位置或将其重命名，以避免在捕获下一个会话时覆盖它。

文件包含来自 USB 3.0 和 USB 2.0 驱动程序堆栈的事件跟踪。 如果要将事件跟踪减少到仅一个 USB 驱动程序堆栈，请从下一个跟踪会话中删除另一个驱动程序堆栈。 为此，可以修改步骤 2 中显示的命令序列，以删除与要从跟踪会话中删除的驱动程序堆栈对应的“logman update”行。

注解

USB 3.0 驱动程序堆栈事件的捕获筛选器

请注意 Logman 捕获命令中的 ETW 关键字，例如 Default 和 PartialDataBusTrace 。 这些字词是 ETW 关键字，用于指示要查看的事件类型。 可以使用 ETW 关键字筛选 USB 驱动程序写入跟踪日志的事件，并自定义要查看的关于从 USB 3.0 驱动程序堆栈捕获的事件的信息量。 保存与任何关键字匹配的事件。 请注意，此筛选方法适用于捕获时，而不是在分析期间使用。

可以根据要求根据关键字筛选事件。 下面是用于筛选 USB 3.0 驱动程序堆栈事件的关键字：

ETW 关键字 (keyword) 说明
Default 显示对常规故障排除有用的事件。 这些事件类似于 USB 2.0 ETW 事件，但不包括任何 USB 传输事件。
StateMachine 显示驱动程序内部状态机转换。 事件不包括在默认关键字 (keyword) 中。
破旧 在跟踪的开头显示设备信息事件，并捕获 USB 树的起始状态。 设备信息 Rundown 事件对于保存非常重要，以便跟踪包含已连接设备的 USB 描述符和 USB 设备说明等详细信息。 这些事件包含在默认关键字 (keyword) 中。 如果不使用默认关键字 (keyword) ，则应使用 Rundown 关键字 (keyword) 。 其余的 Rundown 事件提供有关驱动程序内部状态机最近状态转换的信息。 这些事件包含在 StateMachine 关键字 (keyword) 中。
电源 显示 Default 事件的子集。 显示设备电源转换事件。
IRP 显示 Default 事件的子集。 事件显示来自客户端驱动程序的 IRP 以及用户模式请求生成的 IRP。 但是，有效的 USB 传输 (URB) 请求不会随 IRP 关键字 (keyword) 一起显示，并且需要 HeadersBusTrace、PartialDataBusTrace 或 FullDataBusTrace 才能显示。
HeadersBusTrace 显示所有 USB 传输事件，但不保存数据包。
PartialDataBusTrace 显示所有 USB 传输事件，并保存有限的总线数据有效负载。
FullDataBusTrace 显示所有 USB 传输事件，并保存最多 4 KB 的总线数据，以便进行批量、中断和控制传输。 请注意，仅记录链接 MDL 的第一个缓冲区。 虽然 URB_ISOCH_TRANSFER请求结构) 保存，但不会 (记录常时等量总线数据。 有关详细信息，请参阅 如何发送链接的 MDL 和 如何将数据传输到 USB 常时等量终结点。
HWVerifyHost 显示 Default 事件的子集。 这些事件指示 USB 主机控制器硬件中何时发生错误。
HWVerifyHub 显示 Default 事件的子集。 这些事件指示 USB 集线器硬件中何时发生错误。
HWVerifyDevice 显示 Default 事件的子集。 这些事件指示 USB 设备硬件中何时发生错误。

例如，下面是一系列命令，用于启动会话以捕获 USB 设备电源转换。 由于 (USB 3.0 驱动程序堆栈) 选择提供程序，因此仅针对 USB 3.0 主机控制器下游连接的设备捕获事件。

logman create trace -n usbtrace -o %SystemRoot%\Tracing\usbtrace.etl -nb 128 640 -bs 128
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBXHCI (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3 (Rundown,Power)
logman update trace -n usbtrace -p Microsoft-Windows-Kernel-IoTrace 0 2
logman start -n usbtrace

电源事件的捕获筛选器

USB 设备的一个有用的 ETW 关键字 (keyword) 是 USB 端口驱动程序的 PowerDiagnostics 标志。 使用此关键字 (keyword) 时，端口驱动程序会记录主机控制器和终结点信息，但省略描述传输的所有事件。 如果不需要查看传输事件，可以使用 PowerDiagnostics 关键字 (keyword) 将跟踪日志的大小减少多达 85%。 启动跟踪时指定 PowerDiagnostics 关键字 (keyword) ，如以下示例所示：

Logman start Usbtrace -p Microsoft-Windows-USB-USBPORT PowerDiagnostics -o usbtrace.etl -ets -nb 128 640 -bs 128

Logman update Usbtrace -p Microsoft-Windows-USB-USBHUB –ets

如果筛选的跟踪日志有许多主机控制器异步计划启用和禁用事件，则可以在使用 Netmon 筛选器查看日志时将其筛选掉，如以下示例所示：

NOT (Description == "USBPort_MicrosoftWindowsUSBUSBPORT:Host Controller Async Schedule Enable"
OR Description == "USBPort_MicrosoftWindowsUSBUSBPORT:Host Controller Async Schedule Disable")

有关 Netmon 筛选器的详细信息，请参阅 案例研究：使用 ETW 和 Netmon 对未知 USB 设备进行故障排除中的“USB Netmon 筛选器”。

有时，在跟踪日志中显示传输事件会很有帮助，例如导致错误（如 XACT 错误或停止）的中心请求和设备请求。 可以先捕获没有传输事件的日志，然后分析该较小的日志。 在大致了解问题方案中的问题后，再次运行跟踪而不进行筛选。