Debugging Using Visual Studio

Starting with Windows Driver Kit (WDK)В 8, the driver development environment and the Windows debuggers are integrated into Microsoft Visual Studio. In this integrated environment, most of the tools you need for coding, building, packaging, testing, debugging, and deploying a driver are available in the Visual Studio user interface.

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

To get the integrated environment, first install Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see Download the Windows Driver Kit (WDK).

Typically kernel-mode debugging requires two computers. The debugger runs on the host computer, and the code being debugged runs on the target computer. The target computer is also called the test computer. You can do user-mode debugging on a single computer, but in some cases you might want to debug a user-mode process that is running on a separate target computer.

In the Visual Studio environment, you can configure target computers for kernel-mode and user-mode debugging. You can establish a kernel-mode debugging session. You can attach to a user-mode process or launch and debug a user mode process on the host computer or a target computer. You can analyze dump files. In Visual Studio you can sign, deploy, install, and load a driver on a target computer.

These topics show you how to use Visual Studio to perform several of the tasks involved in debugging a driver.

Windows Debugger (WinDbg)

Debug your Windows 10 IoT Core device using the powerful Windows debugger, WinDbg.

The following sections describe how to successfully connect with WinDbg to a Windows 10 IoT Core device for debugging purposes. This includes a description of the necessary software settings on the device as well as the physical hardware connections.

WinDbg is a very powerful debugger that most Windows developers are familiar with. However, if you are just getting started and would like to learn more about WinDbg, please visit the following links:

MinnowBoard Max (MBM)

You can connect WinDbg to the MinnowBoard Max device using a network connection.

Setup network connection

In order to enable kernel debugging with WinDbg over a network, ensure that:

An Ethernet cable is connected to MinnowBoard Max device to your network

The MinnowBoard Max device has a valid IP address in your network

An active connection to the MinnowBoard Max device via PowerShell

Using the active PowerShell connection, execute the following commands on the MinnowBoard Max to enable debugging over the network.

bcdedit -dbgsettings net hostip: port:

This command enables debugging over the network. Additionally, it specifies the IP address of the PC where WinDbg will be running (DEV_PC_IP_ADDRESS), the network port number to use for the connection (PORT_NUM), and a unique key to be used to differentiate multiple connections (KEY)

For PORT_NUM and KEY, you can use the following values as examples: 50045 and 1.2.3.4 respectively, although you are free to change them as you see fit

bcdedit -debug on

• This command turns on debugging on the device

On the developer PC, start WinDbg with the PORT_NUM and the KEY values provided in the previous steps as follows: «c:\Program Files (x86)\Debugging Tools for Windows (x86)\windbg.exe» -k net:port=

If you have any of the Windows kits installed, you may find WinDbg under C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\WinDbg.exe

• Reboot the IoTCore device to reconnect to the debugger

Raspberry Pi 2 or 3 (RPi2 or RPi3)

You can connect WinDbg to the Raspberry Pi 2 or 3 using a serial connection.

Setup serial connection

In order to enable kernel debugging with WinDbg over a serial connection, ensure that:

You have a debug cable such as the USB-to-TTL Serial Cable from Adafruit or FTDI.

An Ethernet cable or active WiFi connecting your Raspberry Pi 2 or 3 device to your network (for IP connections like SSH or PowerShell)

The Raspberry Pi 2 or 3 device has a valid IP address in your network

An active connection to the Raspberry Pi 2 or 3 device via PowerShell or SSH

UART0 will be used on the Raspberry Pi 2 or 3 device for the kernel debugging connection. The following shows the pin mappings for the Raspberry Pi 2 or 3 as well as the serial cables:

The basic idea for making the correct serial connections is to remember that while one device uses its TX to transmit data, the other device uses its RX to receive the data. Recommended connections are listed below:

The EFIESP junction is no longer created. You’ll have to mount it yourself,you can use mountvol command to get the GUID. mkdir C:\EFIESP mountvol C:\EFIESP \?\Volume

Using the active PowerShell connection, execute the following commands on the Raspberry Pi 2 or 3 device to enable debugging over the serial connection.

bcdedit /store c:\EFIESP\EFI\Microsoft\Boot\BCD -dbgsettings serial

• The above command enables the serial connection for debugging
• The baud-rate for the Raspberry Pi 2 or 3 is hard-coded to 921600, so you don’t have to specify it

bcdedit /store c:\EFIESP\EFI\Microsoft\Boot\BCD -debug on

• This command turns on debugging on the device

On the developer PC, get the COM port number PORT assigned in the system for the USB-to-TTL cable. This will be available in Device Manager under «Ports (COM & LPT)».

«C:\Program Files (x86)\Debugging Tools for Windows (x86)\windbg.exe» -k com:port=

• Start WinDbg with the PORT number

If you have any of the Windows kits installed, you may find WinDbg under C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\WinDbg.exe

• Reboot the IoTCore device to reconnect to the debugger

DragonBoard (DB)

You can connect WinDbg to the DragonBoard using a serial or USB connection.

Using the active PowerShell or SSH connection to your DragonBoard, execute the following commands to enable debugging.

• bcdedit /store c:\EFIESP\EFI\Microsoft\Boot\BCD /debug ON
  • Enables the debugger

Setup USB connection

By default the USB debugger settings are configured in the test images.

Once USB kernel debugger is on, USB ports on the DragonBoard device might not work (i.e. keyboard, usb ethernet might not work).

Setup serial connection

bcdedit /store c:\EFIESP\EFI\Microsoft\Boot\BCD /dbgsettings Serial debugport:1 baudrate:115200

• Configures the serial port

Reboot the IoTCore device to reconnect to the debugger

Debugging Environments

There are six available debugging environments:

• WinDbg Preview
• Windows Debugger (WinDbg)
• Kernel Debugger (KD)
• NTKD
• Console Debugger (CDB)
• NT Symbolic Debugger (NTSD)

The following sections describe the debugging environments.

WinDbg Preview

WinDbg Preview is the latest version of WinDbg with more modern visuals, faster windows, a full-fledged scripting experience, built with the extensible debugger data model front and center. WinDbg Preview is using the same underlying engine as WinDbg today, so all the commands, extensions, and workflows you’re used to will still work as they did before.

WinDbg

Microsoft Windows Debugger (WinDbg) is a Windows-based debugger that is capable of both user-mode and kernel-mode debugging. WinDbg provides debugging for the Windows kernel, kernel-mode drivers, and system services, as well as user-mode applications and drivers.

WinDbg uses the Visual Studio debug symbol formats for source-level debugging. It can access any symbol or variable from a module that has PDB symbol files, and can access any public function’s name that is exposed by modules that were compiled with COFF symbol files (such as Windows .dbg files).

WinDbg can view source code, set breakpoints, view variables (including C++ objects), stack traces, and memory. Its Debugger Command window allows the user to issue a wide variety of commands.

For kernel-mode debugging, WinDbg typically requires two computers (the host computer and the target computer). WinDbg also supports various remote debugging options for both user-mode and kernel-mode targets.

WinDbg is a graphical-interface counterpart to CDB/NTSD and to KD/NTKD.

Microsoft Kernel Debugger (KD) is a character-based console program that enables in-depth analysis of kernel-mode activity on all NT-based operating systems. You can use KD to debug kernel-mode components and drivers, or to monitor the behavior of the operating system itself. KD also supports multiprocessor debugging.

Typically, KD does not run on the computer being debugged. You need two computers (the host computer and the target computer) for kernel-mode debugging.

There is a variation of the KD debugger named NTKD. It is identical to KD in every way, except that it spawns a new text window when it is started, whereas KD inherits the Command Prompt window from which it was invoked.

Microsoft Console Debugger (CDB) is a character-based console program that enables low-level analysis of Windows user-mode memory and constructs. The name Console Debugger is used to indicate the fact that CDB is classified as a console application; it does not imply that the target application must be a console application. In fact, CDB is fully capable of debugging both console applications and graphical Windows programs.

CDB is extremely powerful for debugging a program that is currently running or has recently crashed (live analysis), yet simple to set up. It can be used to investigate the behavior of a working application. In the case of a failing application, CDB can be used to obtain a stack trace or to look at the guilty parameters. It works well across a network (using a remote access server), as it is character-based.

With CDB, you can display and execute program code, set breakpoints, and examine and change values in memory. CDB can analyze binary code by disassembling it and displaying assembly instructions. It can also analyze source code directly.

Because CDB can access memory locations through addresses or global symbols, you can refer to data and instructions by name rather than by address, making it easy to locate and debug specific sections of code. CDB supports debugging multiple threads and processes. It is extensible, and can read and write both paged and non-paged memory.

If the target application is itself a console application, the target will share the console window with CDB. To spawn a separate console window for a target console application, use the -2 command-line option.

There is a variation of the CDB debugger named Microsoft NT Symbolic Debugger (NTSD). It is identical to CDB in every way, except that it spawns a new text window when it is started, whereas CDB inherits the Command Prompt window from which it was invoked.

Since the start command can also be used to spawn a new console window, the following two constructions will give the same results:

It is possible to redirect the input and output from NTSD (or CDB) so that it can be controlled from a kernel debugger (either Visual Studio, WinDbg, or KD). If this technique is used with NTSD, no console window will appear at all. Controlling NTSD from the kernel debugger is therefore especially useful, since it results in an extremely light-weight debugger that places almost no burden on the computer containing the target application. This combination can be used to debug system processes, shutdown, and the later stages of boot up. See Controlling the User-Mode Debugger from the Kernel Debugger for details.

Download Debugging Tools for Windows

The Windows Debugger (WinDbg) can be used to debug kernel-mode and user-mode code, analyze crash dumps, and examine the CPU registers while the code executes.

To get started with Windows debugging, see Getting Started with Windows Debugging.

Download WinDbg Preview

WinDbg Preview is a new version of WinDbg with more modern visuals, faster windows, and a full-fledged scripting experience. It is built with the extensible object-orientated debugger data model front and center. WinDbg Preview is using the same underlying engine as WinDbg today, so all the commands, extensions, and workflows still work as they did before.

Download WinDbg Preview from the Microsoft Store: WinDbg Preview.

Learn more about installation and configuration in WinDbg Preview — Installation.

Debugging Tools for Windows 10 (WinDbg)

Get Debugging Tools for Windows (WinDbg) from the SDK: Windows 10 SDK. Use the download link on the Windows 10 SDK page, as the Debugging Tools for Windows are not available as part of Visual Studio.

If you just need the Debugging Tools for Windows, and not the Windows Driver Kit (WDK) for Windows 10, you can install the debugging tools as a standalone component from the Windows Software Development Kit (SDK).

In the SDK installation wizard, select Debugging Tools for Windows, and deselect all other components.

Adding the Debugging Tools for Windows if the SDK is already installed

If the Windows SDK is already installed, open Settings, navigate to Apps & features, select Windows Software Development Kit, and then select Modify to change the installation to add Debugging Tools for Windows.

Looking for the debugging tools for earlier versions of Windows?

To download the debugger tools for previous versions of Windows, you need to download the Windows SDK for the version you are debugging from the Windows SDK and emulator archive. In the installation wizard of the SDK, select Debugging Tools for Windows, and deselect all other components.

Learn more about the debuggers

Learn more about WinDbg and other debuggers in Debugging Tools for Windows (WinDbg, KD, CDB, NTSD).

Debugging Tools for Windows: New for Windows 10

Windbg Preview

For the lastest news on Windows Debugging tools, see WinDbg Preview — What’s New.

WindowsВ 10, version 1703

This section describes new debugging tools in WindowsВ 10, version 1703.

WindowsВ 10, version 1607

This section describes new debugging tools in WindowsВ 10, version 1607.

• New topic about Debugging a UWP app using WinDbg.
• Updates to the 30 most-viewed developer bug check topics in Bug Check Code Reference.

WindowsВ 10

• .settings (Set Debug Settings) — New command that allows you to set, modify, display, load and save settings in the Debugger.Settings namespace.
• dx (Display NatVis Expression) — Describes the new dx debugger command, which displays object information using the NatVis extension model and LINQ support.
• New commands that work with the NatVis visualization files in the debugger environment.
  • .nvlist (NatVis List)
  • .nvload (NatVis Load)
  • .nvunload (NatVis Unload)
  • .nvunloadall (NatVis Unload All)
• Bluetooth Extensions (Bthkd.dll)
• Storage Kernel Debugger Extensions
• New Symproxy information including SymProxy Automated Installation. In addition the following topics are updated to cover new SymProxy functionality:
  • HTTP Symbol Stores
  • SymProxy
  • Installing SymProxy
  • Configuring the Registry
  • Configuring IIS for SymProxy
• CDB Command-Line Options — Updated to include new command line options.
• !analyze — Updated to include information about using this extension with UMDF 2.15.
• !wdfkd.wdfcrashdump— Updated to include information about using this extension with UMDF 2.15
• !irp — Updated. Starting with Windows 10 the IRP major and minor code text is displayed in command output.
• Using Debugger Markup Language — Updated to describe new select-and-hold (or right-click) behavior available in the Debugger Markup Language (DML).
• Crash dump analysis using the Windows debuggers (WinDbg) — Performance has increased in taking a memory dump over KDNET.
• Debug Universal Drivers — Step by Step Lab (Echo Kernel-Mode)- New step by step lab that shows how to use WinDbg to debug the sample KMDF echo driver.

Looking to download the Debugging Tools?

For information on downloading the debugging tools, see Download Debugging Tools for Windows.