Puis-je personnaliser DoTraceMessage ?

Article
06/15/2023

Oui, vous pouvez écrire votre propre version de la macro DoTraceMessage . DoTraceMessage génère un message de trace.

L’exemple de pilote TraceDrv fournit un exemple des méthodes décrites dans cette rubrique. TraceDrv est disponible dans le référentiel d’exemples de pilotes Windows sur GitHub.

DoTraceMessage : version par défaut

Par défaut, la macro DoTraceMessage a le format suivant :

DoTraceMessage(Flag,"Message",MessageVariables...);

Dans cette version par défaut, Flag représente les indicateurs de trace, qui sont les conditions dans lesquelles le message est généré. MessageVariables contient une liste séparée par des virgules des variables que le pilote définit et qui apparaissent dans le message de trace. Les variables MessageVariables sont mises en forme à l’aide des éléments printf . Le préprocesseur WPP crée une directive de compilateur à partir de la macro DoTraceMessage. Cette macro ajoute les informations de définition de message et les informations de mise en forme au fichier PDB qui a été généré pour le fournisseur de trace, comme un pilote en mode noyau ou une application en mode utilisateur.

La macro DoTraceMessage est développée logiquement dans les éléments suivants :

PRE macro // If defined
If (WPP_CHECK_INIT && Flag is enabled) {
 ....Call WmiTraceMessage;
}
POST macro // If defined

Considérez l’exemple de code suivant.

DoTraceMessage(ERROR, "IOCTL = %d", ControlCode);

Cet appel génère le message de trace lorsque l’indicateur ERROR est activé. Le message est « IOCTL=%d » et messageVariables est la valeur de ControlCode.

Si les macros PRE-logging et POST-logging ont été définies, elles seront également développées. Les macros PRE et POST sont prises en charge dans les systèmes d’exploitation Microsoft Windows 2000 et ultérieurs. Pour utiliser les macros, vous devez générer le pilote à l’aide de WDK. Si vous générez un pilote à l’aide d’une version antérieure du Kit de développement de pilotes Windows (DDK), les fonctionnalités PRE et POST ne sont pas disponibles et les macros ne seront pas exécutées dans le cadre de l’instruction trace. La génération du pilote à l’aide d’une version antérieure du DDK Windows peut ne pas provoquer d’interruption de build, mais le code ne fonctionnera pas comme prévu.

DoTraceMessage : Format général

Voici un format général d’une fonction de message de trace valide :

FunctionName(Conditions...,"Message",MessageVariables...);

Les paramètres qui apparaissent avant le message sont interprétés comme des conditions. Les paramètres qui apparaissent après le message sont interprétés comme des variables de message.

Conditions est une liste de valeurs séparées par des virgules. Le message de trace est généré uniquement si toutes les conditions sont remplies. Vous pouvez spécifier n’importe quelle condition prise en charge dans le code.

Exemple : MyTrace

Voici un exemple de fonction de suivi. Cet exemple montre comment ajouter des conditions pour le niveau de suivi et le sous-composant du fournisseur qui génère le message de trace.

MyDoTrace(Level, Flag, Subcomponent,"Message",MessageVariables...);

Par exemple :

MyDoTrace(TRACE_LEVEL_ERROR, VERBOSE, Network,"IOCTL = %d", ControlCode);

Le niveau de suivi est le niveau standard défini dans Evntrace.h, un fichier d’en-tête public qui se trouve dans le sous-répertoire Include du WDK.

#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(for example, Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9

Comment créer une fonction de suivi personnalisée

Pour créer une fonction de suivi personnalisée, procédez comme suit :

Écrivez d’autres versions des macros qui prennent en charge la macro DoTraceMessage.
Ajoutez le paramètre -func à l’instruction RUN_WPP qui appelle le préprocesseur WPP.

Écrire des macros personnalisées

Pour créer une fonction de suivi personnalisée qui modifie les conditions d’un message de trace (les paramètres qui apparaissent avant le message), vous devez écrire d’autres versions des macros qui prennent en charge les fonctions de suivi, WPP_LEVEL_ENABLED et WPP_LEVEL_LOGGER.

WPP_LEVEL_ENABLED(Flags) détermine si la journalisation est activée avec la valeur d’indicateur spécifiée. Elle retourne TRUE ou FALSE.
WPP_LEVEL_LOGGER(Indicateurs) recherche la session de suivi sur laquelle le fournisseur est activé et retourne un handle à la session de trace.

Par exemple, si vous souhaitez inclure le niveau de trace, en plus des indicateurs, comme condition, définissez une nouvelle WPP_LEVEL_ENABLED macro qui inclut le niveau de trace. Vous pouvez baser la définition de la nouvelle macro sur la macro par défaut, comme le montre l’exemple de code suivant.

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >=lvl

En règle générale, la macro WPP_LEVEL_LOGGER n’est pas affectée. Dans ce cas, vous pouvez définir la nouvelle macro comme macro par défaut. Par exemple :

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) WPP_LEVEL_LOGGER(flags)

Toutefois, dans certains cas, vous devez modifier la macro LOGGER. Par exemple, vous pouvez écrire une fonction de suivi qui dépend uniquement du niveau de trace et non des indicateurs.

Dans l’exemple de code suivant, la valeur des indicateurs dans la macro est remplacée par une valeur factice. Aucun indicateur n’est défini lors de la déclaration de la définition GUID de contrôle.

#define WPP_CONTROL_GUIDS \
   WPP_DEFINE_CONTROL_GUID(CtlGuid,(a044090f,3d9d,48cf,b7ee,9fb114702dc1),  \
        WPP_DEFINE_BIT(DUMMY))

#define WPP_LEVEL_LOGGER(lvl) (WPP_CONTROL(WPP_BIT_ ## DUMMY).Logger)

Ajouter la fonction à WPP

Pour ajouter la fonction de suivi personnalisé à WPP, ajoutez le paramètre -func à l’instruction RUN_WPP avec une déclaration de la fonction, comme le montre l’exemple de code suivant.

RUN_WPP=$(SOURCES) -km -func:DoTraceLevelMessage(LEVEL,FLAGS,MSG,...)

Note Vous ne devez pas spécifier le commutateur -km dans la directive RUN_WPP pour les applications en mode utilisateur ou les bibliothèques de liens dynamiques (DLL).

Pour obtenir la liste complète des paramètres facultatifs pour RUN_WPP, consultez Préprocesseur WPP.

Partager via