KBUGCHECK_CALLBACK_ROUTINE fonction de rappel (wdm.h)

Article
02/27/2024

La routine BugCheckCallback est exécutée chaque fois que le système émet un bogue case activée.

La fonction de rappel KBUGCHECK_REASON_CALLBACK_ROUTINE offre plus de fonctionnalités que cet ancien rappel.

Syntaxe

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

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

Paramètres

[in] Buffer

Pointeur vers la mémoire tampon spécifiée lors de l’inscription du rappel.

[in] Length

Spécifie la longueur, en octets, de la mémoire tampon pointée par le paramètre Buffer .

Valeur de retour

None

Remarques

Les pilotes peuvent fournir un BugCheckCallback qui réinitialise l’appareil à un état connu si le système émet un bogue case activée.

Utilisez KeRegisterBugCheckCallback pour inscrire une routine BugCheckCallback . Un pilote peut ensuite supprimer le rappel à l’aide de la routine KeDeregisterBugCheckCallback . Si le pilote peut être déchargé, il doit supprimer tous les rappels inscrits dans sa routine de déchargement .

Une routine BugCheckCallback est fortement limitée dans les actions qu’elle peut effectuer. Pour plus d’informations, consultez Écriture d’une routine de rappel de vérification de bogue. La routine peut utiliser en toute sécurité les routines READ_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX et WRITE_REGISTER_XXX pour interagir avec l’appareil.

Les pilotes qui nécessitent une interaction plus sophistiquée avec le système car il émet un bogue case activée peuvent à la place implémenter des routines KbCallbackDumpIo ou KbCallbackSecondaryDumpData.

Notez qu’à compter des systèmes d’exploitation Windows XP SP1 et Windows Server 2003, les routines BugCheckCallback s’exécutent après que le fichier de vidage sur incident du système a déjà été écrit. (Sur les versions antérieures de Windows, les routines s’exécutent avant l’écriture du fichier de vidage sur incident.) Par conséquent, toutes les données stockées dans la mémoire tampon spécifiée par le paramètre Buffer n’apparaîtront pas dans le fichier de vidage sur incident. Les pilotes requis pour écrire des données dans le fichier de vidage sur incident implémentent plutôt une routine KbCallbackSecondaryDumpData. (Sur les versions antérieures de Windows, les données écrites dans Buffer apparaissent dans le fichier de vidage sur incident.)

Exemples

Pour définir une routine de rappel BugCheckCallback , vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel BugCheckCallback nommée MyBugCheckCallback, utilisez le type KBUGCHECK_CALLBACK_ROUTINE comme indiqué dans cet exemple de code :

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Ensuite, implémentez votre routine de rappel comme suit :

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

Le type de fonction KBUGCHECK_CALLBACK_ROUTINE est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction KBUGCHECK_CALLBACK_ROUTINE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.