KBUGCHECK_CALLBACK_ROUTINE callback function (wdm.h)

The BugCheckCallback routine is executed whenever the system issues a bug check.


The KBUGCHECK_REASON_CALLBACK_ROUTINE callback function offers more functionality than this older callback.



void KbugcheckCallbackRoutine(
  IN PVOID Buffer,
  IN ULONG Length



[in] A pointer to the buffer that was specified when the callback was registered.


[in] Specifies the length, in bytes, of the buffer that is pointed to by the Buffer parameter.

Return value



Drivers can supply a BugCheckCallback that resets the device to a known state if the system issues a bug check.

Use KeRegisterBugCheckCallback to register a BugCheckCallback routine. A driver can subsequently remove the callback by using the KeDeregisterBugCheckCallback routine. If the driver can be unloaded, it must remove any registered callbacks in its Unload routine.

A BugCheckCallback routine is strongly restricted in the actions it can take. For more information, see Writing a Bug Check Callback Routine. The routine can safely use the READ_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX, and WRITE_REGISTER_XXX routines to interact with the device.

Drivers that require more sophisticated interaction with the system as it issues a bug check can instead implement KbCallbackDumpIo or KbCallbackSecondaryDumpData routines.

Note that beginning with the Windows XP SP1 and Windows Server 2003 operating systems, BugCheckCallback routines execute after the system crash dump file has already been written. (On earlier versions of Windows, the routines execute before the crash dump file is written.) Thus, any data that is stored in the buffer specified by the Buffer parameter will not appear in the crash dump file. Drivers that are required to write data to the crash dump file instead implement a KbCallbackSecondaryDumpData routine. (On earlier versions of Windows, the data written to Buffer does appear in the crash dump file.)


To define a BugCheckCallback callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a BugCheckCallback callback routine that is named MyBugCheckCallback, use the KBUGCHECK_CALLBACK_ROUTINE type as shown in this code example:


Then, implement your callback routine as follows:

    PVOID  Buffer,
    ULONG  Length
      // Function body

The KBUGCHECK_CALLBACK_ROUTINE function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the KBUGCHECK_CALLBACK_ROUTINE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about Use_decl_annotations, see Annotating Function Behavior.


Target Platform Desktop
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)

See also

Writing a Bug Check Callback Routine