Share via

PREfast Build

  • Article

A PREfast Build command runs PREfast for Drivers on the source code while it compiles, or compiles and builds, the driver. You can add the word, prefast, to the beginning of the command that you typically use to compile and build a driver.

PREfast for Drivers analyzes all of the source code that is compiled. To limit the analysis to a particular source file or set of source files, modify the build command as follows:

prefast
[/log=LogFile] [/list] [/view] [/StackHogThreshold=#ofBytes ]
[/filter [/FilterPreset=PresetName]]
[/NEW_FAILURE={never | null | throw}]
[/KERNEL_NEW_FAILURE={never | null | throw}]
[ /reset | /noreset ]
BuildCommandArguments

Parameters

Actions

  • BuildCommand
    A command that causes the source code to be compiled, such as a Build command, a compiler command, an nmake command, or a script.

  • Arguments
    Arguments and parameters for the BuildCommand. These arguments are passed to the compiler without revision.

Parameters

  • **/log=**LogFile
    Specifies an alternate location for the XML-formatted PREfast for Drivers Defect Log.

    The default location of the Defects.xml file is %APPDATA%\Microsoft\PFD.

    For Windows Vista, the %APPDATA% variable becomes <drive>:\Users\<user>\Application Data.

    For Windows XP or Windows Server 2003 the %APPDATA% variable becomes <drive>:\Documents and Settings\<user>\Application Data.

    LogFile is a fully-qualified path (optional) and file name for the Defect Log (*.xml). If you do not specify a path, PREfast for Drivers creates the file in the local directory.

    If you specify a file name extension other than .xml, PREfast for Drivers does not create a Defect Log and it reports that it found no defects.

  • /list
    Displays the Defect Log in text format at the command line as soon as the analysis is complete. This parameter is the equivalent of using a prefast list command after a PREfast build command.

  • /view
    Displays the Defect Log as soon as the analysis is complete. This parameter is the equivalent of using a prefast view command after a PREfast build command.

  • /StackHogThreshold=#ofBytes
    Specifies the stack usage threshold in bytes. If the driver's use of the stack exceeds this value, PREfast for Drivers reports 6262 - Function uses <constant> bytes of stack. The default stack hog threshold is 1024.

  • /filter
    Applies a preset filter to the analysis. As a result, PREfast for Drivers records in the Defect Log only the warnings that are included in the preset filter.

    When you use this parameter, the preset filter can change the results of the analysis, not just the temporary appearance of the Defect Log. Unlike a preset filter that is applied to a Defect Log, you cannot reverse the effect of a filter that is applied during an analysis. Instead, you must run PREfast for Drivers again.

  • **/FilterPreset=**PresetName
    Specifies which preset filter is used during the analysis.

    If the /filter parameter is used, but the /FilterPreset parameter is omitted, PREfast for Drivers uses the preset filter that was applied to the Defect Log when it was last displayed. If no preset filter was applied to the Defect Log, then no filter is applied to the analysis.

    The filter names are case-sensitive. For a list of preset filters, see List of Preset Filters.

    By default, no filters are applied.

  • /NEW_FAILURE
    Determines the mode of failure when an attempt to allocate memory using operator new in user mode fails. The default is throw.

    Never

    The allocation never fails.

    Null

    Returns a NULL pointer.

    Throw

    Throws an exception. The default is throw.

     

    Do not use this parameter unless you have determined that the default failure mode is inappropriate, such as when compiling code that assumes that the default behavior is null.

  • /KERNEL_NEW_FAILURE
    Determines the mode of failure when an attempt to allocate memory using operator new in kernel mode fails. The default is null.

    Never

    The allocation never fails.

    Null

    Returns a NULL pointer. The default is null.

    Throw

    Throws an exception.

     

    Do not use this parameter unless you have determined that the default failure mode is inappropriate, such as when the compiler doesn't recognize kernel-mode code and generates code to throw an exception if the allocation fails, instead of returning a NULL pointer.

  • /reset
    Replaces the existing Defect Log with the results of the current PREfast for Drivers build command. This is the default behavior whether the /reset option is specified or not.

    If an alternate location is specified for the Defect Log with the **/log=**LogFile option, the LogFile file is replaced. If no log file is specified, the default Defects.xml file is replaced.

  • /noreset
    Prevents PREfast for Drivers from replacing the Defect Log. Use this option to collect the information from several runs of PREfast for Drivers into a single log file. To create this composite report, you must use the /noreset option as part of each of the runs.

    If an alternate location is specified for the Defect Log with the **/log=**LogFile option, information from the current build is added to the LogFile. If a Defect Log file is not specified, the information from the current build is added to the default Defects.xml file.

Examples

prefast /log=d:\usbdriver\pfdlog.xml /list build -cZ
prefast cl /c test.c
prefast /stackhogthreshold=2046 /view nmake /f pfw_build.mak
prefast /new_failure build -cZg
prefast /filter /filterpreset=drivers_recommended build -cZ

The following sequence of commands creates a single log file in d:\temp\Summary.xml with the results of running PREfast for Drivers in both dirs1 and dirs2. Any duplicate defects, for example, from common headers, will be removed.

cd dir1
prefast /log=d:\temp\summary.xml build -cZ
cd dir2
prefast /log=d:\temp\summary.xml /noreset build -cZ

Comments

The parameters for this command can appear in any order, but they must appear after the word prefast and before the BuildCommand. Any characters after the BuildCommand are interpreted as build command arguments, and they are passed to the compiler or build utility without revision.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011