ETW in the Windows 7 USB core stack

This post has been republished via RSS; it originally appeared at: Microsoft USB Blog articles.

First published on MSDN on Dec 04, 2009

Hi, my name is Philip Ries and I'm also a developer on the USB core team. I'd like to tell you about the instrumentation that our team added to the USB core drivers for Windows 7, and how you can make use of this instrumentation.

The USB Hub and USB Port drivers are instrumented with Event Tracing for Windows events. What does this mean? In brief, anyone running Windows 7 can activate a USB trace on a live system and record what's going on in our drivers. The recorded log can help troubleshoot USB issues.  Anyone can read the log because the events were compiled using a manifest.

In the rest of this post, I'll describe the steps to record and view a USB ETW log. The recording steps use the "Logman" command-line tool that comes with Windows; the viewing steps include instructions to download a log viewing tool.

Record the log

Are you ready to start the log? A shorter log is more readable, so try to narrow down the start and end of the log as much as possible around an operation you want to examine. I'll call this operation the "scenario" that you'll be tracing. Tip: You can also reduce the log size by disconnecting USB devices that aren't related to the scenario, as well as by entering the trace commands via Remote Desktop instead of on a USB keyboard.

You'll need to open an elevated command prompt: Open the start menu, type "cmd" (without the quotes), right click on cmd.exe, and select "Run as administrator".

In the command prompt window, enter these 2 commands.

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


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

After each command logman should display "The command completed successfully."

Now perform the USB scenario that you want to examine.

When you're done, stop the log with this command:

• Logman stop Usbtrace -ets

The log has been saved as usbtrace.etl in the current directory (often C:\Windows\system32). We're done with the command prompt window now.

View the log

Make sure to note the path and filename of the log file you created. We'll use Netmon (Microsoft Network Monitor) to view the log. You might not guess it from the program's name, but Netmon can handle ETW traces in addition to network traffic logs. Here's how to install it with our ETW parser.

1. Determine whether you have 32-bit Windows or 64-bit Windows:
   
   
   1. Open the Start Menu
   
   
   2. Right click “Computer” and select “Properties”
   
   
   3. Look at the “System type” field. (Note: 32-bit corresponds to “x86” for the downloads)
   
   


2. Install Netmon:
   
   
   1. Go to the bottom of the download page and press the “Download” button for your system type
   
   
   2. Download and run the exe. When it asks about setup type, Typical is fine.
   
   


3. Install Netmon’s parser set
   
   
   1. Go to the parsers CodePlex site
   
   
   2. Click “Downloads”
   
   
   3. Select the Microsoft Parsers package that matches your system type. For example, for x86 choose “Microsoft_Parsers_x86.msi”
   
   
   4. Download and run the MSI installer
   
   
   5. Select to upgrade the installed parsers
   
   


4. Activate the Windows parsers:
   
   
   1. Run Netmon. It has a folder in the Start Menu like “Microsoft Network Monitor 3.3”
   
   
   2. Open Tools->Options
   
   
   3. Click the Parser tab
   
   
   4. Select “Windows” parsers
   
   
   5. Click “Stubs” button to deactivate stubs and use full parsers. See the image below for how the settings should look.
      
   
   
   6. Click OK
   
   
   7. Restart Netmon
   
   

Go ahead and open an ETW log (.etl) and explore it.

In future blog posts I'll show some examples of diagnosing USB issues using USB ETW and Netmon.

Update: Here's Part 2 of this post

netmon-options.png