Edit

Share via

Get started with Windows debugging

  • Article

This article covers how to get started with debugging for Windows. If your goal is to use the debugger to analyze a crash dump, see Analyze crash dump files by using WinDbg.

To get started with Windows debugging, complete the following steps.

1. Install the Windows Debugger

For information on installing WinDbg, see Install WinDbg.

2. Identify the host and target systems

Two separate computer systems are typically used for debugging because instruction execution on the processor is commonly paused during the process. The debugger runs on the host system, and the code that you want to debug runs on the target system.

Host <--------------------------------------------------> Target

Diagram illustrating the connection between host and target systems with a double arrow.

In some situations, it's possible to use a virtual machine as the second system. For example, a virtual PC could run on the same PC as the code that you need to debug. However, if your code communicates with low-level hardware, using a virtual PC might not be the best approach. For more information, see Setting up network debugging of a virtual machine - KDNET.

3. Determine the debugger type: kernel mode or user mode

Next, you need to determine whether to use kernel-mode or user-mode debugging.

  • The operating system and privileged programs run in kernel mode. Kernel-mode code has permission to access any part of the system, and it's not restricted like user-mode code. Kernel-mode code can gain access to any part of any other process running in either user mode or kernel mode. Much of the core OS functionality and many hardware device drivers run in kernel mode.

  • Applications and subsystems on the computer run in user mode. Processes that run in user mode do so within their own virtual address spaces. They're restricted from gaining direct access to many parts of the system, including system hardware, memory that isn't allocated for their use, and other portions of the system that might compromise system integrity. Processes that run in user mode are effectively isolated from the system and from other user-mode processes, so they can't interfere with these resources.

If your goal is to debug a driver, determine if the driver is a kernel-mode driver or a user-mode driver. Windows Driver Model (WDM) drivers and Kernel-Mode Driver Framework (KMDF) are both kernel-mode drivers. As the name suggests, User-Mode Driver Framework (UMDF) drivers are user-mode drivers.

For some issues, it can be difficult to determine which mode the code executes in. In that case, you might need to pick one mode and see what information is available in that mode. Some issues require using the debugger in both user mode and kernel mode.

Depending on which mode you debug in, you might need to configure and use the debuggers in different ways. Some debugging commands operate the same in both modes, and some commands operate differently.

Learn more about using the debugger in kernel mode:

Learn more about using the debugger in user mode:

4. Choose your debugger environment

The WinDbg debugger works well in most situations, but there are times when you might want to use another debugger, such as console debuggers for automation or Visual Studio. For more information, see Debugging environments.

5. Determine how to connect the target and host

Typically, target and host systems are connected by an Ethernet network. If you're doing early bring-up work, or you don't have an Ethernet connection on a device, other network connection options are available. For more information, see these articles:

6. Choose either 32-bit or 64-bit debugging tools

Whether you need a 32-bit or 64-bit debugger depends on the version of Windows that runs on the target and host systems and whether you're debugging 32-bit or 64-bit code. For more information, see Choosing 32-bit or 64-bit debugging tools.

7. Configure symbols

To use all of the advanced functionality that WinDbg provides, you must load the proper symbols. If you do not have symbols properly configured, you will receive messages indicating that symbols are not available when you attempt to use functionality that is dependent on symbols. For more information, see Symbols for Windows debugging.

8. Configure source code

If your goal is to debug your own source code, you need to configure a path to your source code. For more information, see Source path.

9. Become familiar with debugger operation

The Debugger operation section of this documentation describes debugger operation for various tasks. For example, Keeping a Log File in WinDbg describes how WinDbg can write a log file that records the debugging session.

10. Become familiar with debugging techniques

Standard debugging techniques apply to most debugging scenarios, and examples include setting breakpoints, inspecting the call stack, and finding a memory leak. Specialized debugging techniques apply to particular technologies or types of code. Examples include Plug and Play debugging, KMDF debugging, and RPC debugging.

11. Use the debugger reference commands

You can use different debugging commands as you work in the debugger. Use the .hh command in the debugger to display helpful information about any debugging command. For more information about available commands, see Debugger reference.

12. Use debugging extensions for specific technologies

There are multiple debugging extensions that can be used to parse domain-specific data structures. For more information, see Specialized extensions. Loading debugger extension DLLs explains how to load debugger extensions.

This documentation assumes that you have some knowledge about core Windows internals. To learn more about Windows internals, including memory usage, context, threads, and processes, you can review resources such as Windows Internals by Pavel Yosifovich, Mark E. Russinovich, David A. Solomon and Alex Ionescu.

14. Review additional debugging resources

Other resources include the following books and videos:

  • Inside Windows Debugging: Practical Debugging and Tracing Strategies by Tarik Soulami
  • Advanced Windows Debugging by Mario Hewardt and Daniel Pravat
  • Defrag Tools video series, episodes 13 through 29, all about WinDbg

See also