Dela via

WPP-förprocessor

I det här avsnittet beskrivs Windows Software Trace Preprocessor, som ofta kallas WPP-förprocessor.

Anropa WPP-förprocessorn

Du kan anropa WPP-förprocessorn med hjälp av Visual Studio och MSBuild-miljön.

Så här anropar du WPP-förprocessorn

  1. Högerklicka på drivrutinsprojektet i Solutions Explorer och klicka på Egenskaper.

  2. På projektegenskapssidan klickar du på Konfigurationsegenskaper och klickar på WPP-spårning

  3. Under Allmäntställer du in alternativet Kör WPP till Ja.

  4. Under Kommandoraden kan du lägga till alternativ nedan för att anpassa spårningsbeteendet.

    Under WPP-spårning kan du till exempel ange en enda genomsökningskonfigurationsdatafil .

    Om du behöver ange mer än en konfigurationsfil, till exempel för att ange anpassade datatyper, refererar du till filen i kommandoraden med hjälp av alternativet -scan , till exempel:

    -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"

Mer information om byggprocessen finns i TraceWPP-uppgift och WDK och Visual Studio-byggmiljö.

Du kan också köra förprocessorn separat från byggmiljön med hjälp av Verktyget TraceWPP (TraceWPP.exe). Det här verktyget finns i underkatalogen bin/x86 för WDK.

Allmänna alternativ för WPP-spårning

I följande tabeller beskrivs alternativen för WPP-förprocessorn. Du kan konfigurera de här alternativen i Visual Studio med hjälp av egenskapssidan för WPP Tracing för projektet eller som parametrar till TraceWPP-verktyget.

WPP-spårningsalternativ Beskrivning

Kör WPP

Om det är sant anropar WPP.

Aktivera minimal återskapande

Om sant utförs en spårad inkrementell version. om det är falskt utförs en återskapande.

Funktions- och makroalternativ

WPP-spårningsalternativ Kommandoalternativet TraceWPP Beskrivning

Definitioner för förprocessor

-DMakro

Lägger till #definemakro i början av den genererade filen där Makro är namnet på ett makro.

Det här alternativet har samma effekt som kompilatoralternativet /D (definiera ett makro). Den ingår för att säkerställa att definitionerna är giltiga i början av TMH-filerna.

-DMakro=expansion

Lägger till #definemakroexpansion i början av den genererade filen där Makro är namnet på ett makro och Expansion är det expanderade värdet.

Det här alternativet har samma effekt som kompilatoralternativet /D (definiera ett makro). Den ingår för att säkerställa att definitionerna är giltiga i början av TMH-filerna.

Spåra Kernel-Mode-komponenter

-kilometer

Definierar WPP_KERNEL_MODE makro, som spårar komponenter i kernelläge. Som standard spåras endast komponenter i användarläge.

Aktivera DLL-makro

-Dll

Definierar det WPP_DLL makrot, vilket gör att WPP-datastrukturer initieras när WPP_INIT_TRACING anropas. Annars initieras strukturerna bara en gång.

Ange kontroll-GUID

-ctl:GUID

 Definierar ett WPP_CONTROL_GUIDS makro med angivet kontroll-GUID och WPP_DEFINE_BIT-elementen med namnen Fel, Ovanligt och Brus.

Det här är ett alternativ till att lägga till makrot i källfilen.

GUID representerar kontrollens GUID.

Sök- och formateringsalternativ

WPP-spårningsalternativ Kommandoalternativet TraceWPP Beskrivning

Ignorera utropstecken

-noshrieks

Instruerar WPP att ignorera utropstecken, även kallade "skrik".

Används i komplex formatering, till exempel %!tidsstämpel!%. Som standard krävs utropstecken och WPP försöker tolka dem.

Numerisk bas för numrering av formatsträngar

-argbase:Number

Etablerar en numerisk bas för numrering av formatsträngar, till exempel "%1!d!, %2!s!." Standardvärdet är 1.

Funktion för att generera spårningsmeddelanden

-func:FunctionDescription

Anger alternativ till DoTraceMessage-makrot . Dessa funktioner kan sedan användas för att generera spårningsmeddelanden.

Du kan till exempel definiera en funktion som anger både flaggorna och nivån för ett spårningsmeddelande, till exempel:

-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)

Du kan använda flera instanser av alternativet -func .

Det här alternativet är ett alternativ till att ange funktionsbeskrivningar i en lokal konfigurationsfil.

Ange sträng att söka efter

-lookfor:String

Instruerar WPP att söka i källfilerna efter den angivna strängen för att initiera spårning. Som standard söker WPP efter strängen "WPP_INIT_TRACING".

Det här är ett avancerat alternativ för användare som skriver sina egna mallar.

Till exempel i default.tpl:

IF FOUND WPP_INIT_TRACING
 INCLUDE um-init.tpl
ENDIF

Ange modulnamn

-p:String

Anger ett alternativt vänligt namn för meddelandets GUID för meddelanden från denna spårleverantör. Som standard är det vänliga namnet på meddelandets GUID namnet på katalogen där tracingsprovidern skapades.

Det vänliga namnet på meddelandets GUID visas som standard i prefixet för spårningsmeddelandet, vilket representeras av variabeln %1. Du kan använda den här parametern för att lägga till en sträng i prefixet som hjälper användaren att identifiera spårningsprovidern, till exempel det egna namnet på spårningsprovidern, namnet på modulen som innehåller spårningsprovidern eller namnet på ett projekt som implementeras genom att skapa flera spårningsproviders. Den här informationen hjälper användare att associera relaterade spårningsproviders som finns i olika filer eller olika sökvägar.

Parametern -p kräver den version av WPP som ingår i Windows Driver Kit (WDK) för Windows Vista och senare versioner av WDK. Parametern -p fungerar i Windows 2000 och senare versioner av Windows.

Exempel:

-p:TraceDrv
-p:AudioModule

Filalternativ

WPP-spårningsalternativ Kommandoalternativet TraceWPP Beskrivning

Ytterligare inkludera kataloger

-IPath1[;Path2]

Anger en eller flera kataloger som ska läggas till i inkluderingssökvägen. avgränsa med semikolon om fler än ett. Samma som -cfgdir.

Konfigurationskataloger

-cfgdir:Sökväg 1[;Sökväg 2]

Anger platsen för konfigurations- och mallfiler.

Path1 och Path2 representerar den fullständigt kvalificerade sökvägen till en katalog. Du kan ange flera sökvägar. Standardvärdet är den lokala katalogen.

Filnamnstillägg

-Ext:.ext1[.ext2]

Anger de filtyper som WPP identifierar som källfiler. WPP ignorerar filer med ett annat filnamnstillägg.

Som standard identifierar WPP endast .c-, .c++-, .cpp- och .cxx-filer.

Med det här alternativet kan du använda standardinställningarna för WPP utan att behöva ta bort eller byta namn på resursfiler som WPP inte använder, till exempel .rc- och .mc-filer.

Om du till exempel vill lägga till spårning i C++-filer och huvudfiler (.h) använder du följande kommando:

-ext:.cpp.CPP.h.H

Om du vill ge TMH-filerna för C++ och huvudfilerna olika namn använder du alternativet -preserveext .

Bevara filnamnstillägg

-preserveext:.ext1[.ext2]

Bevarar de angivna filnamnstilläggen när du skapar TMH-filer.

Som standard heter TMH-filer för alla filtyper filename.tmh. Detta orsakade filnamnskonflikter när du har fler än en källfil med samma namn.

TMH-filer för C-filer (.c) och huvudfiler (.h) skulle till exempel som standard ha namnet <filename.tmh>. Genom att använda -preserveext:.c .h heter TMH-filerna <filename>.c.tmh och <filename>.h.tmh.

Utdatakatalog

 -odir:path

Anger katalogen för de utdatafiler som WPP skapar.

Sökvägen är den fullständigt kvalificerade sökvägen till katalogen. Standardvärdet är den lokala katalogen.

Ange mallfil

-gen{ File.tpl }. ext

För varje källfil som WPP bearbetar med namnet som anges mellan klammerparenteser skapar du en annan fil med det angivna filnamnstillägget {}.

File.tpl representerar källfilen. *.ext representerar den typ av fil som skapas och filnamnstillägget.

Du kan ange flera -gen-alternativ .

Till exempel innebär -gen{um-default.tpl}.tmh att för varje um-default.tpl-fil som WPP bearbetar, skapas en um-default.tmh-fil .

Skanna konfigurationsdata

-scan:File

Söker efter konfigurationsdata, till exempel anpassade datatyper, i en fil som inte är en konfigurationsfil, samt i defaultwpp.ini.

Placera begin_wpp konfig och end_wpp strängar runt konfigurationsdata för att identifiera dem. Använd samma format för konfigurationsdata som används i defaultwpp.ini.

Om du har lagt till konfigurationsdata i en anpassad konfigurationsfil använder du parametern -ini .

Alternativ konfigurationsfil

-defwpp:path

Anger en alternativ konfigurationsfil. Wpp använder den här filen i stället för den defaultwpp.ini filen.

Ytterligare konfigurationsfil

-ini:Path

Anger ytterligare en konfigurationsfil. WPP använder den angivna filen utöver standardfilen defaultwpp.ini.

Använd den här parametern när du har skapat en ny konfigurationsfil för att lagra konfigurationsdata för spårning. Om du har lagt till konfigurationsdata i en annan typ av fil, till exempel en käll- eller rubrikfil, använder du parametern -scan .

WPP byggprocess

Om WPP är aktiverat för en drivrutin eller ett användarlägesprogram anropar skapandet av drivrutinen eller programmet WPP-förprocessorn innan drivrutins- eller programfilerna kompileras.

WPP-byggprocessen slutför följande steg:

  1. WPP-förprocessorn bearbetar WPP-makron i varje källfil och skapar en rubrikfil för spårningsmeddelanden för varje källfil. Källkoden ändras inte direkt.

  2. När WPP-förprocessorn har skapat huvudfilerna för spårningsmeddelanden bearbetar C-förprocessorn de inbyggda WPP-makrona i huvudfilerna för spårningsmeddelandet på ett normalt sätt.