PSHED_PI_RETRIEVE_ERROR_INFO función de devolución de llamada (ntddk.h)

Artículo
03/08/2023

Una función de devolución de llamada RetrieveErrorInfo del complemento PSHED recupera información de error específica de la plataforma sobre un error de hardware que se ha producido.

Sintaxis

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

Parámetros

[in, out, optional] PluginContext

Puntero al área de contexto que se especificó en el miembro Context de la estructura WHEA_PSHED_PLUGIN_REGISTRATION_PACKET cuando el complemento PSHED llamó a la función PshedRegisterPlugin para registrarse con el PSHED.

[in] ErrorSource

Puntero a una estructura de WHEA_ERROR_SOURCE_DESCRIPTOR que describe el origen de error que informó del error de hardware.

[in] BufferLength

Tamaño, en bytes, del búfer al que apunta el parámetro Packet .

[in, out] Packet

Puntero a una estructura de WHEA_ERROR_PACKET que describe el paquete de error de hardware para el error de hardware.

Valor devuelto

Una función de devolución de llamada RetrieveErrorInfo del complemento PSHED devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	El paquete de error de hardware se actualizó correctamente con cualquier información de error específica de la plataforma.
STATUS_BUFFER_TOO_SMALL	El tamaño del búfer al que apunta el parámetro Packet especificado por el parámetro BufferLength es demasiado pequeño para contener el paquete de error de hardware si se actualiza con la información de error específica de la plataforma.
STATUS_NOT_SUPPORTED	El complemento PSHED no admite el origen de error especificado.
STATUS_UNSUCCESSFUL	Se produjo un error.

Comentarios

Un complemento PSHED que participa en la recuperación de información de error establece los miembros Callbacks.RetrieveErrorInfo, Callbacks.FinalizeErrorRecord y Callbacks.ClearErrorStatus de la estructura de WHEA_PSHED_PLUGIN_REGISTRATION_PACKET para que apunten a sus funciones de devolución de llamada RetrieveErrorInfo, FinalizeErrorRecord y ClearErrorStatus cuando el complemento llama a la función PshedRegisterPlugin para registrarse en el PSHED. El complemento PSHED también debe establecer la marca PshedFAErrorInfoRetrieval en el miembro FunctionalAreaMask de la estructura WHEA_PSHED_PLUGIN_REGISTRATION_PACKET.

Cada controlador de errores de hardware de bajo nivel (LLHEH) llama al PSHED para recuperar cualquier información de error específica de la plataforma sobre un error de hardware que se ha producido. Si se registra un complemento PSHED para participar en la recuperación de información de error, PSHED llama a la función de devolución de llamada RetrieveErrorInfo del complemento PSHED para que pueda actualizar el paquete de error de hardware con cualquier información de error específica de la plataforma. El complemento PSHED puede modificar el contenido existente del paquete de error de hardware, así como agregar información complementaria al paquete de error de hardware. La información complementaria se agrega a un paquete de error de hardware que comienza en el desplazamiento especificado por el miembro RawDataOffset de la estructura de WHEA_ERROR_PACKET .

Un complemento PSHED debe asegurarse de que no agrega información complementaria más allá del final del paquete de error de hardware. La cantidad de memoria que asigna un LLHEH para que un búfer contenga un paquete de error de hardware determinado se calcula a partir del miembro MaxRawDataLength de la estructura WHEA_ERROR_SOURCE_DESCRIPTOR que describe el origen del error. Si un complemento PSHED requiere espacio de búfer adicional para contener la información complementaria, debe participar en la detección de origen de errores y aumentar el valor en el miembro MaxRawDataLength de la estructura WHEA_ERROR_SOURCE_DESCRIPTOR para cada origen de error según corresponda para tener en cuenta cualquier información complementaria.

Para todos los orígenes de error, la función de devolución de llamada RetrieveErrorInfo del complemento PSHED se llama como mínimo a IRQL de DISPATCH_LEVEL. La función de devolución de llamada RetrieveErrorInfo del complemento PSHED solo debe realizar operaciones y realizar llamadas a otras funciones permitidas en ese nivel de IRQL alto.

Una tarea importante de la función de devolución de llamada RetrieveErrorInfo de un complemento PSHED es asegurarse de que la gravedad de la condición de error especificada por el miembro ErrorSeverity del WHEA_ERROR_PACKET es adecuada. Por ejemplo, si el nivel de gravedad de la condición de error se notifica como WheaErrSevFatal por LLHEH, pero el complemento PSHED admite un mecanismo de recuperación para la condición de error concreta que se informó, el complemento PSHED puede cambiar el nivel de gravedad a WheaErrSevRecoverable para que el sistema operativo intente recuperarse del error. Del mismo modo, si el nivel de gravedad de la condición de error se notifica como WheaErrSevRecoverable por llHEH, pero el complemento PSHED reconoce que intentar recuperar la condición de error concreta que se informó solo causaría más problemas, el complemento PSHED puede cambiar el nivel de gravedad a WheaErrSevFatal para que el sistema operativo no intente recuperarse del error.

Para los errores de hardware corregidos, un complemento PSHED debe recuperar toda la información de estado de error que requiere para procesar la condición de error desde su función de devolución de llamada RetrieveErrorInfo , ya que no se garantiza que el resto del procesamiento del error de hardware se sincronice con llHEH.