Floating Point Annotations

For some processor families, particularly x86 processors, using floating-point operations from within kernel-mode code must be done only within the scope of functions that save and restore floating-point state. Violations of this rule can be particularly difficult to find because they will only sporadically cause problems at run time (but these problems can be very serious). With the proper use of annotations, PREfast for Drivers (PFD) is particularly effective at detecting the use of floating point in kernel-mode code and reporting an error if floating-point state is not properly protected. Floating-point rules are checked only for kernel-mode code.

Add the following annotations to function parameters to indicate what they do with the floating-point state:

__drv_floatSaved
__drv_floatRestored

These annotations are already applied to KeSaveFloatingPoint state and KeRestoreFloatingPointState system functions, in addition to annotations for acquiring and releasing resources to prevent leaks. The similar EngXxx functions are also annotated in this way. However, functions that wrap these functions should also use these annotations.

When PFD discovers an unprotected use of floating point, it issues a warning. If the function as a whole is called safely by some calling function, the function can be annotated with __drv_floatUsed annotation. This suppresses the warning and also causes PFD to confirm that the caller is using the function safely. Additional levels of __drv_floatUsed can be added as required. The __drv_floatUsed annotation is automatically provided by PFD when either the function result or one of the function's parameters is a floating point type, but it does not hurt to provide the annotation explicitly.

For example, the __drv_floatSaved annotation indicates that floating-point state is stored in the FloatSave parameter of the KeSaveFloatingPointState system function:

NTSTATUS
  KeSaveFloatingPointState(
    __out
 __deref(__drv_floatSaved)
          PKFLOATING_SAVE  FloatSave
    );

In the following example, the __drv_floatUsed annotation suppresses PFD warnings about using floating-point state by the MyDoesFloatingPoint function. The annotation also causes PFD to confirm that any calls to MyDoesFloatingPoint occur in a safe floating-point context.

__drv_floatUsed
void
    MyDoesFloatingPoint(arguments);

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011