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 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:


KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Then, implement your callback routine as follows:


_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    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.

Requirements

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

Called at HIGH_LEVEL.

See also

KeDeregisterBugCheckCallback
KeRegisterBugCheckCallback
BugCheckDumpIoCallback
BugCheckSecondaryDumpDataCallback

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.