Overview of developing Windows drivers for emulated USB devices (UDE)

Purpose

This section describes USB emulated device (UDE) support in the Windows operating system, for developing an emulated Universal Serial Bus (USB) host controller driver and a connected virtual USB device. Both components are combined into a single KMDF driver that communicates with the Microsoft-provided USB device emulation class extension (UdeCx).

Development tools and Microsoft-provided binaries

The Windows Driver Kit (WDK) contains resources that are required for driver development, such as headers, libraries, tools, and samples.

To write a function controller driver, you need:

• UdeCx: (udecx.sys) a WDF extension used by the function driver. This extension is included in Windows.
• Link to the stub library (Udecxstub.lib). The stub library is in the WDK.
• Include Udecx.h provided in the WDK.

Version history

KMDF version 1.15.

UMDF is not supported.

Architecture of UDE

Writing drivers for emulated host controller and devices

Familiarize yourself with UDE objects and handles. For details on WDF objects, see Introduction to Framework Objects.

Understand the behavior of UDE, how it interacts with the client driver, and the features that the client driver is expected to implement.

Programming reference sections

Creating a New Software Driver

In this topic we explain how to use Visual Studio to start writing a new software driver. Software drivers are different from device function drivers, filter drivers, and file system drivers, which we cover in other topics. For more information about software drivers and how they differ from other types of drivers, see What is a Driver? and Choosing a Driver Model.

To begin, first determine which driver model is appropriate for your software driver. The three options are the Kernel Mode Driver Framework (KMDF), the legacy NT driver model, and the Windows Driver Model (WDM). For help determining which model is best for you, see Choosing a Driver Model.

Case 1: You want to use KMDF

1. In Visual Studio, on the File menu, choose New | Project.
2. In the New Project dialog box, in the left pane, locate and select WDF.
3. In the middle pane, select Kernel Mode Driver (KMDF).
4. Fill in the Name and Location boxes, and select OK. For more details, see Writing a KMDF Driver Based on a Template.

When you create a new KMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h.

Case 2: You want to use the legacy NT model

In Visual Studio, on the File menu, choose New | Project.

In Visual Studio, in the New Project dialog box, under Windows Driver, select WDM | Empty WDM Driver.

You are not going to write a WDM driver, but you need the Empty WDM Driver template.

Fill in the Name and Location boxes, and select OK.

At this point, you have an empty WDM driver project. In the Solution Explorer window, select and hold (or right-click) your driver project, and choose Add | New Item.

In the Add New Item dialog box, select C++ File (.cpp), enter a name for your file, and select OK.

If you want to create a .c file instead of a .cpp file, enter a name that has the .c extension.

Implement the functions required by your software driver. As you implement and organize your functions, you might decide to add header files and additional .cpp or .c files.

Case 3: You want to use WDM

It is extremely unlikely that you’ll want to use WDM for a software driver. But if you do, follow these steps.

In Visual Studio, on the File menu, choose New | Project.

In Visual Studio, in the New Project dialog box, under Windows Driver, select WDM.

Fill in the Name and Location boxes, and select OK.

At this point, you have an empty WDM driver project. In the Solution Explorer window, select and hold (or right-click) your driver project, and choose Add | New Item.

In the Add New Item dialog box, select C++ File (.cpp), enter a name for your file, and select OK.

If you want to create a .c file instead of a .cpp file, enter a name that has the .c extension.

Implement the functions required by your software driver. As you implement and organize your functions, you might decide to add header files and additional .cpp or .c files.

Developing, Testing, and Deploying Drivers

The Windows driver development environment and the Windows debuggers are integrated into Microsoft Visual Studio. In this integrated driver development environment, most of the tools you need for coding, building, packaging, deploying, and testing a driver are available in the Visual Studio user interface.

To set up the integrated development environment, first install Visual Studio and then install the WDK. You can find information about how to get Visual Studio and the WDK on the WDK setup and download page. The Debugging Tools for Windows are included with the WDK installation.

The WDKВ uses MSBuild.exe, which is available both in the Visual Studio user interface and as a command-line tool. Drivers created in the Visual Studio environment use Project and Solution files to describe a project or group of projects. The Visual Studio environment provides a tool for converting legacy Sources and Dirs files to Project and Solution files.

The Visual Studio environment provides templates for:

• New drivers
• Driver packages
• New tests
• Enhancement of existing tests
• Custom driver deployment scripts

In the Visual Studio environment, you can configure the build process so that it automatically creates and signs a driver package. Static and run-time analysis tools are available in Visual Studio. You can configure a target computer for testing your driver and automatically deploy your driver to the target computer each time you rebuild. You can choose from an extensive set of run-time tests, and you can write your own tests.

The topics in this section show you how to use Visual Studio to perform several of the tasks involved in driver development, deployment, and testing.

Additional Videos

You’ll find videos on the following pages in the Windows driver docs:

Overview of developing Windows client drivers for USB devices

Purpose

This section describes Universal Serial Bus (USB) support in the Windows operating system, so that you can develop USB device drivers that are interoperable with Windows.

Where applicable

USB devices are peripherals, such as mouse devices and keyboards, that are connected to a computer through a single port. A USB client driver is the software installed on the computer that communicates with the hardware to make the device function. If the device belongs to a device class supported by Microsoft, Windows loads one of the Microsoft-provided USB drivers (in-box class drivers) for the device. Otherwise, a custom client driver must be provided by the hardware manufacturer or a third party vendor. The user installs the client driver for the device when the device is first detected by Windows. After successful installation, Windows loads the client driver every time the device is attached and unloads the driver when the device is detached from the host computer.

You can develop a custom client driver for a USB device by using the Windows Driver Frameworks (WDF) or the Windows Driver Model (WDM). Instead of communicating with the hardware directly, most client drivers send their requests to the Microsoft-provided USB driver stack that makes hardware abstraction layer (HAL) function calls to send the client driver’s request to the hardware. The topics in this section describe the typical requests that a client driver can send and the device driver interfaces (DDIs) that the client driver must call to create those requests.

Developer audience

A client driver for a USB device is a WDF or WDM driver that communicates with the device through DDIs exposed by the USB driver stack. This section is intended for use by C/C++ programmers who are familiar with WDM. Before you use this section, you should understand basic driver development. For more information, see Getting Started with Windows Drivers. For WDF drivers, the client driver can use Kernel-Mode Driver Framework (KMDF) or User-Mode Driver Framework (UMDF) interfaces designed specifically to work with USB targets. For more information about the USB-specific interfaces, see WDF USB Reference and UMDF USB I/O Target Interfaces.

Development tools

The Windows Driver Kit (WDK) contains resources that are required for driver development, such as headers, libraries, tools, and samples.

USB programming reference

Gives specifications for I/O requests, support routines, structures, and interfaces used by USB client drivers. Those routines and related data structures are defined in the WDK headers.

USB driver samples

Use these samples to get started with USB client driver programming.

Related standards and specifications

You can download official USB specifications from the Universal Serial Bus Documents website. This website contains links to the Universal Serial Bus Revision 3.0 Specification and the Universal Serial Bus Revision 2.0 specification.

Documentation sections

Introduces you to USB driver development. Provides information about choosing the most appropriate model for providing a USB driver for your device. Write, build, and install your first skeleton user-mode and kernel-mode USB drivers by using the USB templates included with Microsoft Visual Studio.

Provides an overview of the USB driver stack architecture.

Learn how a client driver builds a variable-length data structure called a USB Request Block (URB) to submit requests to the USB driver stack.

Learn how a client driver builds a variable-length data structure called a USB Request Block (URB) to submit requests to the USB driver stack.

Device configuration refers to the tasks that the client driver performs to select a USB configuration and an alternate interface in each interface. The section shows the methods calls required to select a USB configuration.

Describes USB pipes, URBs for I/O requests, and how a client driver can use the device driver interfaces (DDIs) to transfer data to and from a USB device.

Download the Windows Driver Kit (WDK)

The WDK is used to develop, test, and deploy Windows drivers.

Runtime requirements

You can run the Windows 10, version 2004 WDK on Windows 7 and later, and use it to develop drivers for these operating systems:

Client OS	Server OS
Windows 10	Windows Server 2019, Windows Server 2016
Windows 8.1	Windows Server 2012 R2
Windows 8	Windows Server 2012
Windows 7	Windows Server 2008 R2 SP1

WDK for Windows 10, version 2004

Step 1: Install Visual Studio 2019

The WDK requires Visual Studio. For more information about system requirements for Visual Studio, see Visual Studio 2019 System Requirements.

The following editions of Visual Studio 2019 support driver development for this release:

When you install Visual Studio 2019, select the Desktop development with C++ workload. The Windows 10 Software Development Kit (SDK) is automatically included, and is displayed in the right-hand Summary pane. Note that the version of the SDK that is compatible with the WDK for Windows 10, version 2004 may not be the default SDK. To select the correct SDK:

In Visual Studio Installer, on the Individual components tab, search for Windows 10 SDK (10.0.19041.0), select this version and continue with install. Note that Visual Studio will automatically install Windows 10 SDK (10.0.19041.1) on your machine.

If you already have Visual Studio 2019 installed, you can install the Windows 10 SDK (10.0.19041.1) by using the Modify button in Visual Studio install.

WDK has Spectre mitigation enabled by default but requires spectre mitigated libraries to be installed with Visual Studio for each architecture you are developing for. Additionally, developing drivers for ARM/ARM64 require the build tools for these architectures to also be installed with Visual Studio. To locate these items you will need to know the latest version of MSVC installed on your system.

To find the latest version of MSVC installed on your system, in Visual Studio Installer go to workload page, on the right pane under installation details, expand Desktop development with C++ and locate the MSVC v142 — VS 2019 C++ x64/x86 build tools (V14.xx) — note where xx should be the highest version available.

With this information (v14.xx), go to Individual components and search for v14.xx. This will return the tool sets for all architectures, including Spectre mitigated libs. Select the driver architecture you are developing for.

For example, searching for v14.25 returns the following:

Step 1.5 Install Refreshed Windows SDK 10.0.19041.685 for Windows 10, version 2004

This SDK is strongly recommended and will eventually be made available through Visual Studio

Step 2: Install Refreshed WDK for Windows 10, version 2004

The WDK Visual Studio extension is included in the default WDK installation.

If you can’t find driver project templates in Visual Studio, the WDK Visual Studio extension didn’t install properly. To resolve this, run the WDK.vsix file from this location: C:\Program Files (x86)\Windows Kits\10\Vsix\VS2019\WDK.vsix.

Enterprise WDK (EWDK) for Windows 10, version 2004

The EWDK is a standalone, self-contained command-line environment for building drivers. It includes the Visual Studio Build Tools, the SDK, and the WDK. The latest public version of the EWDK contains Visual Studio 2019 Build Tools 16.7.0 and MSVC toolset v14.23. To get started, mount the ISO and run LaunchBuildEnv.

The EWDK also requires the .NET Framework version 4.7.2. For more information about other requirements for the .NET Framework, see .NET Framework system requirements.

EWDK with Visual Studio Build Tools

You can use the Visual Studio interface with the build tools provided in the EWDK.

1. Mount the EWDK ISO.
2. Run LaunchBuildEnv.cmd .
3. In the environment created in step 2, type SetupVSEnv, and then press Enter.
4. Launch devenv.exe from the same environment, using the full file path. Example: «C:\Program Files (x86)\Microsoft Visual Studio\2019\\%Community|Professional|Enterprise%\Common7\IDE\devenv.exe»

Note that the Visual Studio major version should match with the version in the EWDK. For example, Visual Studio 2019 works with the EWDK that contain VS16.X build tools.

Driver samples for Windows 10

To download the driver samples, do one of the following:

• Go to the driver samples page on GitHub, click Clone or download, and then click Download ZIP.
• Download the GitHub Extension for Visual Studio, and then connect to the GitHub repositories.
• Browse the driver samples on the Microsoft Samples portal.