KeRegisterBugCheckCallback

BOOLEAN
KeRegisterBugCheckCallback(
IN PKBUGCHECK_CALLBACK_RECORD CallbackRecord,
IN PKBUGCHECK_CALLBACK_ROUTINE CallbackRoutine,
IN PVOID Buffer,
IN ULONG Length,
IN PUCHAR Component
);

Device drivers can call KeRegisterBugCheckCallback to register their bug-check callback routines. If a system bug check occurs, such a callback usually saves device-state information to be written into the system crash dump file.

Parameters

CallbackRecord

Points to a callback record, already initialized with KeInitializeCallbackRecord, for which the caller provides nonpaged storage.

CallbackRoutine

Specifies the entry point of the caller-supplied routine to be registered, declared to conform to the following function type:

VOID
(*PKBUGCHECK_CALLBACK_ROUTINE) (
    IN PVOID Buffer,
    IN ULONG Length
    );

This caller-supplied routine is responsible for writing driver-determined state information at Buffer if a bug check occurs.

Buffer

Points to a caller-supplied buffer, which must be allocated from nonpaged pool.

Length

Specifies the size in bytes of the caller-allocated buffer.

Component

Points to a zero-terminated ANSI string identifying the caller. Usually, this is the name of the device driver, or possibly of its device.

Return Value

KeRegisterBugCheckCallback returns TRUE if the caller-supplied routine has been successfully added to the set of registered bug-check callbacks.

Comments

KeRegisterBugCheckCallback sets up a driver-supplied routine to be called if a bug check occurs so a device driver can save state information, such as the contents of device registers, that would not otherwise be saved in a system crash-dump file.

A driver-supplied bug-check callback routine writes whatever information the driver designer chooses into the memory at Buffer. The format of the data written at Buffer is driver-determined. This memory cannot be freed unless the driver first calls KeDeregisterBugCheckCallback. Like the driver-allocated memory at Buffer, such a bug-check callback routine cannot be pageable.

When the callback routine runs, interrupts are disabled. A callback routine cannot allocate resources, such as memory, because the system is being shut down. A bug-check callback also cannot use synchronization mechanisms, such as a spin lock. However, it should not need to acquire synchronization resources because other driver routines are effectively disabled while the system is being shut down for a bug check. The callback routine can safely call the HAL’s READ_PORT_XXX and/or READ_REGISTER_XXX to collect state information from the device and transfer this data to the driver-allocated buffer. It can call any KeXxx or HalXxx that neither allocates memory nor acquires a synchronization resource.

The given Component string should identify the driver to aid in crash-dump debugging. During driver development, the Component identifier can be passed to the debugger to select only that component’s dump data for examination. A bug-check callback routine also can be debugged.

Callers of KeRegisterBugCheckCallback can be running at any IRQL. Usually, a device driver is running at IRQL PASSIVE_LEVEL in its DriverEntry routine when it calls KeRegisterBugCheckCallback.