Posso personalizzare DoTraceMessage?

Articolo
03/08/2023

Sì, è possibile scrivere la propria versione della macro DoTraceMessage . DoTraceMessage genera un messaggio di traccia.

Il driver di esempio TraceDrv fornisce un esempio dei metodi descritti in questo argomento. TraceDrv è disponibile nel repository di esempi di driver Di Windows in GitHub.

DoTraceMessage: versione predefinita

Per impostazione predefinita, la macro DoTraceMessage ha il formato seguente:

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

In questa versione predefinita flag rappresenta i flag di traccia, ovvero le condizioni in cui viene generato il messaggio. MessageVariables contiene un elenco delimitato da virgole di variabili definite dal driver e visualizzate nel messaggio di traccia. Le variabili MessageVariables vengono formattate usando gli elementi printf . Il preprocessore WPP crea una direttiva del compilatore dalla macro DoTraceMessage. Questa macro aggiunge le informazioni sulla definizione del messaggio e la formattazione al file PDB generato per il provider di traccia, ad esempio un driver in modalità kernel o un'applicazione in modalità utente.

La macro DoTraceMessage viene espansa, logicamente, nel modo seguente:

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

Osservare l'esempio di codice seguente.

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

Questa chiamata genera il messaggio di traccia quando il flag ERROR è abilitato. Il messaggio è "IOCTL=%d" e MessageVariables è il valore di ControlCode.

Se sono state definite le macro pre-registrazione e POST-registrazione, verranno espanse anche. Le macro PRE e le macro POST sono supportate nei sistemi operativi Microsoft Windows 2000 e versioni successive. Per usare le macro, è necessario compilare il driver usando WDK. Se si compila un driver usando una versione precedente di Windows Driver Development Kit (DDK), la funzionalità PRE e POST non è disponibile e le macro non verranno eseguite come parte dell'istruzione di traccia. La compilazione del driver usando una versione precedente di Windows DDK potrebbe non causare un'interruzione di compilazione, ma il codice non funzionerà come previsto.

DoTraceMessage: Formato generale

Di seguito è riportato un formato generale di una funzione di messaggio di traccia valida:

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

Parametri visualizzati prima che il messaggio venga interpretato come condizioni. Parametri visualizzati dopo che il messaggio viene interpretato come variabili di messaggio.

Le condizioni sono un elenco delimitato da virgole di valori. Il messaggio di traccia viene generato solo se tutte le condizioni sono vere. È possibile specificare qualsiasi condizione supportata nel codice.

Esempio: MyTrace

Di seguito è riportato un esempio di funzione di traccia. In questo esempio vengono aggiunte condizioni per il livello di traccia e il sottocomponente del provider che genera il messaggio di traccia.

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

Ad esempio:

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

Il livello di traccia è il livello standard definito in Evntrace.h, un file di intestazione pubblica che si trova nella sottodirectory Include del 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

Come creare una funzione di traccia personalizzata

Per creare una funzione di traccia personalizzata, seguire questa procedura:

Scrivere versioni alternative delle macro che supportano la macro DoTraceMessage.
Aggiungere il parametro -func all'istruzione RUN_WPP che richiama il preprocessore WPP.

Scrivere macro personalizzate

Per creare una funzione di traccia personalizzata che modifica le condizioni per un messaggio di traccia (i parametri visualizzati prima del messaggio), è necessario scrivere versioni alternative delle macro che supportano le funzioni di traccia, WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER.

WPP_LEVEL_ENABLED(Flags) determina se la registrazione è abilitata con il valore del flag specificato. Restituisce TRUE o FALSE.
WPP_LEVEL_LOGGER(Flags) trova la sessione di traccia a cui è abilitato il provider e restituisce un handle alla sessione di traccia.

Ad esempio, se si vuole includere il livello di traccia, oltre ai flag, come condizione, definire una nuova macro WPP_LEVEL_ENABLED che include il livello di traccia. È possibile basare la definizione della nuova macro nella macro predefinita, come illustrato nell'esempio di codice seguente.

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

In genere, la macro WPP_LEVEL_LOGGER non è interessata. In questi casi è possibile definire la nuova macro come macro predefinita. Ad esempio:

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

Tuttavia, in alcuni casi, è necessario modificare la macro LOGGER. Ad esempio, è possibile scrivere una funzione di traccia che dipende solo dal livello di traccia e non dai flag.

Nell'esempio di codice seguente il valore dei flag nella macro viene sostituito da un valore fittizio. Non vengono definiti flag durante la dichiarazione della definizione GUID del controllo.

#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)

Aggiungere la funzione a WPP

Per aggiungere la funzione di traccia personalizzata a WPP, aggiungere il parametro -func all'istruzione RUN_WPP con una dichiarazione della funzione, come illustrato nell'esempio di codice seguente.

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

Nota Non è necessario specificare l'opzione -km nella direttiva RUN_WPP per applicazioni in modalità utente o librerie di collegamento dinamico .

Per un elenco completo dei parametri facoltativi per RUN_WPP, vedere Preprocessore WPP.

Condividi tramite