KBUGCHECK_CALLBACK_ROUTINE funzione di callback (wdm.h)

Articolo
08/08/2023

La routine BugCheckCallback viene eseguita ogni volta che il sistema genera un controllo di bug.

La funzione di callback KBUGCHECK_REASON_CALLBACK_ROUTINE offre più funzionalità di questo callback precedente.

Sintassi

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

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

Parametri

[in] Buffer

Puntatore al buffer specificato quando è stato registrato il callback.

[in] Length

Specifica la lunghezza, in byte, del buffer a cui punta il parametro Buffer .

Valore restituito

nessuno

Osservazioni

I driver possono fornire un bugCheckCallback che reimposta il dispositivo in uno stato noto se il sistema genera un controllo di bug.

Usare KeRegisterBugCheckCallback per registrare una routine BugCheckCallback . Un driver può successivamente rimuovere il callback usando la routine KeDeregisterBugCheckCallback . Se il driver può essere scaricato, deve rimuovere eventuali callback registrati nella routine di scaricamento .

Una routine BugCheckCallback è fortemente limitata nelle azioni che può essere eseguita. Per altre informazioni, vedere Scrittura di una routine di controllo bug. La routine può usare in modo sicuro le routineREAD_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX e WRITE_REGISTER_XXX per interagire con il dispositivo.

I driver che richiedono un'interazione più sofisticata con il sistema perché generano un controllo di bug possono invece implementare le routine KbCallbackDumpIo o KbCallbackSecondaryDumpData.

Si noti che a partire dai sistemi operativi Windows XP SP1 e Windows Server 2003, le routine BugCheckCallback vengono eseguite dopo che il file di dump del sistema è già stato scritto. Nelle versioni precedenti di Windows, le routine vengono eseguite prima della scrittura del file di dump di arresto anomalo. Pertanto, tutti i dati archiviati nel buffer specificato dal parametro Buffer non verranno visualizzati nel file di dump dell'arresto anomalo. I driver necessari per scrivere dati nel file di dump di arresto anomalo implementano invece una routine KbCallbackSecondaryDumpData. Nelle versioni precedenti di Windows, i dati scritti in Buffer vengono visualizzati nel file di dump di arresto anomalo.

Esempio

Per definire una routine di callback BugCheckCallback , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback BugCheckCallback denominata MyBugCheckCallback, usare il tipo di KBUGCHECK_CALLBACK_ROUTINE, come illustrato nell'esempio di codice seguente:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Implementare quindi la routine di callback come indicato di seguito:

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

Il tipo di funzione KBUGCHECK_CALLBACK_ROUTINE è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione KBUGCHECK_CALLBACK_ROUTINE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver WDM. Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.