Feeling bad about using licensed USB debugger tools ?!?! Actually you don't really have to. To start, we have to admit that microsoft provides best ever support in possible to trace what's happening at device driver levels and the big dark room inside which windows handled its driver activities are slowly thrown some light. Recently they have given many tools to trace at driver levels and debug our USB device and obviously many other device drivers given that your windows version has the particular trace provider. To start with, let us see about LOGMAN which is older yet very powerful tool for USB event tracing.
LOGMAN:
This topic provides information about using the
Logman
tool to capture a USB ETW event trace. As a prequesite I request you to have a peep into the USB driver stack article to understand the basics. Logman is a tracing tool that is
built into Windows. You can use Logman to capture events into an event
trace log file.
Event trace log files can grow very quickly, but a smaller log
file is easier to navigate and easier to transmit. Before you start a
trace, consider taking the following steps to exclude extraneous events
from the log so that you can focus on the device activity that you want
to examine.
Remember following steps before using logman.
- Disconnect any non-critical USB devices that are not the device
of interest. Fewer devices result in smaller traces making it easier to
read and analyze.
- If your system has a USB keyboard or mouse, enter the trace commands by using Remote Desktop instead.
- Narrow the start and the end of the trace as much as possible around the operations of interest.
- If you are interested in only a certain category of USB events, you can use keywords to filter the events that are recorded.
STEPS TO CREATE .ETL FILE USING COMMAND PROMPT:
The following steps are followed,
- Open an elevated command prompt ie., right click cmd.exe and run as administrator.
- On typing logman we get the name of the current data collector
set, its type and status if you have already created one. Otherwise the
list is empty.
C:\Windows\system32>logman
Data Collector Set Type Status
---------------------------------------------------------------------------
The command completed successfully.
- Now to start a new trace type the following,
C:\Windows\system32>logman create trace -n usbtrace -o %SystemRoot%\Tracing\usbtrace.etl -nb 128 640 -bs 128
The above command creates a data collector set named as 'usbtrace'
with file path 'usbtrace.etl'. '-nb' command is to set minimum and
maximum number of buffers and '-bs' is to set the buffer size in kilo
bytes. '-h' will help us to understand more about usage of logman for
different cases. The commands specified here are typical and works fine
for usb event tracing.
- After creating the data collector set, next step is to specify trace providers for it. The following commands will help.
Trace providers for windows 7 are 'Microsoft-Windows-USB-USBPORT'
and 'Microsoft-Windows-USB-USBPORT'. We can trace USB 2.0 or 3.0 device
activities at port level or hub level or both.
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-USBPORT
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB
Trace providers for windows 8 are 'Microsoft-Windows-USB-USBXHCI',
'Microsoft-Windows-USB-UCX' and 'Microsoft-Windows-USB-USBHUB3'. We can
trace USB 2.0 or 3.0 device activities at extensible host controller
(XHCI) level or the root hub level or the port level under the XHCI. We
can still use 'Microsoft-Windows-USB-USBPORT' and
'Microsoft-Windows-USB-USBPORT' trace providers windows 8 to trace USB
2.0 devices under host controllers other than XHCI.
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-USBXHCI
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3
- Next step is to start the trace,
C:\Windows\system32>logman start -n usbtrace
- After desired time interval to stop the trace,
C:\Windows\system32>logman stop -n usbtrace
- To delete the particular trace provider so that we can use the same name next time,
C:\Windows\system32>logman delete -n usbtrace
NOTE: This command only deletes the data collector set and not the
.etl file which is stored in the location
"C:\Windows\system32\Tracing\usbtrace000001.etl" which we can move to
any other location for future reference.
FILTERS FOR USB 3.0 DRIVER STACK EVENTS:
XHCI, HUB3 and UCX trace providers which trace USB 3.0 driver stack can
be parameterized and thus can be filtered accordingly. They can hold the
following parameters,
Default:
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.
StateMachine:
Shows driver-internal state machine transitions. The events are not included in the Default keyword.
Rundown:
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.
Power:
Shows a subset of Default events. Shows device power transition events.
IRP:
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, orFullDataBusTrace in
order to be shown.
HeadersBusTrace:
Shows all USB transfer events but doesn't save data packets.
PartialDataBusTrace:
Shows all USB transfer events and saves a limited payload of bus data.
FullDataBusTrace:
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). For more
information, see How to send chained MDLs and How to transfer data to
USB isochronous endpoints.
HWVerifyHost:
Shows a subset of Default events. The events indicate when an error occurs in the USB host controller hardware.
HWVerifyHub:
Shows a subset of Default events. The events indicate when an error occurs in the USB hub hardware.
HWVerifyDevice:
Shows a subset of Default events. The events indicate when an error occurs in the USB device hardware.
example commands:
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-UCX (Default,PartialDataBusTrace)
C:\Windows\system32>logman update trace -n usbtrace -p Microsoft-Windows-USB-USBHUB3 (Rundown,Power)
NOTE:
We can do the same process in windows 7 using Windows performance monitor by following these steps,
- Goto start --> search --> performance monitor.
- In the list available in the left pane, select 'data collector set' option
- Right click 'user defined' slect new --> data collector set --> create manually --> event trace data --> finish.
- A new trace 'datacollector01' will be created and trace providers can be added by right click --> properties.
- You can start and stop the particular trace event by right
clicking it and .etl file is generated and saved in path
"C:\PerfLogs\Admin\usbtrace\"
Here is a screenshot of performance monitor window,
ETL FILE VIEWING:
Windows provides 'Event viewer' software with its operating systems
windows xp, 7 & 8 which can be used as a basic tool to view .etl
files. There are other free tools provided by windows to enhance the
.etl file viewing with better details of USB events and advanced
filtering options. Network Monitor is one of the best available tools.
Follow the link below to find the installation steps.
NETMON 3.4:
Steps for netmon 3.4 installation and loading of parser files for USB event tracing,
- In the Netmon 3.4 download page and press the download button and for your system type.
- Select the typical option and finish the installation.
- Now the next step is to load the necessary parsers provided by microsoft for USB tracing in netmon.
- In the Windows driver kit 8.1
page you can download "wdk\wdksetup.exe" to get the latest network
monitor parsers. NOTE: Windows driver kit 8.1 can be installed in lower
versions like windows 8 & 7 too.
- Now to load the downloaded parsers, goto start --> search
--> powershell and open elevated windows powershell (run as
administrator).
- Type the following command in the powershell and close it.
Set-ExecutionPolicy RemoteSigned -Force
- Open a new 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\Windows Kits\8.1\Tools\x86\Network Monitor Parsers\usb"
..\NplAutoProfile.ps1
- Now open the installed network monitor 3.4 and you will see
parsers getting updated automatically and ready for USB 2.0 and 3.0
event tracing.
- To know more about filtering methods in netmon, which is the vital part of USB tracing, look out for the article on Windows Message Analyzer which has same filtering techniques.
Please do comment and criticize our mistakes !!
-
ARUN
Embedded Engineer
