Export (0) Print
Expand All

BugCheckAddPagesCallback routine

The BugCheckAddPagesCallback routine adds one or more pages of data to the crash dump file when the operating system issues a bug check.

Syntax


KBUGCHECK_REASON_CALLBACK_ROUTINE BugCheckAddPagesCallback;

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

Parameters

Reason [in]

Specifies the reason for the call to the callback routine. For a call to a BugCheckAddPagesCallback routine, the value of this parameter is always KbCallbackAddPages. This value indicates that the purpose of the callback is to enable the driver to add pages of data to the crash dump file. KbCallbackAddPages is a KBUGCHECK_CALLBACK_REASON enumeration value.

Record [in]

A pointer to the KBUGCHECK_REASON_CALLBACK_RECORD structure that the driver supplied when it registered this callback. For more information, see the description of the CallbackRecord parameter in KeRegisterBugCheckCallback.

ReasonSpecificData [in, out]

A pointer to a KBUGCHECK_ADD_PAGES structure. This pointer is cast to type PVOID. Certain members of this structure are filled in by the operating system before it calls the callback routine, and other members must be filled in by the callback routine. For more information, see the following Remarks section.

ReasonSpecificDataLength [in]

Specifies the size, in bytes, of the buffer that the ReasonSpecificData parameter points to. For a call to a BugCheckAddPagesCallback routine, the value of this parameter is always sizeof(KBUGCHECK_ADD_PAGES).

Return value

None.

Remarks

A kernel-mode driver can implement a BugCheckAddPagesCallback callback routine to add one or more pages of data to a crash dump file when a bug check occurs. To register this routine with the operating system, the driver calls the KeRegisterBugCheckReasonCallback routine. Before the driver unloads, it must call the KeDeregisterBugCheckReasonCallback routine to remove the registration.

Starting with Windows 8, a registered BugCheckAddPagesCallback routine is called during a kernel memory dump or a complete memory dump. In earlier versions of Windows, a registered BugCheckAddPagesCallback routine is called during a kernel memory dump, but not during a complete memory dump. By default, a kernel memory dump includes only the physical pages that are being used by the Windows kernel at the time that the bug check occurs, whereas a complete memory dump includes all of the physical memory that is used by Windows. A complete memory dump does not, by default, include physical memory that is used by the platform firmware.

Your BugCheckAddPagesCallback routine can supply driver-specific data to add to the dump file. For example, for a kernel memory dump, this additional data can include physical pages that are not mapped to the system address range in virtual memory but that contain information that can help you to debug your driver. The BugCheckAddPagesCallback routine might add to the dump file any driver-owned physical pages that are unmapped or that are mapped to user-mode addresses in virtual memory.

When a bug check occurs, the operating system calls all the registered BugCheckAddPagesCallback routines to poll drivers for data to add to the crash dump file. Each call adds one or more pages of contiguous data to the crash dump file. A BugCheckAddPagesCallback routine can supply either a virtual address or a physical address for the starting page. If more than one page is supplied during a call, the pages are contiguous in either virtual or physical memory, depending on whether the starting address is virtual or physical. To supply noncontiguous pages, the BugCheckAddPagesCallback routine can set a flag in the KBUGCHECK_ADD_PAGES structure to indicate that it has additional data and has to be called again. For more information, see KBUGCHECK_ADD_PAGES.

Unlike a BugCheckSecondaryDumpDataCallback routine, which appends data to the secondary crash dump region, a BugCheckAddPagesCallback routine adds pages of data to the primary crash dump region. During debugging, primary crash dump data is easier to access than secondary crash dump data.

Before the operating system calls a BugCheckAddPagesCallback routine, it fills in the BugCheckCode member of the KBUGCHECK_ADD_PAGES structure that ReasonSpecificData points to. During the call, the BugCheckAddPagesCallback routine must set the values of the Flags, Address, and Count members of this structure. If the BugCheckAddPagesCallback routine is called more than one time, the operating system preserves the value that the callback routine wrote to the Context member in the previous call. Before the first call, the operating system initializes Context to NULL.

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

Examples

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


KBUGCHECK_REASON_CALLBACK_ROUTINE MyBugCheckAddPagesCallback;

Then, implement your callback routine as follows:


_Use_decl_annotations_
VOID
  MyBugCheckAddPagesCallback(
    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

Supported starting with Windows Server 2008.

Header

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

IRQL

Called at HIGH_LEVEL.

See also

BugCheckSecondaryDumpDataCallback
KBUGCHECK_ADD_PAGES
KBUGCHECK_CALLBACK_REASON
KBUGCHECK_REASON_CALLBACK_RECORD
KeDeregisterBugCheckReasonCallback
KeRegisterBugCheckReasonCallback

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft