IRQL Annotations

All drivers must consider interrupt levels, or IRQL. When PREfast for Drivers (PFD) analyzes driver code that is not annotated, PFD attempts to infer the range of IRQL at which a function could be running and identify any inconsistencies. When the driver code has IRQL annotations, PFD can make a better inference about the range of IRQL at which a function should run and can more accurately find errors. For example, you can add annotations that specify the maximum IRQL at which a function can be called; if a function is called at a higher IRQL, PFD reports an error.

Driver functions should be annotated with as much information about the IRQL that might be appropriate. If the additional information is available, it helps PFD in subsequent checking of both the calling function and the called function. In some cases, adding an annotation is a good way to suppress a false positive. Some functions, such as a utility function, can be called at any IRQL, and in this case, having no IRQL annotation is the proper annotation.

When annotating a function for IRQL, it is especially important to consider how the function might evolve, not just its current implementation. For example, a function as implemented might work correctly at a higher IRQL than the designer intended. Although it is tempting to annotate the function based upon what the code actually does, the designer might be aware of future requirements, such as the need to lower maximum IRQL for some future enhancement or pending system requirement. The annotation should be derived from the intention of the function designer, not from the actual implementation.

You can use the annotations in the following table to indicate the correct IRQL for a function and its parameters. The IRQL values are defined in Wdm.h.

IRQL annotation	Description
__drv_maxIRQL(value)	IRQL value is the maximum IRQL at which the function can be called.
__drv_minIRQL(value)	IRQL value is the minimum IRQL at which the function can be called.
__drv_setsIRQL(value)	The function returns at IRQL value.
__drv_requiresIRQL(value)	The function must be entered at IRQL value.
__drv_raisesIRQL(value)	The function exits at IRQL value, but it can only be called to raise (not lower) the current IRQL.
__drv_savesIRQL	The annotated parameter saves the current IRQL to restore later.
__drv_restoresIRQL	The annotated parameter contains an IRQL value from __drv_savesIRQL that is to be restored when the function returns.
__drv_savesIRQLGlobal(kind, param)	The current IRQL is saved into a location that is internal to PFD from which the IRQL is to be restored. This annotation is used to annotate a function. The location is identified by kind and further refined by param.
__drv_restoresIRQLGlobal(kind, param)	The IRQL saved by the function annotated with __drv_savesIRQLGlobal is restored from a location that is internal to PFD.
__drv_minFunctionIRQL(value)	IRQL value is the minimum value to which the function can lower the IRQL.
__drv_maxFunctionIRQL(value)	IRQL value is the maximum value to which the function can raise the IRQL.
__drv_sameIRQL	The annotated function must enter and exit at the same IRQL. The function can change the IRQL, but it must restore the IRQL to its original value before exiting.
__drv_isCancelIRQL	The annotated parameter is the IRQL passed in as part of the call to a DRIVER_CANCEL callback function. This annotation indicates that the function is a utility that is called from Cancel routines and that completes the requirements for DRIVER_CANCEL functions, including release of the cancel spin lock.
__drv_useCancelIRQL	The annotated parameter is the IRQL value that should be restored by a DRIVER_CANCEL callback function. In most cases, use the __drv_isCancelIRQL annotation instead.

 

Note   There is a difference between the __drv_isCancelIRQL and __drv_useCancelIRQL annotations. The __drv_useCancelIRQL annotation simply specifies that the annotated parameter is the IRQL value that should be restored by a DRIVER_CANCEL callback function. The __drv_isCancelIRQL annotation is a composite annotation that consists of __drv_useCancelIRQL plus several other annotations that ensure correct behavior of a DRIVER_CANCEL callback utility function. By itself, the __drv_useCancelIRQL annotation is only occasionally useful, for example, if the rest of the obligations described by __drv_isCancelIRQL have already been fulfilled in some other way.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011