BugCheckDumpIoCallback routine

The BugCheckDumpIoCallback routine is executed each time the system writes data to a crash dump file.

Syntax


KBUGCHECK_REASON_CALLBACK_ROUTINE BugCheckDumpIoCallback;

VOID BugCheckDumpIoCallback(
  _In_     KBUGCHECK_CALLBACK_REASON Reason,
  _In_     struct _KBUGCHECK_REASON_CALLBACK_RECORD *Record,
  _Inout_  PVOID ReasonSpecificData,
  _In_     ULONG ReasonSpecificDataLength
)
{ ... }

Parameters

Reason [in]

Specifies the situation in which the callback is executed. For BugCheckDumpIoCallback, the value of this parameter is always KbCallbackDumpIo. KbCallbackDumpIo is a KBUGCHECK_CALLBACK_REASON enumeration value.

Record [in]

Pointer to the KBUGCHECK_REASON_CALLBACK_RECORD structure that the driver passed when registering this callback.

ReasonSpecificData [in, out]

Pointer to a KBUGCHECK_DUMP_IO structure that describes the current I/O operation.

ReasonSpecificDataLength [in]

Specifies the size of the buffer supplied by the ReasonSpecificData parameter. For BugCheckDumpIoCallback, the value of this parameter is always sizeof(KBUGCHECK_DUMP_IO).

Return value

None

Remarks

The driver's BugCheckDumpIoCallback routine is called each time data is written to the crash dump file. The system passes, in the ReasonSpecificData parameter, a description of the data being written. The Buffer member points to the current data, and the BufferLength member specifies its length. The Type member indicates the type of data currently being written, such as dump file header information, memory state, or data provided by a driver. For a description of the possible types of information, see KBUGCHECK_DUMP_IO_TYPE.

The system can write the crash dump file either sequentially, or out of order. If the system is writing the crash dump file sequentially, then the Offset member of ReasonSpecificData is -1; otherwise, Offset is set to the current offset, in bytes, in the crash dump file.

When the system writes the file sequentially, it calls each BugCheckDumpIoCallback routine one or more times when writing the header information (Type = KbDumpIoHeader), one or more times when writing the main body of the crash dump file (Type = KbDumpIoBody), and one or more times when writing the secondary dump data (Type = KbDumpIoSecondaryDumpData). Once the system has completed writing the crash dump file, it calls the callback with Buffer = NULL, BufferLength = 0, and Type = KbDumpIoComplete.

The main purpose of a BugCheckDumpIoCallback routine is to allow system crash dump data to be written to devices other than the disk. For example, a device that monitors system state can use the callback to report that the system has issued a bug check, and to provide a crash dump for analysis.

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

A BugCheckDumpIoCallback routine is strongly restricted in the actions it can take. For more information, see Writing a Bug Check Callback Routine.

Examples

To define a BugCheckDumpIoCallback 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 BugCheckDumpIoCallback callback routine that is named MyBugCheckDumpIoCallback, use the KBUGCHECK_REASON_CALLBACK_ROUTINE type as shown in this code example:


KBUGCHECK_REASON_CALLBACK_ROUTINE MyBugcheckDumpIoCallback;

Then, implement your callback routine as follows:


_Use_decl_annotations_
VOID
  MyBugcheckDumpIoCallback(
    KBUGCHECK_CALLBACK_REASON  Reason,
    struct _KBUGCHECK_REASON_CALLBACK_RECORD  *Record,
    PVOID  ReasonSpecificData,
    ULONG  ReasonSpecificDataLength 
    )
  {
      // Function body
  }

The KBUGCHECK_REASON_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_REASON_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

Version

Drivers can implement BugCheckDumpIoCallback routines starting with Windows XP SP1 and Windows Server 2003.

Header

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

IRQL

Called at HIGH_LEVEL.

See also

KBUGCHECK_DUMP_IO
KBUGCHECK_DUMP_IO_TYPE
KBUGCHECK_REASON_CALLBACK_RECORD
KeBugCheck
KeBugCheckEx
KeDeregisterBugCheckCallback
KeRegisterBugCheckCallback
BugCheckCallback
BugCheckSecondaryDumpDataCallback

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft