Utilisation du suivi logiciel WPP dans les pilotes UMDF

Article
03/08/2023

Le suivi logiciel WPP vous permet d’ajouter des messages de suivi qui vous aident à déboguer votre pilote. En outre, l’enregistreur d’événements de l’infrastructure fournit des centaines de messages de suivi que vous pouvez afficher.

Vous pouvez afficher les messages de suivi à l’aide de TraceView ou Tracelog. Vous pouvez également envoyer des messages de trace à un débogueur de noyau.

Ajout de messages de suivi à votre pilote

Pour ajouter des messages de suivi à votre pilote basé sur l’infrastructure, vous devez :

Ajoutez une directive #include à chacun des fichiers sources de votre pilote qui contient l’une des macros WPP. Cette directive doit identifier un fichier d’en-tête de message de trace (TMH). Le nom de fichier doit avoir un format driver-source-file-name.tmh><.

Par exemple, si votre pilote se compose de deux fichiers sources, appelés MyDriver1.c et MyDriver2.c, MyDriver1.c doit contenir :

#include "MyDriver1.tmh"

et MyDriver2.c doivent contenir :

#include "MyDriver2.tmh"

Lorsque vous générez votre pilote dans Microsoft Visual Studio, le préprocesseur WPP génère les fichiers .tmh.
Définissez une macro WPP_CONTROL_GUIDS dans un fichier d’en-tête. Cette macro définit un GUID et des indicateurs de trace pour les messages de suivi de votre pilote. (Pour chacun des exemples de pilotes basés sur UMDF de WDK, le fichier d’en-tête Internal.h inclut cette macro.)
Incluez une macro WPP_INIT_TRACING dans la routine DllMain de votre pilote. Cette macro active le suivi logiciel dans votre pilote. (Pour chacun des exemples de pilotes UMDF de WDK, le fichier d’en-tête DllSup.h inclut cette macro.)
Incluez une macro WPP_CLEANUP dans la routine DllMain de votre pilote. Cette macro désactive le suivi logiciel dans votre pilote. (Pour chacun des exemples de pilotes UMDF de WDK, le fichier d’en-tête DllSup.h inclut cette macro.)
Utilisez la macro DoTraceMessage ou une version personnalisée de la macro dans votre pilote pour créer des messages de trace. (Pour chacun des exemples de pilotes UMDF de WDK, le fichier d’en-tête Internal.h inclut une macro personnalisée.)
Ouvrez les pages de propriétés de votre projet de pilote. Cliquez avec le bouton droit sur le projet de pilote dans Explorateur de solutions, puis sélectionnez Propriétés. Dans les pages de propriétés du pilote, sélectionnez Propriétés de configuration, puis Wpp. Dans le menu Général , définissez Exécuter le suivi WPP sur Oui. Dans le menu Options de fichier, vous devez également spécifier le fichier de modèle WPP de l’infrastructure, par exemple :
```
{km-WdfDefault.tpl}*.tmh
```

Pour plus d’informations sur l’ajout de messages de suivi à votre pilote, consultez Ajout de macros WPP à un pilote.

Exemples de pilotes qui utilisent le suivi logiciel WPP

Tous les exemples de pilotes basés sur UMDF dans WDK fournissent des fichiers DllSup.h, Internal.h et Sources qui activent le suivi logiciel WPP. La plupart de ces exemples de pilotes utilisent également une macro personnalisée pour créer des messages de trace.

Affichage des messages de trace de votre pilote

Si vous avez ajouté des messages de trace à votre pilote, celui-ci est un fournisseur de traces. Vous pouvez utiliser un contrôleur de trace, tel que Tracelog, pour contrôler une session de suivi et créer un journal de suivi. Vous pouvez utiliser un consommateur de traces, tel que Tracefmt, pour afficher les messages.

Pour plus d’informations sur l’utilisation des outils de suivi logiciel, consultez Survey of Software Tracing Tools.

Affichage du journal des traces UMDF

Le fichier journal UMDF se trouve dans %ProgramData%*\\Microsoft\\WDF.

Vous pouvez afficher le fichier journal UMDF à l’aide de TraceView ou tracelog. Les deux outils nécessitent des fichiers TMF (Trace Message Format) qui mettez en forme les messages du journal de trace. Les fichiers TMF sont disponibles dans le WDK, sous le sous-répertoire \tools\tracing. (Dans TraceView, UMDF apparaît en tant que fournisseur nommé avec le nom « UMDF-Framework Trace » ou « Framework Trace », selon la version d’UMDF.)

WDF Verifier vous permet d’envoyer des messages de trace au journal des traces UMDF et à votre débogueur de noyau. (Vous ne devez pas envoyer de messages de trace à votre débogueur de noyau à l’aide de l’option -kd dans Tracelog, car Tracelog peut perturber la journalisation des traces dans UMDF.)

Vous pouvez également utiliser l’extension de débogueur !wmitrace pour afficher les messages de trace dans le débogueur :

Dans WinDbg, attachez-vous au instance de WUDFHost qui héberge le pilote. Pour plus d’informations, consultez Comment activer le débogage d’un pilote UMDF.
Si votre pilote utilise la version 1.11 ou ultérieure et que vous utilisez le débogueur de noyau à partir de Windows 8 ou d’une version ultérieure, vous pouvez ignorer cette étape. Si votre pilote utilise une version d’UMDF antérieure à 1.11, utilisez !wmitrace.tmffile ou !wmitrace.searchpath 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 wdK.
Utilisez la commande !wmitrace.logdump pour afficher le contenu des mémoires tampons de trace :
```
!wmitrace.logdump WudfTrace
```

Contrôle des messages de trace

Vous pouvez contrôler les messages de trace UMDF avec l’interface utilisateur que WDF Verifier fournit ou en modifiant les valeurs de Registre. Vous devez utiliser l’interface WDF Verifier dans la mesure du possible, car les valeurs de Registre peuvent changer dans les versions ultérieures d’UMDF. En outre, vous ne devez pas accéder à ces valeurs dans les fichiers INF ou le code de votre pilote.

Actuellement, vous pouvez modifier les valeurs de Registre suivantes, qui se trouvent sous la clé de Registre HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF :

La valeur LogEnable contrôle si UMDF crée un journal de suivi pour votre pilote. Si cette valeur est définie sur 1, UMDF crée un journal de suivi.
La valeur LogLevel contrôle la quantité d’informations que contiennent les messages de trace UMDF. La valeur par défaut de LogLevel est 3, ce qui fait que les messages de trace UMDF contiennent des messages d’erreur et d’avertissement. Définissez cette valeur sur 7 pour inclure les messages d’erreur et d’avertissement, ainsi que les messages d’information sans erreur. Définissez-la sur 15 pour inclure toutes les informations de trace qu’UMDF est capable de fournir.
La valeur LogKd contrôle si UMDF envoie des messages de trace à votre débogueur de noyau. Si LogKd est défini sur 1, UMDF envoie ses messages de trace à votre débogueur de noyau.
La valeur LogFlushPeriodSeconds spécifie la fréquence à laquelle, en secondes, les messages de trace sont écrits dans le journal de suivi.
La valeur LogMinidumpType contient des indicateurs qui spécifient le type d’informations qu’un fichier de mini-vidage, s’il est produit, contiendra. Pour plus d’informations sur ces indicateurs, consultez l’énumération MINIDUMP_TYPE .

Vous pouvez trouver d’autres valeurs de Registre sous la clé de Registre HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF . Vous ne devez pas modifier ces valeurs.

Partager via