Preprocesor WPP

Tato část popisuje preprocesor trasování softwaru systému Windows, který se běžně označuje jako preprocesor WPP.

Vyvolání preprocesoru WPP

Preprocesor WPP můžete vyvolat pomocí sady Visual Studio a prostředí MSBuild.

Vyvolání preprocesoru WPP

1. Klikněte pravým tlačítkem myši na projekt ovladače v Průzkumníku řešení a klikněte na příkaz Vlastnosti.

2. Na stránce vlastností projektu klikněte na Vlastnosti konfigurace a potom na Trasování WPP.

3. V oddílu Obecnénastavte možnost Spustit WPP na Ano.

4. V části Příkazový řádek můžete přidat možnosti pro přizpůsobení chování trasování.

   Například v části Trasování WPP můžete zadat soubor konfiguračních dat skenování.

   Pokud potřebujete zadat více než jeden konfigurační soubor, například k určení vlastních datových typů, odkazujte na soubor v příkazovém řádku pomocí možnosti -scan , například:

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

Další informace o procesu sestavení naleznete u úlohy TraceWPP a v prostředí pro sestavení WDK a Visual Studio.

Preprocesor můžete spustit také odděleně od prostředí sestavení pomocí nástroje TraceWPP (TraceWPP.exe). Tento nástroj se nachází v podadresáři bin/x86 wdK.

Obecné možnosti trasování WPP

Následující tabulky popisují možnosti preprocesoru WPP. Tyto možnosti můžete v sadě Visual Studio nakonfigurovat pomocí stránky vlastností trasování WPP pro váš projekt nebo jako parametry pro nástroj TraceWPP.

Možnost trasování WPP	Popis
Spusťte WPP	Pokud je „true“, vyvolá WPP.
Povolit minimální opětovné sestavení	Pokud je pravda, provede se sledované přírůstkové sestavení; pokud je false, provede se opětovné sestavení.

Možnosti funkcí a maker

Možnost trasování WPP	Možnost příkazu TraceWPP	Popis
Definice preprocesoru	-DMacro	Přidá #defineMakro na začátek vygenerovaného souboru, kde makro je název makra. Tato možnost má stejný účinek jako možnost kompilátoru /D (definice makra). Je součástí toho, aby bylo zajištěno, že jsou definice platné na začátku souborů TMH.
	-DMakro=Rozšíření	Přidá #defineRozšíření makra na začátek vygenerovaného souboru, kde makro je název makra a rozšíření je rozbalená hodnota. Tato možnost má stejný účinek jako možnost kompilátoru /D (definice makra). Je součástí toho, aby bylo zajištěno, že jsou definice platné na začátku souborů TMH.
Součásti trasování Kernel-Mode	-kilometr	Definuje WPP_KERNEL_MODE makro, které sleduje komponenty režimu jádra. Ve výchozím nastavení jsou trasovány pouze komponenty uživatelského režimu.
Povolit DLL makro	-dll	Definuje WPP_DLL makro, které způsobí inicializaci datových struktur WPP při každém zavolání WPP_INIT_TRACING. V opačném případě se struktury inicializují pouze jednou.
Zadat identifikátor GUID ovládacího prvku	-ctl:GUID	Definuje makro WPP_CONTROL_GUIDS se zadaným GUID ovládacího prvku a položky WPP_DEFINE_BIT, které jsou pojmenovány Chyba, Neobvyklé a Šum. Toto je alternativa k přidání makra do zdrojového souboru. GUID představuje GUID ovládacího prvku.

Možnosti hledání a formátování

Možnost trasování WPP	Možnost příkazu TraceWPP	Popis
Ignorovat vykřičníky	-noshrieks	Přikazuje WPP ignorovat vykřičníky, známé také jako "shrieks". Používá se ve složitém formátování, například %!timestamp!%. Ve výchozím nastavení jsou vyžadovány vykřičníky a WPP se je pokusí interpretovat.
Číselná základna pro číslování řetězců formátu	-argbase:Number	Vytvoří číselnou základnu pro číslování řetězců formátu, například "%1!d!, %2!s!". Výchozí hodnota je 1.
Funkce pro generování trasovacích zpráv	-func:FunctionDescription	Určuje alternativy makra DoTraceMessage . Tyto funkce je pak možné použít ke generování trasovacích zpráv. Můžete například definovat funkci, která určuje příznaky i úroveň zprávy trasování, například: -func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...) Můžete použít více instancí parametru -func . Tato možnost je alternativou k určení popisů funkcí v místním konfiguračním souboru.
Určení řetězce, který se má vyhledat	-lookfor:String	Nasměruje WPP, aby hledal zdrojový soubor zadaného řetězce, aby zahájil trasování. Ve výchozím nastavení WPP vyhledá řetězec "WPP_INIT_TRACING". Jedná se o pokročilou možnost pro uživatele, kteří píší vlastní šablony. Například v souboru default.tpl: IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF
Zadání názvu modulu	-p:String	Určuje alternativní přívětivý název identifikátoru GUID zpráv od tohoto zprostředkovatele trasování. Ve výchozím nastavení je přívětivý název identifikátoru GUID zprávy adresářový název, ve kterém byl vytvořen zprostředkovatel trasování. Srozumitelný název identifikátoru GUID zprávy se ve výchozím nastavení zobrazí v předponě zprávy trasování, která je reprezentována proměnnou %1. Tento parametr můžete použít k přidání řetězce do předpony, která uživateli pomůže identifikovat zprostředkovatele trasování, například popisný název zprostředkovatele trasování, název modulu, který obsahuje zprostředkovatele trasování, nebo název projektu, který je implementován vytvořením několika zprostředkovatelů trasování. Tyto informace pomáhají uživatelům přidružit související zprostředkovatele trasování, kteří jsou v různých souborech nebo v různých cestách. Parametr -p vyžaduje verzi WPP, která je součástí sady Windows Driver Kit (WDK) pro Systém Windows Vista a novější verze WDK. Parametr -p funguje ve Windows 2000 a novějších verzích Windows. Příklady: -p:TraceDrv -p:AudioModule

Možnosti souboru

Možnost trasování WPP	Možnost příkazu TraceWPP	Popis
Další adresáře zahrnutí	-ICesta1[;Cesta2]	Určuje jeden nebo více adresářů, které se mají přidat do cesty zahrnutí; oddělovat středníky, pokud je více než jedna. Stejné jako -cfgdir.
Konfigurační adresáře	-cfgdir:Path1[;Path2]	Určuje umístění konfiguračních souborů a souborů šablon. Cesta1 a Path2 představují plně kvalifikovanou cestu k adresáři. Můžete zadat více cest. Výchozí hodnota je místní adresář.
Přípony souborů	-ext:.ext1[.ext2]	Určuje typy souborů, které WPP rozpozná jako zdrojové soubory. WPP ignoruje soubory s jinou příponou názvu souboru. WPP ve výchozím nastavení rozpozná pouze soubory .c, .c++, .cpp a .cxx. Tato možnost umožňuje použít výchozí nastavení pro WPP, aniž byste museli odstraňovat nebo přejmenovat soubory prostředků, které WPP nepoužívá, například soubory .rc a .mc. Pokud chcete například přidat trasování do souborů C++ a hlaviček (.h), použijte následující příkaz: -ext:.cpp.CPP.h.H Pokud chcete také dát souborům TMH pro soubory C++ a hlavičky různé názvy, použijte možnost -preserveext .
Zachování přípon souborů	-preserveext:.ext1[.ext2]	Zachová zadanou příponu názvu souboru při vytváření souborů TMH. Ve výchozím nastavení jsou soubory TMH pro všechny typy souborů pojmenované filename.tmh. To způsobilo konflikty názvů souborů, pokud máte více než jeden zdrojový soubor se stejným názvem. Například soubory TMH pro soubory C (.c) a hlavičky (.h) mají ve výchozím nastavení název <filename.tmh>. Pomocí parametru -preserveext:.c .h se soubory TMH nazývají <název_souboru.c.tmh a <název_>souboru.h.tmh>.
Výstupní adresář	-odir:path	Určuje adresář pro výstupní soubory, které WPP vytvoří. Cesta je plně kvalifikovaná cesta k adresáři. Výchozí hodnota je místní adresář.
Zadejte soubor šablony	-gen{ File.tpl }. ext	Pro každý zdrojový soubor, který WPP zpracovává s názvem zadaným mezi složenými závorkami {}, vytvořte další soubor se zadanou příponou názvu souboru. File.tpl představuje zdrojový soubor. *.ext představuje typ vytvořeného souboru a jeho příponu názvu souboru. Můžete zadat více možností -gen . Například -gen{um-default.tpl}.tmh znamená, že pro každý soubor um-default.tpl , který WPP zpracovává, vytvoří soubor um-default.tmh .
Kontrola konfiguračních dat	-scan:File	Vyhledá konfigurační data, například vlastní datové typy, v souboru, který není konfiguračním souborem, a také v defaultwpp.ini. Umístěte řetězce begin_wpp config a end_wpp kolem konfiguračních dat, abyste je identifikovali. Pro konfigurační data použijte stejný formát jako v defaultwpp.ini. Pokud jste do vlastního konfiguračního souboru přidali konfigurační data, použijte parametr -ini .
Alternativní konfigurační soubor	-defwpp:path	Určuje alternativní konfigurační soubor. Wpp používá tento soubor místo souboru defaultwpp.ini.
Další konfigurační soubor	-ini:Cesta	Určuje další konfigurační soubor. WPP používá kromě výchozího souboru kromě výchozího souboru defaultwpp.ini. Tento parametr použijte, když jste vytvořili nový konfigurační soubor pro ukládání konfiguračních dat pro trasování. Pokud jste konfigurační data přidali do jiného typu souboru, například do zdrojového nebo hlavičkového souboru, použijte parametr -scan .

Proces sestavení WPP

Pokud je pro ovladač nebo aplikaci v uživatelském režimu povolen program WPP, sestavení ovladače nebo aplikace vyvolá preprocesor WPP před kompilací ovladače nebo souborů aplikace.

Proces sestavení WPP dokončí následující kroky:

1. Preprocesor WPP zpracovává makra WPP v každém zdrojovém souboru a pro každý z nich vytvoří soubor hlavičky trasovacích zpráv. Zdrojový kód není přímo změněn.

2. Jakmile preprocesor WPP vytvoří soubory hlaviček zpráv trasování, preprocesor jazyka C zpracuje předdefinovaná makra WPP v hlavičkových souborech zpráv trasování běžným způsobem.