Overview
The Windows Driver Kit gives you access to static analysis tools: PREfast for Drivers (PFD) and Static Driver Verifier (SDV). The purpose of this article is to explain how to use PFD to validate that your driver correctly declares entry points through role types. This is necessary to make SDV effective in finding bugs.
Role types are function typedefs for driver entry points. They are a way of standardizing function prototypes, which is required by the WDK and MSDN. Role types act as documentation by describing the intended role of a driver entry point routine (or callback function) and the routine’s return value and parameter types. Best of all, role types enable Static Driver Verifier which can discover complex inter-procedural bugs causing blue screens and system hangs.
As part of your regular driver development process, you should use both PFD and SDV. We recommend that you run PFD first and address warnings about missing role types, and then run SDV.
PREfast for Drivers (PFD)
PREfast for Drivers will generate warnings regarding any missing role types, among other issues. PFD runs quickly, and adding role types is fast and easy. At the 2008 Microsoft Windows Driver Developer Conference, I worked with a customer who was brand new to the concept of SDV role types but wanted to run SDV on his driver. We added all of the necessary role types and got a complete run of SDV on his driver in under an hour.
PFD will generate a list of warnings, including which role types are missing. The warnings regarding missing role types for a WDM driver include:
· Warning 28101: This warning specifies that PFD has detected the driver’s DriverEntry routine. Declare this routine with the DRIVER_INITIALIZE role type.
· Warning 28155: This warning specifies that a driver routine was not declared with the correct role type.
o Declare driver unload routines with the DRIVER_UNLOAD role type
o Declare I/O completion routines with IO_COMPLETION_ROUTINE role type
o Declare add device routines with the DRIVER_ADD_DEVICE role type
o Declare dispatch routines with the DRIVER_DISPATCH role type in conjunction with the __drv_dispatchType annotation
o Declare interrupt service routines with the KSERVICE_ROUTINE role type
o Declare DPC for ISR routines with the IO_DPC_ROUTINE role type
o For other applicable role types, visit the WDK or MSDN role type documentation
· Warning 28169: This warning specifies that the driver is missing a __drv_dispatchType annotation on a dispatch routine.
o Add the __drv_dispatchType annotation to the specified dispatch routine. This annotation must be combined with the DRIVER_DISPATCH role type
For example, if the driver header file contains a declaration for the dispatch routine which handles PnP IRPs like this:
NTSTATUSDriverDispatchPnP( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp );
After adding the appropriate annotations, the dispatch routine declaration will look like this:
__drv_dispatchType(IRP_MJ_PNP)DRIVER_DISPATCH DriverDispatchPnP;
The process for adding role types for KMDF and NDIS drivers is similar. In addition to running PFD to discover missing role types, use the WDK or MSDN documentation regarding role types to make sure the driver contains all of the required role types.
Static Driver Verifier (SDV)
SDV calls the entry points in the driver and attempts to find a valid code path which results in a system hang or bug check. In order for SDV to recognize your driver’s entry points, you must declare them using role types as described above.
SDV assumes that no errors of the NULL pointer dereference type are generated when your driver is scanned with PFD. In other words, it is recommended that you run SDV on your driver after the driver is PFD clean with respect to NULL pointer dereferences.
To run SDV, open a WDK build environment window and go to the directory which contains the sources file for your driver. Then run these two commands:
staticdv /clean
staticdv /rule=*
The latter command will run all SDV checks on the driver. SDV can also run with a single rule or a list of rules as specified in a configuration file which you create (config.sdv). For a list of possible rules, run:
staticdv /showrules
When SDV has completed, view the results by running:
staticdv /view
For more information about using PFD to add role types in your driver, visit Make Static Driver Verifier More Efficient: Add a Preset Filter to PFD/OACR Defect Viewer.
For questions regarding SDV and PFD, please send email to sdvpfdex@microsoft.com.