About WDF Debugging Tools

Of the variety of tools for locating bugs in WDF drivers, the primary tool is WinDbg, a debugger with a graphical UI that can be used for both KMDF and UMDF drivers. Several other tools are used for more specialized purposes. This section discusses the available tools and how they are used to debug WDF drivers.

 Note  The Debugging Tools for Windows package can be downloaded from the WHDC Web site. The package includes the tools and documentation on how to use them.

Chapter 1, "Introduction to WDF," provides information about obtaining Debugging Tools for Windows.

WinDbg

The preferred debugger for both UMDF and KMDF drivers is WinDbg. This stand-alone debugger is used with a driver that has already been built and installed. WinDbg has a graphical user interface that supports the usual debugging features, such as setting breakpoints, examining variables, displaying the call stack, stepping through source code, and so on. In addition, WinDbg can run command-line debugger commands and debugger extensions that provide detailed information about many driver-specific issues.

 Note  Although it might be technically possible to use the Visual Studio debugger with UMDF drivers, this debugger is not designed for driver debugging and is not supported by Microsoft for this purpose. In addition, the WDK includes a collection of useful UMDF debugger extensions that can be used only with WinDbg.

The following are the basic ways to use WinDbg with WDF drivers:

• User-mode debugging WinDbg is attached to the WUDFHost process that hosts a UMDF driver.

• Kernel-mode debugging A host computer running WinDbg is connected to an active test computer running a KMDF driver.

• Crash dump analysis If either type of driver crashes, WinDbg can be used to analyze the crash dump.

Although the same tool is used to debug both types of WDF drivers, the approach is different:

• UMDF drivers are typically less complicated to debug than KMDF drivers. The debugger and driver can be hosted on the same system, and the procedures are similar to those used to debug a service.

• Kernel debugging requires a host computer running WinDbg, a test computer running the driver, and a way to connect the two computers so that the debugger can communicate with the test system.

Other Tools

The Debugging Tools for Windows package has several other debugging tools that can be useful adjuncts to WinDbg, including the following:

• KD debugger KD is a command-line debugging tool that has many of the same basic capabilities as WinDbg, but no graphical UI. See "KD" in the Debugging Tools for Windows help file for details.

• Tlist.exe This command-line application displays the processes running on the local computer, along with related information.

WDF includes two sets of debugger extensions, one for each framework. These extensions are small utility programs that can be run within WinDbg to provide WDF-specific information. See "Debugger Extensions" later in this chapter for more information.

Debugging is commonly done as part of the testing process. Although test and verification tools such as PREfast and Driver Verifier are not part of the debugging package, they are typically an integral part of the debugging process.

Chapter 21, "Tools for Testing WDF Drivers," presents a discussion of testing tools for drivers.

WPP Tracing

WPP tracing is commonly used with WDF drivers to help locate and characterize bugs. Most of the WDF samples use WPP tracing, so numerous examples are available.

Chapter 11, "Driver Tracing and Diagnosability," provides details about WPP tracing.

Debugging Macros and Routines

Several debugging macros and routines can be added to driver code to aid in locating and characterizing bugs. Some, such as the ASSERT macro, can be used in either UMDF or KMDF drivers, whereas others can be used only in one type of driver. Some debugging features are specific to WDF, as discussed in this chapter.