How to Enable the Frameworks Verifier
Updated: March 17, 2006
The kernel-mode driver framework (KMDF) includes a built-in verifier that provides features that are not currently available in the driver verifier (Verifier.exe). The frameworks verifier provides extensive tracing messages that supply detailed information about activities within the framework. It tracks references to each WDF object and builds a trace that can be sent to the debugger.
In kernel mode, the frameworks verifier checks lock acquisition and hierarchies, ensures that calls to the framework occur at the correct IRQL, verifies correct I/O cancellation and queue usage, and ensures that the driver and framework follow the documented contracts. It can also simulate low-memory and out-of-memory conditions and test a driver's response to these situations to determine whether the driver responds properly without crashing, hanging, or failing to unload.
By default, the frameworks verifier is disabled because its extensive checks can diminish system performance. During testing, you should enable the verifier before loading your driver. Unlike the driver verifier, enabling the frameworks verifier does not require a system reboot.
Enabling the Frameworks Verifier
To enable the frameworks 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 the frameworks verifier is enabled. In the following example, the frameworks verifier is enabled:
VerifierOn REG_DWORD 0x1 |
3. | Use Device Manager to reenable the device, thereby loading the driver. |
It is not necessary to reboot the system after you enable the frameworks verifier.
To disable the frameworks verifier, follow the same steps, but set the value of VerifierOn to zero.
When the verifier is enabled, you can also use registry settings for the following:
| • | Low-Memory Simulation. To enable the 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. |
| • | 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 this feature, 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. For 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. |
Using Verifier Information during Debugging
After your driver is loaded, you can type the following debugger extension command to determine whether the frameworks verifier is enabled:
!wdfkd.wdfdriverinfo <your drivername> 0x1
The !wdfkd.wdfdriverinfo command returns information about the driver. The hexadecimal 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 the verifier. If the 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 following sample shows the output of the !wdfkd.wdfdriverinfo command for a driver that is named wdfrawbusenumtest:
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 f, which causes the sample output to include the state of the 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.
What should you do?
| • | Enable the frameworks verifier during testing to find errors in your driver. |
| • | Enable low-memory simulation to test your driver's response to memory allocation failures. |
| • | Use handle tracking to find potential memory leaks in your driver. |
| • | Download the latest version of Debugging Tools for Windows to use when debugging WDF drivers. |
| • | Use the debugger extensions that are provided with the KMDF release. |
For more information:
Architecture of the Windows Driver Foundation
Debugging Tools for Windows
Kernel-Mode Driver Framework (KMDF)
In the KMDF Documentation, see:
Design Guide
Debugging a Framework-based Driver
