PSHED_PI_RETRIEVE_ERROR_INFO コールバック関数 (ntddk.h)

[アーティクル]
03/08/2023

PSHED プラグインの RetrieveErrorInfo コールバック関数は、発生したハードウェアエラーに関するプラットフォーム固有のエラー情報を取得します。

構文

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
)
{...}

パラメーター

[in, out, optional] PluginContext

PSHED プラグインが PSHED に自身を登録するために PshedRegisterPlugin 関数を呼び出したときに、WHEA_PSHED_PLUGIN_REGISTRATION_PACKET 構造体の Context メンバーで指定されたコンテキスト領域へのポインター。

[in] ErrorSource

ハードウェアエラーを報告したエラーソースを記述する WHEA_ERROR_SOURCE_DESCRIPTOR 構造体へのポインター。

[in] BufferLength

Packet パラメーターが指すバッファーのサイズ (バイト単位)。

[in, out] Packet

ハードウェアエラーのハードウェアエラーパケットを記述する WHEA_ERROR_PACKET 構造体へのポインター。

戻り値

PSHED プラグインの RetrieveErrorInfo コールバック関数は、次のいずれかの NTSTATUS コードを返します。

リターンコード	説明
STATUS_SUCCESS	ハードウェアエラーパケットは、プラットフォーム固有のエラー情報で正常に更新されました。
STATUS_BUFFER_TOO_SMALL	BufferLength パラメーターで指定されている Packet パラメーターが指すバッファーのサイズが小さすぎて、プラットフォーム固有のエラー情報で更新された場合、ハードウェアエラーパケットを格納できません。
STATUS_NOT_SUPPORTED	PSHED プラグインは、指定されたエラーソースをサポートしていません。
STATUS_UNSUCCESSFUL	エラーが発生しました。

解説

エラー情報取得に参加する PSHED プラグインは、プラグインが PshedRegisterPlugin 関数を呼び出して PSHED に登録するときに、WHEA_PSHED_PLUGIN_REGISTRATION_PACKET 構造体の Callbacks.RetrieveErrorInfo、Callbacks.FinalizeErrorRecord、および Callbacks.ClearErrorStatus メンバーを、その RetrieveErrorInfo、FinalizeErrorRecord、ClearErrorStatus コールバック関数を指すように設定します。 PSHED プラグインは、WHEA_PSHED_PLUGIN_REGISTRATION_PACKET構造体の FunctionalAreaMask メンバーに PshedFAErrorInfoRetrieval フラグも設定する必要があります。

各低レベルのハードウェアエラーハンドラー (LLHEH) は PSHED を呼び出して、発生したハードウェアエラーに関するプラットフォーム固有のエラー情報を取得します。 PSHED プラグインがエラー情報の取得に参加するように登録されている場合、PSHED は PSHED プラグインの RetrieveErrorInfo コールバック関数を呼び出して、プラットフォーム固有のエラー情報でハードウェアエラーパケットを更新できるようにします。 PSHED プラグインは、ハードウェアエラーパケットの既存の内容を変更したり、ハードウェアエラーパケットに補足情報を追加したりできます。補足情報は、WHEA_ERROR_PACKET構造体の RawDataOffset メンバーによって指定されたオフセットから始まるハードウェアエラーパケットに追加されます。

PSHED プラグインは、ハードウェアエラーパケットの末尾を超えて補足情報を追加しないようにする必要があります。 LLHEH が特定のハードウェアエラーパケットを格納するためにバッファーに割り当てるメモリの量は、エラーソースを記述するWHEA_ERROR_SOURCE_DESCRIPTOR構造体の MaxRawDataLength メンバーから計算されます。 PSHED プラグインに補足情報を含めるために追加のバッファー領域が必要な場合は、エラーソースの検出に参加し、補足情報を考慮するために、各エラーソースのWHEA_ERROR_SOURCE_DESCRIPTOR構造体の MaxRawDataLength メンバーの値を増やす必要があります。

すべてのエラーソースについて、PSHED プラグインの RetrieveErrorInfo コールバック関数は、DISPATCH_LEVELの最小 IRQL で呼び出されます。 PSHED プラグインの RetrieveErrorInfo コールバック関数は、操作のみを実行し、その高 IRQL レベルで許可されている他の関数を呼び出す必要があります。

PSHED プラグインの RetrieveErrorInfo コールバック関数の重要なタスクは、WHEA_ERROR_PACKETの ErrorSeverity メンバーによって指定されたエラー条件の重大度が適切であることを確認することです。たとえば、エラー状態の重大度レベルが LLHEH によって WheaErrSevFatal として報告されているが、PSHED プラグインが報告された特定のエラー条件の回復メカニズムをサポートしている場合、PSHED プラグインは重大度レベルを WheaErrSevRecoverable に変更して、オペレーティングシステムがエラーからの回復を試みるようにすることができます。同様に、エラー状態の重大度レベルが LLHEH によって WheaErrSevRecoverable として報告されるが、報告された特定のエラー条件の回復を試みると、それ以上の問題が発生することが PSHED プラグインによって認識される場合、PSHED プラグインは重大度レベルを WheaErrSevFatal に変更して、オペレーティングシステムがエラーからの回復を試みないようにすることができます。

修正されたハードウェアエラーの場合、PSHED プラグインは、ハードウェアエラーの処理の残りの部分が LLHEH と同期されるとは限らないため、エラー状態を処理するために必要なすべてのエラー状態情報を RetrieveErrorInfo コールバック関数内から取得する必要があります。