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

[Shyamal Varma]

First published on MSDN on Jul 26, 2012

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!