Basic Driver Annotations

  • Article

The following basic driver annotations can be used throughout a driver. The anno_list argument consists of one or more annotations in a space-separated list.

Annotation Description

__drv_at(arg, anno_list)

__drv_arg(arg, anno_list)

Indicates that the annotations in anno_list apply to arg, which is an expression that yields a C/C++ l-value. By convention, the __drv_arg annotation is used for annotations on function parameters but the two are completely equivalent.

__drv_deref(anno_list)

Indicates that an additional level of dereference should be applied to the annotation.

__drv_fun(anno_list)

Indicates that the annotations in anno_list apply to the function as a whole (that is, the annotation applies to some property of the global state of the calling function).

__drv_in(anno_list)

Indicates that anno_list applies on input (a precondition).

__drv_in_deref(anno_list)

Is equivalent to __drv_in(__drv_deref(anno_list)). This annotation is provided as a convenience.

__drv_out(anno_list)

Indicates that anno_list applies on output (a postcondition).

__drv_out_deref(anno_list)

Is equivalent to __drv_out(__drv_deref(anno_list)). This annotation is provided as a convenience.

__drv_ret(anno_list)

Indicates that the annotations in anno_list apply to the function return value.

__drv_at(expression, anno_list)

Indicates that anno_list is to be applied to the object named by expression, which must yield an l-Value. This form is often used with this to annotate the C++ this object or members of that class, but any l-value can be used. It is often used on the function body to annotate complex objects with respect to a parameter.

 

Annotation Lists

An annotation list can contain positioning annotations such as __deref, __drv_deref, and __drv_at/__drv_arg; conditional annotations specified with __drv_when; and general-purpose annotations such as __notnull.

For example, the following annotation list indicates that both the annotated output parameter and its first level of dereference must not be null:

__drv_out(__notnull __deref(__notnull))

Note that the following two annotation lists are equivalent, but the first is considerably more readable than the second:

__drv_arg(***p, __drv_in(__notnull)) char ***p

__drv_in(__drv_deref(__drv_deref(__drv_deref(__notnull)))) char ***p

Nesting Annotations

The basic driver annotations can be combined by nesting. Because there is often more than one way to express the same annotation, the choice is primarily based on readability.

For example, the following expressions apply the annotations in anno_list to parameter p1 of type xyz at one level of dereference. The first two examples must be placed inline with the parameter declaration.

__drv_in_deref(anno_list) xyz p1;

__drv_in(__drv_deref(anno_list)) xyz p1;

The following three annotations are equivalent to the two preceding examples, but they can be placed anywhere that an annotation for that function is valid; they do not have to be near the declaration of p1. These expressions are examples of composing annotation, but they also show how a complex annotation can be separated from the parameter to which it applies.

__drv_arg(p1, __drv_in(__drv_deref(anno_list)))

__drv_arg(*p1, __drv_in(anno_list))

__drv_arg(p1, __drv_in_deref(anno_list))

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011