PSHED_PI_RETRIEVE_ERROR_INFO回调函数 (ntddk.h)

项目
08/07/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 插件调用 PshedRegisterPlugin 函数以向 PSHED 注册自身时，在 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 插件设置 Callbacks.RetrieveErrorInfo，当插件调用 PshedRegisterPlugin 函数以向 PSHED 注册自身时，WHEA_PSHED_PLUGIN_REGISTRATION_PACKET结构的 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 成员中增加值，以考虑任何补充信息。

对于所有错误源，以最低 IRQL DISPATCH_LEVEL调用 PSHED 插件的 RetrieveErrorInfo 回调函数。 PSHED 插件的 RetrieveErrorInfo 回调函数只能执行操作，并调用该高 IRQL 级别允许的其他函数。

PSHED 插件的 RetrieveErrorInfo 回调函数的一项重要任务是确保WHEA_ERROR_PACKET的 ErrorSeverity 成员指定的错误条件的严重性适当。例如，如果 LLHEH 将错误条件的严重性级别报告为 WheaErrSevFatal ，但 PSHED 插件支持针对报告的特定错误条件的恢复机制，则 PSHED 插件可以将严重级别更改为 WheaErrSevRecoverable ，以便操作系统尝试从错误中恢复。同样，如果错误条件的严重性级别被 LLHEH 报告为 WheaErrSevRecoverable ，但 PSHED 插件识别到尝试恢复报告的特定错误条件只会进一步导致问题，则 PSHED 插件可以将严重级别更改为 WheaErrSevFatal ，以便操作系统不会尝试从错误中恢复。

对于更正的硬件错误，PSHED 插件必须从其 RetrieveErrorInfo 回调函数中检索处理错误条件所需的所有错误状态信息，因为硬件错误的其余处理不保证与 LLHEH 同步。