How to Prepare for KMDF Debugging | Developing Drivers with the Windows Driver Foundation (Pro Developer)

The process of preparing to debug a KMDF driver is more complicated than that for a UMDF driver. To start, kernel-mode debugging typically requires three hardware components:

A host computer running WinDbg.

This is typically the computer that is used to develop and build the driver.
A test computer running an appropriate build of Windows with the driver installed and kernel debugging enabled.

Debugging is typically done with a checked build of the driver because checked builds are much easier to debug. Test computers also often run a checked build of Windows.
A way for the two computers to communicate.

Historically, this was handled by connecting serial ports on the host and test computers with a null-modem cable. An alternative is to use USB or IEEE 1394 cables.

Before you can start debugging, you must install the driver on a test computer running the target version of Windows and configure that computer for debugging. You must also install the debugging tools on your host computer and connect the two computers with the appropriate cable.

This section provides a brief discussion of how to prepare host and test computers and start a debugging session.

Note Windows XP and later versions of Windows allow you to run a kernel debugger on the same computer that hosts the target driver. However, this approach to kernel debugging is limited. For example, you cannot set breakpoints. This chapter assumes you are using two computers to debug your KMDF driver.

Tip See "Kernel-Mode Setup" in the Debugging Tools for Windows help file for detailed instructions on how to set up computers for kernel debugging.

How to Enable Kernel Debugging on the Test Computer

The version of Windows on the test computer must have kernel debugging explicitly enabled. Among other things, this enables the communication link between the test and host computers. The procedure for enabling kernel debugging depends on whether the test computer is running Windows Vista or an earlier version of Windows.

How to Enable Kernel Debugging for Windows Vista

Windows Vista and later versions of Windows store boot configuration information in a data store called boot configuration data (BCD). BCD abstracts the underlying firmware and provides a common programming interface to manipulate the boot environment for all Windows-supported hardware platforms, including Extensible Firmware Interface (EFI) systems. The simplest way to enable kernel debugging is with the BCDEdit tool, which is included with Windows Vista.

To Enable Kernel Debugging on a Windows Vista System

Open a command window with elevated privileges.
Run the following command:
- bcdedit /debug on

You must also run an additional BCDEdit command to select and configure the communication link. For example, the following BCDEdit command specifies the debug settings for all operating systems on the computer as an IEEE 1394 connection using channel 32:

bcdedit /dbgsettings 1394 channel:32

Tip It is also possible to configure debugging separately for each Windows version. See "BCDEdit Commands for Boot Environment" on the WHDC Web site for details-online at http://go.microsoft.com/fwlink/?LinkId=80914.

After running these commands, reboot the computer to run Windows Vista in debugging mode.

To Turn off Kernel Debugging

Run the following command:
- bcdedit /debug off

How to Enable Kernel Debugging for Earlier Versions of Windows

For versions of Windows earlier than Windows Vista, you enable kernel debugging by editing the system's Boot.ini file, which is located in the root folder of the boot drive. You must create an [operating systems] entry with the /debug boot option and one or more additional arguments to configure the communication link.

The example in Listing 22-1 shows a Boot.ini file where the first entry in the [operating systems] section is a version of Windows that enables kernel debugging with communication over a 1394 port. The second entry is a standard Windows XP system configuration.

Listing 22-1: Boot.ini entries for kernel debugging over 1394

 [boot loader] timeout=30 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS [operating systems] multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Debugging with 1394" /fastdetect /debug /debugport=1394 /channel=32 multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect

Systems with multiple versions of Windows on separate partitions have additional [operating systems] entries in Boot.ini-at least one per version. At the start of the boot process, the Windows Boot Loader displays every entry and the user can select which one to load. If the user does not explicitly choose a configuration, the first [operating systems] entry loads by default.

Tip See "Boot Options for Driver Testing and Debugging" in the WDK for information about editing the Boot.ini file-online at http://go.microsoft.com/fwlink/?LinkId=80622.

How to Prepare the Test Computer for KMDF Debugging

Many of the WDF debugging features must be enabled by setting registry values for the driver key's Parameters\Wdf subkey on the test computer. The driver key is named for the driver and is located under the following key:

 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\DriverName\Parameters\Wdf

Table 22-4 summarizes the values that are associated with Wdf subkey in the registry. These values are all disabled by default.

Table 22-4: KMDF Debugging Registry Values
Open table as spreadsheet
Value	Type	Description
VerifierOn	REG_DWORD	Set to a nonzero value to enable the KMDF Verifier.
VerifyOn	REG_DWORD	Set to a nonzero value to enable the WDFVERIFY macro. If VerifierOn is set, WDFVERIFY is automatically enabled.
DbgBreakOnError	REG_DWORD	Set to a nonzero value to instruct the framework to break into the debugger when a driver calls WdfVerifierDbgBreakPoint.
VerboseOn	REG_DWORD	Set to a nonzero value to capture verbose information in the KMDF log.
LogPages	REG_DWORD	Set to a value from 1 to 10 to specify the number of memory pages that the framework assigns to its logger. The default value is 1.
VerifierAllocateFailCount	REG_DWORD	Set to a nonzero value to test low-memory conditions. When VerifierAllocateFailCount is set to n, the framework fails every attempt to allocate memory for the driver's objects after the nth allocation. This value works only if VerifierOn is also set.
TrackHandles	MULTI_SZ	Set to a MULTI_SZ string that contains the names of one or more object types to track handle references to those types. This feature can help find memory leaks that are caused by unreleased references. To track all object types, set TrackHandles to "*".
ForceLogsInMiniDump	REG_DWORD	Set to a nonzero value to include the KMDF log in a small memory dump file if the system crashes.

Note Changes in registry settings do not take effect until the next time that the driver is loaded.

How to Start a KMDF Debugging Session

After you have enabled kernel debugging on the test computer, you can start a KMDF debugging session.

To Start a KMDF Debugging Session

Run WinDbg.
On the File menu, click Kernel Debug to put WinDbg in kernel-debugging mode.
In the Kernel Debug dialog box, select and configure the communication link with the test computer.

For example, if you are using a 1394 cable, you must specify the channel number.

After WinDbg is in kernel-debugging mode, the test system must break into the debugger before debugging can start. Breaking into the debugger stops the test computer and turns its operation over to WinDbg.

Here are the common ways that a test system can break into the debugger:

You instruct WinDbg to force a break. This can be done from the UI by clicking the Debug menu and then clicking Break, or by clicking the corresponding toolbar button. You can also run the .break command in the Command window.
You use WinDbg to dynamically insert breakpoints into the running driver. This approach is quite flexible because it allows breakpoints to be inserted, disabled, enabled, or removed during the debugging session. The procedure is discussed in the UMDF and KMDF walkthroughs later in this chapter.
You insert DbgBreakPoint statements in the driver's source code. This approach is simpler but less flexible because the driver must be recompiled and reinstalled to change a breakpoint.
The driver bug checks and crashes the test computer. At this point, you can use WinDbg to examine crash dump data, but the computer must be rebooted before it can run again. You can force a system crash by running .crash in the Command window.

After the test system has broken into the debugger, you can examine variables, step through driver source code, and so on. You can enter debugger commands only after the driver has broken into the debugger. In particular, before you can use bp or related commands to set dynamic breakpoints, you might need to force a break so that you can run the command.

The process of debugging driver load and startup code is different from debugging a running driver because you must have at least one breakpoint set before the loading process starts. One way is to set a hard-coded breakpoint in the appropriate load or startup routine. A better and more flexible approach is to set a deferred breakpoint.

To Debug Driver Load and Startup Code in a KMDF Driver

Run WinDbg.
Enable kernel debugging, as described in "How to Prepare for KMDF Debugging" earlier in this chapter.
Use the bu command to set a deferred breakpoint in the appropriate routine, typically DriverEntry or EvtDriverDeviceAdd.
Start the driver loading process.

One way to force the driver to load is to use Device Manager or DevCon to disable and then enable the driver. For a USB device such as the Fx2 device, you can just remove the device and then insert it again.

When the driver load and startup code reaches the breakpoint, it breaks into the debugger and debugging can start.

How to Start Debugging a KMDF Driver Crash

If a driver bug causes a system crash, the computer must be rebooted. However, you can use WinDbg to attempt to determine the source of the crash by analyzing the crash dump in either of the following ways:

If WinDbg is running and connected when the test computer crashes, the system breaks into the debugger and you can analyze the crash dump immediately.

The !analyze debugger extension is the most commonly used tool for this purpose.
The test computer can be configured to attempt to create a crash dump file when it crashes.

If the file is successfully created, you can load the file into WinDbg and analyze the crash. WinDbg is not required to be connected to the test computer for this purpose.

Tip See articles in the Debugging Tools for Windows help file for more information: "Creating a Kernel-Mode Dump File" describes how to create a crash dump file; "Using the !analyze Extension" provides information on using !analyze to analyze a crash dump.

One useful tool for debugging driver crashes is the KMDF log. KMDF generates a log for each driver that contains a history of recent events such as the progress of IRPs through the framework and the corresponding requests through the driver. See "How to Use WinDbg to View the KMDF Log" later in this chapter for details.