PSHED_PI_RETRIEVE_ERROR_INFO Rückruffunktion (ntddk.h)

Artikel
02/26/2024

Die Rückruffunktion RetrieveErrorInfo eines PSHED-Plug-Ins ruft plattformspezifische Fehlerinformationen zu einem aufgetretenen Hardwarefehler ab.

Syntax

PSHED_PI_RETRIEVE_ERROR_INFO PshedPiRetrieveErrorInfo;

NTSTATUS PshedPiRetrieveErrorInfo(
  [in, out, optional] PVOID PluginContext,
  [in]                PWHEA_ERROR_SOURCE_DESCRIPTOR ErrorSource,
  [in]                ULONGLONG BufferLength,
  [in, out]           PWHEA_ERROR_PACKET Packet
)
{...}

Parameter

[in, out, optional] PluginContext

Ein Zeiger auf den Kontextbereich, der im Kontextelement der WHEA_PSHED_PLUGIN_REGISTRATION_PACKET-Struktur angegeben wurde, als das PSHED-Plug-In die PshedRegisterPlugin-Funktion aufgerufen hat, um sich bei PSHED zu registrieren.

[in] ErrorSource

Ein Zeiger auf eine WHEA_ERROR_SOURCE_DESCRIPTOR Struktur, die die Fehlerquelle beschreibt, die den Hardwarefehler gemeldet hat.

[in] BufferLength

Die Größe des Puffers in Bytes, auf den der Packet-Parameter verweist.

[in, out] Packet

Ein Zeiger auf eine WHEA_ERROR_PACKET-Struktur , die das Hardwarefehlerpaket für den Hardwarefehler beschreibt.

Rückgabewert

Die Rückruffunktion RetrieveErrorInfo eines PSHED-Plug-Ins gibt einen der folgenden NTSTATUS-Codes zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Das Hardwarefehlerpaket wurde erfolgreich mit plattformspezifischen Fehlerinformationen aktualisiert.
STATUS_BUFFER_TOO_SMALL	Die Größe des Puffers, auf den der Packet-Parameter verweist, wie durch den Parameter BufferLength angegeben, ist zu klein, um das Hardwarefehlerpaket zu enthalten, wenn es mit den plattformspezifischen Fehlerinformationen aktualisiert wird.
STATUS_NOT_SUPPORTED	Das PSHED-Plug-In unterstützt die angegebene Fehlerquelle nicht.
STATUS_UNSUCCESSFUL	Ein Fehler ist aufgetreten.

Hinweise

Ein PSHED-Plug-In, das am Abruf von Fehlerinformationen beteiligt ist, legt die Rückruffunktionen Callbacks.RetrieveErrorInfo, Callbacks.FinalizeErrorRecord und Callbacks.ClearErrorStatus der WHEA_PSHED_PLUGIN_REGISTRATION_PACKET-Struktur fest, um auf die Rückruffunktionen RetrieveErrorInfo, FinalizeErrorRecord und ClearErrorStatus zu verweisen, wenn das Plug-In die PshedRegisterPlugin-Funktion aufruft, um sich bei PSHED zu registrieren. Das PSHED-Plug-In muss auch das PshedFAErrorInfoRetrieval-Flag im FunctionalAreaMask-Member der WHEA_PSHED_PLUGIN_REGISTRATION_PACKET-Struktur festlegen.

Jeder Hardwarefehlerhandler (Low-Level Hardware Error Handler, LLHEH) ruft den PSHED auf, um plattformspezifische Fehlerinformationen zu einem aufgetretenen Hardwarefehler abzurufen. Wenn ein PSHED-Plug-In für die Teilnahme am Abrufen von Fehlerinformationen registriert ist, ruft das PSHED die Rückruffunktion RetrieveErrorInfo des PSHED-Plug-Ins auf, damit das Hardwarefehlerpaket mit plattformspezifischen Fehlerinformationen aktualisiert werden kann. Das PSHED-Plug-In kann den vorhandenen Inhalt des Hardwarefehlerpakets ändern und dem Hardwarefehlerpaket zusätzliche Informationen hinzufügen. Zusätzliche Informationen werden einem Hardwarefehlerpaket hinzugefügt, beginnend mit dem Offset, der vom RawDataOffset-Element der WHEA_ERROR_PACKET-Struktur angegeben wird.

Ein PSHED-Plug-In muss sicherstellen, dass es keine zusätzlichen Informationen über das Ende des Hardwarefehlerpakets hinaus hinzugibt. Die Arbeitsspeichermenge, die ein LLHEH für einen Puffer reserviert, der ein bestimmtes Hardwarefehlerpaket enthält, wird aus dem MaxRawDataLength-Element der WHEA_ERROR_SOURCE_DESCRIPTOR-Struktur berechnet, die die Fehlerquelle beschreibt. Wenn ein PSHED-Plug-In zusätzliche Pufferspeicher benötigt, um die zusätzlichen Informationen zu enthalten, muss es an der Fehlerquellenermittlung teilnehmen und den Wert im MaxRawDataLength-Element der WHEA_ERROR_SOURCE_DESCRIPTOR-Struktur für jede Fehlerquelle entsprechend erhöhen, um zusätzliche Informationen zu berücksichtigen.

Für alle Fehlerquellen wird die Rückruffunktion RetrieveErrorInfo des PSHED-Plug-Ins mit einem IRQL von mindestens DISPATCH_LEVEL aufgerufen. Die Rückruffunktion RetrieveErrorInfo des PSHED-Plug-Ins darf nur Vorgänge ausführen und aufruft andere Funktionen, die auf dieser hohen IRQL-Ebene zulässig sind.

Eine wichtige Aufgabe der RetrieveErrorInfo-Rückruffunktion eines PSHED-Plug-Ins besteht darin, sicherzustellen, dass der Schweregrad der Fehlerbedingung gemäß dem ErrorSeverity-Member des WHEA_ERROR_PACKET angemessen ist. Wenn beispielsweise der Schweregrad der Fehlerbedingung vom LLHEH als WheaErrSevFatal gemeldet wird, das PSHED-Plug-In jedoch einen Wiederherstellungsmechanismus für die bestimmte gemeldete Fehlerbedingung unterstützt, kann das PSHED-Plug-In den Schweregrad in WheaErrSevRecoverable ändern, sodass das Betriebssystem versucht, den Fehler wiederherzustellen. Wenn der Schweregrad der Fehlerbedingung vom LLHEH als WheaErrSevRecoverable gemeldet wird, das PSHED-Plug-In jedoch erkennt, dass der Versuch der Wiederherstellung der gemeldeten bestimmten Fehlerbedingung nur weitere Probleme verursachen würde, kann das PSHED-Plug-In den Schweregrad in WheaErrSevFatal ändern, sodass das Betriebssystem keine Wiederherstellung nach dem Fehler versucht.

Bei korrigierten Hardwarefehlern muss ein PSHED-Plug-In alle Fehler status Informationen abrufen, die es für die Verarbeitung der Fehlerbedingung benötigt, aus seiner RetrieveErrorInfo-Rückruffunktion, da die restliche Verarbeitung des Hardwarefehlers nicht garantiert mit dem LLHEH synchronisiert wird.