1. Debugging Macros and Routines
KMDF drivers can include any of the standard debugging macros and routines, such as ASSERT or DbgPrintEx. Several routines and macros are also specific to WDF as summarized in Table 1.
Table 1. Debugging Macros
| Category | Tests |
|---|
| WdfVerifierDbgBreakPoint | This routine breaks into the debugger if the DbgBreakOnError value is set in the registry. |
| WDFVERIFY | If
the VerifyOn value is set in the registry, this macro tests a logical
expression and breaks into the kernel debugger if the expression
evaluates to FALSE. Unlike ASSERT, this macro is included in both
checked and free builds. |
| VERIFY_IS_IRQL_PASSIVE_LEVEL | If
the VerifyOn value is set in the register, this macro breaks into the
kernel debugger if the driver is not executing at IRQL=PASSIVE_LEVEL. |
2. WDF Debugger Extension Commands
KMDF
includes a set of debugger extension commands that can be invoked in
the debugger’s command window to obtain a variety of WDF-related data.
The output often includes command strings that can be pasted into the
command line to retrieve additional related information. Table 2 shows some of the more commonly used commands.
Table 2. Debugger Extension Commands
| Category | Tests |
|---|
| !wdfhelp | Displays the list of debugger extensions. |
| !wdfcrashdump | Displays a crash dump that includes the framework’s log information. |
| !wdfdevice | Displays information that is associated with a WDFDEVICE-typed handle. |
| !wdfdevicequeues | Displays information about all the queue objects that belong to a specified device. |
| !wdfdriverinfo | Displays information about a framework-based driver, such as its run-time version and hierarchy of object handles. |
| !wdfhandle | Displays information about a specified KMDF handle. |
| !wdfIotarget | Displays information about a WDFIOTARGET-typed object handle. |
| !wdfdr | Displays all loaded WDF drivers. |
| !wdfIodump | Displays the framework’s log information. |
| !wdfqueue | Displays information about a WDFQUEUE-typed object handle. |
| !wdfrequest | Displays information about a WDFREQUEST-typed object handle. |
When KMDF Verifier is enabled, several of the WDF debugger extension commands provide more information than is available otherwise. For example, !wdfdriverinfo reports leaked handles.
The code for the WDF debugger extensions is contained in a DLL that is named wdfkd.dll. The DLL is included with WDK debugging tools and is stored in Program Files\Debugging Tools for Windows\winext. Check it against the most recent version of the DLL, which is included with the latest KMDF distribution. Wdfkd.dll is stored under WinDDK\BuildNumber\bin\. There are actually three versions of wdfkd.dll,
one for each supported architecture (amd64, Intel Itanium, or x86). If
necessary, overwrite the version that came with the debugger with the
most recent version.
3. Using WPP Tracing with a KMDF Driver
WPP tracing works in essentially the same way with a
KMDF driver as it does with a WDM driver. However, KMDF provides
hundreds of framework-specific tracing messages. To enable KMDF support
for WPP, include the following RUN_WPP directive in the project’s Sources file:
RUN_WPP = $(SOURCES) \
-km \
-func:TraceEvents(LEVEL,FLAGS,MSG,...) \
-gen:{km-WdfDefault.tpl}*.tmh
