KBUGCHECK_CALLBACK_ROUTINE回调函数 (wdm.h)

项目
02/27/2024

每当系统发出 bug 检查时，就会执行 BugCheckCallback 例程。

KBUGCHECK_REASON_CALLBACK_ROUTINE回调函数提供的功能比此旧回调更多。

语法

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

参数

[in] Buffer

指向注册回调时指定的缓冲区的指针。

[in] Length

指定 Buffer 参数指向 的缓冲区的长度（以字节为单位）。

返回值

无

备注

如果系统发出 bug 检查，驱动程序可以提供 BugCheckCallback，将设备重置为已知状态。

使用 KeRegisterBugCheckCallback 注册 BugCheckCallback 例程。驱动程序随后可以使用 KeDeregisterBugCheckCallback 例程删除回调。如果驱动程序可以卸载，则必须删除其 Unload 例程中的任何已注册回调。

BugCheckCallback 例程在可以执行的操作方面受到严格的限制。有关详细信息，请参阅编写 Bug 检查回调例程。例程可以安全地使用 READ_PORT_XXX、 READ_REGISTER_XXX、 WRITE_PORT_XXX 和 WRITE_REGISTER_XXX 例程来与设备交互。

在发出 bug 检查需要与系统进行更复杂的交互的驱动程序可以改为实现 KbCallbackDumpIo 或 KbCallbackSecondaryDumpData 例程。

请注意，从 Windows XP SP1 和 Windows Server 2003 操作系统开始， BugCheckCallback 例程在编写系统故障转储文件后执行。 (在早期版本的 Windows 上，例程在写入故障转储文件之前执行。) 因此， 存储在 Buffer 参数指定的缓冲区中的任何数据都不会显示在故障转储文件中。将数据写入故障转储文件所需的驱动程序实现 KbCallbackSecondaryDumpData 例程。 (在早期版本的 Windows 上，写入 缓冲区 的数据确实显示在故障转储文件中。)

示例

若要定义 BugCheckCallback 回调例程，必须先提供一个函数声明来标识要定义的回调例程的类型。 Windows 为驱动程序提供了一组回调函数类型。使用回调函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为 MyBugCheckCallback的 BugCheckCallback 回调例程，请使用 KBUGCHECK_CALLBACK_ROUTINE 类型，如以下代码示例所示：

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

KBUGCHECK_CALLBACK_ROUTINE函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中KBUGCHECK_CALLBACK_ROUTINE函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关 Use_decl_annotations的信息，请参阅批注函数行为。