Tools Included in Debugging Tools for Windows

Debugging Tools for Windows includes several tools in addition to the debugging engine and the Debugging Environments. The tools are in the installation directory of Debugging Tools for Windows.

DumpChk
Validate a memory dump file.

GFlags
Control registry keys and other settings.

Kill
Terminate a process.

Logger and LogViewer
Record and display function calls and other actions of a program.

PLMDebug
Use the Windows debugger to debug Windows app, which run under Process Lifecycle Management (PLM). With PLMDebug, you can take manual control of suspending, resuming, and terminating a Windows app.

Remote Tool
Remotely control any console program, including KD, CDB, and NTSD. See Remote Debugging Through Remote.exe.

TList
List all running processes.

UMDH
Analyze heap allocations.

USBView
Display USB host controllers and connected devices.

DbgRpc (Dbgrpc.exe)
Display Microsoft Remote Procedure Call (RPC) state information. See RPC Debugging and Using the DbgRpc Tool.

KDbgCtrl (Kernel Debugging Control, Kdbgctrl.exe)
Control and configure the kernel debugging connection. See Using KDbgCtrl.

SrcSrv
A source server that can be used to deliver source files while debugging.

SymSrv
A symbol server that the debugger can use to connect to a symbol store.

SymProxy
Create a single HTTP symbol server on your network that all your debuggers can point to. This has the benefit of pointing to multiple symbol servers (both internal and external) with a single symbol path, handling all authentication, and increasing performance via symbol caching. Symproxy.dll is in the SymProxy folder in the installation directory.

SymChk
Compare executable files to symbol files to verify that the correct symbols are available.

AgeStore
Removes old entries in the downstream store of a symbol server or a source server.

DBH
Display information about the contents of a symbol file.

PDBCopy
Remove private symbol information from a symbol file, and control which public symbols are included in the file.

DbgSrv
A process server used for remote debugging. See Process Servers (User Mode).

KdSrv
A KD connection server used for remote debugging.See KD Connection Servers (Kernel Mode).

DbEngPrx
A repeater (small proxy server) used for remote debugging. See Repeaters.

Breakin (Breakin.exe)
Causes a user-mode break to occur in a process. For help, open a Command Prompt window, navigate to the installation directory, and enter breakin /?.

List (File List Utility) (List.exe)
For help, open a Command Prompt window, navigate to the installation directory, and enter list /?.

RTList (Remote Task List Viewer) (Rtlist.exe)
List running processes via a DbgSrv process server. For help, open a Command Prompt window, navigate to the installation directory, and enter rtlist /?.

Installation Directory

The default installation directory for 64 bit OS installs for the debugging tools is C:\Program Files (x86)\Windows Kits\10\Debuggers\. If you have a 32-bit OS, you can find the Windows Kits folder under C:\Program Files. To determine if you should use the 32 bit or 64 bit tools, see Choosing the 32-Bit or 64-Bit Debugging Tools.

Getting Started with WinDbg (Kernel-Mode)

WinDbg is a kernel-mode and user-mode debugger that is included in Debugging Tools for Windows. Here we provide hands-on exercises that will help you get started using WinDbg as a kernel-mode debugger.

For information about how to get Debugging Tools for Windows, see Debugging Tools for Windows (WinDbg, KD, CDB, NTSD). After you have installed the debugging tools, locate the installation directories for 64-bit (x64) and 32-bit (x86) versions of the tools. For example:

• C:\Program Files (x86)\Windows Kits\10\Debuggers\x64
• C:\Program Files (x86)\Windows Kits\10\Debuggers\x86

Set up a kernel-mode debugging

A kernel-mode debugging environment typically has two computers: the host computer and the target computer. The debugger runs on the host computer, and the code being debugged runs on the target computer. The host and target are connected by a debug cable.

The Windows debuggers support these types of cables for debugging:

• Ethernet
• USB 2.0 / USB 3.0
• Serial (also called null modem)

For speed and reliablity, using Ethernet with a local network hub, is recommended. This diagram illustrates a host and target computer connected for debugging over Ethernet cable.

Another option for older versions of Windows is to use a direct cable such as USB or serial cable.

For details about how to set up the host and target computers, see Setting Up Kernel-Mode Debugging Manually.

Virtual Machine — VMs

For information on connecting a debugger to a Hyper-V virtual machine, see Setting Up Network Debugging of a Virtual Machine — KDNET.

Establish a kernel-mode debugging session

After you have set up your host and target computer and connected them with a debug cable, you can establish a kernel-mode debugging session by following the instructions in the same topic that you used for getting set up. For example, if you decided to set up your host and target computers for debugging over Ethernet, you can find instructions for establishing a kernel-mode debugging session is this topic:

Get started using WinDbg

On the host computer, open WinDbg and establish a kernel-mode debugging session with the target computer.

In WinDbg, choose Contents from the Help menu. This opens the debugger documentation CHM file. The debugger documentation is also available on line in Debugging Tools for Windows.

When you establish a kernel-mode debugging session, WinDbg might break in to the target computer automatically. If WinDbg has not already broken in, choose Break from the Debug menu.

Near the bottom of the WinDbg window, in the command line, enter this command:

The output is similar to this:

The symbol search path tells WinDbg where to look for symbol (PDB) files. The debugger needs symbol files to obtain information about code modules (function names, variable names, and the like).

Enter this command, which tells WinDbg to do its initial finding and loading of symbol files:

To see a list of loaded modules, enter this command:

The output is similar to this:

To start target computer running, enter this command:

To break in again, choose Break from the Debug menu.

Enter this command to examine the _FILE_OBJECT data type in the nt module:

The output is similar to this:

Enter this command to examine some of the symbols in the nt module:

The output is similar to this:

Enter this command to put a breakpoint at MmCreateProcessAddressSpace:

To verify that the breakpoint is set, enter this command:

The output is similar to this:

Enter g to let the target computer run.

If the target computer doesn’t break in to the debugger immediately, perform a few actions on the target computer (for example, open Notepad). The target computer will break in to the debugger when MmCreateProcessAddressSpace is called. To see the stack trace, enter these commands:

The output is similar to this:

On the View menu, choose Disassembly.

On the Debug menu, choose Step Over (or press F10). Enter step commands a few more times as you watch the Disassembly window.

Clear your breakpoint by entering this command:

Enter g to let the target computer run. Break in again by choosing Break from the Debug menu or pressing CTRL-Break.

To see a list of all processes, enter this command:

The output is similar to this:

Copy the address of one process, and enter this command:

For example: !process ffffe00000d5290 2

The output shows the threads in the process.

Copy the address of one thread, and enter this command:

For example: !thread ffffe00000e6d080

The output shows information about the individual thread.

To see all the device nodes in the Plug and Play device tree, enter this command:

To see the device nodes along with their hardware resources, enter this command:

To see a device node that has a service name of disk, enter this command:

The output of !devnode 0 1 displays the address of the physical device object (PDO) for the node. Copy the address of a physical device object (PDO), and enter this command:

For example: PdoAddress!devstack 0xffffe00001159610

To get information about the driver disk.sys, enter this command:

The output of !drvobj displays addresses of dispatch routines: for example, CLASSPNP!ClassGlobalDispatch. To set and verify a breakpoint at ClassGlobalDispatch, enter these commands:

Enter g to let the target computer run.

If the target computer doesn’t break in to the debugger immediately, perform a few actions on the target computer (for example, open Notepad and save a file). The target computer will break in to the debugger when ClassGlobalDispatch is called. To see the stack trace, enter these commands:

The output is similar to this:

To end your debugging session, enter this command:

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.

Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)

Start here for an overview of Debugging Tools for Windows. This tool set includes WinDbg and other debuggers.

Install Debugging Tools for Windows

You can get Debugging Tools for Windows as part of a development kit or as a standalone tool set:

As part of the WDK

Debugging Tools for Windows is included in the Windows Driver Kit (WDK). To get the WDK, see Download the Windows Driver Kit (WDK).

As part of the Windows SDK

Debugging Tools for Windows is included in the Windows Software Development Kit (SDK). To download the installer or an ISO image, see Windows 10 SDK on Windows Dev Center.

As a standalone tool set

You can install the Debugging Tools for Windows alone, without the Windows SDK or WDK, by starting installation of the Windows SDK and then selecting only Debugging Tools for Windows in the list of features to install (and clearing the selection of all other features). To download the installer or an ISO image, see Windows 10 SDK on Windows Dev Center.

Get started with Windows Debugging

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

To get started with debugging kernel-mode drivers, see Debug Universal Drivers — Step by Step Lab (Echo Kernel-Mode). This is a step-by-step lab that shows how to use WinDbg to debug Echo, a sample driver that uses the Kernel-Mode Driver Framework (KMDF).

Debugging environments

If your computer has Visual Studio and the WDK installed, then you have six available debugging environments. For descriptions of these environments, see Debugging Environments.

All of these debugging environments provide user interfaces for the same underlying debugging engine, which is implemented in the Windows Symbolic Debugger Engine (Dbgeng.dll). This debugging engine is also called the Windows debugger, and the six debugging environments are collectively called the Windows debuggers.

Visual Studio includes its own debugging environment and debugging engine, which together are called the Visual Studio debugger. For information on debugging in Visual Studio, see Debugging in Visual Studio. For debugging managed code, such as C#, using the Visual Studio debugger is often the easiest way to get started.

Windows debuggers

The Windows debuggers can run on x86-based, x64-based, or ARM-based processors, and they can debug code that is running on those same architectures. Sometimes the debugger and the code being debugged run on the same computer, but other times the debugger and the code being debugged run on separate computers. In either case, the computer that is running the debugger is called the host computer, and the computer that is being debugged is called the target computer. The Windows debuggers support the following versions of Windows for both the host and target computers.

• WindowsВ 10 and Windows ServerВ 2016
• WindowsВ 8.1 and Windows ServerВ 2012В R2
• WindowsВ 8 and Windows ServerВ 2012
• WindowsВ 7 and Windows ServerВ 2008В R2

Symbols and symbol files

Symbol files store a variety of data that are not required when running the executable binaries, but symbol files are very useful when debugging code. For more information about creating and using symbol files, see Symbols for Windows debugging (WinDbg, KD, CDB, NTSD).

Blue screens and crash dump files

If Windows stops working and displays a blue screen, the computer has shut down abruptly to protect itself from data loss and displays a bug check code. For more information, see Bug Checks (Blue Screens). You analyze crash dump files that are created when Windows shuts down by using WinDbg and other Windows debuggers. For more information, see Crash dump analysis using the Windows debuggers (WinDbg).

Tools and utilities

In addition to the debuggers, Debugging Tools for Windows includes a set of tools that are useful for debugging. For a full list of the tools, see Tools Included in Debugging Tools for Windows.

Additional documentation

For additional information related to Debugging Tools for Windows, see Debugging Resources. For information on what’s new in Windows 10, see Debugging Tools for Windows: New for Windows 10.