KBUGCHECK_CALLBACK_ROUTINE função de retorno de chamada (wdm.h)

Artigo
08/08/2023

A rotina BugCheckCallback é executada sempre que o sistema emite um bug marcar.

A função de retorno de chamada KBUGCHECK_REASON_CALLBACK_ROUTINE oferece mais funcionalidade do que esse retorno de chamada mais antigo.

Sintaxe

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

Parâmetros

[in] Buffer

Um ponteiro para o buffer que foi especificado quando o retorno de chamada foi registrado.

[in] Length

Especifica o comprimento, em bytes, do buffer apontado pelo parâmetro Buffer .

Retornar valor

Nenhum

Comentários

Os drivers podem fornecer um BugCheckCallback que redefine o dispositivo para um estado conhecido se o sistema emitir um bug marcar.

Use KeRegisterBugCheckCallback para registrar uma rotina BugCheckCallback . Um driver pode remover posteriormente o retorno de chamada usando a rotina KeDeregisterBugCheckCallback . Se o driver puder ser descarregado, ele deverá remover quaisquer retornos de chamada registrados em sua rotina de descarregamento .

Uma rotina BugCheckCallback é fortemente restrita nas ações que ela pode executar. Para obter mais informações, consulte Escrevendo uma rotina de retorno de chamada de verificação de bugs. A rotina pode usar com segurança as rotinas READ_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX e WRITE_REGISTER_XXX para interagir com o dispositivo.

Drivers que exigem interação mais sofisticada com o sistema, pois ele emite um bug marcar podem implementar rotinas KbCallbackDumpIo ou KbCallbackSecondaryDumpData.

Observe que, a partir dos sistemas operacionais Windows XP SP1 e Windows Server 2003, as rotinas BugCheckCallback são executadas depois que o arquivo de despejo de falha do sistema já foi gravado. (Em versões anteriores do Windows, as rotinas são executadas antes que o arquivo de despejo de falha seja gravado.) Assim, todos os dados armazenados no buffer especificado pelo parâmetro Buffer não aparecerão no arquivo de despejo de memória. Os drivers necessários para gravar dados no arquivo de despejo de memória em vez disso implementam uma rotina KbCallbackSecondaryDumpData. (Em versões anteriores do Windows, os dados gravados no Buffer aparecem no arquivo de despejo de memória.)

Exemplos

Para definir uma rotina de retorno de chamada BugCheckCallback , primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada BugCheckCallback chamada MyBugCheckCallback, use o tipo KBUGCHECK_CALLBACK_ROUTINE conforme mostrado neste exemplo de código:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

O tipo de função KBUGCHECK_CALLBACK_ROUTINE é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função KBUGCHECK_CALLBACK_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.