WinUSB (Winusb.sys) Installation

For certain Universal Serial Bus (USB) devices, such as devices that are accessed by only a single application, you can install WinUSB (Winusb.sys) in the device’s kernel-mode stack as the USB device’s function driver instead of implementing a driver.

This topic contains these sections:

Automatic installation of WinUSB without an INF file

As an OEM or independent hardware vendor (IHV), you can build your device so that the Winusb.sys gets installed automatically on WindowsВ 8 and later versions of the operating system. Such a device is called a WinUSB device and does not require you to write a custom INF file that references in-box Winusb.inf.

When you connect a WinUSB device, the system reads device information and loads Winusb.sys automatically.

For more information, see WinUSB Device.

Installing WinUSB by specifying the system-provided device class

When you connect your device, you might notice that Windows loads Winusb.sys automatically (if the IHV has defined the device as a WinUSB Device). Otherwise follow these instructions to load the driver:

1. Plug in your device to the host system.
2. Open Device Manager and locate the device.
3. Select and hold (or right-click) the device and select Update driver software. from the context menu.
4. In the wizard, select Browse my computer for driver software.
5. Select Let me pick from a list of device drivers on my computer.
6. From the list of device classes, select Universal Serial Bus devices.
7. The wizard displays WinUsb Device. Select it to load the driver.

If Universal Serial Bus devices does not appear in the list of device classes, then you need to install the driver by using a custom INF. The preceding procedure does not add a device interface GUID for an app (UWP app or Windows desktop app) to access the device. You must add the GUID manually by following this procedure.

Load the driver as described in the preceding procedure.

Generate a device interface GUID for your device, by using a tool such as guidgen.exe.

Find the registry key for the device under this key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\USB\

Under the Device Parameters key, add a String registry entry named DeviceInterfaceGUID or a Multi-String entry named DeviceInterfaceGUIDs. Set the value to the GUID you generated in step 2.

Disconnect the device from the system and reconnect it to the same physical port. NoteВ В If you change the physical port then you must repeat steps 1 through 4.

Writing a custom INF for WinUSB installation

As part of the driver package, you provide an .inf file that installs Winusb.sys as the function driver for the USB device.

The following example .inf file shows WinUSB installation for most USB devices with some modifications, such as changing USB_Install in section names to an appropriate DDInstall value. You should also change the version, manufacturer, and model sections as necessary. For example, provide an appropriate manufacture’s name, the name of your signed catalog file, the correct device class, and the vendor identifier (VID) and product identifier (PID) for the device. For info on creating a catalog file, see Creating a Catalog File for Test-Signing a Driver Package.

Also notice that the setup class is set to «USBDevice». Vendors can use the «USBDevice» setup class for devices that do not belong to another class and are not USB host controllers or hubs.

If you are installing WinUSB as the function driver for one of the functions in a USB composite device, you must provide the hardware ID that is associated with the function, in the INF. You can obtain the hardware ID for the function from the properties of the devnode in Device Manager. The hardware ID string format is «USB\VID_vvvv&PID_pppp».

The following INF installs WinUSB as the OSR USB FX2 board’s function driver on a x64-based system.

Starting in Windows 10, version 1709, the Windows Driver Kit provides InfVerif.exe that you can use to test a driver INF file to make sure there are no syntax issues and the INF file is universal. We recommened that you provide a universal INF. For more information, see Using a Universal INF File.

Only include a ClassInstall32 section in a device INF file to install a new custom device setup class. INF files for devices in an installed class, whether a system-supplied device setup class or a custom class, must not include a ClassInstall32 section.

Except for device-specific values and several issues that are noted in the following list, you can use these sections and directives to install WinUSB for any USB device. These list items describe the Includes and Directives in the preceding .inf file.

USB_Install: The Include and Needs directives in the USB_Install section are required for installing WinUSB. You should not modify these directives.

USB_Install.Services: The Include directive in the USB_Install.Services section includes the system-supplied .inf for WinUSB (WinUSB.inf). This .inf file is installed by the WinUSB co-installer if it isn’t already on the target system. The Needs directive specifies the section within WinUSB.inf that contains information required to install Winusb.sys as the device’s function driver. You should not modify these directives. NoteВ В Because WindowsВ XP doesn’t provide WinUSB.inf, the file must either be copied to WindowsВ XP systems by the co-installer, or you should provide a separate decorated section for WindowsВ XP.

USB_Install.HW: This section is the key in the .inf file. It specifies the device interface globally unique identifier (GUID) for your device. The AddReg directive sets the specified interface GUID in a standard registry value. When Winusb.sys is loaded as the device’s function driver, it reads the registry value DeviceInterfaceGUIDs key and uses the specified GUID to represent the device interface. You should replace the GUID in this example with one that you create specifically for your device. If the protocols for the device change, create a new device interface GUID.

NoteВ В User-mode software must call SetupDiGetClassDevs to enumerate the registered device interfaces that are associated with one of the device interface classes specified under the DeviceInterfaceGUIDs key. SetupDiGetClassDevs returns the device handle for the device that the user-mode software must then pass to the WinUsb_Initialize routine to obtain a WinUSB handle for the device interface. For more info about these routines, see How to Access a USB Device by Using WinUSB Functions.

The following INF installs WinUSB as the OSR USB FX2 board’s function driver on a x64-based system. The example shows INF with WDF coinstallers.

USB_Install.CoInstallers: This section, which includes the referenced AddReg and CopyFiles sections, contains data and instructions to install the WinUSB and KMDF co-installers and associate them with the device. Most USB devices can use these sections and directives without modification.

The x86-based and x64-based versions of Windows have separate co-installers.

NoteВ В Each co-installer has free and checked versions. Use the free version to install WinUSB on free builds of Windows, including all retail versions. Use the checked version (with the «_chk» suffix) to install WinUSB on checked builds of Windows.

Each time Winusb.sys loads, it registers a device interface that has the device interface classes that are specified in the registry under the DeviceInterfaceGUIDs key.

NoteВ В If you use the redistributable WinUSB package for WindowsВ XP or Windows ServerВ 2003, make sure that you don’t uninstall WinUSB in your uninstall packages. Other USB devices might be using WinUSB, so its binaries must remain in the shared folder.

How to create a driver package that installs Winusb.sys

To use WinUSB as the device’s function driver, you create a driver package. The driver package must contain these files:

• WinUSB co-installer (Winusbcoinstaller.dll)
• KMDF co-installer (WdfcoinstallerXXX.dll)
• An .inf file that installs Winusb.sys as the device’s function driver. For more information, see Writing an .Inf File for WinUSB Installation.
• A signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows starting withВ Vista.

NoteВ В Make sure that the driver package contents meet these requirements:

• The KMDF and WinUSB co-installer files must be obtained from the same version of the Windows Driver Kit (WDK).
• The co-installer files must be obtained from the latest version of the WDK, so that the driver supports all the latest Windows releases.
• The contents of the driver package must be digitally signed with a Winqual release signature. For more info about how to create and test signed catalog files, see Kernel-Mode Code Signing Walkthrough on the Windows Dev Center — Hardware site.

Create a driver package folder on the machine that the USB device is connected to. For example, c:\UsbDevice.

Copy the WinUSB co-installer (WinusbcoinstallerX.dll) from the WinDDK\BuildNumber\redist\winusb folder to the driver package folder.

The WinUSB co-installer (Winusbcoinstaller.dll) installs WinUSB on the target system, if necessary. The WDK includes three versions of the co-installer depending on the system architecture: x86-based, x64-based, and Itanium-based systems. They are all named WinusbcoinstallerX.dll and are located in the appropriate subdirectory in the WinDDK\BuildNumber\redist\winusb folder.

Copy the KMDF co-installer (WdfcoinstallerXXX.dll) from the WinDDK\BuildNumber\redist\wdf folder to the driver package folder.

The KMDF co-installer (WdfcoinstallerXXX.dll) installs the correct version of KMDF on the target system, if necessary. The version of WinUSB co-installer must match the KMDF co-installer because KMDF-based client drivers, such as Winusb.sys, require the corresponding version of the KMDF framework to be installed properly on the system. For example, Winusbcoinstaller2.dll requires KMDF version 1.9, which is installed by Wdfcoinstaller01009.dll. The x86 and x64 versions of WdfcoinstallerXXX.dll are included with the WDK under the WinDDK\BuildNumber\redist\wdf folder. The following table shows the WinUSB co-installer and the associated KMDF co-installer to use on the target system.

Use this table to determine the WinUSB co-installer and the associated KMDF co-installer.

WinUSB co-installer	KMDF library version	KMDF co-installer
Winusbcoinstaller.dll	Requires KMDF version 1.5 or later
Winusbcoinstaller2.dll	Requires KMDF version 1.9 or later	Wdfcoinstaller01009.dll
Winusbcoinstaller2.dll	Requires KMDF version 1.11 or later	WdfCoInstaller01011.dll

Write an .inf file that installs Winusb.sys as the function driver for the USB device.

Create a signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows.

Attach the USB device to your computer.

Open Device Manager to install the driver. Follow the instructions on the Update Driver Software wizard and choose manual installation. You will need to provide the location of the driver package folder to complete the installation.

How to write your first USB client driver (UMDF)

In this topic you’ll use the USB User-Mode Driver template provided with Microsoft Visual StudioВ 2019 to write a user-mode driver framework (UMDF)-based client driver. After building and installing the client driver, you’ll view the client driver in Device Manager and view the driver output in a debugger.

UMDF (referred to as the framework in this topic) is based on the component object model (COM). Every framework object must implement IUnknown and its methods, QueryInterface, AddRef, and Release, by default. The AddRef and Release methods manage the object’s lifetime, so the client driver does not need to maintain the reference count. The QueryInterface method enables the client driver to get interface pointers to other framework objects in the Windows Driver Frameworks (WDF) object model. Framework objects perform complicated driver tasks and interact with Windows. Certain framework objects expose interfaces that enable a client driver to interact with the framework.

A UMDF-based client driver is implemented as an in-process COM server (DLL), and C++ is the preferred language for writing a client driver for a USB device. Typically, the client driver implements several interfaces exposed by the framework. This topic refers to a client driver-defined class that implements framework interfaces as a callback class. After these classes are instantiated, the resulting callback objects are partnered with particular framework objects. This partnership gives the client driver the opportunity to respond to device or system-related events that are reported by the framework. Whenever Windows notifies the framework about certain events, the framework invokes the client driver’s callback, if one is available. Otherwise the framework proceeds with the default processing of the event. The template code defines driver, device, and queue callback classes.

For an explanation about the source code generated by the template, see Understanding the UMDF template code for USB client driver.

Prerequisites

For developing, debugging, and installing a user-mode driver, you need two computers:

• A host computer running WindowsВ 7 or a later version of the Windows operating system. The host computer is your development environment, where you write and debug your driver.
• A target computer running the version of the operating system that you want to test your driver on, for example, Windows 10, version 1903. The target computer has the user-mode driver that you want to debug and one of the debuggers.

In some cases, where the host and target computers are running the same version of Windows, you can have just one computer running Windows 7 or a later version of the Windows. This topic assumes that you are using two computers for developing, debugging, and installing your user mode driver.

Before you begin, make sure that you meet the following requirements:

Software requirements

Your host computer has Visual StudioВ 2019.

Your host computer has the latest Windows Driver Kit (WDK) for Windows 10, version 1903.

The kit include headers, libraries, tools, documentation, and the debugging tools required to develop, build, and debug a USB client driver. You can get the latest version of the WDK from How to Get the WDK.

Your host computer has the latest version of debugging tools for Windows. You can get the latest version from the WDK or you can Download and Install Debugging Tools for Windows.

If you are using two computers, you must configure the host and target computers for user-mode debugging. For more information, see Setting Up User-Mode Debugging in Visual Studio.

Hardware requirements

Get a USB device for which you will be writing the client driver. In most cases, you are provided with a USB device and its hardware specification. The specification describes device capabilities and the supported vendor commands. Use the specification to determine the functionality of the USB driver and the related design decisions.

If you are new to USB driver development, use the OSR USB FX2 learning kit to study USB samples included with the WDK. It contains the USB FX2 device and all the required hardware specifications to implement a client driver.

Recommended reading

• Concepts for All Driver Developers
• Device nodes and device stacks
• Getting started with Windows drivers
• User-Mode Driver Framework
• Developing Drivers with Windows Driver Foundation, written by Penny Orwick and Guy Smith. For more information, see Developing Drivers with WDF.

Instructions

Step 1: Generate the UMDF driver code by using the Visual StudioВ 2019 USB driver template

For instructions about generating UMDF driver code, see Writing a UMDF driver based on a template.

For USB-specific code, select the following options in Visual StudioВ 2019

1. In the New Project dialog box, in the search box at the top, type USB.
2. n the middle pane, select User Mode Driver, USB (UMDF V2).
3. lick Next.
4. Enter a project name, choose a save location, and click Create.

The following screen shots show the New Project dialog box for the USB User-Mode Driver template.





This topic assumes that the name of the project is «MyUSBDriver_UMDF_». It contains the following files:

Files	Description
Driver.h; Driver.c	Declares and defines a callback class that implements the IDriverEntry interface. The class defines methods that are invoked by the framework driver object. The main purpose of this class is to create a device object for the client driver.
Device.h; Device.c	Declares and defines a callback class that implements the IPnpCallbackHardware interface. The class defines methods that are invoked by the framework device object. The main purpose of this class is to handle events occurring as a result of Plug and Play (PnP) state changes. The class also allocates and initializes resources required by the client driver as long as it is loaded in the system.
IoQueue.h; IoQueue.c	Declares and defines a callback class that implements the IQueueCallbackDeviceIoControl interface. The class defines methods that are invoked by the framework queue object. The purpose of this class is to retrieve I/O requests that are queued in the framework.
Internal.h	Provides common declarations shared by the client driver and user applications that communicate with the USB device. It also declares tracing functions and macros.
Dllsup.cpp	Contains the implementation of the driver module’s entry point.
.inf	INF file that is required to install the client driver on the target computer.
Exports.def	DEF file that exports the entry point function name of the driver module.

Step 2: Modify the INF file to add information about your device

Before you build the driver, you must modify the template INF file with information about your device, specifically the hardware ID string.

To provide the hardware ID string

Attach your USB device to your host computer and let Windows enumerate the device.

Open Device Manager and open properties for your device.

On the Details tab, select Hardward Ids under Property.

The hardware ID for the device is displayed in the list box. Select and hold (or right-click) and copy the hardware ID string.

In Solution Explorer, expand Driver Files, and open the INF.

Replace the following your hardware ID string.

Notice the AddReg entries in the driver’s information (INF) file.

• WudfCoinstaller.dll (configuration co-installer)
• WUDFUpdate_ .dll (redistributable co-installer)
• Wdfcoinstaller .dll (co-installers for KMDF)
• Winusbcoinstaller2.dll ((co-installers for Winusb.sys)
• MyUSBDriver_UMDF_.dll (client driver module)

If your INF AddReg directive references the UMDF redistributable co-installer (WUDFUpdate_ .dll ), you must not make a reference to the configuration co-installer (WUDFCoInstaller.dll). Referencing both co-installers in the INF will lead to installation errors.

All UMDF-based USB client drivers require two Microsoft-provided drivers: the reflector and WinUSB.

Reflector—If your driver gets loaded successfully, the reflector is loaded as the top-most driver in the kernel-mode stack. The reflector must be the top driver in the kernel mode stack. To meet this requirement, the template’s INF file specifies the reflector as a service and WinUSB as a lower-filter driver in the INF:

AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall ; flag 0x2 sets this as the service for the device

AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall ; this service is installed because its a filter.

WinUSB—The installation package must contain coinstallers for Winusb.sys because for the client driver, WinUSB is the gateway to the kernel-mode USB driver stack. Another component that gets loaded is a user-mode DLL, named WinUsb.dll, in the client driver’s host process (Wudfhost.exe). Winusb.dll exposes WinUSB Functions that simplify the communication process between the client driver and WinUSB.

Step 3: Build the USB client driver code

To build your driver

1. Open the driver project or solution in Visual StudioВ 2019.
2. Right-click the solution in the Solution Explorer and select Configuration Manager.
3. From the Configuration Manager, select your Active Solution Configuration (for example, Debug or Release) and your Active Solution Platform (for example, Win32) that correspond to the type of build you are interested in.
4. Verify that your device interface GUID is accurate throughout the project.
   • The device interface GUID is defined in Trace.h and is referenced from MyUSBDriverUMDFCreateDevice in Device.c. When you create your project with the name «MyUSBDriver_UMDF_», Visual Studio 2019 defines the device interface GUID with the name GUID_DEVINTERFACE_MyUSBDriver_UMDF_ but calls WdfDeviceCreateDeviceInterface with the incorrect parameter «GUID_DEVINTERFACE_MyUSBDriverUMDF». Replace the incorrect parameter with the name defined in Trace.h to ensure that the driver builds properly.
5. From the Build menu, click Build Solution.

For more information, see Building a Driver.

Step 4: Configure a computer for testing and debugging

To test and debug a driver, you run the debugger on the host computer and the driver on the target computer. So far, you have used Visual Studio on the host computer to build a driver. Next you need to configure a target computer. To configure a target computer, follow the instructions in Provision a computer for driver deployment and testing.

Step 5: Enable tracing for kernel debugging

The template code contains several trace messages (TraceEvents) that can help you track function calls. All functions in the source code contain trace messages that mark the entry and exit of a routine. For errors, the trace message contains the error code and a meaningful string. Because WPP tracing is enabled for your driver project, the PDB symbol file created during the build process contains trace message formatting instructions. If you configure the host and target computers for WPP tracing, your driver can send trace messages to a file or the debugger.

To configure your host computer for WPP tracing

Create trace message format (TMF) files by extracting trace message formatting instructions from the PDB symbol file.

You can use Tracepdb.exe to create TMF files. The tool is located in the Windows Kits\10\bin\ folder of the WDK. The following command creates TMF files for the driver project.

tracepdb -f [PDBFiles] -p [TMFDirectory]

The -f option specifies the location and the name of the PDB symbol file. The -p option specifies the location for the TMF files that are created by Tracepdb. For more information, see Tracepdb Commands.

At the specified location you’ll see three files (one per .c file in the project). They are given GUID file names.

In the debugger, type the following commands:

• Load the Wmitrace.dll extension.
• Verfies that the debugger extension is loaded.
• Adds the location of the TMF files to the debugger extension’s search path.

The output resembles this:

To configure your target computer for WPP tracing

1. Make sure you have the Tracelog tool on your target computer. The tool is located in the Windows Kits\10\Tools\ folder of the WDK. For more information, see Tracelog Command Syntax.
2. Open a Command Window and run as administrator.
3. Type the following command:

The command starts a trace session named MyTrace.

The guid argument specifies the GUID of the trace provider, which is the client driver. You can get the GUID from Trace.h in the Visual Studio 2019 project. As another option, you can type the following command and specify the GUID in a .guid file. The file contains the GUID in hyphen format:

You can stop the trace session by typing the following command:

Step 6: Deploy the driver on the target computer

In the Solution Explorer window, select and hold (or right-click) the

Package , and choose Properties.

1. In the left pane, navigate to Configuration Properties > Driver Install > Deployment.
2. Check Enable deployment, and check Import into driver store.
3. For Remote Computer Name, specify the name of the target computer.
4. Select Install and Verify.
5. Select Ok.
6. On the Debug menu, choose Start Debugging, or press F5 on the keyboard.

Do not specify the hardware ID of your device under Hardware ID Driver Update. The hardware ID must be specified only in your driver’s information (INF) file.

Step 7: View the driver in Device Manager

Enter the following command to open Device Manager.

devmgmt

Verify that Device Manager shows the following node.

USB Device

MyUSBDriver_UMDF_Device

Step 8: View the output in the debugger

Verify that trace messages appear in the Debugger Immediate Window on the host computer.

The output should be similar to the following:

Remarks

Let’s take a look at how the framework and the client driver work together to interact with Windows and handle requests sent to the USB device. This illustration shows the modules loaded in the system for a UMDF -based USB client driver.

The purpose of each module is described here:

• Application—a user-mode process that issues I/O requests to communicate with the USB device.
• I/O Manager—a Windows component that creates I/O request packets (IRPs) to represent the received application requests, and forwards them to the top of the kernel-mode device stack for the target device.
• Reflector—a Microsoft-provided kernel-mode driver installed at the top of the kernel-mode device stack (WUDFRd.sys). The reflector redirects IRPs received from the I/O manager to the client driver host process. Upon receiving the request, the framework and the client driver handle the request.
• Host process —the process in which the user-mode driver runs (Wudfhost.exe). It also hosts the framework and the I/O dispatcher.
• Client driver—the user-mode function driver for the USB device.
• UMDF—the framework module that handles most interactions with Windows on the behalf of the client driver. It exposes the user-mode device driver interfaces (DDIs) that the client driver can use to perform common driver tasks.
• Dispatcher—mechanism that runs in the host process; determines how to forward a request to the kernel mode after it has been processed by user-mode drivers and has reached the bottom of the user-mode stack. In the illustration, the dispatcher forwards the request to the user-mode DLL, Winusb.dll.
• Winusb.dll—a Microsoft-provided user-mode DLL that exposes WinUSB Functions that simplify the communication process between the client driver and WinUSB (Winusb.sys, loaded in kernel mode).
• Winusb.sys—a Microsoft-provided driver that is required by all UMDF client drivers for USB devices. The driver must be installed below the reflector and acts as the gateway to the USB driver stack in the kernel-mode. For more information, see WinUSB.
• USB driver stack—a set of drivers, provided by Microsoft, that handle protocol-level communication with the USB device. For more information, see USB host-side drivers in Windows.

Whenever an application makes a request for the USB driver stack, the Windows I/O manager sends the request to the reflector, which directs it to client driver in user mode. The client driver handles the request by calling specific UMDF methods, which internally call WinUSB Functions to send the request to WinUSB. Upon receiving the request, WinUSB either processes the request or forwards it to the USB driver stack.