Utilisation de l’enregistreur d’événements de l’infrastructure

  • Article

WDF comprend un enregistreur de suivi interne, parfois appelé Enregistreur en vol (IFR) de l’infrastructure. L’enregistreur WDF crée un journal de suivi qui contient un historique récent des événements pour chaque pilote WDF. Les journaux de suivi suivent la progression des paquets de demandes d’E/S (IRPs) via l’infrastructure et les requêtes correspondantes via un pilote. Chaque pilote Kernel-Mode Driver Framework (KMDF) et User-Mode Driver Framework (UMDF) a son propre journal.

L’enregistreur WDF est toujours activé. Pour chaque journal de suivi, l’enregistreur d’événements stocke les enregistrements d’événements dans une mémoire tampon circulaire. Si vous le souhaitez, vous pouvez activer le détail, ce qui permet à l’enregistreur d’événements d’enregistrer des informations supplémentaires qui peuvent vous aider à déboguer votre pilote, telles que les entrées ou les sorties de chemins de code internes. Par défaut, la taille de la mémoire tampon est d’une page mémoire et le détail est désactivé. Vous pouvez modifier la taille et le détail de la mémoire tampon en ajustant ces valeurs dans l’application WdfVerifier. Notez que l’activation du détail peut dégrader les performances du système.

Vous pouvez utiliser des extensions de débogueur WDF pour afficher et enregistrer le journal WDF pendant le débogage interactif. Pour afficher le journal WDF pendant une session de débogage :

  1. Chargez les symboles appropriés. Vous pouvez utiliser la commande .symfix+ débogueur pour ajouter le magasin de symboles publics Microsoft à votre chemin de symbole existant. Le magasin de symboles public inclut des symboles pour les fichiers binaires WDF. Vous pouvez également charger des symboles pour vos symboles de pilote.

    Pour plus d’informations sur l’obtention des symboles Window et la définition du chemin d’accès aux symboles du débogueur, consultez la documentation fournie avec le package débogage Windows .

  2. Chargez la bibliothèque d’extensionsWdfkd.dll dans votre débogueur. Si vous utilisez le débogueur de noyau, vous pouvez le faire à l’aide de la commande .load . Pour charger la version correcte de Wdfkd.dll vous devez spécifier le chemin complet de la DLL. Par exemple, vous utilisez le chemin d’accès suivant sur un ordinateur hôte de débogueur x86 :

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    Vous pouvez ensuite vérifier que l’extension est chargée à l’aide de la commande !chain pour afficher toutes les extensions chargées.

    Pour plus d’informations sur l’extension du débogueur d’infrastructure, utilisez l’extension !wdfhelp . Pour plus d’informations sur le débogueur de noyau, consultez la documentation fournie avec le package de débogage Windows .

  3. Si votre pilote utilise framework version 1.11 ou ultérieure et que vous utilisez le débogueur de noyau à partir de Windows 8 ou version ultérieure, vous pouvez ignorer cette étape.

    Si votre pilote utilise une version du framework antérieure à 1.11, utilisez !wdftmffile ou !wdfsearchpath pour spécifier un fichier de format de message de trace spécifique à la plateforme (.tmf) ou un chemin d’accès à un fichier .tmf. Les fichiers .tmf se trouvent dans des sous-répertoires spécifiques à la plateforme dans le WDK.

    Étant donné que les fichiers .tmf sont spécifiques à la version, vous devez spécifier un fichier .tmf qui correspond à la version de la bibliothèque runtime de l’infrastructure en cours d’exécution. Par exemple, si KMDF version 1.9 s’exécute sur l’ordinateur hôte :

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    Vous pouvez également définir le chemin de recherche en définissant la variable d’environnement TRACE_FORMAT_SEARCH_PATH. La commande !wdftmffile est prioritaire sur le chemin de recherche défini par la variable d’environnement.

    Pour vérifier le numéro de version du framework, vous pouvez exécuter la commande d’extension du débogueur !wdfldr à partir du débogueur du noyau.

  4. Utilisez l’extension !wdflogdump pour afficher les enregistrements de l’enregistreur d’événements. Par exemple, la capture d’écran suivante d’une fenêtre de commande WinDbg montre un exemple typique de la sortie de !wdflogdump :

    Capture d’écran de la sortie de l’extension !wdflogdump dans la fenêtre De commande WinDbg.

Chaque ligne du journal de l’infrastructure est précédée d’une chaîne appelée préfixe de message de trace. L’enregistreur de suivi ajoute ce préfixe à chaque message écrit dans le journal. Par défaut, le préfixe inclut un ensemble standard d’éléments de données, mais vous pouvez modifier les éléments par défaut en fonction de vos besoins particuliers. Vous pouvez modifier la chaîne de préfixe d’un pilote WDF en définissant la variable d’environnement TRACE_FORMAT_PREFIX ou en utilisant la commande d’extension du débogueur !wdfsettraceprefix .

Pour définir la variable d’environnement, utilisez une commande similaire à ce qui suit :

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

Cette commande définit le préfixe de message de trace comme suit :

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

Vous pouvez également utiliser la commande d’extension !wdflogsave pour enregistrer les enregistrements de l’enregistreur d’événements dans un fichier journal de suivi des événements (.etl) que vous pouvez afficher à l’aide de TraceView.

Vous pouvez parfois utiliser l’extension de débogueur !wdfcrashdump sur un vidage sur incident pour afficher les informations de journal après les vérifications des bogues système. Les informations de journal sont disponibles dans le vidage sur incident uniquement si l’infrastructure peut déterminer que votre pilote a provoqué le bogue case activée ou si vous avez défini la valeur de Registre ForceLogsInMiniDump pour le pilote.

Si un débogueur est attaché lorsque le bogue case activée se produit, vous pouvez utiliser !wdfcrashdump pour afficher immédiatement les informations du journal, ou vous pouvez afficher les informations en chargeant le fichier de vidage mémoire. En raison des limitations de taille d’un petit fichier de vidage de mémoire, le journal du pilote à l’origine de l’incident peut ne pas apparaître dans le vidage.

L’infrastructure peut déterminer si un pilote particulier a provoqué le bogue case activée codes suivants :

À compter d’UMDF version 2, UMDF stocke le journal de trace UMDF (ou IFR UMDF) dans la mémoire non paginée du noyau. L’infrastructure alloue un instance IFR par hôte de pilote (Wudfhost).

Pour plus d’informations sur les commandes d’extension du débogueur, consultez Extensions de débogueur pour les pilotes basés sur framework.