Windows 驱动程序的 SAL 2.0 注释

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

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

驱动程序批注 类别 用途

IRQL_requires_max ()

IRQL_requires_min ()

IRQL_raises ()

IRQL_requires ()

IRQL_raises ()

IRQL_saves

IRQL_restores

IRQL_saves_global (kind)

IRQL_restores_global (kind)

IRQL_always_function_min ()

IRQL_always_function_max ()

IRQL_requires_same

IRQL 批注

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

IRQL_is_cancel IRQL 批注

使用 IRQL_is_cancel 批注有助于确保 DRIVER_CANCEL 回调函数的正确行为。

Kernel_float_saved

Kernel_float_restored

Kernel_float_used

驱动程序的浮点批注

使用浮点批注可帮助代码分析工具在内核模式代码中检测浮点的使用情况,并在未正确保护浮点状态时报告错误。

Kernel_clear_do_init

DO_DEVICE_INITIALIZING 批注

使用 Kernel_clear_do_init 批注指定是否应使用批注的函数清除设备对象的 "标志" 字段中的 DO_DEVICE_INITIALIZING 位。

Kernel_IoGetDmaAdapter

Kernel_IoGetDmaAdapter 绘图

使用 Kernel_IoGetDmaAdapter 注释指示代码分析工具查找是否误用 DMA 指针。

Interlocked_operand

联锁操作数的批注

使用函数参数 Interlocked_operand 批注将它们标识为互锁操作数。 许多函数作为其参数之一,这是一个变量的地址,该变量应使用联锁处理器指令进行访问。 这些是缓存读取原子说明,如果未正确使用操作数,则会产生非常微妙的 bug。

Dispatch_type

驱动程序调度例程的注释

使用声明 WDM 驱动程序调度例程时使用的 Dispatch_type 注释。 请参阅 使用 WDM 驱动程序的函数角色类型声明函数批注驱动程序调度例程

Flt_CompletionContext_Outptr

Flt_CompletionContext_Outptr 绘图

在声明文件系统微筛选器预操作回调函数 (PFLT_PRE_OPERATION_CALLBACK) 时使用Flt_CompletionContext_Outptr注释。 将此批注放置在 CompletionContext 参数上。 此批注指示代码分析工具检查 CompletionContext 是否适用于 FLT_PREOP_CALLBACK_STATUS 返回值。

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