共用方式為

Function Results Annotations

  • 發行項

For many functions, the set of possible results for an output parameter or the function's return value is limited. Informing PREfast for Drivers (PFD) of this often makes its analysis much more accurate because PFD can avoid following impossible paths. For example, a function that returns a Boolean value is really returning an integer, which might be any value; the Boolean type is simply a convention that indicates that the value should be only TRUE or FALSE.

You can use the __drv_valueIs annotation to indicate a set of possible result values for a function. This annotation has the following syntax:

__drv_valueIs(list)

The result for the output parameter or function return value must be one of the values in list. List consists of a series of partial expressions in the form <relational operator><constant>, separated by semicolons.

For example, consider the following code example:

BOOLEAN b = boolfunc(...);
if (b == true) { <do something> }
...
if (b == false) { <do something else> }

PFD interprets b as an integer, and it cannot determine that b can have only two possible values. Therefore, when analyzing this function, PFD might simulate situations in which both statements are skipped (for example, if PFD assumed that b was 3). This kind of situation can lead to both false positives and false negatives. For this example, the parameter b can be annotated with __drv_valueIs(==0; ==1), which limits b to FALSE or TRUE.

Functions that return NTSTATUS are typically annotated with __drv_valueIs(<0; ==0), which indicates the value range for failure and success.

Combining conditions with the __drv_valueIs annotation can limit the result values to those that are made possible by the input parameters. For example, the annotations that are applied to the return value for ExAcquireResourceExclusiveLite indicate that if Wait is 0, the function can return either 0 or 1. But if Wait is nonzero, the function can return only 1.

__drv_when(!Wait, __drv_valueIs(==0; ==1)) 
__drv_when(Wait, __drv_valueIs(==1))

An alternative annotation would be:

__drv_when(!Wait, __drv_valueIs(==0;==1) __checkReturn)

This annotation indicates that if Wait is false, the function can return 0 or 1, and the result must be checked. If Wait is nonzero, it doesn't matter what the function returns because the return value does not have to be checked.

If the __success annotation is applicable to the current function and you are annotating the value that indicates success (usually the return value), using __success and __failure may have similar effects and may express the situation more accurately.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011