Developing Drivers with the Windows Driver Foundation (Pro Developer)

KMDF includes a built-in verifier with features that complement Driver Verifier and that do additional KMDF-specific checking. KMDF Verifier-sometimes called the frameworks verifier-provides extensive tracing messages that supply detailed information about activities within the framework. It tracks references to each KMDF object and builds a trace log that can be sent to the debugger.

 Tip  See "Debugging a Framework-based Driver" in the WDK for details about using KMDF Verifier-online at http://go.microsoft.com/fwlink/?LinkId=79790.

Driver Verifier is a generic verifier that validates whether any driver-including KMDF-follows the WDM rules. KMDF Verifier validates whether a KMDF driver follows the more specific KMDF rules. In addition, KMDF Verifier provides a sequential fault injection mechanism that is not available in Driver Verifier. Driver Verifier in Windows Vista allows you to specify the probability of a failure, but only KMDF Verifier can fail every allocation sequentially starting from the nth allocation.

When to Use KMDF Verifier

You should run both Driver Verifier and KMDF Verifier during development. During testing, you should enable the KMDF Verifier before loading your driver. It is not necessary to reboot the system after you enable the KMDF Verifier.

How KMDF Verifier Works

KMDF Verifier operates on an installed and running driver. It provides extensive tracing messages that supply detailed information about activities within the framework. KMDF Verifier tracks references to each KMDF object and builds a trace that can be sent to the debugger.

KMDF Verifier performs the following actions:

• Checks lock acquisition and hierarchies.

• Ensures that calls to the framework occur at the correct IRQL.

• Verifies correct I/O cancellation and queue usage.

• Ensures that the driver and framework follow the documented contracts.

KMDF Verifier can also simulate low-memory and out-of-memory conditions. It tests a driver's response to these situations to determine whether the driver responds properly without crashing, hanging, or failing to unload.

How to Enable KMDF Verifier

By default, KMDF Verifier is disabled because its extensive checks can diminish system performance.

To enable KMDF Verifier

1. If your driver is already loaded, use Device Manager to disable the device. Disabling the device causes the driver to be unloaded.

2. Use RegEdit to set VerifierOn to a nonzero value in the driver's Parameters\Wdf subkey of the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services key in the Windows registry.

   A nonzero value indicates that KMDF Verifier is enabled, as in the following example:

   VerifierOn REG_DWORD 0x1

3. Use Device Manager to reenable the device, thereby loading the driver.

VerifierOn implicitly sets another registry value, VerifyOn, which enables the WDFVERIFY macro that is defined in Wdfassert.h. You can use the WDFVERIFY macro in your code to test a logical expression and, if the expression evaluates to FALSE, the driver breaks into the kernel debugger. Set VerifyOn to zero to disable this macro.

To disable KMDF Verifier, follow the same steps as to enable the KMDF Verifier, but set the value of VerifierOn to zero.

When KMDF Verifier is enabled, you can also use registry settings to enable the following options:

• Enabling low-memory simulation To enable KMDF Verifier's low-memory simulation, use RegEdit to set a value (n) that is greater than zero for VerifierAllocateFailCount in the driver's Parameters\Wdf subkey in the Windows registry. After n attempts to allocate memory, the framework fails every additional attempt. These failures help to test your driver's handling of low-memory conditions.

• Breaking into the debugger If DbgBreakOnError is set to a nonzero value, the framework breaks into the debugger-if available-each time that a driver calls WdfVerifierDbgBreakPoint. If DbgBreakOnError is set to zero, the framework does not break into the debugger. If the DbgBreakOnError registry value does not exist but the VerifierOn registry value is set to a nonzero value, the framework breaks into the debugger each time that a driver calls WdfVerifierDbgBreakPoint.

• Tracking handles To enable handle reference tracking for one or more object types, set the TrackHandles value in the registry. When TrackHandles is enabled, KMDF tracks references that are taken on the specified object types. This feature can help you find memory leaks that are caused by references that your driver does not release.

  To enable handle reference tracking, use RegEdit to set the TrackHandles value in the driver's Parameters\Wdf subkey of the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services key.

TrackHandles is a MULTI_SZ value, so you can specify the name of one or more WDF object types, as in the following example:

TrackHandles MULTI_SZ: WDFDEVICE WDFQUEUE

This setting causes KMDF to track the handles of WDFDEVICE and WDFQUEUE objects. You can also specify an asterisk (*) to track all KMDF objects.

How to Use KMDF Verifier Information during Debugging

After your driver is loaded, you can type the following debugger extension command to determine whether KMDF Verifier is enabled:

• !wdfkd.wdfdriverinfo DriverName 0x1

The !wdfkd.wdfdriverinfo debugger extension returns information about the driver. The value that follows the driver name denotes a set of flags that determine which information to return. The value 0x1 causes the command to return the state of KMDF Verifier. If KMDF Verifier is enabled, the debugger displays the following information:

• The name of the driver image.

• The name of the WDF library image.

• The address of the internal FxDriverGlobals variable.

• The value of the internal WdfBindInfo variable.

• The KMDF version number against which the driver was compiled.

  The version number cannot be greater than the version of KMDF that is loaded on the test machine.

For example, the sample in Listing 21-3 shows the output of the !wdfkd.wdfdriverinfo debugger extension for a driver named WdfRawBusEnumTest.

Listing 21-3: Example !wdfkd.wdfdriverinfo output for WdfRawBusEnumTest driver

0: kd> !wdfdriverinfo wdfrawbusenumtest f ---------------------------------- Default driver image name: wdfrawbusenumtest WDF library image name: Wdf01000 FxDriverGlobals 0x83b6af18 WdfBindInfo 0xf22550ec Version v1.5 build(1234) ---------------------------------- WDFDRIVER: 0x7cfb30d0 !WDFDEVICE 0x7c58b1c0 context: dt 0x83a74ff8 ROOT_CONTEXT (size is 0x1 bytes) <no associated attribute callbacks> !WDFDEVICE 0x7d2df1c8 context: dt 0x82d20ff0 RAW_PDO_CONTEXT (size is 0xc bytes) <no associated attribute callbacks> !WDFDEVICE 0x7c8671d8 context: dt 0x83798fe0 PDO_DEVICE_DATA (size is 0x1c bytes) EvtCleanupCallback f2251710 wdfrawbusenumtest!RawBus_Pdo_Cleanup --------------------------------- WDF Verifier settings for wdfrawbusenumtest.sys is ON Pool tracking is ON Handle verification is ON IO verification is ON Lock verification is ON Handle reference tracking is ON for the following types: WDFDEVICE ---------------------------------

The example command uses the flag value 0xF, which causes the sample output to include the state of KMDF Verifier and all other possible information. The sample output also includes information about the context and callback functions that are associated with each handle to a WDFDEVICE object because the TrackHandles registry setting is enabled for WDFDEVICE objects.