Diagnostic Annotations
Occasionally, a particular combination of parameters is either dangerous or can be done better in some other way. In combination with conditions, PREfast for Drivers (PFD) can check for many such usage errors.
Use the __drv_preferredFunction and __drv_reportError annotations to generate error messages. These annotations are typically used in combination with the conditional annotation, __drv_when. Use them for recommendations and for annotating specific usages that should be avoided. If a function must never be used under any circumstances, it should be marked with #pragma __deprecated or __declspec(deprecated) so that the compiler can generate an error when it compiles the code.
Preferred Functions
The __drv_preferredFunction annotations can be used to generate error messages. This annotation has the following syntax:
| Term | Description |
|---|---|
__drv_preferredFunction(name, reason) |
The name is the name of a preferred function, and reason is an additional explanation of why that function is preferred. For example, consider the hypothetical functions GetResource and TryToGetResource. GetResource takes a Wait parameter. When Wait is TRUE (nonzero), a call should wait until the resource is acquired. When Wait is FALSE, GetResource can still be used to acquire the resource, but TryToGetResource is more efficient. The following annotations would cause PFD to flag this circumstance: |
__drv_when(!Wait,
__drv_preferredFunction(TryToGetResource,
"When calling GetResource with Wait==false,
"TryToGetResource performs better."))
Error Messages
Use the __drv_reportError annotation to direct PFD to generate a message that it has encountered the error that the annotation describes. This annotation has the following syntax:
| Term | Description |
|---|---|
__drv_reportError(string) |
The __drv_reportError annotation is similar to __drv_preferredFunction except that it generates a warning that the problem that the string parameter describes should be fixed. For example, __drv_reportError can be used for completely unacceptable usage such as an attempt to use a must-succeed allocation from the ExAllocatePool family of functions. |
__drv_when(PoolType&0x1f==2 || PoolType&0x1f==6",
__drv_reportError("Must succeed pool allocations are"
"forbidden. Allocation failures cause a system crash"))
Send comments about this topic to Microsoft
Build date: 5/3/2011