WPP-Präprozessor
In diesem Abschnitt wird der Windows Software Trace Preprocessor beschrieben, der allgemein als WPP-Präprozessor bezeichnet wird.
Aufrufen des WPP-Präprozessors
Sie können den WPP-Präprozessor mit Visual Studio und der MSBuild-Umgebung aufrufen.
So rufen Sie den WPP-Präprozessor auf
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Treiberprojekt, und klicken Sie dann auf "Eigenschaften".
Klicken Sie auf der Projekteigenschaftsseite auf "Konfigurationseigenschaften" , und klicken Sie auf "WPP-Ablaufverfolgung".
Legen Sie unter "Allgemein" die Option "WPP ausführen" auf "Ja" fest.
Unter der Befehlszeile können Sie unten Optionen hinzufügen, um das Ablaufverfolgungsverhalten anzupassen.
Beispielsweise können Sie unter der WPP-Ablaufverfolgung eine einzelne Scankonfigurationsdatendatei angeben.
Wenn Sie z. B. mehrere Konfigurationsdateien angeben müssen, um benutzerdefinierte Datentypen anzugeben, verweisen Sie auf Die Datei in der Befehlszeile mithilfe der Option "-scan ", z. B.:
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
Weitere Informationen zum Buildprozess finden Sie unter TraceWPP-Aufgabe und WDK- und Visual Studio-Buildumgebung.
Sie können den Präprozessor auch getrennt von der Buildumgebung ausführen, indem Sie das TraceWPP-Tool (TraceWPP.exe) verwenden. Dieses Tool befindet sich im Unterverzeichnis "bin/x86" des WDK.
Allgemeine Optionen für WPP-Ablaufverfolgung
In den folgenden Tabellen werden die Optionen für den WPP-Präprozessor beschrieben. Sie können diese Optionen in Visual Studio mithilfe der WPP-Ablaufverfolgungseigenschaftsseite für Ihr Projekt oder als Parameter für das TraceWPP-Tool konfigurieren.
| WPP-Ablaufverfolgungsoption | Beschreibung |
|---|---|
Ausführen von WPP |
Bei "true" wird WPP aufgerufen. |
Minimale Neuerstellung aktivieren |
Wenn wahr, wird ein nachverfolgter inkrementeller Build ausgeführt; wenn "false" ausgeführt wird, wird eine Neuerstellung ausgeführt. |
Funktions- und Makrooptionen
| WPP-Ablaufverfolgungsoption | TraceWPP-Befehlsoption | Beschreibung |
|---|---|---|
Präprozessordefinitionen |
-D-Makro |
Fügt #define Makro am Anfang der generierten Datei hinzu, wobei Makro der Name eines Makros ist. Diese Option hat die gleiche Wirkung wie die Compileroption /D (Definieren eines Makros). Sie ist enthalten, um sicherzustellen, dass die Definition am Anfang der TMH-Dateien gültig ist. |
-D-Makroerweiterung= |
Fügt #define Makroerweiterung am Anfang der generierten Datei hinzu, wobei "Makro" der Name eines Makros ist und "Erweiterung" der erweiterte Wert ist. Diese Option hat die gleiche Wirkung wie die Compileroption /D (Definieren eines Makros). Sie ist enthalten, um sicherzustellen, dass die Definition am Anfang der TMH-Dateien gültig ist. |
|
Komponenten für den Kernelmodus nachverfolgen |
-Kilometer |
Definiert das WPP_KERNEL_MODE Makro, das Kernelmoduskomponenten verfolgt. Standardmäßig werden nur Benutzermoduskomponenten nachverfolgt. |
Dll-Makro aktivieren |
-dll |
Definiert das WPP_DLL-Makro, wodurch die WPP-Datenstrukturen immer dann initialisiert werden, wenn WPP_INIT_TRACING aufgerufen wird. Andernfalls werden die Strukturen nur einmal initialisiert. |
Angeben der Steuerelement-GUID |
-ctl: GUID |
Definiert ein WPP_CONTROL_GUIDS Makro mit der angegebenen Steuerelement-GUID und WPP_DEFINE_BIT Einträgen mit dem Namen "Error", "Unusual" und "Noise".
Dies ist eine Alternative zum Hinzufügen des Makros zur Quelldatei. GUID stellt die GUID des Steuerelements dar. |
Such- und Formatierungsoptionen
| WPP-Ablaufverfolgungsoption | TraceWPP-Befehlsoption | Beschreibung |
|---|---|---|
Ausrufezeichen ignorieren |
-noshrieks |
Leitet WPP an, Ausrufezeichen zu ignorieren, auch bekannt als "Schrieks". Wird in komplexer Formatierung verwendet, z. B. %!Timestamp!%. Standardmäßig sind Ausrufezeichen erforderlich, und WPP versucht, sie zu interpretieren. |
Numerische Basis für die Nummerierung von Formatzeichenfolgen |
-argbase: Number |
Richtet eine numerische Basis für die Nummerierung von Formatzeichenfolgen ein, z. B. "%1!d!, %2!s!". Der Standardwert ist 1. |
Funktion zum Generieren von Ablaufverfolgungsmeldungen |
-func: FunctionDescription |
Gibt Alternativen zum DoTraceMessage-Makro an. Diese Funktionen können dann zum Generieren von Ablaufverfolgungsmeldungen verwendet werden. Sie können beispielsweise eine Funktion definieren, die sowohl die Flags als auch die Ebene für eine Ablaufverfolgungsnachricht angibt, z. B.: Sie können mehrere Instanzen der Option "-func " verwenden. Diese Option ist eine Alternative zum Angeben von Funktionsbeschreibungen in einer lokalen Konfigurationsdatei. |
Zeichenfolge angeben, nach der gesucht werden soll |
-lookfor:String |
Leitet WPP an, die Quelldateien für die angegebene Zeichenfolge zu durchsuchen, um die Ablaufverfolgung zu initiieren. WPP sucht standardmäßig nach der Zeichenfolge "WPP_INIT_TRACING". Dies ist eine erweiterte Option für Benutzer, die ihre eigenen Vorlagen schreiben. Beispiel: in default.tpl: |
Modulname angeben |
-p: Zeichenfolge |
Gibt einen alternativen Anzeigenamen für die Nachrichten-GUID von Nachrichten aus diesem Ablaufverfolgungsanbieter an. Standardmäßig ist der Anzeigename der Nachrichten-GUID der Name des Verzeichnisses, in dem der Ablaufverfolgungsanbieter erstellt wurde. Der Anzeigename der Nachrichten-GUID wird standardmäßig im Präfix der Ablaufverfolgungsnachricht angezeigt, das durch die Variable "%1" dargestellt wird. Sie können diesen Parameter verwenden, um dem Präfix eine Zeichenfolge hinzuzufügen, die dem Benutzer hilft, den Ablaufverfolgungsanbieter zu identifizieren, z. B. den Anzeigenamen des Ablaufverfolgungsanbieters, den Namen des Moduls, das den Ablaufverfolgungsanbieter enthält, oder den Namen eines Projekts, das durch Erstellen mehrerer Ablaufverfolgungsanbieter implementiert wird. Diese Informationen helfen Benutzern, verwandte Ablaufverfolgungsanbieter zuzuordnen, die sich in verschiedenen Dateien oder verschiedenen Pfaden befinden. Der Parameter -p erfordert die Version von WPP, die im Windows Driver Kit (WDK) für Windows Vista und neueren Versionen von WDK enthalten ist. Der Parameter "-p " funktioniert unter Windows 2000 und höheren Versionen von Windows. Beispiele: |
Dateioptionen
| WPP-Ablaufverfolgungsoption | TraceWPP-Befehlsoption | Beschreibung |
|---|---|---|
Zusätzliche Includeverzeichnisse |
-I Path1[;Path2] |
Gibt mindestens ein Verzeichnis an, das dem include-Pfad hinzugefügt werden soll. Verwenden Sie Semikolons als Trennzeichen, wenn mehrere Verzeichnisse vorhanden sind. Identisch mit -cfgdir. |
Konfigurationsverzeichnisse |
-cfgdir: Path1[;Path2] |
Gibt den Speicherort von Konfigurations- und Vorlagendateien an. Path1 und Path2 stellen den vollqualifizierten Pfad zu einem Verzeichnis dar. Sie können mehrere Pfade angeben. Der Standardwert ist das lokale Verzeichnis. |
Dateierweiterungen |
-Extern:. ext1 [.ext2] |
Gibt die Dateitypen an, die WPP als Quelldateien erkennt. WPP ignoriert Dateien mit einer anderen Dateinamenerweiterung. Standardmäßig erkennt WPP nur C-, C++-, .cpp- und CXX-Dateien. Mit dieser Option können Sie die Standardeinstellungen für WPP verwenden, ohne Ressourcendateien löschen oder umbenennen zu müssen, die von WPP nicht verwendet werden, z. B. RC- und MC-Dateien. Wenn Sie z. B. C++-Dateien und Headerdateien (H) die Ablaufverfolgung hinzufügen möchten, verwenden Sie den folgenden Befehl: -ext:.cpp. CPP.h.H Verwenden Sie außerdem die Option "-preserveext ", um die TMH-Dateien für die C++- und Headerdateien unterschiedlichen Namen zu geben. |
Dateierweiterungen beibehalten |
-preserveext: .ext1[.ext2] |
Behält die angegebenen Dateinamenerweiterungen beim Erstellen von TMH-Dateien bei. Standardmäßig heißen TMH-Dateien für alle Dateitypen den Namen "filename.tmh". Dies führte zu Dateinamenkonflikten, wenn Sie mehrere Quelldateien mit demselben Namen haben. Standardmäßig würden TMH-Dateien für C-Dateien (.c) und Headerdateien (H) den Namen <"filename.tmh>" haben. Mithilfe von "-preserveext:.c .h" werden die TMH-Dateien "filename.c.tmh>" und <"filename.h.tmh>" genannt<. |
Ausgabeverzeichnis |
-odir: Pfad | Gibt das Verzeichnis für die Ausgabedateien an, die WPP erstellt. Der Pfad ist der vollqualifizierte Pfad zum Verzeichnis. Der Standardwert ist das lokale Verzeichnis. |
Vorlagendatei angeben |
-gen{ File.tpl }. ext |
Erstellen Sie für jede Quelldatei, die WPP mit dem zwischen geschweiften Klammern {}angegebenen Namen verarbeitet, eine weitere Datei mit der angegebenen Dateinamenerweiterung. File.tpl stellt die Quelldatei dar. *.ext stellt den Typ der erstellten Datei und deren Dateinamenerweiterung dar. Sie können mehrere Optionen für die Gen-Generation angeben. Beispielsweise bedeutet "-gen{um-default.tpl}.tmh", dass für jede von WPP verarbeitete Datei um-default.tpl eine um-default.tmh-Datei erzeugt wird. |
Scannen von Konfigurationsdaten |
-scan:File |
Sucht nach Konfigurationsdaten, z. B. benutzerdefinierten Datentypen, in einer Datei, die keine Konfigurationsdatei ist, sowie in defaultwpp.ini. Platzieren Sie begin_wpp Konfiguration und end_wpp Zeichenfolgen um die Konfigurationsdaten, um sie zu identifizieren. Verwenden Sie das gleiche Format für die Konfigurationsdaten wie in defaultwpp.ini. Wenn Sie die Konfigurationsdaten zu einer benutzerdefinierten Konfigurationsdatei hinzugefügt haben, verwenden Sie den Parameter "-ini ". |
Alternative Konfigurationsdatei |
-defwpp:path |
Gibt eine alternative Konfigurationsdatei an. Wpp verwendet diese Datei anstelle der defaultwpp.ini Datei. |
Zusätzliche Konfigurationsdatei |
-ini:Path |
Gibt eine zusätzliche Konfigurationsdatei an. WPP verwendet zusätzlich zur Standarddatei defaultwpp.ini die angegebene Datei. Verwenden Sie diesen Parameter, wenn Sie eine neue Konfigurationsdatei zum Speichern von Konfigurationsdaten für die Ablaufverfolgung erstellt haben. Wenn Sie die Konfigurationsdaten einem anderen Dateityp hinzugefügt haben, z. B. einer Quell- oder Headerdatei, verwenden Sie den Parameter "-scan ". |
WPP-Buildprozess
Wenn WPP für eine Treiber- oder Benutzermodusanwendung aktiviert ist, ruft das Erstellen des Treibers oder der Anwendung den WPP-Präprozessor auf, bevor die Treiber- oder Anwendungsdateien kompiliert werden.
Der WPP-Buildprozess führt die folgenden Schritte aus:
Der WPP-Präprozessor verarbeitet WPP-Makros in jeder Quelldatei und erstellt eine Nachrichtenkopfdatei für die Ablaufverfolgung für jede Quelldatei. Der Quellcode wird nicht direkt geändert.
Nachdem der WPP-Vorprozessor die Nachrichtenkopfdateien für die Ablaufverfolgung erstellt hat, verarbeitet der C-Präprozessor die integrierten WPP-Makros in den Nachrichtenkopfdateien der Ablaufverfolgung auf normale Weise.