KBUGCHECK_CALLBACK_ROUTINE Rückruffunktion (wdm.h)

Artikel
02/29/2024

Die BugCheckCallback-Routine wird immer ausgeführt, wenn das System eine Fehlerüberprüfung ausgibt.

Die KBUGCHECK_REASON_CALLBACK_ROUTINE Rückruffunktion bietet mehr Funktionen als dieser ältere Rückruf.

Syntax

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

Parameter

[in] Buffer

Ein Zeiger auf den Puffer, der beim Registrieren des Rückrufs angegeben wurde.

[in] Length

Gibt die Länge des Puffers in Bytes an, auf den der Buffer-Parameter verweist.

Rückgabewert

Keine

Bemerkungen

Treiber können einen BugCheckCallback bereitstellen, der das Gerät in einen bekannten Zustand zurücksetzt, wenn das System eine Fehlerprüfung ausgibt.

Verwenden Sie KeRegisterBugCheckCallback , um eine BugCheckCallback-Routine zu registrieren. Ein Treiber kann den Rückruf anschließend mithilfe der KeDeregisterBugCheckCallback-Routine entfernen. Wenn der Treiber entladen werden kann, muss er alle registrierten Rückrufe in seiner Unload-Routine entfernen.

Eine BugCheckCallback-Routine ist in den Aktionen, die sie ausführen kann, stark eingeschränkt. Weitere Informationen finden Sie unter Schreiben einer Rückrufroutine für die Fehlerüberprüfung. Die Routine kann die Routinen READ_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX und WRITE_REGISTER_XXX sicher verwenden, um mit dem Gerät zu interagieren.

Treiber, die eine komplexere Interaktion mit dem System erfordern, während es eine Fehlerüberprüfung ausgibt, können stattdessen KbCallbackDumpIo- oder KbCallbackSecondaryDumpData-Routinen implementieren.

Beachten Sie, dass ab den Betriebssystemen Windows XP SP1 und Windows Server 2003 BugCheckCallback-Routinen ausgeführt werden, nachdem die Systemabbilddatei bereits geschrieben wurde. (In früheren Versionen von Windows werden die Routinen ausgeführt, bevor die Absturzabbilddatei geschrieben wird.) Daher werden alle Daten, die in dem durch den Buffer-Parameter angegebenen Puffer gespeichert sind, nicht in der Absturzabbilddatei angezeigt. Treiber, die zum Schreiben von Daten in die Absturzabbilddatei erforderlich sind, implementieren stattdessen eine KbCallbackSecondaryDumpData-Routine. (In früheren Versionen von Windows werden die in Buffer geschriebenen Daten in der Absturzabbilddatei angezeigt.)

Beispiele

Um eine BugCheckCallback-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine BugCheckCallback-Rückrufroutine mit dem Namen MyBugCheckCallbackzu definieren, verwenden Sie den typ KBUGCHECK_CALLBACK_ROUTINE, wie in diesem Codebeispiel gezeigt:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

Der KBUGCHECK_CALLBACK_ROUTINE Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den KBUGCHECK_CALLBACK_ROUTINE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.