SAL 2.0 Annotations for Windows Drivers

The Microsoft Source Code Annotation Language (SAL) includes annotations that are specific to the analysis of Windows drivers and the related kernel code. The annotation language provides a way of describing properties of functions, parameters, return values, structures, and structure fields. Annotations are like comments that you add to your code and are ignored by the compiler but are used by the static analysis tools. The use of annotations helps improve developer effectiveness, helps improve the accuracy of the results from static analysis, and allows the tools to better determine whether a particular bug exists. The driver annotations are not intended for use in non-driver or non-kernel-related code. The driver annotations are defined in Driverspecs.h.

Note  Windows 8 introduces SAL 2.0, which replaces SAL 1.0. For information about SAL 2.0, see Using SAL Annotations to Reduce C/C++ Code Defects. SAL 2.0 replaces SAL 1.0. SAL 2.0 should be used with the Windows Driver Kit (WDK) 8 for Windows 8. If you need information about the SAL 1.0 for drivers, refer to the documentation that ships with the WDK for Windows 7.

Driver annotationsCategoryUse

_IRQL_requires_max_(value)

_IRQL_requires_min_(value)

_IRQL_raises_(value)

_IRQL_requires_(value)

_IRQL_raises_(value)

_IRQL_saves_

_IRQL_restores_

_IRQL_saves_global_(kind, param)

_IRQL_restores_global_(kind, param)

_IRQL_always_function_min_(value)

_IRQL_always_function_max_(value)

_IRQL_requires_same_

IRQL annotations

Use the IRQL annotations to specify the range of IRQL levels at which a function should run. The IRQL annotations help the code analysis tool to more accurately find errors.

_IRQL_is_cancel_ IRQL annotations

Use the _IRQL_is_cancel_ annotation can help ensure correct behavior of a DRIVER_CANCEL callback function.

_Kernel_float_saved_

_Kernel_float_restored_

_Kernel_float_used_

Floating point annotations for drivers

Use the floating point annotations to help the code analysis tool detect the use of floating point in kernel-mode code and to report errors if the floating-point state is not properly protected.

_Kernel_clear_do_init_

DO_DEVICE_INITIALIZING annotation

Use the _Kernel_clear_do_init_ annotation to specify whether the annotated function is expected to clear the DO_DEVICE_INITIALIZING bit in the Flags field of the device object.

_Kernel_IoGetDmaAdapter_

_Kernel_IoGetDmaAdapter_ Annotation

Use the _Kernel_IoGetDmaAdapter_ annotation to direct the code analysis tools to look for misuse of DMA pointers.

_Interlocked_operand_

Annotations for interlocked operands

Use the _Interlocked_operand_ annotation for function parameters to identify them as an interlocked operands. A number of functions take as one of their parameters the address of a variable that should be accessed by using an interlocked processor instruction. These are cache read-through atomic instructions, and if the operands are used incorrectly, very subtle bugs result.

_Dispatch_type_

Annotations for Driver Dispatch Routines.

Use the _Dispatch_type_ annotation used when you declare WDM driver dispatch routines. See Declaring Functions Using Function Role Types for WDM Drivers and Annotating Driver Dispatch Routines

_Flt_CompletionContext_Outptr_

_Flt_CompletionContext_Outptr_ Annotation

Use the _Flt_CompletionContext_Outptr_ annotation when you declare file system minifilter pre-operation callback functions (PFLT_PRE_OPERATION_CALLBACK). Place this annotation on the CompletionContext parameter. This annotation directs the code analysis tool to check that the CompletionContext is correct for the FLT_PREOP_CALLBACK_STATUS return value.

 

Related topics

Using SAL Annotations to Reduce C/C++ Code Defects

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft