Export (0) Print
Expand All

BugCheckSecondaryDumpDataCallback routine

The BugCheckSecondaryDumpDataCallback routine provides data to the system to append to the crash dump file when the system issues a bug check.

Syntax


KBUGCHECK_REASON_CALLBACK_ROUTINE BugCheckSecondaryDumpDataCallback;

VOID BugCheckSecondaryDumpDataCallback(
  _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 BugCheckSecondaryDumpDataCallback, the value of this parameter is always KbCallbackSecondaryDumpData.

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_SECONDARY_DUMP_DATA structure. Certain members of this structure are populated by the system, and others must be supplied by the callback.

ReasonSpecificDataLength [in]

Specifies the size, in bytes, of the buffer supplied by the ReasonSpecificData parameter. For BugCheckSecondaryDumpDataCallback, the value of this parameter is always sizeof(KBUGCHECK_SECONDARY_DUMP_DATA).

Return value

None

Remarks

The system uses BugCheckSecondaryDumpDataCallback routines to poll drivers for crash dump data.

The system sets the InBuffer, InBufferLength, OutBuffer, and MaximumAllowed members of the KBUGCHECK_SECONDARY_DUMP_DATA structure that ReasonSpecificData points to. The MaximumAllowed member specifies the maximum amount of dump data the routine can provide.

The value of the OutBuffer member determines whether the system is requesting the size of the driver's dump data, or the data itself, as follows:

  • If the OutBuffer member of KBUGCHECK_SECONDARY_DUMP_DATA is NULL, the system is only requesting size information. The BugCheckSecondaryDumpDataCallback routine fills in the OutBuffer and OutBufferLength members.

  • If the OutBuffer member of KBUGCHECK_SECONDARY_DUMP_DATA equals the InBuffer member, the system is requesting the driver's secondary dump data. The BugCheckSecondaryDumpDataCallback routine fills in the OutBuffer and OutBufferLength members, and writes the data to the buffer specified by OutBuffer.

The InBuffer member of KBUGCHECK_SECONDARY_DUMP_DATA points to a small buffer for the routine's use. The InBufferLength member specifies the size of the buffer. If the amount of data to be written is less than InBufferLength, the callback routine can use this buffer to supply the crash dump data to the system. The callback routine then sets OutBuffer to InBuffer and OutBufferLength to the actual amount of data written to the buffer.

A driver that must write an amount of data that is larger than InBufferLength can use its own buffer to provide the data. This buffer must have been allocated before the callback routine is executed, and must reside in resident memory (such as nonpaged pool). The callback routine then sets OutBuffer to point to the driver's buffer, and OutBufferLength to the amount of data in the buffer to be written to the crash dump file.

In Windows XP and Windows Server 2003, if OutBuffer is set to point to a driver-allocated buffer, the buffer must begin on a page-aligned boundary in memory. Otherwise, no data is written to the secondary data area of the crash dump file. In Windows Vista and later versions of Windows, there is no such alignment requirement.

Each block of data to be written to the crash dump file is tagged with the value of the Guid member of KBUGCHECK_SECONDARY_DUMP_DATA. The GUID used must be unique to the driver. To display the secondary dump data corresponding to this GUID, you can use the .enumtag command or the IDebugDataSpaces3::ReadTagged method in a debugger extension. For information about debuggers and debugger extensions, see Windows Debugging.

A driver can write multiple blocks with the same GUID to the crash dump file, but this is very poor practice, because only the first block will be accessible to the debugger. Drivers that register multiple BugCheckSecondaryDumpDataCallback routines should allocate a unique GUID for each callback.

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

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

Examples

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


KBUGCHECK_REASON_CALLBACK_ROUTINE MyBugCheckSecondaryDumpDataCallback;

Then, implement your callback routine as follows:


_Use_decl_annotations_
VOID
  MyBugCheckSecondaryDumpDataCallback(
    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 BugCheckSecondaryDumpDataCallback 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_REASON_CALLBACK_RECORD
KBUGCHECK_SECONDARY_DUMP_DATA
KeDeregisterBugCheckCallback
KeRegisterBugCheckCallback
BugCheckDumpIoCallback
BugCheckAddPagesCallback

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft