Windows 驱动程序的 SAL 2.0 注释

Microsoft源代码注释语言(SAL)包括特定于 Windows 驱动程序和相关内核代码分析的注释。 批注语言提供了描述函数、参数、返回值、结构和结构字段的属性的方法。 批注类似于添加到代码中的注释,编译器忽略注释,但由静态分析工具使用。 使用批注有助于提高开发人员的有效性,帮助提高静态分析结果的准确性,并允许工具更好地确定是否存在特定 bug。 驱动程序注释不适用于非驱动程序或非内核相关代码。 驱动程序注释在 Driverspecs.h 中定义。

注意 Windows 8 引入了 SAL 2.0,取代 SAL 1.0。 有关 SAL 2.0 的信息,请参阅 使用 SAL 注释减少 C/C++ 代码缺陷。 SAL 2.0 取代 SAL 1.0。 SAL 2.0 应与 Windows 8 的 Windows 驱动程序工具包 (WDK) 8 一起使用。 如果需要有关适用于驱动程序的 SAL 1.0 的信息,请参阅适用于 Windows 7 的 WDK 附带的文档。

IRQL 注释

使用 IRQL 注释 指定函数应在其中运行 IRQL 级别的范围。 IRQL 注释可帮助代码分析工具更准确地查找错误。

_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_is_cancel_ - 使用 _IRQL_is_cancel 注解来辅助确保 DRIVER_CANCEL 回调函数的正确行为。

驱动程序的浮点批注

_Kernel_float_saved_

_Kernel_float_restored_

_Kernel_float_used_

使用驱动程序的 浮点注释 来帮助代码分析工具检测内核模式代码中使用浮点,并在浮点状态未得到正确保护时报告错误。

DO_DEVICE_INITIALIZING批注

_Kernel_clear_do_init_

使用 DO_DEVICE_INITIALIZING 注解 来指定注解函数是否预期清除设备对象的 Flags 字段中的 DO_DEVICE_INITIALIZING 位。

Kernel_IoGetDmaAdapter注解

_Kernel_IoGetDmaAdapter_

使用 Kernel_IoGetDmaAdapter 注释 指示代码分析工具查找 DMA 指针的滥用。

互锁操作数的注释

_Interlocked_operand_

对函数参数使用互锁操作数的注释将其标识为互锁操作数。 某些函数将其中一个参数作为应通过互锁处理器指令访问的变量的地址。 这些是缓存读穿原子指令,如果操作数使用不当,则会导致极其细微的漏洞。

驱动程序调度例程的注释

_Dispatch_type_

声明 WDM 驱动程序调度例程时,请使用 驱动程序调度例程的注释。 有关详细信息,请参阅 使用 WDM 驱动程序的函数角色类型声明函数批注驱动程序调度例程

文件系统微型筛选器预操作回调_Flt_CompletionContext_Outptr_批注

_Flt_CompletionContext_Outptr_

PFLT_PRE_OPERATION_CALLBACK声明文件系统微型筛选器预作回调函数时,请使用文件系统微型筛选器预作回调_Flt_CompletionContext_Outptr_批注

将此批注置于 CompletionContext 参数上。 此批注指示代码分析工具检查 CompletionContext 是否适合FLT_PREOP_CALLBACK_STATUS返回值。

另请参阅

使用 SAL 注释减少 C/C++ 代码缺陷