Getting Started with Windows Drivers

Starting at some point after Windows 10, version 2004, drivers that run on Windows will be classified as either Windows Drivers or Windows Desktop Drivers.

Windows Drivers will run on all Window 10 variants, including Windows 10X and Windows 10 Desktop editions. Windows Desktop Drivers will only run on Windows 10 Desktop editions.

The Windows Driver classification will extend and replace the current Universal Driver classification.

This page provides a preview of the upcoming requirements for Windows Drivers.

The distinction between Windows Drivers and Windows Desktop Drivers does not affect any driver being submitted and certified for Windows 10 Version 2004. Changes in certification and submission will happen at a later date.

Windows Drivers Requirements

When Windows Drivers become a certification option, the following requirements will apply:

• Compliant with DCH Design Principles.
• Follow the principles of Driver Package Isolation.
• Follow API Layering Requirements.
• Certified with Windows Hardware Compatibility Program Certification Process using the Hardware Lab Kit. Note that the Windows Hardware Compatibility Program Certification Process requirements apply to both KMDF and UMDF drivers.

Windows Drivers vs. Windows Desktop Drivers

The following table summarizes the distinctions above:

Feature	Windows Drivers	Windows Desktop Drivers
Run on Windows 10 Desktop	Yes	Yes
Run on Windows 10X	Yes	No
Must be certified with WHCP	Yes	No
WDK & HLK are primary vehicles for developing and certifying drivers	Yes	Yes
Adhere to stricter reliability and serviceability requirements (e.g. driver package isolation)	Yes	No

While it won’t be required for a driver running only on Windows 10 Desktop to meet the additional requirements for a Windows Driver, doing so will enhance driver serviceability and reliability, as well as preparing the driver for possible future certification on Windows 10X.

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.

Building a Windows driver

You can use Microsoft Visual StudioВ 2019 in conjunction with the Windows Driver Kit (WDK) Version 2004 to build Windows Drivers. You can download kits and tools from the Windows Hardware Dev Center.

In many cases, you can recompile a legacy kernel-mode driver as a Windows Driver, as long as the driver does not work with any user-mode components. Legacy WDM and KMDF drivers should recompile as Windows Drivers targeting WindowsВ 10 with no conversion required. While the drivers may compile without any conversion, this does not mean that the driver meets all of the Windows Drivers requirements. Please see Getting Started with Windows Drivers for details regarding Windows Drivers requirements.

In contrast, existing user-mode drivers may require modification to compile as Windows drivers. Specifically, your driver package must not have any dependencies outside of UWP. For example, only some of the Win32 APIs are part of UWP.

Converting an existing driver project to a Windows driver project

1. In Visual StudioВ 2019, open the existing driver project.
2. In the Solution Explorer pane, select and hold (or right-click) the solution and choose Configuration Manager. Set the target operating system to WindowsВ 10.
3. Select and hold (or right-click) the driver project and choose Properties. Under Configuration Properties->Driver, verify that Target Platform is set to Windows Drivers. To build a driver that runs on WindowsВ 10 for Desktop editions only, select Desktop.
4. Build the driver. You might see linker errors.
5. Fix the errors one by one by going through the error log. Refer to individual reference pages in the documentation for possible alternate APIs. If replacements are not available, you may need to redesign your driver.

Creating a New Windows Driver Project in Microsoft Visual Studio

Create a new driver from a template (File->New Project->Create New Project->Project Type->Driver->Select the template of interest).

After you create the project, in the Solution Explorer pane, select and hold (or right-click) the solution and choose Configuration Manager. Set Active solution configuration to the desired target Windows version, and set Active solution platform to Win32 or x64. If ARM is not listed, choose to build for ARM.

If you choose WindowsВ 10, the driver model defaults to Universal.

To change driver model manually, select and hold (or right-click) the driver project and choose Properties. Under Configuration Properties->Driver Settings->General, find the Target Platform entry. Choose Windows Driver. Microsoft Visual Studio uses this setting to determine what libraries to link against.

NoteВ В You cannot build a Windows Driver for Windows versions earlier than WindowsВ 10 Version 1809.

You might need to modify the .inf file to specify the provider, specified as an %ManufacturerName% token that is expanded later in the INF file’s Strings section. For example:

You can now build the solution. Visual Studio links against the required libraries and generates a .cat file, an .inf file, and a driver binary.

Creating a New Universal Application or DLL Project in Microsoft Visual Studio

1. Create a new driver from a template (File->New Project->Create New Project->Project Type->Driver->Select the template of interest) and choose Empty Desktop Application for Drivers (Universal) or Empty Dll for Drivers (Universal).
2. After you create the project, in the Solution Explorer pane, select and hold (or right-click) the solution and choose Configuration Manager. Set Active solution configuration to the desired target Windows version, and set Active solution platform to Win32 or x64. If ARM is not listed, choose to build for ARM. If you choose Windows 10, the application model defaults to Universal. To change the target platform manually, select and hold (or right-click) the driver project and choose Properties. Under Configuration Properties->Driver Settings->General, find the Target Platform entry.
3. Build the solution.

For information about the configuration settings you can use in Visual Studio when building your driver, see Building a Driver with the WDK.

Using Visual Studio or MSBuild to build a driver

This topic describes how you can build a driver using the Visual Studio development environment, or from the command line by using the Microsoft Build Engine (MSBuild).

ImportantВ В Starting in Windows Driver Kit (WDK)В 8, MSBuild replaced the Windows Build Utility (Build.exe). The WDK now uses the same compiler and build tools that you use to build Visual Studio projects. Driver projects that were built with previous versions of the WDK must be converted to work in the Visual Studio environment. You can run a conversion utility from the command line, or you can convert an existing driver by creating new Visual Studio project from existing sources. For more info, see Creating a Driver From Existing Source Files and WDK and the Visual Studio build environment.

Building a Driver Using Visual Studio

You build a driver the same way you build any project or solution in Visual Studio. When you create a new driver project using a Windows driver template, the template defines a default (active) project configuration and a default (active) solution build configuration.

NoteВ В You can convert projects and solutions that you created with WDKВ 8 or Windows Driver Kit (WDK)В 8.1 to work with Windows Driver Kit (WDK)В 10 and Visual StudioВ 2019. Before you open the projects or solutions, run the ProjectUpgradeTool. The ProjectUpgradeTool converts the projects and solutions so that they can be built using WDKВ 10.

For information about managing and editing build configurations, see Building in Visual Studio.

The default Solution build configuration is Debug and Win32.

To select a configuration and build a driver

1. Ensure that you have the same version of SDK and WDK installed on your computer.
2. Open the driver project or solution in Visual Studio.
3. Select and hold (or right-click) the solution in the Solutions Explorer and select Configuration Manager.
4. From the Configuration Manager, select the Active solution configuration (for example, Debug or Release) and the Active solution platform (for example, Win32) that correspond to the type of build you are interested in.
5. Select and hold (or right-click) the Avshws project and select Properties. Navigate to Driver Settings > General, and set Target OS Version and Target Platform.
6. Configure the project properties for your driver or driver package. You can set properties for deployment, driver signing, or other tasks. For more information, see Configuring project properties for your driver and driver package.
7. From the Build menu, select Build Solution (Ctrl+Shift+B).

Building a Driver Using the Command Line (MSBuild)

You can build a driver from the command line using the Visual Studio Command Prompt window and the Microsoft Build Engine (MSBuild)

To build a driver using the Visual Studio Command Prompt window

Open a Developer Command Prompt for VS2019 window.

From this window you can use MSBuild.exe to build any Visual Studio project by specifying the project (.VcxProj) or solutions (.Sln) file.

Navigate to the project directory and enter the MSbuild command for your target.

For example, to perform a clean build of a Visual Studio driver project called MyDriver.vcxproj using the default Platform and Configuration, navigate to the project directory and enter the following MSBuild command:

Syntax — To specify a specific configuration and platform, use the following command syntax:

For example, the following command builds a driver for the «Debug» configuration, «Win32» platform, and for WindowsВ 10.

The TargetPlatformVersion setting is optional and allows you to specify the kit version to build with. The default is to use the latest kit.

Configuring project properties for your driver and driver package

You use property pages to configure and set options for your driver and driver package. You can choose to configure your driver so that it is automatically signed when you build your solution, or automatically deployed to a remote test computer.

The WDK provides a number of command-line tools, such as Stampinf and WPP Preprocessor (WPP Tracing), that are commonly included in the build process. These tools are not distributed with Visual Studio. To combine these tools with the Visual Studio build environment they are wrapped as WDK tasks for MSBuild. If you use one of the driver templates or have an existing driver that you have converted, these property pages might already exist for your project. If not, the property pages are automatically added to your project as you add the related file types to the project or solution (for example, .mc or .man files for the message compiler). For more information, see WDK and the Visual Studio build environment

You can set properties for an individual driver or for an entire driver package. The following table shows some of the available properties that you can configure specifically for drivers and driver packages.

Signing properties for individual driver files (see Signing a Driver)

Signing properties for driver packages (see Signing a Driver)

Troubleshooting tip for building a driver

The following tip can help you troubleshoot problems when you use the WDK and Visual Studio to build drivers.

To increase the verbosity of the build output using the options in Visual Studio

1. Select Tools>Options.
2. Select the Project and Solutions folder and select Build and Run.
3. Change the options for the MSBuild project build output verbosity and MSBuild project build log file verbosity. By default, these are set to Minimal.

Driver Project Properties	Driver Package Properties