Préprocesseur WPP
Cette section décrit le préprocesseur de trace logicielle Windows, communément appelé préprocesseur WPP.
Appel du préprocesseur WPP
Vous pouvez appeler le préprocesseur WPP à l’aide de Visual Studio et de l’environnement MSBuild.
Pour appeler le préprocesseur WPP
Cliquez avec le bouton droit sur le projet de pilote dans l’Explorateur de solutions, puis cliquez sur Propriétés.
Dans la page de propriétés du projet, cliquez sur Propriétés de configuration, puis sur Suivi WPP
Sous Général, définissez l’option Exécuter WPP sur Oui.
Sous Ligne de commande, vous pouvez ajouter des options ci-dessous pour personnaliser le comportement de suivi.
Par exemple, sous Suivi WPP, vous pouvez spécifier un seul fichier de données de configuration de l’analyse.
Si vous devez fournir plusieurs fichiers de configuration, par exemple pour spécifier des types de données personnalisés, référencez votre fichier en ligne de commande à l’aide de l’option -scan , par exemple :
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
Pour plus d’informations sur le processus de génération, consultez la tâche TraceWPP et l’environnement de génération WDK et Visual Studio.
Vous pouvez également exécuter le préprocesseur distinct de l’environnement de génération à l’aide de l’outil TraceWPP (TraceWPP.exe). Cet outil se trouve dans le sous-répertoire bin/x86 du WDK.
Options générales du suivi WPP
Les tableaux suivants décrivent les options du préprocesseur WPP. Vous pouvez configurer ces options dans Visual Studio à l’aide de la page de propriétés suivi WPP de votre projet ou en tant que paramètres pour l’outil TraceWPP.
| Option de suivi WPP | Description |
|---|---|
Exécuter WPP |
Si la valeur est true, appelle WPP. |
Activer la reconstruction minimale |
Si la valeur est true, une build incrémentielle suivie est effectuée ; si la valeur est false, une reconstruction est effectuée. |
Options de fonction et de macro
| Option de suivi WPP | Option de commande TraceWPP | Description |
|---|---|---|
Définitions de préprocesseur |
-DMacro |
Ajoute #define macro au début du fichier généré où Macro est le nom d’une macro. Cette option a le même effet que l’option de compilateur /D (définir une macro). Il est inclus pour s’assurer que les définitions sont valides au début des fichiers TMH. |
-DMacro=Expansion |
Ajoute #define extension de macro au début du fichier généré où macro est le nom d’une macro et l’expansion est la valeur développée. Cette option a le même effet que l’option de compilateur /D (définir une macro). Il est inclus pour s’assurer que les définitions sont valides au début des fichiers TMH. |
|
Composants en mode noyau de trace |
-kilomètre |
Définit la macro WPP_KERNEL_MODE, qui trace les composants en mode noyau. Par défaut, seuls les composants en mode utilisateur sont suivis. |
Activer la macro dll |
-dll |
Définit la macro WPP_DLL, ce qui entraîne l’initialisation des structures de données WPP chaque fois que WPP_INIT_TRACING est appelée. Sinon, les structures ne sont initialisées qu’une seule fois. |
Spécifier le GUID de contrôle |
-ctl : GUID |
Définit une macro WPP_CONTROL_GUIDS avec le GUID de contrôle spécifié et les entrées WPP_DEFINE_BIT nommées Erreur, Inhabituel et Noise.
Il s’agit d’une alternative à l’ajout de la macro au fichier source. GUID représente le GUID de contrôle. |
Options de recherche et de mise en forme
| Option de suivi WPP | Option de commande TraceWPP | Description |
|---|---|---|
Ignorer les marques d’exclamation |
-noshrieks |
Dirige WPP pour ignorer les marques d’exclamation, également appelées « cris ». Utilisé dans la mise en forme complexe, par exemple % !timestamp !%. Par défaut, les marques d’exclamation sont requises et WPP tente de les interpréter. |
Base numérique pour la numérotation des chaînes de format |
-argbase : Nombre |
Établit une base numérique pour la numérotation des chaînes de format, telles que « %1 !d !, %2 !s ! ». La valeur par défaut est 1. |
Fonction pour générer des messages de trace |
-func : FunctionDescription |
Spécifie des alternatives à la macro DoTraceMessage. Ces fonctions peuvent ensuite être utilisées pour générer des messages de trace. Par exemple, vous pouvez définir une fonction qui spécifie les indicateurs et le niveau d’un message de trace, par exemple : Vous pouvez utiliser plusieurs instances de l’option -func . Cette option est une alternative à la spécification des descriptions de fonction dans un fichier de configuration local. |
Spécifier la chaîne à rechercher |
-lookfor :String |
Dirige WPP pour rechercher les fichiers sources de la chaîne spécifiée pour lancer le suivi. Par défaut, WPP recherche la chaîne « WPP_INIT_TRACING ». Il s’agit d’une option avancée pour les utilisateurs qui écrivent leurs propres modèles. Par exemple, dans default.tpl : |
Spécifier le nom du module |
-p : String |
Spécifie un autre nom convivial pour le GUID de message des messages de ce fournisseur de trace. Par défaut, le nom convivial du GUID du message est le nom du répertoire dans lequel le fournisseur de trace a été créé. Le nom convivial du GUID du message s’affiche, par défaut, dans le préfixe de message de trace représenté par la variable %1. Vous pouvez utiliser ce paramètre pour ajouter une chaîne au préfixe qui permet à l’utilisateur d’identifier le fournisseur de trace, tel que le nom convivial du fournisseur de trace, le nom du module qui inclut le fournisseur de trace ou le nom d’un projet implémenté en créant plusieurs fournisseurs de trace. Ces informations permettent aux utilisateurs d’associer des fournisseurs de trace associés qui se trouvent dans différents fichiers ou chemins d’accès différents. Le paramètre -p nécessite la version de WPP incluse dans le Kit de pilotes Windows (WDK) pour Windows Vista et les versions ultérieures de WDK. Le paramètre -p fonctionne sur Windows 2000 et les versions ultérieures de Windows. Exemples : |
Options de fichier
| Option de suivi WPP | Option de commande TraceWPP | Description |
|---|---|---|
Autres répertoires Include |
-I Path1[ ;Chemin d’accès2] |
Spécifie un ou plusieurs répertoires à ajouter au chemin include. Si vous ajoutez plusieurs répertoires, séparez-les par des points-virgules. Identique à -cfgdir. |
Répertoires de configuration |
-cfgdir : Path1[ ;Chemin d’accès2] |
Spécifie l’emplacement des fichiers de configuration et de modèle. Path1 et Path2 représentent le chemin complet d’un répertoire. Vous pouvez spécifier plusieurs chemins d’accès. La valeur par défaut est le répertoire local. |
Extensions de fichier |
-Poste:. ext1 [.ext2] |
Spécifie les types de fichiers que WPP reconnaît en tant que fichiers sources. WPP ignore les fichiers avec une autre extension de nom de fichier. Par défaut, WPP reconnaît uniquement les fichiers .c, .c++, .cpp et .cxx. Cette option vous permet d’utiliser les paramètres par défaut pour WPP sans avoir à supprimer ou renommer des fichiers de ressources que WPP n’utilise pas, tels que les fichiers .rc et .mc. Par exemple, pour ajouter le suivi aux fichiers C++ et aux fichiers d’en-tête (.h), utilisez la commande suivante : -ext:.cpp. CPP.h.H En outre, pour donner aux fichiers TMH des fichiers C++ et d’en-tête différents noms, utilisez l’option -preserveext . |
Conserver les extensions de fichier |
-preserveext : .ext1[.ext2] |
Conserve les extensions de nom de fichier spécifiées lors de la création de fichiers TMH. Par défaut, les fichiers TMH pour tous les types de fichiers sont nommés filename.tmh. Cela a provoqué des conflits de nom de fichier lorsque vous avez plusieurs fichiers sources portant le même nom. Par exemple, par défaut, les fichiers TMH pour les fichiers C (.c) et les fichiers d’en-tête (.h) sont nommés <filename.tmh>. À l’aide de -preserveext :.c .h, les fichiers TMH sont nommés <filename.c.tmh et <filename.h.tmh>>. |
Répertoire de sortie |
-odir : chemin d’accès | Spécifie le répertoire des fichiers de sortie créés par WPP. Chemin d’accès complet au répertoire. La valeur par défaut est le répertoire local. |
Spécifier un fichier de modèle |
-gen{ File.tpl }. ext |
Pour chaque fichier source que WPP traite avec le nom spécifié entre accolades {}, créez un autre fichier avec l’extension de nom de fichier spécifiée. File.tpl représente le fichier source. *.ext représente le type de fichier créé et son extension de nom de fichier. Vous pouvez spécifier plusieurs options -gen . Par exemple, -gen{um-default.tpl}.tmh signifie que pour chaque fichier um-default.tpl que WPP traite, il produit un fichier um-default.tmh . |
Analyser les données de configuration |
-scan :File |
Recherche des données de configuration, telles que des types de données personnalisés, dans un fichier qui n’est pas un fichier de configuration, ainsi que dans defaultwpp.ini. Placez begin_wpp configuration et end_wpp chaînes autour des données de configuration pour l’identifier. Utilisez le même format pour les données de configuration que celles utilisées dans defaultwpp.ini. Si vous avez ajouté les données de configuration à un fichier de configuration personnalisé, utilisez le paramètre -ini . |
Autre fichier de configuration |
-defwpp :path |
Spécifie un autre fichier de configuration. Wpp utilise ce fichier au lieu du fichier defaultwpp.ini. |
Fichier de configuration supplémentaire |
-ini :Path |
Spécifie un fichier de configuration supplémentaire. WPP utilise le fichier spécifié en plus du fichier par défaut, defaultwpp.ini. Utilisez ce paramètre lorsque vous avez créé un fichier de configuration pour stocker les données de configuration pour le suivi. Si vous avez ajouté les données de configuration à un autre type de fichier, tel qu’un fichier source ou un fichier d’en-tête, utilisez le paramètre -scan . |
Processus de génération WPP
Si WPP est activé pour une application en mode pilote ou en mode utilisateur, la génération du pilote ou de l’application appelle le préprocesseur WPP avant la compilation des fichiers du pilote ou de l’application.
Le processus de génération WPP effectue les étapes suivantes :
Le préprocesseur WPP traite les macros WPP dans chaque fichier source et crée un fichier d’en-tête de message de trace pour chaque fichier source. Le code source n’est pas directement modifié.
Une fois le préprocesseur WPP créé les fichiers d’en-tête de message de trace, le préprocesseur C traite les macros WPP intégrées dans les fichiers d’en-tête de message de trace de manière normale.