Authored by Philip Ries [MSFT]
Windows 8 provides a USB driver stack to support USB 3.0 devices. The Microsoft-provided USB 3.0 driver stack consists of three drivers: Usbxhci.sys, Ucx01000.sys, and Usbhub3.sys. All three drivers work together to add native support to Windows for most USB 3.0 host controllers. The new driver stack supports SuperSpeed, high-speed, full-speed, and low-speed devices.
The USB 2.0 driver stack is supported on Windows 8. For tracing purposes, the USB 2.0 driver stack consists of: Usbport.sys, Usbhub.sys.
Through event traces, the USB 3.0 driver stack provides a view into the fine-grained activity of the host controller and all devices connected to it. In this blog post, I will show you how to capture USB ETW event traces and get you started with the parser. I’ll also discuss some new parser features and filters and briefly explain how to use capture filters to narrow down the event traces for a specific scenario.
I recommend that you always capture event traces from both USB 2.0 and 3.0 driver stacks in Windows 8. That way, you don’t have to figure out the type of host controller to which the device is connected, before capturing event traces.
Capturing USB event traces
You can capture USB event traces without installing any software.
- Open an elevated command prompt window
One way is to type “command prompt” on the Start screen. Right-click on the Command Prompt shown in the result, and select Run as administrator.
- Disconnect the USB devices that you are not interested in. Fewer devices result in smaller traces making it easier to read and analyze.
- Start a capture session by pasting this sequence of commands:
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
- Perform the action that you want to capture. For example, plug in a USB flash drive that shows up as an Unknown device in Device Manager. The session captures device enumeration activities. Keep the command prompt window open.
- Stop the session when you’re finished by pasting this sequence of commands:
logman stop -n usbtrace logman delete -n usbtrace move /Y %SystemRoot%\Tracing\usbtrace_000001.etl %SystemRoot%\Tracing\usbtrace.etl
The preceding capture session generates an etl file, named usbtrace.etl. The trace file is stored at %SystemRoot%\Tracing\usbtrace.etl (C:\Windows\Tracing\usbtrace.etl). Move the file to another location or rename it in order to avoid overwriting it when you capture the next session.
USB ETW Parsers
You can view USB ETW event traces using Microsoft Network Monitor, also referred to as Netmon. Netmon won’t parse the trace out of the box; it also requires USB ETW parsers, which are text files written in Network Monitor Parser Language (NPL) that describe the structure of USB ETW event traces and define USB-specific columns and filters that the user can use. These parsers make Netmon the best tool for analyzing USB ETW traces.
This blog post is being released ahead of an easier, Web-based way to get the parsers. For the time being only, parsing the trace additionally requires the Windows Driver Kit (WDK). This blog post will be updated when we have an easier solution for you. We anticipate changing only steps 3-5.
USB ETW parser setup requires Windows 7 or a later version of Windows. You can read a trace file on a Windows 7 computer even when the file contains event traces captured on a Windows 8 computer.
To install USB ETW parsers:
- Determine whether you have 32-bit Windows or 64-bit Windows:
- Open the Start Menu.
- Right click Computer and select Properties.
- Look at the System type field. (Note: 32-bit corresponds to “x86” for the downloads).
- Install Netmon:
- Go to the bottom of the Quick details on the Netmon 3.4 download page and press the Download button for your system type.
- Download and run the exe. When it asks about setup type, Typical is fine.
- Open the Start screen, type “powershell”, right click on the Windows PowerShell result, and select Run as administrator.
- Type or paste the following command:
Set-ExecutionPolicy RemoteSigned -Force
- Close the PowerShell window
- Open a PowerShell window (you don’t need to Run as administrator) and run the following commands. Adjust the path if you installed the kit to a different location:
cd "C:\Program Files (x86)\Windows Kits\8.0\Tools\x86\Network Monitor Parsers\usb" ..\NplAutoProfile.ps1
Now you’re set up! You can now launch Netmon and open an .etl trace by selecting File -> Open -> Capture.
What’s New in USB ETW Parser for USB 3.0
Before you learn about the USB 3.0 features of the USB ETW parser, I recommend that you read my previous tutorial on reading USB 2.0 driver stack traces. That post describes techniques that apply to the new parser. In this post I’ll point out the key additions to what you can do with the events from the USB 3.0 driver stack on Windows 8.
Note: The event trace is made up of individual events, each of which indicates something that happened in the driver stack. Each event conforms to one of several types defined by the driver stack. Important types of events from the USB 2.0 driver stack are also defined in the USB 3.0 driver stack. However, there are subtle differences between those types. As an example, let’s look at a USB control transfer completion event type.
USB 2.0 driver stack event type:
Description: USBPort:Complete URB_FUNCTION_CONTROL_TRANSFER_EX with Data
Frame Details pane: Contains idVendor (also known as USB VID) and idProduct (also known as USB PID)
USB 3.0 driver stack event type:
Description: UsbUcx:Complete URB_FUNCTION_CONTROL_TRANSFER_EX with data
Frame Details pane: Does not contain idVendor or idPid. Instead, you can add new columns to the Frame Summary pane—see below.
USB 3.0 driver stack traces provide useful device information in new columns that are not available for USB 2.0 driver stack traces, such as USB Device Description, USB Vid, and USB Pid.
Plus, all USB event traces, even traces from the USB 2.0 driver stack, now show more information about the request as each URB completes. Notice values, such as, “673280 of 1048576” under USB Length. Those values indicate the actual transfer length of each URB on completion with the context of the total request length (original TransferBufferLength specified by the client driver). Also, you can see how long (in seconds) it took for a request to complete under the USB Request Duration column.
You can write new filters such as these for event traces from USB 2.0 and USB 3.0 driver stacks:
USBIsError == 1 // Any error events from the USB drivers
USBIsDisconnect == 1 // Show when any device disconnected
All columns can be filtered. Just right-click a cell and Netmon creates a filter based on its value and the column name.
Activity ID tracing
Drivers in the USB driver stack (both 2.0 and 3.0) act as ETW event trace providers. When you are capturing event traces on Windows 7 or later, you can capture traces from other providers, such as other drivers and applications alongside events from the USB driver stack. You can then read the combined log (assuming that you have created a Netmon parser for your provider’s event traces).
In traces captured on Windows 8, you can also associate events across providers (from applications, client driver, and the USB driver stack) by using activity ID GUIDs. An application can include activity ID GUIDs by calling EtwActivityIdControl (EVENT_ACTIVITY_CTRL_SET_ID). A kernel-mode driver calls IoSetActivityIdIrp. Those calls tell the USB driver stack about the activity to which the requested work is related. Events from multiple providers can be associated in Netmon when the events have the same activity ID GUID. Based on those GUIDs, Netmon can show you the set of USB events that resulted from an instrumented activity at an upper layer.
While viewing combined event traces from other providers in Netmon, right-click an event from an application and choose Find Conversations -> NetEvent to see associated driver events.
Keywords: Capture filters
By using ETW keywords, you can customize how much information you want to view about events captured from the USB 3.0 driver stack. Notice ETW keywords such as Default and PartialDataBusTrace in the capture command line. Those words are ETW keywords that indicate the types of events you want to view. You can filter events based on keywords depending on your requirements. Events that match any of your keywords are saved.
Note that this method of filtering is for use at capture time, not during analysis.
Here are keywords for filtering USB 3.0 driver stack events:
Shows events that are useful for general troubleshooting. The events are similar to USB 2.0 ETW events but do not include any USB transfer events.
Shows driver-internal state machine transitions. The events are not included in the Default keyword.
Shows device information events at the beginning of the trace and captures the starting state of the USB tree. The device information Rundown events are important to save so that the trace contains details, such as the USB descriptors and USB Device Description, of connected devices. These events are included in the Default keyword. When you don’t use the Default keyword, you should use the Rundown keyword. The remaining Rundown events provide information on recent state transitions of the driver-internal state machines. These events are included in the StateMachine keyword.
Shows a subset of Default events. Shows device power transition events.
Shows a subset of Default events. The events show IRPs from the client driver and IRPs resulting from user-mode requests. However, valid USB transfer (URB) requests are not shown with the IRP keyword, and require HeadersBusTrace, PartialDataBusTrace, or FullDataBusTrace in order to be shown.
Shows all USB transfer events but doesn’t save data packets.
Shows all USB transfer events and saves a limited payload of bus data.
Shows all USB transfer events and saves up to 4 KB of bus data for bulk, interrupt, and control transfers. Note that only the first buffer of a chained MDL is logged. Isochronous bus data is never logged (though the URB_ISOCH_TRANSFER request structure is saved).
Shows a subset of Default events. The events indicate when an error occurs in the USB host controller hardware.
Shows a subset of Default events. The events indicate when an error occurs in the USB hub hardware.
Shows a subset of Default events. The events indicate when an error occurs in the USB device hardware.
As an example, here is a sequence of commands that start a session to capture USB device power transitions. Due to the selection of providers (the USB 3.0 driver stack), events are captured only for devices that are connected downstream of a USB 3.0 host controller.
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
In the final part of the following three-part video, from the 2011 BUILD conference, I demonstrate an end-to-end diagnosis using ETW traces from the USB 3.0 driver stack, plus how to read a combined trace with Activity IDs. Skip to 33:30 for this ETW content. Here is a direct link if you have any problems.
USB driver stack event traces in Windows are a powerful tool for diagnosis. We hope that you and the USB hardware ecosystem will benefit from these improvements in Windows 8.
Boot tracing (special tracing commands)
(added Feb. 8 2013)
If you want to view USB event traces of the activity that takes place when the system boots, you need a different set of commands. This way of capturing traces can be useful if you encounter an issue that occurs only when the system boots, rather than while the system is running. Start the trace by entering the following commands in an elevated command window:
logman create trace autosession\UsbBootTrace -o UsbBootTrace.etl -ets -nb 128 640 -bs 128 logman update autosession\UsbBootTrace -ets -p Microsoft-Windows-USB-USBPORT logman update autosession\UsbBootTrace -ets -p Microsoft-Windows-USB-USBHUB logman update autosession\UsbBootTrace -ets -p Microsoft-Windows-USB-USBXHCI Default logman update autosession\UsbBootTrace -ets -p Microsoft-Windows-USB-UCX Default,PartialDataBusTrace,StateMachine logman update autosession\UsbBootTrace -ets -p Microsoft-Windows-USB-USBHUB3 Default,PartialDataBusTrace,StateMachine
Then reboot. When you’re ready to stop the trace, enter the following commands in an elevated command window:
logman stop UsbBootTrace -ets logman delete autosession\UsbBootTrace -ets
In this case, you will find the trace file (UsbBootTrace.etl) in the directory where you ran the commands that started the trace. Note that if you reboot before you stop the trace, the trace file will be overwritten.
– Philip Ries
Software development engineer on the core USB team.