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.

Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio

This feature is not available in WindowsВ 10, version 1507 and later versions of the WDK.

You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a USB 2.0 cable. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see Debugging Using Visual Studio.

As an alternative to using Visual Studio to set up USB 2.0 debugging, you can do the setup manually. For more information, see Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually.

The computer that runs the debugger is called the host computer, and the computer that is being debugged is called the target computer.

Debugging over a USB 2.0 connection requires the following hardware:

A Universal Serial Bus (USB) 2.0 debug cable. This cable is not a standard USB 2.0 cable, because it has an extra hardware component that makes it compatible with the USB2 Debug Device Functional Specification. You can find these cables by doing an Internet search for «USB 2.0 debug cable».

On the host computer, an EHCI (USB 2.0) host controller

On the target computer, an EHCI (USB 2.0) host controller that supports debugging

Identifying a Debug Port on the Target Computer

On the target computer, launch the UsbView tool. The UsbView tool is included in Debugging Tools for Windows.

In UsbView, locate all of the host controllers that are compatible with the EHCI specification. For example, you could look for controllers that are listed as Enhanced.

In UsbView, expand the nodes of the EHCI host controllers. Look for an indication that a host controller supports debugging, and look for the number of the debug port. For example, UsbView displays this output for an EHCI host controller that supports debugging on port 1.

NoteВ В Many EHCI host controllers support debugging on port 1, but some EHCI host controllers support debugging on port 2.

Make a note of the bus, device, and function numbers for the EHCI controller that you intend to use for debugging. UsbView displays these number. In the preceding example, the bus number is 0, the device number is 29, and the function number is 7.

After you have identified the EHCI controller and the port number that supports debugging, the next step is to locate the physical USB connector that is associated with the correct port number. To find the physical connector, plug any USB 2.0 device into any USB connector on the target computer. Refresh UsbView to see where your device is located. If UsbView shows your device connected to the EHCI host controller and port that you identified as the debug port, then you have found a physical USB connector that you can use for debugging. It could be that there is no external physical USB connector that is associated with a debug port on an EHCI controller. In that case, you can look for a physical USB connector inside the computer. Perform the same steps to determine whether the internal USB connector is suitable for kernel debugging. If you cannot find a physical USB connector (either external or internal) that is associated with a debug port, then you cannot use the computer as a target for debugging over a USB 2.0 cable.

NoteВ В See this remark for an exception.

Connecting the USB debug cable

1. Verify that the host computer is not configured to be the target of USB debugging. (If necessary, open a Command Prompt window as Administrator, enter bcdedit /debug off, and reboot.)
2. On the host computer, use UsbView to find the EHCI host controllers and ports that support debugging. If possible, plug one end of the USB 2.0 debug cable into an EHCI port (on the host computer) that does not support debugging. Otherwise, plug the cable into any EHCI port on the host computer.
3. Plug the other end of the USB 2.0 debug cable into the connector that you identified previously on the target computer.

Configuring the host and target computers

Begin configuring your host and target computers as described in Provision a computer for driver deployment and testing (WDK 8.1).

On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select Provision computer and choose debugger settings.

For Connection Type, choose USB.

For Target Name, enter a string to represent the target computer. This string does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions:

• The maximum length of the string is 24 characters.
• The only characters in the string are the hyphen (-), the underscore(_), the digits 0 through 9, and the letters A through Z (upper or lower case).

Enter the Bus Parameters value of b.d.f, where b, d, and f are the bus, device, and function numbers for the USB host controller that you intend to use for debugging on the target computer. The bus, device, and function numbers must be in decimal format (example: 0.29.7). These values are displayed in Device Manager under Location on the General tab for the USB host controller.

The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click Finish.

Verifying dbgsettings on the Target Computer

On the target computer, open a Command Prompt window as Administrator, and enter these commands:

bcdedit /dbgsettings

bcdedit /enum

Verify that debugtype is USB and targetname is the name you specified in Visual Studio on the host computer. You can ignore the values of debugport and baudrate; they do not apply to debugging over USB.

Verify that busparams matches the bus parameters you specified.

If you do not see the value you entered for Bus Parameters, enter this command:

bcdedit /set «» busparams b.d.f

where b, d, and f are the bus, device, and function numbers of the EHCI controller on the target computer that you have chosen to use for debugging.

bcdedit /set «» busparams 0.29.7

Reboot the target computer.

Starting a Debugging Session for the First Time

1. Connect a USB 2.0 debug cable to the USB 2.0 ports that you have chosen for debugging on the host and target computers.
2. On the host computer, open Visual Studio as Administrator.
3. On the Tools menu, choose Attach to Process.
4. For Transport, choose Windows Kernel Mode Debugger.
5. For Qualifier, select the name of the target computer that you previously configured.
6. Click Attach.

At this point, the USB debug driver gets installed on the host computer. This is why it is important to run Visual Studio as Administrator. After the USB debug driver is installed, you do not need to run as Administrator for subsequent debugging sessions.

Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio

This feature is not available in WindowsВ 10, version 1507 and later versions of the WDK.

You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over an Ethernet network. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see Debugging Using Visual Studio.

As an alternative to using Visual Studio to set up Ethernet debugging, you can do the setup automatically. For more information, see Setting Up KDNET Network Kernel Debugging Automatically.

Debugging over an Ethernet network has the following advantages compared to debugging over other types of cable:

• The host and target computers can be anywhere on the local network.
• It is easy to debug many target computers from one host computer.
• Network cable is inexpensive and readily available.
• Given any two computers, it is likely that they will both have Ethernet adapters. It is less likely that they will both have serial ports or both have 1394 ports.

The computer that runs the debugger is called the host computer, and the computer that is being debugged is called the target computer. The host computer must be running WindowsВ XP or later, and the target computer must be running WindowsВ 8 or later.

Supported network adapters

The host computer can use any wired or wireless network adapter, but the target computer must use a network adapter that is supported by Debugging Tools for Windows. For a list of supported network adapters, see Supported Ethernet NICs for Network Kernel Debugging in WindowsВ 8.1 and Supported Ethernet NICs for Network Kernel Debugging in WindowsВ 10.

Configuring the host and target computer

Connect the network adapter of the target computer to a network hub or switch using and appropriate network cable. Connect the network adapter of the host computer to a network hub or switch using a standard cable or a wireless connection.

Begin configuring your host and target computers as described in Provision a computer for driver deployment and testing (WDK 8.1).

On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select Provision computer and choose debugger settings.

For Connection Type, choose Network.

For Port Number, accept the default value or fill in a value of your choice. You can choose any number from 49152 through 65535. The port that you choose will be opened for exclusive access by the debugger running on the host computer. Take care to choose a port number that is not used by any other applications that run on the host computer.

NoteВ В The range of port numbers that can be used for network debugging might be limited by your company’s network policy. There is no way to tell from the host computer what the limitations are. To determine whether your company’s policy limits the range of ports that can be used for network debugging, check with your network administrators.

For Key, we strongly recommend that you use the automatically generated default value. However, you can enter your own key if you prefer. For more information, see Creating your own key later in this topic. For Host IP, accept the default value. This is the IP address of your host computer.

Use Device Manager on the target computer to determine the PCI bus, device, and function numbers for the adapter you want to use for debugging. For Bus Parameters, enter b.d.f where b, d, and f are the bus number, device number, and function number of the adapter. These values are displayed in Device Manager under Location on the General tab.

The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click Finish.

CautionВ В If your target computer is in a docking station, and you have network debugging enabled for a network adapter that is part of the docking station, do not remove the computer from the docking station. If you need to remove the target computer from the docking station, disable kernel debugging first. To disable kernel debugging on the target computer, open a Command Prompt window as Administrator and enter the command bcdedit /debug off. Reboot the target computer.

NoteВ В If you intend to install the Hyper-V role on the target computer, see Setting Up Network Debugging of a Virtual Machine Host.

Verifying dbgsettings on the Target Computer

Before using BCDEdit to change boot information you may need to temporarily suspend Windows security features such as BitLocker and Secure Boot on the test PC. Re-enable these security features when testing is complete and appropriately manage the test PC, when the security features are disabled.

On the target computer, open a Command Prompt window as Administrator, and enter these commands:

bcdedit /dbgsettings

bcdedit /enum

Verify that debugtype is NET and port is the port number you specified in Visual Studio on the host computer. Also verify that key is the key that was automatically generated (or you specified) in Visual Studio.

Verify that busparams matches the bus parameters you specified.

If you do not see the value you entered for Bus Parameters, enter this command:

bcdedit /set «» busparams b.d.f

where b, d, and f are the bus, device, and function numbers of the network adapter on the target computer that you have chosen to use for debugging. These values are displayed in device manager under Location on the General tab.

bcdedit /set «» busparams 0.29.7

Starting the Debugging Session

1. On the host computer, in Visual Studio, on the Tools menu, choose Attach to Process.
2. For Transport, choose Windows Kernel Mode Debugger.
3. For Qualifier, select the name of the target computer that you previously configured.
4. Click Attach.

Allowing the debugger through the firewall

When you first attempt to establish a network debugging connection, you might be prompted to allow the debugging application (Microsoft Visual Studio) through the firewall. Client versions of Windows display the prompt, but Server versions of Windows do not display the prompt. Respond to the prompt by checking the boxes for all three network types: domain, private, and public. If you do not get the prompt, or if you did not check the boxes when the prompt was available, you must use Control Panel to allow access through the firewall. Open Control Panel > System and Security, and click Allow an app through Windows Firewall. In the list of applications, use the check boxes to allow Visual Studio through the firewall. Restart Visual Studio.

Creating Your Own Key

To keep the target computer secure, packets that travel between the host and target computers must be encrypted. We strongly recommend that you use an automatically generated encryption key (provided by the Visual Studio configuration wizard) when you configure the target computer). However, you can choose to create your own key. Network debugging uses a 256-bit key that is specified as four 64-bit values, in base 36, separated by periods. Each 64-bit value is specified by using up to 13 characters. Valid characters are the letters a through z and the digits 0 through 9. Special characters are not allowed. The following list gives examples of valid (although not strong) keys:

Troubleshooting Tips for Debugging over a Network Cable

Debugging application must be allowed through firewall

Your debugger (WinDbg or KD) must have access through the firewall. You can use Control Panel to allow access through the firewall. Open Control Panel > System and Security, and click Allow an app through Windows Firewall. In the list of applications, use the check boxes to allow Visual Studio through the firewall. Restart Visual Studio.

Port number must be in range allowed by network policy

The range of port numbers that can be used for network debugging might be limited by your company’s network policy. To determine whether your company’s policy limits the range of ports that can be used for network debugging, check with your network administrator.

Use the following procedure if you need to change the port number.

1. On the host computer, in Visual Studio, on the Driver menu, choose Test > Configure Computers.
2. Select the name of your test computer, and click Next.
3. Select Provision computer and choose debugger settings. Click Next.
4. For Port Number, enter a number that is in the range allowed by your network administrator. Click Next.
5. The reconfiguration process takes a few minutes and automatically reboots the target computer. When the process is complete, click Next and Finish.

Specify busparams

You must specify the bus, device, and function numbers of the network adapter that you intend to use for debugging. To specify the bus parameters, open Device Manager, and locate the network adapter that you want to use for debugging. Open the property page for the network adapter, and make a note of the bus number, device number, and function number displayed under Location on the General tab. In an elevated Command Prompt Window, enter the following command, where b, d, and f are the bus, device and function numbers in decimal format:

bcdedit -set «» busparams b.d.f