Přidání trasování softwaru WPP do ovladače systému Windows

Chcete-li použít trasování softwaru WPP v zprostředkovateli trasování, jako je ovladač režimu jádra nebo aplikace v uživatelském režimu, musíte do zdrojových souborů ovladače přidat kód (nebo instrument) a upravit projekt ovladače. Tato část popisuje tyto kroky.

Poznámka:

Nejjednodušší způsob, jak přidat trasování WPP do ovladače, je použít některou ze šablon ovladačů KMDF nebo UMDF v sadě Visual Studio. Pokud použijete šablony, většina kódu, který je potřeba přidat, už je za vás hotová. Ve Visual Studio vyberte Soubor > Nový > Projekta pak vyberte projekt ovladače WDF (Windows Driver Foundation) pro Windows (uživatelský režim nebo režim jádra). Makra WPP jsou definována v souboru hlavičky Trace.h, který je součástí projektu. Pokud používáte některou ze šablon, můžete přeskočit k kroku 5.

Krok 1: Definování GUID ovládacího prvku a příznaků trasování

Každý zprostředkovatel trasování (například ovladač nebo aplikace v uživatelském režimu) musí být jednoznačně definovaný. Uděláte to tak, že přidáte WPP_CONTROL_GUIDS makro, které definuje ovládací GUID, identifikátor a příznaky trasování. To se provádí, abyste mohli identifikovat a řídit, kdy a co chcete sledovat. Zatímco každý ovladač má obvykle samostatný identifikátor GUID ovládacího prvku, ovladač může mít více identifikátorů GUID ovládacích prvků nebo více ovladačů může sdílet jeden identifikátor GUID ovládacího prvku.

Pro usnadnění je makro WPP_CONTROL_GUIDS obvykle definováno v běžném souboru hlaviček. Hlavičkový soubor musí být zahrnut (#include) do jakéhokoli zdrojového souboru, který chcete připravit pro trasování.

Přidání makra WPP_CONTROL_GUIDS do ovladače:

Do projektu ve Visual Studio přidejte nový hlavičkový soubor C++, který můžete použít k definování trasovacích maker WPP. Například v Průzkumníku řešení vyberte ovladač a podržte ho (nebo na něj klikněte pravým tlačítkem myši) a vyberte Přidat > Nová položka. Uložte soubor (například Trace.h).
Přidejte makro WPP_CONTROL_GUIDS k určení přívětivého názvu zprostředkovatele trasování, definici identifikátoru GUID pro ovládání a pro definování příznaků trasování, které můžete použít k rozlišení konkrétních trasovacích zpráv.

Makro WPP_CONTROL_GUIDS má následující syntaxi:

Syntaxe pro WPP_CONTROL_GUIDS
```
#define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID),  \
        WPP_DEFINE_BIT(NameOfTraceFlag1)  \
        WPP_DEFINE_BIT(NameOfTraceFlag2)  \
        .............................   \
        .............................   \
        WPP_DEFINE_BIT(NameOfTraceFlag31) \
        )
```
Například následující kód používá myDriverTraceGuid jako GUIDFriendlyName. Všimněte si, že ControlGUID má mírně jiný formát než standardní forma šestnáctkového identifikátoru GUID s 32 číslicemi. ControlGUID má pět polí, ale jsou odděleny čárkami a hranatými závorkami namísto obvyklých spojovníků a složených závorek. Zadáte například ((84bdb2e9,829e,41b3,b891 02f454bc2bd7) místo {84bdb2e9-829e-41b3-b891-02f454bc2bd7}.

Příklad příkazu WPP_CONTROL_GUIDS
```
#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        )                             
```
Poznámka:

Tento fragment kódu můžete zkopírovat do souboru hlaviček. Ujistěte se, že změníte identifikátor GUID ovládacího prvku a popisný název. K vygenerování identifikátoru GUID ovládacího prvku můžete použít GUIDgen.exe. Součástí sady Visual Studio je Guidgen.exe ( nástrojeTools > vytvoření identifikátoru GUID). Můžete také použít nástroj Uuidgen.exe, který je k dispozici v okně příkazového řádku sady Visual Studio (další informace získáte zadáním uuidgen.exe /?).
Definujte příznaky trasování pro poskytovatele trasování.

Prvky WPP_DEFINE_BIT v makru WPP_CONTROL_GUIDS určují trasovací příznaky pro poskytovatele trasování. Vlajky obvykle představují stále podrobnější úrovně reportingu, ale můžete je použít jako podmínky pro generování zpráv trasování podle potřeby. V příkladu WPP_CONTROL_GUIDS definuje WPP_DEFINE_BIT čtyři příznaky trasování (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE a TRACE_QUEUE).

Můžete definovat až 31 příznaků trasování. WPP přiřadí bitové hodnoty prvkům v pořadí, v jakém se zobrazují, například bit 0 (0x1), bit 1 (0x2), bit 2 (0x4), bit 3 (0x8) atd. Příznaky trasování použijete při přidání funkcí trasovací zprávy do zdrojového kódu (popsané v kroku 5: Instrumentace kódu ovladače ke generování trasovacích zpráv v příslušných bodech).

Poznámka:

Pomocí příznaků trasování můžete řídit, kdy se mají sledovat konkrétní komponenty (například konkrétní vstupně-výstupní požadavky nebo aktivity objektů zařízení nebo ovladačů). Příznak trasování přidáte do příkazu zprávy trasování (například DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). Při vytváření relace sledování s kontrolorem sledování, jako je Tracelog, zadáte parametr -flag pro poskytovatele sledování v této relaci, přičemž v tomto případě je příznakem bit 1 (0x1), který odpovídá příznaku TRACE_DRIVER. Když spustíte relaci trasování, všechny zprávy trasování, které se týkají příslušného příznaku trasování, se zapíší do protokolu.

Krok 2: Vyberte, které funkce trasování zpráv chcete použít, a definujte makra WPP pro tyto funkce

Podobně jako funkce ladicího tisku je funkce pro trasování zpráv funkce (nebo makro), kterou přidáte do kódu pro zápis trasovacích zpráv.

Volba funkce trasovací zprávy

Výchozí funkcí zprávy trasování je makro DoTraceMessage. Pokud použijete výchozí funkci, můžete určit, kdy chcete generovat zprávy, pomocí hodnot příznaku trasování pro vašeho poskytovatele. Hodnoty trasovacích příznaků jsou příznaky, které jste definovali při vytváření GUID ovládacího prvku v kroku 1. Pokud používáte DoTraceMessage , výchozí makra WPP jsou již definována (WPP_LEVEL_ENABLED a WPP_LEVEL_LOGGER), takže můžete přeskočit zbytek tohoto kroku a přejít na Krok 5.
Pokud používáte některou ze šablon KMDF nebo UMDF, funkce TraceEvents a potřebná makra WPP už jsou definovaná pro povolení této funkce, takže můžete přeskočit k kroku 5.
Pokud vytváříte vlastní funkci trasovací zprávy nebo převádíte existující funkci debug výpisu, pokračujte s dalším krokem.

Vytvoření nebo přizpůsobení funkce zprávy trasování

Pokud používáte vlastní funkce trasování zpráv nebo chcete převést ladicí funkce výstupu (například KdPrint) na generování trasovacích zpráv, musíte definovat makra WPP, která identifikují a povolí funkce trasování zpráv ve vašem zprostředkovateli trasování. Vložte tato makra do souboru záhlaví Trace.h, který jste přidali do projektu.
Definujte makra WPP pro povolení funkce trasování.

Každá funkce pro trasování zpráv, kterou použijete, musí mít odpovídající dvojici maker. Tato makra identifikují zprostředkovatele trasování a určují podmínky, které generují zprávy. Obvykle definujete dvojici maker, WPP_<podmínku>_LOGGER a WPP_<podmínku>_ENABLED ve vztahu k výchozím makrům WPP_LEVEL_ENABLED a WPP_LEVEL_LOGGER.

termín	Popis
WPP_CONDITIONS_LOGGER	Používá se k nalezení relace trasování spojené s poskytovatelem a vrací popisovač relace.
WPP_CONDITIONS_ENABLED	Slouží k určení, zda je protokolování povoleno se zadanou podmínkou.

Pro makra WPP, která definujete, PODMÍNKY představují podmínky, které funkce zprávy trasování podporuje, v pořadí, v jakém se zobrazují v seznamu parametrů funkce oddělené podtržítky. Například, výchozí funkce trasování zpráv, DoTraceMessage, podporuje pouze Příznak trasování jako podmínku, takže je v názvech maker (WPP_LEVEL_ENABLED) pouze jeden parametr.

Poznámka:

Názvy výchozích maker (WPP_LEVEL_ENABLED a WPP_LEVEL_LOGGER) bohužel naznačují, že se vztahují k parametru Trace Level, ale ve skutečnosti odkazují na příznak trasování.

Pokud používáte vlastní funkci zprávy trasování, můžete nastavit další kvalifikátory, například úroveň trasování. Úroveň trasování je definována v souboru Evntrace.h a úrovně trasování poskytují pohodlný způsob klasifikace zpráv trasování jako chyby, upozornění a informační zprávy.

Do souboru hlavičky, který jste přidali do projektu, můžete například přidat následující fragment kódu. Následující kód definuje vlastní makra WPP pro funkci zprávy trasování, která podporuje parametry Úroveň trasování i Příznak trasování jako podmínky pro generování trasovacích zpráv. Makro WPP_LEVEL_FLAGS_ENABLED vrátí hodnotu TRUE, pokud je protokolování povolené pro zadanou hodnotu FLAGS a povolená hodnota LEVEL je větší nebo rovna argumentu úrovně použitému ve volání funkce zprávy trasování.

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

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

Dále je potřeba zadat vlastní funkce trasování zpráv v konfiguračním bloku WPP (begin_wpp config a end_wpp). Například při použití šablony pro projekty UMDF nebo KMDF Driver v prostředí Visual Studio definuje šablona makra WPP pro vlastní funkci trasování zpráv s názvem TraceEvents. Funkce makra TraceEvents používá úroveň trasování a příznak trasování jako podmínky pro generování zpráv. Pokud jste definovali makro WPP_LEVEL_FLAGS_ENABLED v souboru záhlaví Trace.h, můžete přidat následující definici makra.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

Existující příkazy ladicího tisku můžete také převést na příkazy trasování zpráv přidáním podobné deklarace FUNC v bloku konfigurace WPP. Následující příklad například přidá kód, který převede existující příkazy KdPrint. Deklarace FUNC také globálně definuje KdPrint, aby používala zadanou úroveň trasování a příznak {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}. Místo odesílání výstupu do ladicího programu se ladicí tiskové příkazy odesílají do protokolu trasování.

//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatibility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//

Poznámka:

Pokud chcete převést KdPrintEx na funkci zprávy trasování, musíte provést několik dalších kroků. Ve srovnání s KdPrintfunkce KdPrintEx přebírá dva další argumenty. Pokud chcete převést funkci KdPrintEx, musíte definovat WPP_DEFINE_BIT pro ComponentID a definovat vlastní podmínku WPP_<>_LOGGER a WPP_<podmínku>_ENABLED makry. Druhý parametr KdPrintEx určuje úroveň podobnou hodnotám úrovně trasování , takže je nemusíte nutně předefinovat.


#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(\
    myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \    /* change GUID for your provider */
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID)      /* bit  4 = 0x00000010 */\         /* Added for the ComponentID param of KdPrintEx */
    )

#define WPP_Flags_LEVEL_LOGGER(Flags, level)                                  \
    WPP_LEVEL_LOGGER(Flags)

#define WPP_Flags_LEVEL_ENABLED(Flags, level)                                 \
    (WPP_LEVEL_ENABLED(Flags) && \
    WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)



//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));   
// end_wpp
//

Krok 3: Zahrnutí přidružených souborů hlaviček trasování (.h a .tmh) do zdrojových souborů C nebo C++

Pokud jste definovali guid ovládacího prvku a příznaky trasování pro ovladač v souboru hlaviček (například trace.h), musíte zahrnout hlavičkový soubor do zdrojových souborů, kde inicializujete a uvolníte WPP (krok 4) nebo zavoláte funkce trasování zpráv.

Kromě toho musíte přidat příkaz #include pro hlavičkový soubor se zprávami trasování (.tmh). Při sestavování ovladače nebo aplikace vygeneruje preprocesor WPP soubory hlaviček trasovací zprávy (.tmh) pro každý zdrojový soubor, který obsahuje funkce trasovací zprávy.

/* -- driver.c  - include the *.tmh file that is generated by WPP --*/

#include "trace.h"     /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh"  /* this file is auto-generated */

Krok 4: Přidání maker do příslušných funkcí zpětného volání pro inicializaci a vyčištění programu WPP

Inicializovat WPP při vstupu ovladače

Přidejte WPP_INIT_TRACING makro do rutiny DriverEntry ovladače režimu jádra nebo ovladače UMDF 2.0 nebo do DLLMain rutiny ovladače uživatelského režimu (UMDF 1.x) nebo aplikace.

Vyčištění prostředků WPP při ukončení ovladače

Přidejte makro WPP_CLEANUP do rutiny uvolnění ovladače (například DriverContextCleanup nebo DriverUnload) ovladače režimu jádra nebo ovladače UMDF 2.0.

Pro ovladač uživatelského režimu (UMDF 1.x) nebo aplikaci přidejte makro WPP_CLEANUP do rutiny DLLMain.

Makro WPP_CLEANUP byste měli také přidat do rutiny DriverEntry, pokud DriverEntry selže. Pokud například DriverEntry selže, rutina uvolnění ovladače nebude vyvolána. Podívejte se na volání WdfDriverCreate v následujícím příkladu.

Příklad ovladače v režimu jádra používajícího WPP_INIT_TRACING a WPP_CLEANUP v DriverEntry


NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{  

          //  ... 

                //
    // Initialize WPP Tracing in DriverEntry
    //
    WPP_INIT_TRACING( DriverObject, RegistryPath );

                //  ...


 //
    // Create a framework driver object to represent our driver.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes, // Driver Object Attributes
        &config,          // Driver Config Info
        WDF_NO_HANDLE // hDriver
        );

    if (!NT_SUCCESS(status)) {

        TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDriverCreate failed with status 0x%x\n", status);
        //
        // Cleanup tracing here because DriverContextCleanup will not be called
        // as we have failed to create WDFDRIVER object itself.
        // Please note that if you return failure from DriverEntry after the
        // WDFDRIVER object is created successfully, you don't have to
        // call WPP cleanup because in those cases DriverContextCleanup
        // will be executed when the framework deletes the DriverObject.
        //
        WPP_CLEANUP(DriverObject);

    }

                return status;

}

Příklad ovladače režimu jádra používajícího WPP_CLEANUP v DriverContextCleanup



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

Příklad ovladače UMDF 2.0 pomocí WPP_INIT_TRACING v DriverEntry


/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"


 // Initialize WPP Tracing in the DriverEntry routine
 //
    WPP_INIT_TRACING( MYDRIVER_TRACING_ID );

Příklad použití maker UMDF 1.0 WPP_INIT_TRACING a WPP_CLEANUP ve funkci DLLMain

/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"


//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
// 

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);              // Initialize WPP tracing

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();                                                                                                              // Deactivate and cleanup WPP tracing
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Krok 5: Instrumentace kódu ovladače pro generování trasovacích zpráv v příslušných bodech

Můžete použít libovolnou funkci zprávy trasování, kterou zvolíte, za předpokladu, že se správně definuje funkce zprávy trasování, příznaky trasování a úrovně. Výchozí funkcí zprávy trasování je makro DoTraceMessage. Toto makro můžete do kódu přidat pro zápis zpráv do souboru protokolu. Následující tabulka uvádí některé z předdefinovaných funkcí trasovacích zpráv a ladicí tiskové funkce, které můžete použít k vytváření trasovacích zpráv.

Příklady funkcí trasování zpráv	Kdy použít
DoTraceMessage	Toto je výchozí funkce sledovací zprávy. Výhodou použití DoTraceMessage je, že funkce je již definována za vás. Příznaky trasování, které zadáte, můžete použít v makrech WPP_CONFIG_GUIDS. Nevýhodou použití DoTraceMessageje, že funkce přebírá pouze jeden podmíněný parametr, tj. příznak trasování. Pokud chcete použít úrovně trasování, protokolovat pouze chybové zprávy nebo zprávy upozornění, můžete použít DoDebugTrace makru nebo použít TraceEvents, která používá příznaky trasování i úrovně trasování.
TraceEvents	Pokud vytvoříte ovladač pomocí šablon WDF v sadě Visual Studio, jedná se o výchozí funkci trasování zpráv. Výhodou použití TraceEvents je, že funkce zprávy trasování, příznaky trasování a úroveň trasování už jsou pro vás definovány. Kromě toho šablony zahrnují také instrumentaci, která při vstupu a ukončení funkce zapisuje zprávy do souboru protokolu.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx	Výhodou použití ladicích funkcí pro tisk je, že nemusíte upravovat stávající příkazy ladění. Můžete snadno přepnout ze zobrazení zpráv v ladicím programu na záznam trasovacích zpráv v souboru. Pokud jste upravili funkci zprávy trasování tak, aby zahrnovala jednu z ladicích tiskových funkcí, nemusíte dělat nic víc. Když vytvoříte relaci trasování pomocí logmana nebo Tracelogu nebo jiného kontroleru trasování, stačí zadat příznaky a úrovně pro svého poskytovatele. Všechny ladicí výstupy, které splňují zadané podmínky, se vytisknou do logu.

Použití příkazů DoTraceMessage

Do kódu přidejte makro DoTraceMessage, podobně jako byste přidali rutinu pro ladění výstupu. Makro DoTraceMessage přijímá 3 parametry: úroveň příznaku (TraceFlagName), který určuje podmínku pro zapsání trasovací zprávy, řetězec Zpráva a volitelný seznam proměnných.
```
DoTraceMessage(TraceFlagName, Message, [VariableList... ])
```
Například následující příkaz DoTraceMessage zapíše název funkce, která obsahuje příkaz DoTraceMessage, pokud je pro relaci trasování povolen příznak TRACE_DRIVER, jak je definováno v WPP_CONTROL_GUIDS.
```
     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );
```
Příklad používá předdefinovaný řetězec pro aktuálně spuštěnou funkci (%FUNC!). Další informace o řetězcích specifikace definovaného formátu WPP najdete v tématu Co jsou řetězce specifikace rozšířeného formátu WPP?
Pokud chcete vygenerovat trasovací zprávu, vytvořte pro svého poskytovatele trasování relaci trasování pomocí logmana nebo tracelogu a zadejte příznak trasování, který nastaví příznak TRACE_DRIVER (bit 1, 0x2).

//
//  DoTraceMessage examples
// 

     ...

// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2), 
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.

     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

     ...

// writes the name of the function, the line number, and the error code 

      DoTraceMessage(
            TRACE_DRIVER,
            "[%s] Failed at %d (error code= %d)\n",
            __FUNCTION__,
            __LINE__,
            dwLastError);

Použití příkazů TraceEvents

Pokud používáte šablony ovladačů systému Windows v sadě Visual Studio, je makro TraceEvents definováno v souboru hlavičky Trace.h.

Přidejte do kódu TraceEvents makro, jako byste chtěli ladit rutinu tisku. Makro TraceEvents přebírá následující parametry: úroveň trasování (úroveň) a příznak trasování (Příznaky), které definují podmínky, kdy je zpráva trasování zapsána, řetězec Zpráva a volitelný seznam proměnných.
```
TraceEvents(Level, Flags, Message, [VariableList... ])
```
Například následující příkazu TraceEvents zapíše název funkce, která obsahuje příkaz TraceEvents, pokud jsou splněny podmínky zadané v úroveň trasování a parametry příznaku trasování. Úroveň trasování je celočíselná hodnota; cokoli na úrovni trasování, která je zadaná pro danou relaci trasování, nebo pod touto úrovní, bude sledováno. TRACE_LEVEL_INFORMATION je definován v Evntrace.h a má hodnotu 4. Příznak TRACE_DRIVER (bit 1, 0x2) je definován v WPP_CONTROL_GUIDS. Pokud je tento TRACE_DRIVER bit nastavený pro trasovací relaci a úroveň trasování je 4 nebo vyšší, TraceEvents zapíše zprávu trasování.
```
        TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");
```
Příklad používá předdefinovaný řetězec pro aktuálně spuštěnou funkci (%FUNC!). Další informace o řetězcích specifikace definovaného formátu WPP najdete v tématu Co jsou řetězce specifikace rozšířeného formátu WPP?
Chcete-li vygenerovat trasovací zprávu, vytvořte relaci trasování pro svého poskytovatele trasování pomocí Logmanu nebo Tracelog. Zadejte úroveň trasování pro TRACE_LEVEL_INFORMATION (4) nebo vyšší a zadejte úroveň trasování, která nastaví TRACE_DRIVER bit (bit 1, 0x2).

//
//  TraceEvents examples
// 


    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

//


    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                       "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");

    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                "Built %s %s\n", __DATE__, __TIME__);

Krok 6: Úprava projektu sady Visual Studio pro spuštění preprocesoru WPP a sestavení řešení

WDK poskytuje podporu pro preprocesor WPP, abyste mohli spustit preprocesor pomocí sady Visual Studio a prostředí MSBuild.

Spuštění preprocesoru WPP

V Průzkumníku řešení vyberte a podržte projekt ovladače (nebo na ho klikněte pravým tlačítkem myši) a vyberte Vlastnosti.
Na stránce vlastností daného projektu vyberte Vlastnosti konfigurace a vyberte Trasování WPP.
V oddílu Obecnénastavte možnost Spustit WPP na Ano.
V části příkazového řádkupřidejte další možnosti pro přizpůsobení chování trasování. Informace o tom, co můžete přidat, viz část preprocesoru WPP.
Sestavte projekt nebo řešení pro cílovou konfiguraci a platformu. Viz Sestavení ovladače pomocíWDK .

Informace o procesu sestavení najdete v tématu úlohy TraceWPP a WDK a prostředí sestavení sady 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 a bin/x64 wdK.

Krok 7: Spuštění relace trasování pro zachycení a ověření trasovacích zpráv

Pokud chcete ověřit, že jste správně nastavili trasování WPP, měli byste ovladač nebo aplikaci nainstalovat do testovacího počítače a pak vytvořit relaci trasování pro zachycení trasovacích zpráv. Relaci trasování můžete vytvořit pro svého zprostředkovatele trasování pomocí libovolného kontroleru trasování, jako je Logman, Tracelognebo TraceView. Zprávy můžete zapsat do souboru protokolu nebo odeslat ladicímu programu jádra. V závislosti na funkcích zpráv trasování, které používáte, je potřeba zadat příznaky trasování a úrovně trasování, které budou generovat zprávy.

Pokud například používáte úrovně trasování definované v Evntrace.h a chcete zachytit TRACE_LEVEL_INFORMATION (4) nebo vyšší, musíte nastavit úroveň na 4. Když nastavíte úroveň 4 pro relaci trasování, zachytí se také všechny informační zprávy (4), upozornění (3), chyby (2) a kritické zprávy (1), pokud budou splněny i ostatní podmínky, jako jsou trasovací příznaky.

Pokud chcete ověřit, že se vygenerují všechny zprávy, můžete jednoduše nastavit úroveň trasování a příznaky trasování na maximální hodnoty, aby se vygenerovaly všechny zprávy. Příznaky trasování používají bitovou masku (ULONG), takže můžete nastavit všechny bity (například 0xFFFFFFFF). Úrovně trasování jsou reprezentovány bajtovou hodnotou. Pokud například používáte Logman, můžete zadat 0xFF pro pokrytí všech úrovní.

(Příklad) Spuštění relace trasování pomocí Logmanu

logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl 

logman start "myWPP_session"

logman stop "myWPP_session"

(Příklad) Spuštění relace trasování pomocí TraceLogu

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

Příkaz Tracelog obsahuje parametr -f, který určuje název a umístění souboru protokolu trasování událostí. Obsahuje parametr -flag k určení sad příznaků a parametru -level k určení nastavení úrovně. Tyto parametry můžete vynechat, ale někteří poskytovatelé sledování negenerují žádné sledující zprávy, pokud nenastavíte příznak nebo úroveň. Úroveň trasování je definována v souboru Evntrace.h a úrovně trasování poskytují pohodlný způsob klasifikace trasovacích zpráv jako kritických, chyb, upozornění a informačních zpráv.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-18

Sdílet prostřednictvím

Přidání trasování softwaru WPP do ovladače systému Windows

Krok 1: Definování GUID ovládacího prvku a příznaků trasování

Krok 2: Vyberte, které funkce trasování zpráv chcete použít, a definujte makra WPP pro tyto funkce

Volba funkce trasovací zprávy

Vytvoření nebo přizpůsobení funkce zprávy trasování

Krok 3: Zahrnutí přidružených souborů hlaviček trasování (.h a .tmh) do zdrojových souborů C nebo C++

Krok 4: Přidání maker do příslušných funkcí zpětného volání pro inicializaci a vyčištění programu WPP

Inicializovat WPP při vstupu ovladače

Vyčištění prostředků WPP při ukončení ovladače

Krok 5: Instrumentace kódu ovladače pro generování trasovacích zpráv v příslušných bodech

Použití příkazů DoTraceMessage

Použití příkazů TraceEvents

Krok 6: Úprava projektu sady Visual Studio pro spuštění preprocesoru WPP a sestavení řešení

Spuštění preprocesoru WPP

Krok 7: Spuštění relace trasování pro zachycení a ověření trasovacích zpráv

Váš názor

Další materiály