Understanding PREfast for Drivers
PREfast for Drivers is the driver-specific extension of the Code Analysis (/analyze) option of the Visual Studio Team System compiler. PREfast for Drivers interprets some coding and interface rules differently and includes rules that apply only to drivers, particularly kernel-mode drivers.
Building with PREfast for Drivers
You can run PREfast for Drivers (PFD) in two ways. You can run PFD as part of Windows Auto Code Review (OACR), which happens by default when you use a build environment window and the standard configuration of the WDK. Or you can run PFD by itself (standalone), by explicitly using the prefast command in a build environment window.
Whichever way that PFD is run, it intercepts the build utility's call to the standard compiler, Cl.exe and, instead, runs a CL intercept compiler that analyzes the driver source code and creates a log file of error and warning messages. Then, it calls the standard version of Cl.exe to produce the typical build output. The resulting object files are the same as those produced by a standard build command.
When the intercepting compiler runs, PREfast for Drivers examines each function in the code independently and then simulates the execution of all possible paths through the code, looking for common driver errors and unwise coding practices. PREfast for Drivers runs relatively quickly, even on larger drivers, and the report that it generates precisely identifies the line of driver code with the suspected error.
PREfast for Drivers Warnings
PREfast for Drivers uses a rule-based model to identify errors in the program or driver code. Each rule is associated with a warning that is reported if PREfast for Drivers detect a violation of the rule. For detailed information about each warning, see PREfast for Drivers Warnings.
Unlike standard PREfast, PREfast for Drivers reports the driver-specific warnings (warnings 28100-28199) and the driver-specific versions of the general warnings (warnings 6000-6999). PREfast for Drivers indicates that it is reporting a driver-specific version of a general warning by adding (PFD) to the warning name.
Using PFD with OACR.
In most cases, PFD is easily run as part of Windows Auto Code Review (OACR). In these cases, run a build command, such as build -cz, and then continue with other activities until OACR announces that it has found bugs (or updates the OACR icon to indicate that it found no bugs). If you will only be using OACR, you can skip the sections about using standalone PFD.
Be aware that the command line options discussed in the following sections can be set in the file Oacr.ini on the PrefastOptions variable (which is already present in Oacr.ini).
Controlling Standalone PREfast for Drivers
The PREfast for Drivers commands are relatively simple. To run PREfast for Drivers, add prefast to the beginning of a standard build command. For example:
prefast build -cZ
Unlike Static Driver Verifier, in which you select rules to run, PREfast for Drivers runs all of its standard rules automatically and, but it lets you suppress particular warnings and filter the output file, called a Defect Log.
Annotations
One of the important capabilities that PREfast and PFD provides is the ability to annotate function descriptions and some other entities in the source code of the driver. The objective of the annotations is to provide a more complete expression of the contract between the called and calling functions, so that PFD can check that the contract is met. Another goal of the annotations is that they inform whoever reads the code how the function should be used and what results can be expected. The annotations declare the contract of the interface and do not attempt to describe how that contract is achieved. In many cases, the results from running PFD reflect the absence of an appropriate annotation, and by adding the annotation, both the warning about the missing annotation is suppressed, and additional checks are enabled.
PFD is primarily designed for use with drivers, and specifically kernel-mode drivers. PFD can also be used with user-mode drivers. However, if you have a user-mode driver, occasionally it might be inappropriate to run PFD with the standard set of rules that are intended for kernel-mode drivers. To address this, you can set PFD to analyze user-mode or kernel mode code. By default, PFD is set to analyze a kernel-mode driver; however, it is possible to have it analyze user-mode by using a command line option. You can also select modes by means of annotations in the source file: the kernel_driver, kernel_code, user_driver and user_code annotations. For more information, see Setting the PREfast Analysis Mode.
Interpreting the Results
PREfast for Drivers is easy to run and it runs quickly, even on very large drivers and programs. The work for the developer is in examining the output, analyzing the errors that PREfast for Drivers detected, and distinguishing real coding errors from valid code that PREfast for Drivers misinterpreted.
For a comprehensive reference that describes each warning that PREfast might detect, see PREfast for Drivers Warnings. The warning descriptions include sample code that elicits the warning and sample code to avoid the warning. Typically, the changes that you make to avoid PREfast for Drivers warnings make the code easier to interpret and maintain, because if PREfast for Drivers misinterprets your code, a person might misinterpret it too.
If the Defect Log has errors that you determine, after careful examination, are invalid and cannot be avoided even with the use of annotations, you can use a #pragma warning directive to suppress a warning for particular lines of code, or filters to filter the warnings out of the Defect Log display. For detailed information, see Filtering the Defect Log and Using a Pragma Warning Directive.
Send comments about this topic to Microsoft
Build date: 5/3/2011