Preprocessore WPP

Articolo
06/15/2023

Questa sezione descrive il preprocessore di traccia software Windows, comunemente noto come preprocessore WPP.

Richiamo del preprocessore WPP

È possibile richiamare il preprocessore WPP usando Visual Studio e l'ambiente MSBuild.

Per richiamare il preprocessore WPP

Fare clic con il pulsante destro del mouse sul progetto driver in Esplora soluzioni e scegliere Proprietà.
Nella pagina delle proprietà del progetto fare clic su Proprietà di configurazione e quindi su Traccia WPP
In Generale impostare l'opzione Esegui WPP su Sì.
In Riga di comando è possibile aggiungere le opzioni seguenti per personalizzare il comportamento di traccia.

In Traccia WPP, ad esempio, è possibile specificare un singolo file di dati di configurazione di analisi .

Se è necessario specificare più file di configurazione, ad esempio per specificare tipi di dati personalizzati, fare riferimento al file nella riga di comando usando l'opzione -scan , ad esempio:
```
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
```

Per altre informazioni sul processo di compilazione, vedere Attività TraceWPP e WDK e ambiente di compilazione di Visual Studio.

È anche possibile eseguire il preprocessore separato dall'ambiente di compilazione usando lo strumento TraceWPP (TraceWPP.exe). Questo strumento si trova nella sottodirectory bin/x86 di WDK.

Opzioni generali di traccia WPP

Le tabelle seguenti descrivono le opzioni per il preprocessore WPP. È possibile configurare queste opzioni in Visual Studio usando la pagina delle proprietà Traccia WPP per il progetto o come parametri per lo strumento TraceWPP.

Opzione di traccia WPP	Descrizione
Eseguire WPP	Se true, richiama WPP.
Abilitare la ricompilazione minima	Se true, viene eseguita una compilazione incrementale rilevata; se false, viene eseguita una ricompilazione.

Opzioni di funzione e macro

Opzione di traccia WPP	Opzione di comando TraceWPP	Descrizione
Definizioni del preprocessore	Macro -D	Aggiunge #defineMacro all'inizio del file generato in cui Macro è il nome di una macro. Questa opzione ha lo stesso effetto dell'opzione del compilatore /D (definire una macro). È incluso per assicurarsi che le definizioni siano valide all'inizio dei file TMH.
	Espansione macro=-D	Aggiunge #defineespansione macro all'inizio del file generato in cui Macro è il nome di una macro ed Espansione è il valore espanso. Questa opzione ha lo stesso effetto dell'opzione del compilatore /D (definire una macro). È incluso per assicurarsi che le definizioni siano valide all'inizio dei file TMH.
Componenti di traccia Kernel-Mode	-km	Definisce la macro WPP_KERNEL_MODE, che traccia i componenti in modalità kernel. Per impostazione predefinita, vengono tracciati solo i componenti in modalità utente.
Abilitare la macro dll	-dll	Definisce la macro WPP_DLL, che determina l'inizializzazione delle strutture di dati WPP ogni volta che viene chiamato WPP_INIT_TRACING. In caso contrario, le strutture vengono inizializzate una sola volta.
Specificare il GUID del controllo	-ctl:GUID	Definisce una macro WPP_CONTROL_GUIDS con il GUID del controllo specificato e WPP_DEFINE_BIT voci denominate Error, Unusual e Noise. Si tratta di un'alternativa all'aggiunta della macro al file di origine. GUID rappresenta il GUID del controllo.

Opzioni di ricerca e formattazione

Opzione di traccia WPP	Opzione di comando TraceWPP	Descrizione
Ignora segni esclamativi	-noshrieks	Indirizza WPP a ignorare i segni esclamativi, noti anche come "shrieks". Utilizzato nella formattazione complessa, ad esempio %!timestamp!%. Per impostazione predefinita, i segni esclamativi sono obbligatori e WPP tenta di interpretarli.
Base numerica per la numerazione delle stringhe di formato	-argbase:Number	Stabilisce una base numerica per la numerazione delle stringhe di formato, ad esempio "%1!d!, %2!s!". Il valore predefinito è 1.
Funzione per generare messaggi di traccia	-func:FunctionDescription	Specifica le alternative alla macro DoTraceMessage . Queste funzioni possono quindi essere usate per generare messaggi di traccia. Ad esempio, è possibile definire una funzione che specifica sia i flag che il livello per un messaggio di traccia, ad esempio: `-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)` È possibile usare più istanze dell'opzione -func . Questa opzione è un'alternativa alla specifica delle descrizioni delle funzioni in un file di configurazione locale.
Specificare la stringa da cercare	-lookfor:String	Indirizza WPP a cercare la stringa specificata nei file di origine per avviare la traccia. Per impostazione predefinita, WPP cerca la stringa "WPP_INIT_TRACING". Si tratta di un'opzione avanzata per gli utenti che scrivono modelli personalizzati. Ad esempio, in default.tpl: `IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF`
Specificare il nome del modulo	-p:String	Specifica un nome descrittivo alternativo per il GUID del messaggio dei messaggi di questo provider di traccia. Per impostazione predefinita, il nome descrittivo del GUID del messaggio è il nome della directory in cui è stato compilato il provider di traccia. Il nome descrittivo del GUID del messaggio viene visualizzato, per impostazione predefinita, nel prefisso del messaggio di traccia rappresentato dalla variabile %1. È possibile usare questo parametro per aggiungere una stringa al prefisso che consente all'utente di identificare il provider di traccia, ad esempio il nome descrittivo del provider di traccia, il nome del modulo che include il provider di traccia o il nome di un progetto implementato creando diversi provider di traccia. Queste informazioni consentono agli utenti di associare provider di traccia correlati che si trovano in file o percorsi diversi. Il parametro -p richiede la versione di WPP inclusa in Windows Driver Kit (WDK) per Windows Vista e versioni successive di WDK. Il parametro -p funziona in Windows 2000 e versioni successive di Windows. Esempi: `-p:TraceDrv -p:AudioModule`

Opzioni file

Opzione di traccia WPP	Opzione di comando TraceWPP	Descrizione
Directory di inclusione aggiuntive	-IPath1[;Path2]	Specifica una o più directory da aggiungere al percorso di inclusione. Usare il punto e virgola (;) come delimitatore per più percorsi. Uguale a -cfgdir.
Directory di configurazione	-cfgdir:Path1[;Path2]	Specifica il percorso dei file di configurazione e modello. Path1 e Path2 rappresentano il percorso completo di una directory. È possibile specificare più percorsi. Il valore predefinito è la directory locale.
Estensioni di file	-Ext:.ext1[.ext2]	Specifica i tipi di file riconosciuti da WPP come file di origine. WPP ignora i file con un'estensione di file diversa. Per impostazione predefinita, WPP riconosce solo i file con estensione c, c++, cpp e cxx. Questa opzione consente di usare le impostazioni predefinite per WPP senza dover eliminare o rinominare i file di risorse non usati da WPP, ad esempio i file RC e mc. Ad esempio, per aggiungere traccia ai file C++ e ai file di intestazione (con estensione h), usare il comando seguente: -ext:.cpp. CPP.h.H Inoltre, per assegnare i file TMH per i file C++ e di intestazione diversi nomi, usare l'opzione -preserveext .
Mantenere le estensioni di file	-preserveext:.ext1[.ext2]	Mantiene le estensioni di file specificate durante la creazione di file TMH. Per impostazione predefinita, i file TMH per tutti i tipi di file sono denominati filename.tmh. Ciò ha causato conflitti di nomi di file quando sono presenti più file di origine con lo stesso nome. Per impostazione predefinita, ad esempio, i file TMH per i file C (con estensione c) e i file di intestazione (.h) saranno denominati <filename.tmh>. Usando -preserveext:.c .h, i file TMH sono denominati <filename.c.tmh> e <filename.h.tmh>.
Directory di output	-odir:path	Specifica la directory per i file di output creati da WPP. Path è il percorso completo della directory. Il valore predefinito è la directory locale.
Specificare il file modello	-gen{ File.tpl }. ext	Per ogni file di origine elaborato da WPP con il nome specificato tra parentesi {}graffe, creare un altro file con l'estensione del nome file specificata. File.tpl rappresenta il file di origine. .ext rappresenta il tipo di file creato e l'estensione del nome file. È possibile specificare più opzioni -gen* . Ad esempio, -gen{um-default.tpl}.tmh significa che per ogni file um-default.tpl elaborato da WPP viene generato un file um-default.tmh .
Analizzare i dati di configurazione	-scan:File	Cerca i dati di configurazione, ad esempio i tipi di dati personalizzati, in un file che non è un file di configurazione, nonché in defaultwpp.ini. Posizionare begin_wpp configurazione e end_wpp stringhe intorno ai dati di configurazione per identificarlo. Usare lo stesso formato per i dati di configurazione usati in defaultwpp.ini. Se i dati di configurazione sono stati aggiunti a un file di configurazione personalizzato, usare il parametro -ini .
File di configurazione alternativo	-defwpp:path	Specifica un file di configurazione alternativo. Wpp usa questo file anziché il file defaultwpp.ini.
File di configurazione aggiuntivo	-ini:Path	Specifica un file di configurazione aggiuntivo. WPP usa il file specificato oltre al file predefinito defaultwpp.ini. Usare questo parametro quando è stato creato un nuovo file di configurazione per archiviare i dati di configurazione per la traccia. Se i dati di configurazione sono stati aggiunti a un altro tipo di file, ad esempio un file di origine o di intestazione, usare il parametro -scan .

Processo di compilazione WPP

Se WPP è abilitato per un'applicazione in modalità driver o utente, la compilazione del driver o dell'applicazione richiama il preprocessore WPP prima della compilazione del driver o dei file dell'applicazione.

Il processo di compilazione WPP completa i passaggi seguenti:

Il preprocessore WPP elabora le macro WPP in ogni file di origine e crea un file di intestazione del messaggio di traccia per ogni file di origine. Il codice sorgente non viene modificato direttamente.
Dopo che il preprocessore WPP ha creato i file di intestazione del messaggio di traccia, il preprocessore C elabora le macro WPP predefinite nei file di intestazione del messaggio di traccia in modo normale.

Share via