BugCheckDumpIoCallback

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

VOID
  BugcheckDumpIoCallback (
    IN KBUGCHECK_CALLBACK_REASON Reason,
    IN PKBUGCHECK_REASON_CALLBACK_RECORD Record,
    IN OUT PVOID ReasonSpecificData,
    IN ULONG ReasonSpecificDataLength 
    );

Parameters

Reason

Specifies the situation in which the callback is executed. For BugCheckDumpIoCallback, this parameter is always KbCallbackDumpIo.

Record

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

ReasonSpecificData

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

ReasonSpecificDataLength

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

Return Value

None

Comments

Drivers can only implement BugCheckDumpIoCallback routines on Windows XP SP1, Windows Server 2003, and later operating systems.

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

BugCheckDumpIoCallback routines execute at IRQL = HIGH_LEVEL.

See Also

KBUGCHECK_DUMP_IO, KBUGCHECK_DUMP_IO_TYPE, KBUGCHECK_REASON_CALLBACK_RECORD, KeBugCheck, KeBugCheckEx, KeDeregisterBugCheckCallback, KeRegisterBugCheckCallback, BugCheckCallback, BugCheckSecondaryDumpDataCallback