This topic has not yet been rated - Rate this topic

BugCheckCallback routine

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

Syntax


KBUGCHECK_CALLBACK_ROUTINE BugCheckCallback;

VOID BugCheckCallback(
  _In_  PVOID Buffer,
  _In_  ULONG Length
)
{ ... }

Parameters

Buffer [in]: A pointer to the buffer that was specified when the callback was registered.
Length [in]: Specifies the length, in bytes, of the buffer that is pointed to by the Buffer parameter.

Return value

None

Remarks

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 BugCheckDumpIoCallback or BugCheckSecondaryDumpDataCallback 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 BugCheckSecondaryDumpDataCallback routine. (On earlier versions of Windows, the data written to Buffer does appear in the crash dump file.)

Examples

To define a BugCheckCallback routine that is named MyBugCheckCallback, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as shown in the following code example:


KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Then, implement your callback routine as follows:


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

The KBUGCHECK_CALLBACK_ROUTINE function type is defined in the Wdm.h header file. For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for WDM Drivers.

Requirements

Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
IRQL	Called at HIGH_LEVEL.