适用于 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 驱动程序工具包 (WDK) 8 一起使用，以便Windows 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_

使用函数参数 的互锁操作数的注释 将它们标识为互锁操作数。 许多函数将应使用互锁处理器指令访问的变量的地址作为其参数之一。 这些是缓存读取原子指令，如果操作数使用不当，则会产生非常细微的 bug。

驱动程序调度例程的注释

_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++ 代码缺陷