USB debugging innovations in Windows 8 Part 1: Overview

1. HW-258P USB debugging innovations in Windows 8Part 1: Overview Yang You Program Manager Microsoft Corporation

2. Agenda • What USB Debugging tools are available to diagnose device and driver issues • Learn about the USB 3.0 driver architecture • Recap You’ll leave with an understanding of • The tools available for debugging USB issues • The USB 3.0 core drivers that can be examined with the tools

3. USB Debugging tools designed with device and driver developers in mind

4. Common USB Issues • Enumeration issues resulting in an “Unknown Device” • Bugcheck during client driver interaction • Power transition issues • Performance issues • Stuck transfers Diagnosing these issues require: • Insights into the state of the USB controller and device • Analyzing a record of the recent USB interactions • Ability to filter information to focus on a device or transfer

5. Location Matters The right tools must be available to diagnose the issue • On-Site: • Hands on debugging • Able to leverage kernel debugging tools, bus analyzers • Off-Site: • Crashdump • Capture and analyze debug logs

6. Diagnosing USB issues with Windows 8 is faster with USB 3.0

7. With USB Debugger Extension + Event Tracing for USB 3.0 • You can inspect internal USB core stack data structures to find out the state of the USB controller and the USB device • You can view a recent USB WPP debug messages to determine what sort USB interactions led to an issue • It’s easy to record and analyze USB transfers, including the full data payloads • Add debugging events into your own device driver that can be correlated with events in the USB core stack

8. Understanding the USB 3.0 Drivers

9. USB 3.0 Software Architecture USB 3.0 Driver Stack Client Drivers Client Drivers • New components • USBXHCI.SYS – KMDF function driver for the XHCI controller • UCX01000.SYS • KMDF driver to provide USB abstraction and validation of client requests • USBHUB3.SYS • KMDF bus driver built using formal interactive state machines to manage the state of the hubs, ports and devices including enumeration and power management Client Drivers USBCCGP WINUSB Legend Hardware USBHUB3 (USB 3.0 Hub Driver) Existing USB Stack Components UCX (Host Controller Extension Driver) USB 3.0 Stack Components Class or Vendor Drivers USBXHCI (xHCI Driver) xHCI Host Controller and Root Hub

10. A new family of USB 3.0 debugging tools that let you diagnose USB device and driver issues more quickly

11. Reduce Development and Support Costs • Diagnose USB driver issues faster by examining USB controller and device state with the USB 3.0 Kernel Debug Extension • Troubleshoot USB device issues more easily by analyzing recent USB interactions using USB WPP and Event Tracing • Leverage USB domain knowledge to reduce ramp up time with these tools

12. Further reading and documentation • Learn more and watch demos in these follow up videos: • USB Debugging Innovations: Part 2 - Kernel Debug Tools • USB Debugging Innovations: Part 3 - Event Tracing USB Core Team Blog: blogs.msdn.com/usbcoreblog/

13. © 2011 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

15. HW-258P USB Debugging Innovations in Windows 8Part 2: Kernel Debug Tools Eliyas Yakub Principal Development Lead Microsoft Corporation

16. Agenda • Understanding the key USB 3.0 data structures and drivers • Examining the state of the USB 3.0 driver stack with the USB kernel debug extension • Recap You’ll leave with examples of how to • Use the USB kernel debug extension to view key USB data structures • View a history of recent USB debug messages

17. A New Standard for USB • XHCI is the standard eXtensibleHost Controller Interface for USB 3.0 • Backward compatible with USB 2.0 and 1.1 Devices Let’s review the standardized data structures that can be examined with the debugging tools

18. xHCI Data Structures Slot Context 0 0 0 0 1 1 1 1 Device Context Device Context 256 Device Context Base Address Array EndPoint Context Doorbell Array (256 Doorbell Registers) EndPoint Context 2 255 31 255 31 Enqueue Enqueue Data TRB TRB Data Transfer Ring TRB Data TRB Dequeue Dequeue TRB TD T RANS F E R TRB Command Ring Event Ring TRB TD TRB TRB TRB TRB – Transfer Request Block TD – Transfer Descriptor

19. Debugging USB 3.0

20. What is the USB Kernel Debug Extension? • New debugger extension USB3KD.DLL to debug the 3.0 core stack • View the internal state of all three USB 3.0 components in a user friendly manner • Available with the Windows Debugging Tools in the WDK

21. Debuggers Commands HUB Controller !usb_tree<optional 1> or !hub_tree !hub_info <DeviceExtension> !hub_info_from_fdo <DeviceObject> !device_info <DEVICE_CONTEXT> !device_info_from_pdo <DeviceObject> !port_info <PORT_CONTEXT> !xhci_dumpall<1> !xhci_capability<DeviceExtension> !xhci_commandring<DeviceExtension> !xhci_deviceslots <DeviceExtension> !xhci_eventring <DeviceExtension> !xhci_registers <DeviceExtension> !xhci_resourceusage <DeviceExtension> !xhci_trb <trb_address> <count> !xhci_transferring <transferring_address> Misc Controller Extension !ucx_controller_list !ucx_controller <UCXCONTROLLER_PRIVCONTEXT> !ucx_device <UCXUSBDEVICE_PRIVCONTEXT> !ucx_endpoint <UCXENDPOINT_PRIVCONTEXT> !usbdstatus <URB_STATUS> !urb <UrbAddress>

22. demo Key Debugger Commands Learn how to use !xhci_dumpall !usb_tree !ucx_controller_list

23. How do I view recent activities of USB3 drivers? • RCDRKD.DLL is an always-on WPP debug message recorder • A circular buffer to save errors and important device state changing operations • Extended debugger extensions (RCDRKD.DLL) to view the logs • For a particular device or endpoint • TMF information needed to format WPP messages are available in PDB file • RCDRKD.DLL is used to retrieve TMF information from the PDB file directly, parse and display the trace

24. demo View WPP Traces from the Debugger Extract the TMF View and interpret WPP Recorder logs

25. Reduce Development and Support Costs • Diagnose USB driver issues faster by examining USB controller and device state with the USB 3.0 Kernel Debug Extension • Troubleshoot USB device and host issues more easily by analyzing recent USB interactions using USB WPP Recorder logs • Leverage USB domain knowledge to reduce ramp up time with these tools

26. Further reading and documentation • Learn more and watch demos in these follow up videos: • USB Debugging Innovations: Part 1 - Overview • USB Debugging Innovations: Part 3 - Event Tracing USB Core Team Blog: blogs.msdn.com/usbcoreblog/

27. © 2011 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

30. HW-258P USB Debugging Innovations in Windows 8:Part 3: Event Tracing Philip Ries Software Development Engineer Microsoft Corporation

31. Agenda • What is USB Event Tracing (ETW)? • What’s changed since Windows 7? • Learn about the tools you can use to analyze USB event traces You’ll leave with examples of how to • Record and analyze a USB event trace • View correlated traces from multiple drivers in Netmon

32. USB event tracing gives you a recording of USB driver and bus activity with unprecedented detail

33. USB Event Tracing Leveraging the Event Tracing for Windows (ETW) Framework • See what the USB controller and hub drivers are doing • Errors encountered • Transfers on the bus • Control Transfers • Device Enumeration • Raw Data • Power State Transitions • Individual devices

34. Event Tracing: Windows 8 vs. Windows 7 Windows 7 Windows 8 USB 2.0 ETW USB 3.0 ETW Full USB bus data Activity ID • USB 2.0 ETW • Partial bus data

35. Recording an USB ETW Trace • Start Tracing • logmanstart usbtrace -ets -o usbtrace.etl -nb 128 640 -bs 128 • logman update usbtrace -ets -p Microsoft-Windows-USB-USBXHCI Default • logmanupdate usbtrace -ets -p Microsoft-Windows-USB-UCX Default,HeadersBusTrace • logman update usbtrace -ets -p Microsoft-Windows-USB-USBHUB3 Default,HeadersBusTrace • /* Optional Keywords: PartialDataBusTrace, FullDataBusTrace */ • <Reproduce Issue> • Stop Tracing • logman stop usbtrace–ets • /* This creates a usbtrace.etl file in the current folder */

36. Viewing an ETW Trace with Network Monitor • Network Monitor (Netmon) is a free tool that can be used to analyze USB ETW traces • Custom parsers for USB 2.0 and USB 3.0 are available on Codeplex • Using custom parsers, you can view events related to specific USB devices, add USB-specific columns, and apply filters

37. Demo Diagnosing a USB Device Issue with ETW

38. Relating Events in different layers • Add ETW events to your applications and drivers for debugging • Logs with multiple active applications that share the same device can be difficult to analyze • How do you view the USB events generated by a particular application? Application A Application B USB Transfer A USB Transfer B UMDF Driver ? ? ? ? ? ? USB Core Stack

39. Correlating ETW Events with Activity IDs • ETW events have an ActivityID field (16 byte Guid). • WinUSB automatically assigns the Activity ID of an application’s thread to each USB transfer • Activity ID is propagated into all related USB events Application A Application B USB Transfer A USB Transfer B UMDF Driver B BBA AA USB Core Stack

40. Demo Viewing correlated event traces with Activity IDs

41. Reduce Development and Support Costs • Collect ETW traces from your customers to diagnose USB issues remotely • Use Netmon and USB parsers to analyze ETW traces quickly • Add ETW events with activity IDs to your drivers and applications to improve debugging

42. Further reading and documentation • Learn more and watch demos in these follow up videos: • USB Debugging Innovations: Part 1 - Overview • USB Debugging Innovations: Part 2 – Kernel Debug Tools USB Core Team Blog: blogs.msdn.com/usbcoreblog/ • Bing: usbetwnetmon • Bing: Event Tracing (Windows) • Bing: netmon parser

43. thank you Feedback and questions http://forums.dev.windows.com Session feedbackhttp://bldw.in/SessionFeedback

44. © 2011 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.