PSHED_PI_RETRIEVE_ERROR_INFO função de retorno de chamada (ntddk.h)

Artigo
03/08/2023

A função de retorno de chamada RetrieveErrorInfo de um plug-in PSHED recupera informações de erro específicas da plataforma sobre um erro de hardware ocorrido.

Sintaxe

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

Um ponteiro para a área de contexto especificada no membro Context da estrutura WHEA_PSHED_PLUGIN_REGISTRATION_PACKET quando o plug-in PSHED chamou a função PshedRegisterPlugin para se registrar no PSHED.

[in] ErrorSource

Um ponteiro para uma estrutura WHEA_ERROR_SOURCE_DESCRIPTOR que descreve a origem do erro que relatou o erro de hardware.

[in] BufferLength

O tamanho, em bytes, do buffer apontado pelo parâmetro Packet .

[in, out] Packet

Um ponteiro para uma estrutura WHEA_ERROR_PACKET que descreve o pacote de erro de hardware para o erro de hardware.

Retornar valor

A função de retorno de chamada RetrieveErrorInfo de um plug-in PSHED retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O pacote de erro de hardware foi atualizado com êxito com qualquer informação de erro específica da plataforma.
STATUS_BUFFER_TOO_SMALL	O tamanho do buffer apontado pelo parâmetro Packet conforme especificado pelo parâmetro BufferLength é muito pequeno para conter o pacote de erro de hardware se ele for atualizado com as informações de erro específicas da plataforma.
STATUS_NOT_SUPPORTED	O plug-in PSHED não dá suporte à origem de erro especificada.
STATUS_UNSUCCESSFUL	Ocorreu um erro.

Comentários

Um plug-in PSHED que participa da recuperação de informações de erro define o Callbacks.RetrieveErrorInfo, Os membros Callbacks.FinalizeErrorRecord e Callbacks.ClearErrorStatus da estrutura WHEA_PSHED_PLUGIN_REGISTRATION_PACKET para apontar para suas funções de retorno de chamada RetrieveErrorInfo, FinalizeErrorRecord e ClearErrorStatus quando o plug-in chama a função PshedRegisterPlugin para se registrar no PSHED. O plug-in PSHED também deve definir o sinalizador PshedFAErrorInfoRetrieval no membro FunctionalAreaMask da estrutura WHEA_PSHED_PLUGIN_REGISTRATION_PACKET.

Cada LLHEH (manipulador de erros de hardware) de baixo nível chama o PSHED para recuperar qualquer informação de erro específica da plataforma sobre um erro de hardware ocorrido. Se um plug-in PSHED estiver registrado para participar da recuperação de informações de erro, o PSHED chamará a função de retorno de chamada RetrieveErrorInfo do plug-in PSHED para que ele possa atualizar o pacote de erro de hardware com qualquer informação de erro específica da plataforma. O plug-in PSHED pode modificar o conteúdo existente do pacote de erro de hardware, bem como adicionar informações suplementares ao pacote de erro de hardware. Informações suplementares são adicionadas a um pacote de erro de hardware começando no deslocamento especificado pelo membro RawDataOffset da estrutura WHEA_ERROR_PACKET .

Um plug-in PSHED deve garantir que ele não adicione informações suplementares além do final do pacote de erro de hardware. A quantidade de memória que um LLHEH aloca para um buffer para conter um pacote de erro de hardware específico é calculada do membro MaxRawDataLength da estrutura WHEA_ERROR_SOURCE_DESCRIPTOR que descreve a origem do erro. Se um plug-in PSHED exigir espaço de buffer adicional para conter as informações suplementares, ele deverá participar da descoberta de origem do erro e aumentar o valor no membro MaxRawDataLength da estrutura WHEA_ERROR_SOURCE_DESCRIPTOR para cada fonte de erro, conforme apropriado, para levar em conta as informações complementares.

Para todas as fontes de erro, a função de retorno de chamada RetrieveErrorInfo do plug-in PSHED é chamada em um IRQL mínimo de DISPATCH_LEVEL. A função de retorno de chamada RetrieveErrorInfo do plug-in PSHED só deve executar operações e fazer chamadas para outras funções permitidas nesse alto nível de IRQL.

Uma tarefa importante da função de retorno de chamada RetrieveErrorInfo de um plug-in PSHED é garantir que a gravidade da condição de erro, conforme especificado pelo membro ErrorSeverity do WHEA_ERROR_PACKET seja apropriada. Por exemplo, se o nível de gravidade da condição de erro for relatado como WheaErrSevFatal pelo LLHEH, mas o plug-in PSHED der suporte a um mecanismo de recuperação para a condição de erro específica relatada, o plug-in PSHED poderá alterar o nível de gravidade para WheaErrSevRecoverable para que o sistema operacional tente se recuperar do erro. Da mesma forma, se o nível de gravidade da condição de erro for relatado como WheaErrSevRecoverable pelo LLHEH, mas o plug-in PSHED reconhecer que a tentativa de recuperação da condição de erro específica relatada só causaria mais problemas, o plug-in PSHED poderá alterar o nível de gravidade para WheaErrSevFatal para que o sistema operacional não tente se recuperar do erro.

Para erros de hardware corrigidos, um plug-in PSHED deve recuperar todas as informações de status de erro necessárias para processar a condição de erro de dentro de sua função de retorno de chamada RetrieveErrorInfo, pois o restante do processamento do erro de hardware não tem garantia de ser sincronizado com o LLHEH.