Microsoft Windows USB Core Team Blog

USB 2.1, 2.0, 1.1 device enumeration changes in Windows 8

USB Blog — Thu, 11 Apr 2013 21:44:00 GMT

Authored by Martin Borve [MSFT]

In 2009 we posted a detailed description of how Windows 7 enumerates a USB device. In Windows 8, we’ve made modifications in the USB driver stack on how the stack enumerates USB 2.1, 2.0, and 1.1 devices. Those modifications support new USB features and improve device enumeration performance. The purpose of this article is to bring awareness to these subtle changes and enable device/firmware builders to easily determine the root cause of enumeration failures.

Reduced Timing Delays

Before Windows 8, the timing for delays were approximately 15-30 milliseconds longer than delays required by the official USB 2.0 specification. Cumulatively, those delays added several 100 milliseconds to the device enumeration time. In Windows 8, we’ve reduced the timing delays to 0-15 milliseconds resulting in faster enumeration.

Elimination of Second-Port Reset for High-Speed Devices

Before Windows 8, the USB driver stack reset the device’s upstream port twice. That behavior was to support legacy USB devices that were confused by the second request for the Device Descriptor. To allow those devices to enumerate successfully, the driver stack had to reset the upstream port between the first and second requests for the Device Descriptor. This second reset was expensive in terms of enumeration time.

Because that second reset was required just to support legacy low and full-speed devices, we’ve removed it for high-speed devices in Windows 8. Just in case the first attempt to enumerate a high-speed device fails, the driver stack reverts to resetting the port twice when it retries enumeration for the device.

BOS Descriptor Query and Validation

The USB 3.0 and USB 2.0 LPM specifications define a new USB descriptor called the Binary Device Object Store (BOS). The BOS descriptor returns a set of device-level capability descriptors for the USB device. For a USB device, which reports a bcdUSB value greater than 0x0200 in their device descriptor, in Windows 8, the USB driver stack requests for the BOS descriptor header immediately after the Language ID query request. If that request fails, the driver stack proceeds to the Product ID String query request.

If the request for the BOS descriptor header succeeds, the driver stack requests the entire BOS descriptor set by using the value returned in the BOS descriptor’s wTotalLength field as the request length. If that request fails, the driver stack will fail enumeration of the device.

Note: To make sure your device enumerates on Windows 8 and future versions of Windows, do not rely on the sequence in which the USB driver stack queries for the BOS descriptor. Instead, make sure that the device reports correct values to pass validation checks as described in these sections.

BOS Descriptor Validation

The USB driver stack validates the retrieved BOS descriptor. Make sure that in your device:

The number of bytes greater than or equal to the size of the BOS descriptor.
bDescriptorType indicates the BOS Descriptor type (0x0F).
bLength is the correct size of the BOS descriptor.
wTotalLength is greater than or equal to the size of the BOS descriptor.
wTotalLength is large enough to contain the number of capability descriptors reported in bNumDeviceCaps. The device computes the value by assuming a minimal 2-byte capability descriptor containing bLength and bDescriptorType fields, multiplied by the bNumDeviceCaps value, and added to the size of the BOS descriptor.
bNumDeviceCaps is not zero.

If any of those validation checks fail, the driver stack will fail enumeration of the device. Otherwise the stack validates each Device Capability Descriptor.

Device Capability Descriptors Validation

Generic Device Capability Descriptor Validation

For each device capability descriptor returned within the BOS descriptor set, the USB driver stack validates these conditions:

There is enough space left in the descriptor set for a capability descriptor.
The capability descriptor’s bLength value does not overrun the end of the descriptor set.
The capability descriptor’s bLength value is non-zero.

If any of those validations fail, the driver stack discards the BOS descriptor and proceeds to the Product ID String query.

Validation of USB 2.0 Extension Capability Descriptor

The driver stack validates the USB 2.0 Extension Capability Descriptor. If your device has that descriptor, make sure that:

bLength is set to the size of the USB 2.0 Extension Descriptor.
The reserved bits of the bmAttributes field are zero.

If any of those validation checks fail, the driver stack discards the BOS descriptor and proceeds to the Product ID String query.

Validation of SuperSpeed USB Device Capability Descriptor

The driver stack validates the USB 2.0 Extension Capability Descriptor. If your device has that descriptor, make sure that:

bLength is set to the size of the SuperSpeed USB Device Capability Descriptor.
The reserved bits of the bmAttributes field are zero.
The wSpeedsSupported field is non-zero.
wU2DevExitLat is less than 0x0800.

If any of those validations fail, the driver stack discards the BOS descriptor and proceeds to the Product ID String query.

Validation of Container ID Descriptor

The USB driver stack validates the Container ID Descriptor. If your device has that descriptor, make sure that:

bLength is set to the size of the Container ID Capability Descriptor.
bReserved field is zero.

If any of those validations fail, the driver stack discards the BOS descriptor and proceeds to the Product ID String query.

Other Capability Descriptors

The USB driver stack performs generic validation checks on any other capability descriptors found. Beyond that they are ignored.

Help! My USB 3.0 Device is Operating at a Lower Speed

USB Blog — Tue, 26 Mar 2013 18:40:00 GMT

Authored by Andrea Keating [MSFT]

If you have upgraded a system with USB 3.0 controllers from Windows 7 to Windows 8 and notice that the connected USB 3.0 devices are not operating at SuperSpeed (see How to determine if a USB device is operating at SuperSpeed) then this article will help you troubleshoot and fix the issue.

Microsoft provides a new USB driver stack for USB 3.0 in Windows 8. The new stack includes an in-box host controller driver that works with all available controllers. We recommend that you do not load a 3^rd party driver for your USB 3.0 controller (or XHCI controller) on Windows 8 because of compatibility issues. Different USB 3.0 controllers vary slightly in speed, however all USB 3.0 controllers are significantly faster than 2.0 controllers.

Read the troubleshooting section in How to determine if a USB device is operating at SuperSpeed to identify the most common issues. That section describes common issues related to setup or improper hardware configuration.

This post describes issues related to the BIOS.

Make sure that the xHCI controller is enabled in the BIOS

Check that your BIOS setting enables the xHCI controller. Some older systems that have been upgraded to Windows 8 allow for SuperSpeed port to be routed to an EHCI controller in the BIOS. That option disables the USB 3.0 ports of an xHCI controller and exposes only the USB 2.0 ports. Those USB 2.0 ports appear under an EHCI controller. In this image, notice that the Legacy USB Support (EHCI) option is enabled through the Auto option and XHCI handoff is Enabled.

BIOS example -xHCI controller is enabled

Depending on your system, the option to enable an xHCI controller may or may not appear in the BIOS. If there is such an option, it might not be in the same location as shown in the image. To check your BIOS option, follow instructions from the boot screen about how to enter setup. For many systems you can do so by pressing F2, however that can be different.

Make sure that your system has the latest BIOS version (applies to upgraded systems with Intel controllers)

On some systems with Intel xHCI controllers, SuperSpeed devices can operate at a lower speed. The issue is system-related and only seen in systems that have been upgraded from Windows 7 to Windows 8. It does not apply to all systems with Intel xHCI controllers. Typically, we see the issue in a system that have an older BIOS version. Specifically, when the BIOS enables the legacy (EHCI) controller but does not display an option to disable it. That causes the port to be always routed to the EHCI controller until the BIOS is updated.

To identify if your system has an Intel xHCI controller, locate the controller in Device Manager. The controller named Intel USB 3.0 eXtensible Host Controller - 0100 (Microsoft) in this image experiences the issue discussed.

Contact your system vendor and get a BIOS update, if required. Those updates are usually available on the vendor’s Web site. If the newer BIOS does not fix the issue, ask your system vendor to identify a BIOS version that is compatible with Windows 8.

Supporting D3Cold for USB Devices

USB Blog — Tue, 19 Feb 2013 00:01:00 GMT

Authored by Vivek Gupta [MSFT]

Windows 8 supports a new device power state called the D3cold state. Adopting D3cold for USB presents some unique challenges for USB devices and drivers. In this blog post, I will talk about those challenges and certain restrictions. This post assumes that you are familiar with the content presented in Supporting D3cold in a Driver.

What does D3cold mean for USB devices?

The deepest sleep state for a USB device defined in the USB specification is selective suspend. Whenever the power policy owner (often the function driver for the device) requests a D0->D2 or D0->D3 transition, the Microsoft-provided USB driver stack sends the device to the selective suspended state. In that state, the device consumes power in the range of few milliwatts. For traditional PC platforms, that power consumption is insignificant compared to the total system power consumption while the system is in S0. Therefore sending devices to selective suspend to conserve power has traditionally been good enough.

However, for newer platforms that support connected standby, the overall system power consumption in S0 can be extremely low. For such a system, even the few milliwatts that a USB device consumes while in selective suspend, starts to matter. With the goal of optimizing power for the new systems, we have defined D3cold for internal USB devices. In that state, the system cuts power to the device, the device drops off the bus, and the device does not consume any power.

Behavior of the USB driver stack for supporting D3cold

Typically a device drops off the bus when the user surprise-removes (unplugs) the device. When a device is surprise removed, the USB stack detects the removal and reports it to PnP manager as removed, so the device stack can be torn down.

When a device enters D3cold, the hardware state is very similar to the surprise removal state but USB driver stack behaves differently. For D3cold, the driver stack does not report the device as removed and the device stack remains just the same. Later, when the device exits D3cold, the driver stack restores the USB configuration for the device. In Windows 8, only the USB 3.0 driver stack restores configuration but not the USB 2.0 driver stack. Therefore D3cold is not supported by the USB 2.0 driver stack. For information about USB 2.0 and USB 3.0 driver stacks, see USB Driver Stack Architecture.

Supporting D3cold in ACPI firmware

In order for power to be cut in D3cold the ACPI firmware should describe power resources appropriately. More information about how to enable D3cold in ACPI, refer to the ACPI specification. In particular, see the _PR3 method.

The USB driver stack only supports D3cold for internal devices. That is because there is no way for the driver stack to distinguish between a device that is in D3cold and another device that has been surprise-removed by the user. Because internal devices cannot be surprise-removed, it is safe for the driver stack to assume that the device is in D3cold state. Therefore, the USB driver stack enables D3cold only for those USB devices that are marked as non-removable in ACPI.

Expected behavior of a function driver for supporting D3Cold

In D3cold, a USB device drops off the bus. Because of that behavior, the USB stack needs to do some extra work to ensure that the process of the device entering and exiting D3cold remains transparent to the end user and applications.

To support D3cold, the function driver must implement these functionalities:

Enabling D3cold support

To support D3cold, the function driver must explicitly enable the state. The driver can do that either by using the D3cold interface or by modifying the DDInstall.HW section of the device INF. For information about those modifications, see the Remarks section in this topic.

Sending D3cold request

To send the device to D3cold, the function driver must use D3 as the target device power state with IRP_MN_SET_POWER. Traditionally, if the driver uses the idle IRP mechanism with D3, USB driver stack fails the idle IRP on receiving the power IRP with D3. To avoid that behavior, the driver must set a new registry entry in the hardware key for the device:

Path: HKLM\System\CCS\Enum\<DeviceId>\<InstanceID>\Device Parameters

Name: AllowIdleIrpInD3
Type: REG_DWORD
Value: 1

Saving device state information

Then there is the question of the device losing its internal device state (such as information about the USB configuration) in D3cold. Even though the USB driver stack (only the USB 3.0 driver stack) restores the configuration state of the device, there might be additional device or class-specific state settings that get lost in D3cold. If there is any such setting, the function driver is responsible for preserving that state information. That implementation is similar to the driver’s functionality when the device resumes from a system sleep transition.

The function driver does not know exactly when the device transitions from D3 to D3cold. Therefore the driver must be prepared to save state information before it sends the D3 IRP. D3cold interface provides query functions that can help the driver optimize that behavior. By calling GetD3ColdCapability, the driver can determine whether its device can enter D3cold. By calling GetLastTransitionStatus, the driver determines whether the device successfully entered D3cold.

Detecting surprise power on

Though this is not unique to USB, it’s worth calling out that the function driver should be registered with the power framework so that the function driver can bring back the device to D0 in the case of surprise power on. If the driver chooses not to register with the power framework, then D3Cold can only be enabled in the case where the device does not share a power rail with any other device.

Latency in resuming from D3 cold

For a USB device to support D3cold, it should be able to connect to the USB bus within 1 second of being powered on. This is because after the function driver initiates a resume from D3cold state, power is restored to the device and then USB driver stack waits for the device to re-appear on the bus so that the stack can enumerate the device. If the device takes longer than 1 second, the driver stack does not wait for the device and reports the device as missing (removed).

Wait-wake IRP support with D3cold

Because the USB device is not attached to the bus in D3cold, there is no in-band support for wake from D3cold. Therefore, D3cold should be enabled only for those scenarios that do not require device-initiated wake. In fact the USB driver stack does not allow a wait-wake IRP in conjunction with a D3 IRP. If the function driver sends a wait-wake IRP followed by a D3 IRP, the driver stack fails the wait-wake IRP.

However, on some system configurations, there might be a mechanism to perform out-of-band wake from D3 cold with the help of ACPI. For example, there might be a dedicated GPIO line for that purpose. If appropriate methods are defined in the ACPI, ACPI filter driver pends the wait-wake IRP and completes it only when the out-of-band wake event occurs. In that case, the USB driver stack never gets the wait-wake IRP; therefore it’s ok for the function driver to send a wait-wake IRP with the D3 IRP. However, because ACPI always keeps the wait-wake IRP pending, the driver stack does not arm the device for in-band wake, even when the device transitions to D3hot. Therefore, if the device requires USB wake from D3hot, the device must use the same out-of-band mechanism to enable the device for wake and then propagate the device wake event.

D3cold for composite devices

A composite device has multiple functions, each managed by its own function driver. The following guidelines apply for such devices as long as the parent driver for the entire device is the Microsoft-provided USB Generic Parent Driver (Usbccgp.sys). In order to support D3cold on a composite device,

Function driver for each of the functions must enable D3cold.
The ACPI firmware must report the device as D3cold-capable.
Device should be on a dedicated power rail.
Device must not be a SuperSpeed device. This restriction is primarily because USBCCGP driver on Windows 8 hasn’t been enlightened to handle “surprise power-on” for composite SuperSpeed devices.

Summary

To summarize, in addition to the requirements listed in the MSDN documentation, D3cold for a USB device can be enabled only on Windows 8 if the following restrictions are met.

The devices must be connected downstream of an xHCI controller and should be marked internal in ACPI.
Power resources described in ACPI must indicate that the power should be cut from the device when it enters D3.
The device must be able to connect to the bus within 1 second after it is powered on.
If the device is composite, it must be on a dedicated power rail and it must not be a SuperSpeed device. Each function driver should opt into D3cold.
The function driver must enable D3cold for only those scenarios that do not require device-initiated wake. If the device does require wake, the system should implement an out-of-band wake for both D3hot and D3cold.
The function driver must be responsible for handling loss of state information and must be able to deal with loss of non-USB state while resuming from low power state.
The function driver must register with the power framework. Otherwise, the device must be on a dedicated power rail.
If the device driver uses the idle IRP mechanism, it must set the AllowIdleIrpInD3 registry entry.

If you are a device manufacturer, read the restriction described in this post and decide if it is possible to enable D3cold for your device. Improper implementation of D3cold for the device can lead to poor user experience.

How to install WinUSB.sys without a custom INF?

USB Blog — Wed, 26 Sep 2012 22:16:00 GMT

Authored by Eliyas Yakub [MSFT] and Qiang Qiu [MSFT]

WinUSB is a Microsoft-provided kernel-mode client driver for USB devices. If you are developing a USB device for which Windows doesn’t include an in-box class driver, you can use Winusb.sys as the device driver instead of writing your own driver. In this blog, we’ll explain how you can build your device so that the Winusb.sys gets installed automatically on Windows 8 and earlier versions of the operating system.

Prior to Windows 8 if you choose Winusb.sys as the function driver for your device, you have to write a custom INF (see Writing an .Inf File for WinUSB Installation, and then install the driver on the target machine. The custom INF must specify your device specific hardware ID and also include sections from the inbox Winusb.inf. Those sections are required for instantiating the service, copying inbox binaries, and registering DeviceInterfaceGUID that is required by applications to find the device and talk to it.

In Windows 8, the in-box Winusb.inf file has been updated. The INF includes an install section that references a compatible ID called USB\MS_COMP_WINUSB. It also includes a newly defined setup class called “USBDevice”.

The compatible ID and USBDevice definitions are shown here:

[Version]
Class=USBDevice
ClassGuid={88BAE032-5A81-49f0-BC3D-A4FF138216D6}

[Generic.Section.NTamd64]
%USB\MS_COMP_WINUSB.DeviceDesc%=WINUSB,USB\MS_COMP_WINUSB

In order to match the compatible ID, the device must provide the ID by using Microsoft OS Descriptors. By building a device that reports the MS_COMP_WINUSB compatible ID, you can avoid writing a custom INF. The ability to provide compatible IDs through Microsoft OS descriptors has existed for several OS releases and has been widely used by other classes of devices, such as MTP, RNDIS, and Bluetooth.

The new USBDevice class is used for USB devices that do not conform to a USB-specific class specification. We will talk about need for defining this new USBDevice class later in this document.

Here are the steps for installing your device automatically using WinUSB.INF:

The device must provide a compatible-ID using the extended MS OS feature descriptor as described in WinUSB Device. This is sufficient to match the in-box Winusb.inf and load the WinUSB driver module.
However, to find the device from your application, configure the device, and perform I/O operations, you need to register its DeviceInterfaceGUID. In previous versions of Windows, that registration was done through the custom INF. Starting in Windows 8, your device should report the interface GUID by using extended properties OS feature descriptor as described in the WinUSB Device.
There are several device registry settings, that control the behavior of WinUSB, such as selective suspend, power policy ownership, idle timeout, wake settings. Those properties can also be provided by including one or more extended properties feature descriptors on the device.

WinUSB compatible ID support on earlier versions of Windows

As stated earlier, the ability to provide compatible and sub-compatible IDs through Microsoft OS Descriptors has existed since Windows XP SP3, and has been widely used by other classes of devices such as MTP, RNDIS, and Bluetooth. To enable the use of compatible ID for WinUSB devices, a new certified INF is now available on Windows update for down-level operating systems. If your computer is configured to get driver update automatically, the WinUSB driver will get installed without any user intervention by using the new INF package.

For some reason, if you have to provide an INF then there is no point in building your device with compatible-ID because you cannot certify the INF with a compatible-ID match. You must use device specific hardware-ID in your INF.

USBDevice Class

For years, development community has misused the “USB” setup class by using it for their unclassified devices instead of defining a custom class. The USB controller class is strictly used for installing controllers, hubs, and composite devices. For instance, if you use “USB” class for a class filter driver for a device, the filter gets applied to other USB stack drivers which are also part of that class. Misusing the “USB” class has led to reliability and performance issues.

To prevent that scenario, we have defined a new class, “USBDevice” for devices that do not belong to any other class.

Class=USBDevice
ClassGuid={88BAE032-5A81-49f0-BC3D-A4FF138216D6}

When a device is installed by using WinUSB.INF on Windows 8, it automatically installs the device under the “USBDevice” class. This class is system-defined on Windows 8. On down-level OS versions, this class is defined by the new INF available through Windows Update. Note that this class is not limited to WinUSB. If you have a custom driver for your device, you can use the “USBDevice” setup class in the INF.

For some reason, if you have to install the device under a custom class then you do need to write your own INF. If you do write your INF then there is no point in building the device to report compatible-ID because you cannot certify your INF with a compatible-ID match. You have to use most device specific hardware-ID in your INF.

Showing a meaningful device description in Device Manager

Typically the description of the device that is shown in Device Manager is derived from the INF file. One drawback of using a generic in-box INF to install the driver is that all devices installed through that INF get the same device description, which is "WinUsb Device". This is not ideal.

To uniquely identify and differentiate the device in Device Manager, Windows 8 provides a new property on a device class that instructs the system to give precedence to the device description reported by the device (iProduct string descriptor) over the description that comes from the INF. The USBDevice class defined in Windows 8 has this property. In other words, when a device is installed under USBDevice class, system queries the device for a device description and sets the Device Manager string to whatever is retrieved in the query. The device description provided in the INF is ignored.

The new class property is not supported on earlier versions of Windows. So if you really care about having a customized description for your device on earlier version of Windows, you have to write your own custom INF.

In the Device Manager images shown in this blog post, notice the device description strings: “MUTT”, “FX3”, and “SuperMUTT”. Those strings are provided by the USB device in its product string descriptor.

Examples

We built couple of test devices using MUTT to demonstrate how this feature works. We have below snapshots of device manager and registry settings to show what the compat-id and device description looks.

Example 1: Single Interface Device

This picture is for a single interface MUTT device that provides “WINUSB” as the compatibleID and as a result Winusb.sys gets loaded as the function driver for the device.

Example 2: Composite Device

This image shows how a composite device appears that provides WINUSB compatible-ID for each of the functions in Device Manager.

Example 3: Providing selective suspend and system wake settings

Until now, in order to configure power management features of WinUSB, you had to write registry entry values in the HW.AddReg section of your custom INF. The details can be found in WinUSB Power Management.

Now you can configure the behavior of Winusb.sys through the device itself. You can report registry values through the extended properties OS feature descriptor that enable or disable features in WinUSB for that device. In this example, we updated the single interface MUTT device to configure selective suspend and system wake capabilities of the device..

Selective suspend allows the device to enter low-power state when it is idle. System wake refers to the ability to a device to wake up a system when the system is in low-power state.

For selective suspend and system wake, these registry entries are required.

Registry Key	Description
DeviceIdleEnabled	This value is set to 1 to indicate that the device can power down when idle (selective suspend).
DefaultIdleState	This value is set to 1 to indicate that the device can be suspended when idle by default.
DefaultIdleTimeout	This value is set to 5000 in milliseconds to indicate the amount of time in milliseconds to wait before determining that a device is idle.
UserSetDeviceIdleEnabled	This value is set to 1 to allow the user to control the ability of the device to enable or disable USB selective suspend. A check box Allow the computer to turn off this device to save power on the device Power Management property page and the user can check or uncheck the box to enable or disable USB selective suspend.
SystemWakeEnabled	This value is set to 1 to allow the user to control the ability of the device to wake the system from a low-power state. A check box Allow this device to wake the computer shows up in the device power management property page and the user can check or uncheck the box to enable or disable USB system wake.

After the device is enumerated and initialized, these registry entries get written under the Device Parameters section of the hardware key. The picture below shows the registry entries for the customer properties that are reported by the device using extended properties OS feature descriptor.

This image shows device’s Power Management Properties page:

Summary

We explored in this article how you can build a device by using Microsoft OS descriptors to provide compatible ID and configuration information so that Winusb.sys is installed automatically as a function driver. This feature is available on Windows 8 and earlier versions up to Windows XP SP3. We hope that by reading this post you will understand best practices for using the new USBDevice class.

-Eliyas Yakub and Qiang Qiu

MUTT Software Package is now available

USB Blog — Wed, 08 Aug 2012 19:35:00 GMT

The Microsoft USB Test Tool (MUTT) software package contains test tools for hardware test engineers to test interoperability of their USB controller or hub with the Microsoft USB driver stack. The package contains two downloads: the tools package and a readme document.

The tools package contains several tools that perform stress and transfer tests (including power transitions) and SuperSpeed tests. The package also contains the USB Hardware Verifier tool (see this blog post). The document gives you a brief overview of the types of MUTT hardware, provides step-by-step guidance about various tests you should run, and suggests topologies for controller, hub, device, and BIOS/UEFI testing.
Download the tools package and documentation from MSDN.

-USB Core Team [MSFT]

-----

Selected version history:

2012/08/08: Initial post

2012/10/18: Version 1.8 published

How to Capture and Read USB ETW Traces in Windows 8

USB Blog — Tue, 07 Aug 2012 16:00:00 GMT

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.

Event traces from the USB 3.0 driver stack are similar to the USB 2.0 driver stack traces, which were introduced in Windows 7. Event traces from the USB 2.0 driver stack can be captured on a Windows 8 computer, too. The way you capture event traces from USB 2.0 and USB 3.0 driver stacks is similar. You can capture events from the USB 2.0 or USB 3.0 driver stack independently.

When you connect a USB 2.0 device to a USB 3.0 host controller, you get event traces from the USB 3.0 driver stack. This behavior can be confusing because you will view new USB 3.0 driver stack events for a USB 2.0 device.

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.

The file contains event traces from the USB 3.0 and USB 2.0 driver stacks. If you want to pare down the trace to just one USB driver stack, remove the other driver stack from your next trace session. You can do so by modifying the command sequence shown in step 3 to remove the "logman update" lines corresponding to the driver stack you want to remove from the trace session. You can find the driver names comprising each driver stack at the beginning of this post.

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.

Download and install the Windows Driver Kit for Windows 8.
Allow execution of PowerShell scripts:

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.

New columns

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:

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, or FullDataBusTrace 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).

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.

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

Example trace

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 create trace autosession\UsbBootTrace -o UsbBootTrace.etl -ets -nb 128 640 -bs 128
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.

Using WinUSB for USB 3.0 (SuperSpeed) Devices on Windows 8

USB Blog — Thu, 26 Jul 2012 20:27:00 GMT

Authored by Eliyas Yakub [MSFT]

In this blog, I’ll answer some of the frequently asked questions about WinUSB and its support for SuperSpeed (USB 3.0) devices on Windows 8. WinUSB is a generic kernel-mode driver for USB devices. If you are developing a USB device for which Windows doesn’t provide an in-box class driver, you can use Winusb.sys as the device driver instead of writing your own.

Can I use WinUSB to communicate with a SuperSpeed device?

Yes. WinUSB works with USB 3.0 devices. If you are writing an application that calls WinUSB functions, you don’t need to change the application for SuperSpeed devices. The existing WinUSB functions can transfer data to and from the device’s bulk and interrupt endpoints.

Does WinUSB support USB isochronous transfers?

No. At this time, WinUSB cannot perform data transfers to or from isochronous endpoints of a device.

Does WinUSB support SuperSpeed Streams transfer type?

SuperSpeed bulk endpoints support a new capability called streams. The capability multiplexes logical data streams into a single bulk endpoint. Generally speaking, WinUSB does not support communication with individual streams of a SuperSpeed bulk endpoint. At this time, you can only perform transfers to the endpoint as a whole.

How can an application obtain a SuperSpeed device capability descriptor?

A USB 3.0 device capability descriptor is used by the Microsoft-provided USB driver stack to configure the device. The descriptor is not useful for applications and USB client drivers. However, if an application wants, it can obtain the descriptor by first retrieving the BOS descriptor (see USB_BOS_DESCRIPTOR_TYPE in usbspec.h) by calling the WinUsb_GetDescriptor function, and then parsing for the device capability descriptor.

How can an application obtain a SuperSpeed endpoint companion descriptor?

Because WinUSB doesn’t support isochronous transfers or streams of a USB 3.0 bulk endpoint, the application doesn’t need the endpoint companion descriptor. However, the application can obtain the descriptor by first retrieving the configuration descriptor and then parsing it for endpoint companion descriptor.

Alternatively, your application can send some IOCTL requests to retrieve those descriptors. The USB core stack provides generic IOCTLs to obtain information about USB device topology and descriptors. Mostly that information is used by diagnostic tools. There is a sample in the WDK called USBVIEW that demonstrates how to use those IOCTLs to retrieve all descriptors.

Are there any improvements in WPP/ETW tracing?

WinUSB performs extensive WPP tracing but not ETW tracing. In Windows 8, we made these improvements for WPP tracing making it easier for you to debug device issues:

You can get debug trace messages from WinUSB.sys (see How to collect and view WinUSB WPP traces in Windows 7). To view and format messages in an ETL file, you need TMF files. Prior to Windows 8, we had to provide the TMF files separately (as a download on the blog). Any time, a fix was made to WinUSB, we had to repost the TMF files to match the new binary.

In Windows 8, TMF information for WinUSB.SYS is available in its public PDB file. If you are using Traceview.exe (included in the WDK for Windows 8) to view an ETL file, you can point it to the public PDB file. The tool will extract the PDB and format the ETL. You could also run Tracepdb.exe to extract the TMF files from the PDB file and then use utilities such as Tracelog.exe to view them.

We extended WPP to always log trace messages in WinUSB’s internal circular buffer called Inflight Recorder (IFR). You can view trace messages from this buffer any time by using a kernel-mode debugger. A new debugger extension DLL called rcdrkd.dll (short form of recorder kd) is shipped in the debugger package. The extension can find the trace buffers, format them by using the TMF information from a matching PDB file, and display the output in the debugger.

Here is an example on how to load the extension and use the command. For more information about this debugger extension, see RCDRKD Extensions.

0: kd> !load C:\WinDDK\8.0\Debuggers\x64\winext\rcdrkd.dll

0: kd> !rcdrlogdump winusb

Trace searchpath is:

Trace format prefix is: %7!u!: %!FUNC! -

Trying to extract TMF information from - C:\Debuggers\sym\winusb.pdb\02D00B5E5A9242669A9907D98CACC2521\winusb.pdb

--- start of log ---

1: DriverEntry - DriverObject 0xFFFFFA8009DD16F0

2: WinUSB_GetRegParams - CyclePortEnabled is set to FALSE

3: WinUSB_AddDevice - Default PowerPolicy: WinUSB is the power policy owner.

4: WinUSB_AddDevice - Default PowerPolicy: EnableIdle = 0x00000001(true)

5: WinUSB_AddDevice - Default PowerPolicy: SystemWakeEnabled = 0x00000000(false)

6: WinUSB_AddDevice - Default PowerPolicy: SuspendDelay = 5000 ms

7: WinUSB_AddDevice - Default PowerPolicy: DeviceIdleEnabled = 0x00000001(true)

8: WinUSB_AddDevice - Default PowerPolicy: UserSetDeviceIdleEnabled = 0x00000001(true)

9: WinUSB_AddDevice - Default PowerPolicy: DefaultDeviceIdleState = 0x00000001(true)

10: WinUSB_AddDevice - Default PowerPolicy: IdleConfigured = 0x00000000(false)

11: WinUSB_AddDevice - Default PipePolicy: ShortPacketTerminate = 0x00000000(false)

12: WinUSB_AddDevice - Default PipePolicy: AutoClearStall = 0x00000000(false)

13: WinUSB_AddDevice - Default PipePolicy: PipeTransferTimeout = 0

14: WinUSB_AddDevice - Default PipePolicy: IgnoreShortPackets = 0x00000000(false)

15: WinUSB_AddDevice - Default PipePolicy: AllowPartialReads = 0x00000001(true)

16: WinUSB_AddDevice - Default PipePolicy: AutoFlush = 0x00000000(false)

17: WinUSB_AddDevice - Default PipePolicy: RawIo = 0x00000000(false)

18: WinUSB_AddDevice - Default PipePolicy: ResetOnResume = 0x00000000(false)

19: WinUSB_PrepareHardware - Preparing hardware for WDF device (0000057FF84C4CD8)

20: WinUSB_PrepareHardware - Created UsbDevice (0000057FF90CDC68)

21: WinUSB_PrepareHardware - Resetting Default settings for WDFDevice (0000057FF84C4CD8)

22: WinUSB_D0Entry - Starting Read Io Target for WdfUsbPipe (0000057FF5100DE8)

23: WinUSB_D0Entry - Starting Read Io Target for WdfUsbPipe (0000057FF59F3BA8)

24: WinUSB_DeviceControl - IOCTL_WINUSB_VERSION_EXCHANGE

25: WinUSB_DeviceControl - IOCTL_WINUSB_GET_DESCRIPTOR

26: WinUSB_DeviceControl - IOCTL_WINUSB_GET_DESCRIPTOR

27: WinUSB_DeviceControl - IOCTL_WINUSB_GET_DESCRIPTOR

28: WinUSB_DeviceControl - IOCTL_WINUSB_RESET_DEFAULTS

29: WinUSB_DeviceControl - IOCTL_WINUSB_GET_DESCRIPTOR

30: WinUSB_DeviceControl - IOCTL_WINUSB_GET_DESCRIPTOR

31: WinUSB_DeviceControl - IOCTL_WINUSB_SET_POWER_POLICY

32: WinUSB_DeviceControl - IOCTL_WINUSB_SET_POWER_POLICY

33: WinUSB_SetPowerPolicy - Existing power policy same as passed in power policy.

34: WinUSB_D0Exit - Stopping Read Io Target for WdfUsbPipe (0000057FF5100DE8) to cancel pending IO

Have you done anything to make installation of WinUSB easier?

Yes we have. You can now install automatically Winusb.sys for your device by using an in-box INF on Windows 8, Windows 7, and Windows Vista. I will talk about this in the next blog. So stay tuned!

Common issues in USB 3.0 devices

USB Blog — Fri, 13 Jul 2012 00:44:00 GMT

1 Introduction

My name is Vivek Gupta; I am an engineer in Microsoft. I am part of the team that developed the USB 3.0 stack in Windows 8.

USB 3.0 offers significant improvement in performance and power over USB 2.0. However, like any new technology, it also brings its own set of new challenges. During the development of USB3.0 stack in Windows 8, we observed some common mistakes made by hardware vendors when developing USB 3.0 hardware. I am going to talk about these issues with the goal of helping hardware designers avoid these errors in future designs. I am also going to talk about how to catch some of these failures using a tool that we have developed called USB Hardware Verifier. In this blog entry, I am going to focus only on the issues related to devices. We will cover the issues related to hubs and controllers in future blog entries.

2 Design choices on how to deal with failures

2.1 Transient Failures

Some of the issues that we encountered are just transient failures that do not happen consistently. For example: a link going into an error state or an occasional transfer failure. Our driver stack typically tries to be resilient towards such failures by initiating an appropriate error recovery action or if applicable, retrying the operation in progress. Of course if such errors happen frequently, then they will lead to a poor end user experience. These types of errors give an impression to the user that the hardware is flaky. For example a device failing transfers could cause the device enumeration to take longer or fail altogether.

2.2 Consistent Failures

Then there are more consistent failures where hardware is behaving in a non-spec compliant manner by design. For example a device returning invalid descriptor or repeatedly failing a spec required control transfer. We had a design choice regarding how our driver stack should deal with such failures. In many cases, these errors are not fatal i.e. we could choose to ignore the error and go on working with that hardware. However, the problem with that approach is that we are essentially guessing the intent of the hardware and we might have to default to non-optimal values. This in turn could lead to sub optimal user experience, examples of which I will give below. Moreover, since the hardware “works”, there is no forcing function for the hardware vendors to fix these issues and we lose the ability to ensure the quality of Windows experience. Therefore we consciously try to detect such issues and fail the hardware explicitly as early as possible. For example, if a device returns an invalid descriptor, we will fail the enumeration of the device and the device will come up with an error code in Device Manager.

There are a few exceptions to the above design pattern. In some scenarios, it might not be efficient to look for such errors and we decided to avoid the performance penalty. Then there are cases where we realized that the specification is ambiguous and the hardware issue is really due to a different interpretation of the specification by the hardware vendor. In such cases, we try to get the specification updated to clear up the ambiguity but also keep working with the hardware. Finally, we wanted to maintain backwards compatibility with Windows 7 for old devices and hubs. For USB 2.0 or lower devices, our goal was to maintain the Windows 7 behavior for hardware errors. If the device version is greater than USB2.0, then we are stricter about requiring spec compliant behavior.

2.3 Workarounds

As we were developing the Windows 8 USB 3.0 stack, we also implemented specific workarounds for specific hardware where we allowed non-spec compliant behavior and interpreted the hardware behavior in a manner not dictated by the specifications. This was typically done only if we got a confirmation from the hardware vendor about the intended behavior, such that we didn’t need to “guess” the intent of the hardware and only after we had received assurance that the behavior would be fixed in the next version. As we approached the end of Windows 8 development we stopped implementing any additional workarounds and over time we became much more critical about applying workarounds to new hardware, as new hardware had plenty of time to test with Windows 8. With the broad availability of Windows 8 and the USB 3.0 stack, hardware vendors should be able to successfully build their hardware in a compliant way, thus avoiding the need for adding workarounds.

3 Catching the failures

As we will see later in the document that in many cases, hardware issues manifest themselves in ways such that it is not trivial to determine the exact failure just by looking at the end to end behavior. In order to enable our hardware partners to catch these errors really early in the development cycle, we created a tool that catches and reports these errors. We refer to this tool as “USB Hardware Verifier”. This tool is part of the MUTT software package.

3.1 Usage

Usage of the tool involves three steps: starting a session, running the desired tests with your hardware and then stopping the session. This tool captures hardware events as they occur. It gives the user the ability to display information about those events in real time and at the same time, allows the user to capture the information in a trace file that can be parsed at a later time. The tool also provides an ability to filter events based on the VendorId and ProductId of the hardware so that the user can target a specific hardware.

To start the session, run the tool at an elevated command prompt and to stop the session at any time, simply press CTRL+C.

USB3HWVerifierAnalyzer.exe

The tool supports these options:

-v <VendorID> : Logs all hardware verifier events for the specified VendorID

-p <ProductID> : Logs all hardware verifier events for the specified ProductID

-f <ETL file> : Parses the specified ETL file. Note that this option is used to parse an existing ETL file offline.

/v output : Displays all events to the console.

At the end of the session, a file named AllEvents.etl is added in the current directory. This file contains trace information about all events that were captured during the session. The command window also shows detailed report after the session ends. This report categorizes the information by controller, hub, or device, making it easier to read. The report contains a key that you can use to filter events based on those categories. Note that while displaying information in real time, the tool might not capture some information (such as VID/PID) related to events that occur before the device gets fully enumerated. The missing information is available in the detailed report though.

Here is an example output from the USB hardware verifier tool.

…
12983512883.067484s: (UsbHub3/176):

Event Message:DescriptorValidationError20HubPortPwrCtrlMaskZero

VendorID/ProductID: 0x45E/0x1234

DeviceInterfacePath: \??\USB#VID_045E&PID_1234#6&c4be011&0&2#{f18a0e88-c30c-11d0-8815-00a0c906bed8}

DeviceDescription: Generic USB Hub

PortPath: 0x2, 0x0, 0x0, 0x0, 0x0, 0x0

12983512888.452400s: (UsbHub3/173)

Event Message: SuperSpeed Device is Connected on the 2.0 Bus:

PortPath: 0x2, 0x4, 0x0, 0x0, 0x0, 0x0

12983512900.098652s: (UsbHub3/176):

Event Message:DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0

12983512900.098654s: (UsbHub3/176):

Event Message:DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0

12983512900.098656s: (UsbHub3/176):

Event Message:DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0

…

In the above output, you will notice that the tool is reporting an error (highlighted) for the hub where the port power control mask is zero in the hub descriptor. Similarly, it is reporting a number of errors for a device. The first error (highlighted) is about the companion endpoint descriptor for an isoch endpoint having WBytesPerInterval field too large. In the real time output, the details of this device are not displayed. However, the following test report shows those details.

The following output shows an example test report for the preceding session

**********************************************************************************************

Test Results:

Below is a report of all the Hardware verifier events encountered. The Key field refers to a Controller, hub, or device. During the lifetime of this utility, all unfiltered events are captured in file AllEvents.etl (in current directory). The Key in below report can be used to filter events in AllEvents.etl file

**********************************************************************************************

Record #1 (Key = 0x57ff0de4858)

VendorID/ProductID: 0x45E/0x1234

DeviceInterfacePath: \??\USB#VID_045E&PID_1234#6&c4be011&0&2#{f18a0e88-c30c-11d0-8815-00a0c906bed8}

DeviceDescription: Generic USB Hub

PortPath: 0x2, 0x0, 0x0, 0x0, 0x0, 0x0

All errors encountered:

#1: (UsbHub3/176): DescriptorValidationError20HubPortPwrCtrlMaskZero

Record #2 (Key = 0x57ff79fd4e8)

VendorID/ProductID: 0x45E/0x3456

PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0

All errors encountered:

#1: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

#2: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

#3: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge

…

4 Hardware Failures

I will now talk in detail about some of the common issues that we encountered. For each issue, I will also point out whether it can be caught by the USB hardware verifier tool and if so, what is the failure string corresponding to the issue.

4.1 U1/U2 Related Issues

The USB 3.0 specification introduces two new link power management states U1 and U2. A big share of hardware issues that we encountered were related to the implementation of these states. I have already talked in detail about these states and the related problems in this paper. I will not be covering those failures here; I strongly encourage you to read that paper

4.2 2.0 LPM Related Issues

We added limited support for 2.0 LPM in the Windows 8 USB 3.0 stack. We have seen some issues related to this mechanism. I will cover this topic in detail in a future blog entry.

4.3 Invalid Descriptors

As part of device enumeration, the USB core stack reads, parses and validates the descriptors reported by the device. Some devices report descriptors that are not valid as per the USB spec. In the USB hardware verifier output, these failures can be identified by the tag DeviceHwVerifierDescriptorValidationFailure. Since there are many variations of this failure, each specific failure has an associated tag starting with the string DescriptorValidationError, some examples of which are given below.

4.3.1 Missing or zero Container Id

The concept of Container Id was introduced in Windows 7. In the USB world, container ID was reported as part of the MS OS descriptor. With USB 3.0 and USB 2.1 addendum, this concept was adopted in the USB specification. Devices are required to report Container ID (USB 3.0 specification Section 9.6.2.3) as part of their BOS descriptors. However, we have observed that some devices do not report the Container Id descriptor or report it as all zeroes. We will fail the enumeration for such a device because if we ignored this failure and enumerated the device, the device might work but might not appear correctly in the UI. In the USB hardware verifier output, this failure can be identified by tag DescriptorValidationErrorMSOSContainerIdAllZeroes.

4.3.2 Invalid U1/U2 exit latencies

U1 and U2 are power states introduced in USB 3.0. Some devices report edU1/U2 exit latencies that were not valid. We will fail the enumeration for such a device. If we ignored this failure, we wouldn’t know the real values for the device and would be forced to disable U1/U2 leading to more power consumption.

In the USB hardware verifier output, these failures can be identified by the tags DescriptorValidationErrorSuperSpeedCapBU1DevExitLatTooLarge and DescriptorValidationErrorSuperSpeedCapBU2DevExitLatTooLarge

4.4 SuperSpeed devices connecting on the 2.0 port

We observed that sometimes a SuperSpeed device would connect to USB 2.0 even though the device is connected to a 3.0 connector and SuperSpeed is available on that port. This can happen either when the device is initially attached or after a system sleep resume cycle. Such behavior can lead to reduced functionality and non-ideal user experience.

In the USB hardware verifier output, this failure can be identified by the tag DeviceHwVerifierSuperSpeedDeviceWorkingAtLowerSpeed. However, if the device is deliberately connected behind a 2.0 Hub for testing purposes, then it is expected that the device will work at 2.0 and in that case, please ignore this failure.

4.5 SuperSpeed devices reporting old USB version when operating at 2.0

When a 3.0 device is plugged in behind a 2.0 Hub or controller, it will operate at one of the 2.0 speeds. Devices in this scenario are required to report their bcdUSB in the Device Descriptor as 0210 (USB 3.0 Specification Section 9.2.6.6). However some devices reported this value as 0200. When a device does that, the driver stack cannot detect this error and therefore the device will enumerate and continue to work. However, the driver stack will not query for the BOS descriptor for such a device and hence will not be able to indicate that the device can perform faster when connected to USB 3.0. The user will get the lower speed and potentially reduced functionality without knowing the remedy. This failure cannot be caught by the USB hardware verifier.

4.6 Devices connecting at both 2.0 and SuperSpeed simultaneously

The USB 3.0 specification clearly states that any USB 3.0 device, that is not a hub, should not connect at both USB 2.0 and SuperSpeed simultaneously (USB 3.0 Specification Section 9.2.6.6). Such devices are not supported by Windows and can lead to unknown behavior. In Windows 8, we do not explicitly prevent such a device from enumerating and therefore it might seem that these devices are working with Windows. However, there are good chances that these devices might not work at all with future versions of Windows. This failure cannot be caught by the USB hardware verifier.

4.7 Wake capability in Interface descriptor

For 3.0 devices, supporting remote wake also involves supporting function wake (USB 3.0 Specification Section 9.2.5.3). So there are two places where a device needs to indicate that it is remote wake capable. First is the “Remote Wake” bit of bmAttributes in the configuration descriptor (USB 3.0 Specification Section 9.6.3) and the second place is in the “Function Remote Wake Capable” in the Get Status for the first interface of each function in the device (USB 3.0 Specification Section 9.4.5). We expect devices to report consistent information in these bits. For single function devices, we expect these bits to match. For multi-function devices, we expect the Remote Wake bit in the configuration descriptor to be 1 if at least one of the functions reports 1 for the Function Remote Wake Capable bit. However, we have observed some devices did not report the interface status correctly. In such cases, we are forced to choose one bit over another. A wrong guess on our part could lead to incorrect power capabilities and the client driver making a wrong decision about whether to arm the device for wake or not. It could also result in client driver not enabling Selective Suspend for the device.

In the USB hardware verifier output, these failures can be identified by the tag DeviceHwVerifierInterfaceWakeCapabilityMismatch.

4.8 Not supporting 3.0 specific requests

Some devices failed the standard control transfers that are new additions to the USB 3.0 specification over USB 2.0. These transfers are used to relay information to the device. It is quite likely that the information relayed in the request is not interesting to some devices. However, since these are standard requests, we expect devices to always succeed the transfer as required by the USB 3.0 specification. As it is, the failure of this transfer is not a problem from the point of view of the driver stack because quite likely the device is not interested in that information at all. However the driver stack cannot differentiate between a device that always fails this transfer because it does not need this information versus a device that needs the information but happens to fail the transfer because of a transient error (in which case the driver stack should retry).

4.8.1 Set Isoch delay

“SET_ISOCH_DELAY” (USB 3.0 Specification Section 9.4.11) is a standard control transfer sent to inform the device of the delay from the time a host transmits a packet to the time it is received by the device. Unfortunately we saw a significant number of devices fail this transfer and as a result, we were forced to ignore this transfer failure in the Windows 8 driver stack.

In the USB hardware verifier output, this failure can be identified by the tag DeviceHwVerifierSetIsochDelayFailure.

4.8.2 Set SEL

“SET_SEL” (USB 3.0 Specification Section 9.4.12) is a standard control transfer sent to inform the device about U1 and U2 exit latencies of the path from the host to the device. Our Windows 8 driver stack ignores the failure of this transfer if the device stalled the transfer as it indicates that the device is consciously returning failure. If the transfer fails for any other reason, then the driver stack fails the device enumeration.

In the USB hardware verifier output, this failure can be identified by the tag DeviceHwVerifierSetSelFailure.

4.9 Different Serial Number on re-enumeration

Some devices reported one serial number during the initial enumeration on device attach and then reported a different serial number on re-enumeration after a port reset. Re-enumeration can happen while resuming from system sleep or it can be initiated by the client driver. While re-enumerating the device, we match the serial number of the device with the initial serial number to ensure it is the same device. This step is particularly important on system resume where the user has the opportunity to replace the device. If the serial number does not match, then the re-enumeration is failed and the device is surprise removed before it is enumerated again. This sequence is particularly problematic if the device is a boot device, in which case the system will crash.

In the USB hardware verifier output, this failure can be identified by the tag DeviceHwVerifierSerialNumberMismatchOnRenumeration.

4.10 Device disappearing on system resume

When the system goes to sleep, some controllers or platforms will cut the VBUS off and cause the downstream devices to disconnect from the bus. When the system resumes and VBUS is reapplied, these devices will connect back. If the device is bus powered, then it will also need to power back on before connecting on the bus.

If the driver stack reads the port status during system resume and finds that the device is back, the driver will re-enumerate the device and re-store its configuration without letting the operating system know that the device re-connected. As a result, this re-enumeration is transparent to applications. Any operations in progress before the system went to sleep can continue without interruption.

However, if the driver stack finds that the device has not connected back, it will report the device as missing to the operating system. When the device connects back, there will be a new instance created for the device and the device will start working. However, the surprise removal of the old instance of the device will interrupt any applications that were using the device before the system went to sleep. For example if a file copy was in progress for a storage device, it will fail. Also, creating a new instance will take some time and the user might see a delay in device becoming available after resume.

To mitigate this issue, we implemented a heuristics in our Windows 8 driver stack. When the driver stack finds that the device is not connected on system resume, it gives a grace period (which is currently set to one second) to the device to connect back before reporting the device missing. However, we observed that some devices take longer than this to connect back, leading to surprise removal and a poor end user experience.

In the USB hardware verifier output, this failure can be identified by the tag HubHwVerifierPortDeviceDisconnected. However, please note that this tag will appear whenever the device is disconnected. So if you did indeed remove the device, then ignore this tag.

4.11 SuperSpeed devices requiring additional delays

We found that some SuperSpeed devices required a delay between two operations initiated by the driver stack even though the specification mandates them to not be dependent on such a delay. Often these delays were such that they were part of the USB 2.0 specification but have been removed in the USB 3.0 specification.

These errors cannot be detected as such by the USB hardware verifier. However, these failures will most likely manifest themselves as the device not completing the next control transfer successfully. These failures can be identified in the USB hardware verifier output by the tag DeviceHwVerifierControlTransferFailure. One tricky part with catching such errors is that they might not happen consistently and might only reproduce with specific host controllers and topologies. Therefore it is always a good idea to test a device with multiple host controllers and in various topologies.

4.11.1 Delay after connect

When a SuperSpeed device connects to a host, it goes through a sequence of operations in the hardware before the connect bit goes to 1 and a connect change is indicated. By the time the host gets the connect change, the device must be ready to respond to host requests. But we saw that some devices got confused if the host started communicating with the device immediately which leads to the device failing enumeration. It is not even possible to implement a device specific workaround for this issue as we have not even received the device descriptor of the device at that point in enumeration.

4.11.2 Delay after reset

The USB 3.0 specification mandates that after a port is successfully reset or resumed, the USB driver stack is allowed to access the device attached to the port immediately and it is expected to respond to data transfers (USB 3.0 Specification Section 9.2.6.2). Unfortunately some devices got confused if the driver stack did that and failed enumeration.

4.12 Devices disconnecting on disable/suspend

When the user chooses to “Safely remove hardware” from the task bar, our driver stack disables the port that the device is attached to. However, we observed that when we disabled or suspended some devices, they would disconnect from the port. This causes unexpected surprise removal of the device. Moreover, since the driver re-enumerates a new instance of the device, the port comes back in enabled state. This can lead to end user confusion. For example, If the device has an indicator light, it does not go off and user might get confused as to whether it is indeed safe to remove the device. Also, it leads to the device consuming more power without any good reason to do so.

Note that this behavior changed from Windows 7 to Windows 8. In Windows 7, we didn’t disable the port. The reason we changed the behavior from Windows 7 to Windows 8 is because Windows 7 behavior leaves the port in the enabled state and leads to the same problems that we discussed above: end user confusion and more power consumption.

5 Conclusion

In this blog, I talked about some of the issues that we encountered with USB 3.0 devices. We hope that the future versions of the devices will avoid these issues leading to a better end user experience and a great Windows experience. We urge our hardware partners to start using the USB hardware verifier tool early in their development cycle so that the errors can be caught and fixed without incurring high costs.

There have been several errata to the USB 3.0 specification. These errata are aimed at removing the ambiguities and filling the gaps. Often these improvements weed out inter-operability issues between software and hardware as well as between hardware components. We strongly encourage the hardware vendors to follow the latest versions of these specifications to provide the best user experience.

In the subsequent blog entries in future, we will talk about issues related to hubs and controllers. Stay tuned!

How to determine whether a USB 3.0 device is operating at SuperSpeed?

USB Blog — Wed, 27 Jun 2012 20:59:35 GMT

How to determine whether a USB 3.0 device is operating at SuperSpeed?

Note: The information provided in this blog post applies to Windows 8.

Hi, I am Sanket Patel, a software developer on the USB team. In this blog post, I will describe some ways in which you can determine whether a USB 3.0 device that is attached to a PC running Windows 8 version of the operating system, is operating at the optimal connection speed - SuperSpeed.

USB 3.0 introduces a new operating speed called SuperSpeed. Compared to USB 2.0 bandwidth of 480 Mbps, SuperSpeed supports 5.0 Gbps making it 10 times faster than USB 2.0. USB 3.0 also supports lower operating speeds: high speed, full speed, and low speed. Along with increased bandwidth, USB 3.0 host controllers and devices come with the promise of compatibility. USB 3.0 controllers are required to work with all existing USB devices. The fact that current PCs ship with both USB 2.0 and USB 3.0 ports presents an interesting challenge: how should you determine whether a USB 3.0 device is indeed operating at SuperSpeed?

Here are some ways to determine the operating speed of the USB device:

Make sure that you have USB 3.0-capable hardware
View device information in Device Manager
Look for Windows 8 UI messages
Use USBView to view the bus speed
Determine the bus speed programmatically
Troubleshooting

Make sure that you have USB 3.0-capable hardware

Typically, newer PCs with USB 3.0 support have both USB 3.0 and USB 2.0 controllers, and both those ports are exposed. The receptacles on USB 3.0 ports are usually blue to distinguish from the receptacles on USB 2.0 ports, which are black. So, if the PC has a blue port, that is a good indication of USB 3.0 support. Note this is not a requirement of the official USB specification, rather a convention adopted by some PC makers.

Figure 1 shows a typical USB 2.0 port.

Figure 1. USB 2.0 port with a black receptacle

Figure 2 shows a typical USB 3.0 port.

Figure 2. USB 3.0 port with a blue receptacle

If the PC does not use blue receptacle for the USB 3.0 ports, it might have a USB 3.0 logo () next to the port.

Figure 3 shows the USB 2.0 logo.

Figure 3. USB 2.0 logo

Figure 4 shows the USB 3.0 logo.

Figure 4. USB 3.0 logo

You should also look for the logo on USB 3.0 devices and cables. Figure 5 shows the USB 3.0 logo on the connector of a USB 3.0 cable.

Figure 5 USB 3.0 logo on USB 3.0 cable

View device information in Device Manager

Next, confirm that Windows enumerated the host controller as a USB 3.0 controller. To confirm that, open Device Manager and locate the controller under the Universal Serial Bus controllers node. If Windows recognized it as a USB 3.0 controller, USB 3.0 eXtensible Host Controller is appended to the device description as shown in Figure 6.

Figure 6. USB 3.0 eXtensible Host Controller in Device Manager

Look for Windows 8 UI messages to determine whether the USB 3.0 device is operating at SuperSpeed

To indicate whether the USB 3.0 device is operating at SuperSpeed, Windows 8 shows UI messages in specific places. If the PC has USB 3.0 controller to which a USB 3.0 device is attached, Windows 8 shows Connected to USB 3.0 when the device is operating at SuperSpeed. If the operating speed is lower than SuperSpeed, the message is Device can perform faster when connected to USB 3.0.

You can view those UI messages in PC Settings.

Open the Charms Bar by dragging the cursor to top right of the screen or by pressing Win + C.
Select Settings and then Change PC settings.
Select the Devices under PC settings application.

Figure 7 shows the UI message when the USB 3.0 device is operating at SuperSpeed.

Figure 7. PC settings – UI message for a USB 3.0 device that is operating at SuperSpeed

Figure 8 shows the UI message when the USB device is operating at a bus speed that is lower than SuperSpeed.

Figure 8. PC settings – UI message for a USB 3.0 device that is operating at a speed lower than SuperSpeed

You can view similar messages in Devices and Printers, as shown in figures 9 and 10.

Figure 9. Devices and Printers - UI message for a USB 3.0 device that is operating at SuperSpeed

Figure 10. Devices and Printers – UI message for a USB 3.0 device that is operating at a speed lower than SuperSpeed

If the USB 3.0 device is a storage device, Windows Explorer shows similar messages when the volume label is selected, as shown in figures 11 and 12. Note that the View -> Details pane must be selected for the message to be visible.

Figure 11. Windows Explorer - message for a USB 3.0 device that is operating at SuperSpeed

Figure 12. Windows Explorer - UI message for a USB 3.0 device that is operating at a speed lower than SuperSpeed

Use USBView to view device information about the bus speed

If you are writing a device driver, the USBView tool might be more useful for verifying the bus speed. The tool is included in the Windows Driver Kit (WDK) 8 Release Preview (RP), which is available for download at this Web site. USBView in this release has been updated to display SuperSpeed information.

Figure 13 shows a USB 3.0 device operating at SuperSpeed in USBView.

Figure 13. USBView – Message for a USB 3.0 device that is operating at SuperSpeed

Determine the bus speed programmatically

If you are a device driver developer, the USB driver stack exposes a new IOCTL, IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX_V2, which you can use to query speed information for USB 3.0 devices.

Troubleshooting

Here are a few things to try if you find that your USB 3.0 device is capable of operating at SuperSpeed but is operating a lower bus speed:

Make sure that you do not have a USB 2.0 hub between the device and the PC. That is because USB 3.0 devices that are attached to a USB 2.0 hub can only operate at high speed. In this case, either switch to a USB 3.0 hub or attach the device directly to the USB 3.0 port on the PC.
Ensure that the USB 3.0 hub that your device is attached to appears correctly in Device Manager. For certain unsupported USB 3.0 hubs, Windows may disable the SuperSpeed portion of the hub and report it as “Non Functional” in Device Manager.

Figure 14 shows a non-functional hub in Device Manager.

Figure 14. SuperSpeed USB Hub is not functional

Make sure that the cable that is used to connect the device is a USB 3.0 cable. It is also possible that the USB 3.0 cable has signal integrity issues. In that case, the device might switch to high speed. If that happens, you must change the USB 3.0 cable.
Update the firmware for the USB 3.0 device by obtaining the latest version from the manufacturer site. Some USB 3.0 device manufacturers release fixes, for bugs found in the device, as firmware updates.
Update the firmware for the USB 3.0 controller by obtaining the latest version from the manufacturer site. Some USB 3.0 controller manufacturers release fixes, for bugs found in the controller, as firmware updates.
Update the BIOS for your system by obtaining the latest version from the manufacturer. On some motherboards, the BIOS can incorrectly route a device that is connected to a USB 3.0 controller to a USB 2.0 controller. That incorrect routing allows the USB 3.0 device to operate at high speed but not at SuperSpeed. A BIOS update might fix such a problem.

Summary

In this blog post, we discussed ways of making sure that you get optimal experience with your USB 3.0 device attached to a USB 3.0 controller on a PC. If you have any questions, please leave us a comment.

-Sanket Patel

New for Windows 8: Problem Descriptions for USB Devices and Hubs in Device Manager

USB Blog — Fri, 08 Jun 2012 19:10:18 GMT

Perhaps the most commonly encountered problem with USB devices is enumeration failure. If a USB device fails to enumerate successfully it will appear in Device Manager with a problem code of 43, and will be listed as an “Unknown Device” If Windows was unable to identify the device before it failed enumeration. There are a number of reasons why a USB device can fail to enumerate, however the specific reason for the failure has not been easily discovered without using diagnostic tools such as USB ETW logging.

Windows 8 will now provide a problem description in Device Manager for USB devices that have failed to enumerate, and for USB hubs that have failed during operation. When one of these failures occurs, the USB device’s status on its “General” property page will display a problem description indicating what the failure was. Below is an example device status for a USB device that failed because it returned an invalid USB configuration descriptor. The problem description is highlighted.

The possible problem descriptions that can be returned for a USB device that failed enumeration in Windows 8 are:

A request for the USB device descriptor failed.
The USB set address request failed.
A USB port reset request failed.
A previous instance of the USB device was not removed.
The USB device returned an invalid USB configuration descriptor.
The USB device returned an invalid USB device descriptor.
Unable to access the registry.
A request for the USB configuration descriptor failed.
A request for the USB device's port status failed.
The USB device returned an invalid serial number string.
The USB set SEL request failed.
A request for the USB BOS descriptor failed.
A request for the USB device qualifier descriptor failed.
A request for the USB serial number string descriptor failed.
A request for the USB language ID string descriptor failed.
A request for the USB product description string descriptor failed.
A request for the Microsoft OS extended configuration descriptor failed.
A request for the Microsoft OS container ID descriptor failed.
The USB device returned an invalid USB BOS descriptor.
The USB device returned an invalid USB device qualifier descriptor.
The USB device returned an invalid USB language ID string descriptor.
The USB device returned an invalid Microsoft OS container ID descriptor.
The USB device returned an invalid Microsoft OS extended configuration descriptor.
The USB device returned an invalid product description string descriptor.
The SuperSpeed link to the USB device keeps going to an error state SSInactive.
The SuperSpeed link to the USB device keeps going to an error state Compliance. If the device is removable, remove the device and then disable/enable from device manager to recover.
The USB device is not compatible with Windows.

The possible problem descriptions for a USB hub failure in Windows 8 are:

The USB hub returned an invalid port status.
The USB hub failed a control transfer request.
The USB hub failed an interrupt transfer request.
The USB hub failed to reset.

To resolve these errors a user should follow the steps outlined in the blog post What to Try When Your USB Device is an "Unknown Device". A USB device developer encountering any of these errors should investigate further using USB ETW logging.

-Martin Borve