Windows ドライバーへの WPP ソフトウェアトレースの追加

[アーティクル]
06/14/2023

カーネルモードドライバーやユーザーモードアプリケーションなどのトレースプロバイダーで WPP ソフトウェアトレースを使用するには、コード (または インストルメント) ドライバーソースファイルを追加し、ドライバープロジェクトを変更する必要があります。このセクションでは、これらの手順について説明します。

ヒント: ドライバーに WPP トレースを追加する最も簡単な方法は、Visual Studio で KMDF または UMDF ドライバーテンプレートのいずれかを使用することです。テンプレートを使用する場合、追加する必要があるコードの多くは既に行われています。 Visual Studio で、 [新しい >プロジェクト> のファイル] を選択し、Windows ドライバー (ユーザーモードまたはカーネルモード) WDF プロジェクトを選択します。 WPP マクロは、プロジェクトの一部として含まれている Trace.h ヘッダーファイルで定義されます。いずれかのテンプレートを使用する場合は、手順 5に進むことができます。

手順 1: コントロール GUID とトレースフラグを定義する
手順 2: 使用するトレースメッセージ関数を選択し、それらの関数の WPP マクロを定義する
手順 3: 関連付けられているトレースヘッダーファイル (.h および .tmh) を C または C++ のソースファイルに含める
手順 4: WPP を初期化してクリーンする適切なコールバック関数にマクロを追加する
手順 5: ドライバーコードをインストルメント化して、適切なポイントでトレースメッセージを生成する
手順 6: Visual Studio プロジェクトを変更して WPP プリプロセッサを実行し、ソリューションをビルドする
手順 7: トレースセッションを開始してトレースメッセージをキャプチャして確認する

手順 1: コントロール GUID とトレースフラグを定義する

すべてのトレースプロバイダー (ドライバー、ユーザーモードアプリなど) を一意に定義する必要があります。これを行うには、コントロール GUID、識別子、トレースフラグを定義する WPP_CONTROL_GUIDS マクロを追加します。これは、トレースするタイミングと対象を特定して制御できるように行われます。通常、各ドライバーは個別のコントロール GUID を持ちますが、ドライバーは複数のコントロール GUID を持つ場合もあれば、複数のドライバーが 1 つのコントロール GUID を共有することもできます。

便宜上、 WPP_CONTROL_GUIDS マクロは通常、共通のヘッダーファイルで定義されます。トレース用にインストルメント化するソースファイルには、ヘッダーファイルを含める (#include) 必要があります。

ドライバー WPP_CONTROL_GUIDSマクロを追加するには:

WPP トレースマクロの定義に使用できる新しい C++ ヘッダーファイルを Visual Studio プロジェクトに追加します。たとえば、ソリューションエクスプローラーでドライバーを長押し (または右クリック) し、 [新しい > 項目の追加]を選択します。ファイルを保存します (例: Trace.h)。
WPP_CONTROL_GUIDS マクロを追加して、トレースプロバイダーのフレンドリ名を指定し、コントロール GUID を定義し、特定のトレースメッセージを修飾するために使用できるトレースフラグを定義します。

WPP_CONTROL_GUIDS マクロには、次の構文があります。

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) \
        )
```
たとえば、次のコードでは、 GUIDFriendlyName として myDriverTraceGuid を使用します。 ControlGUID には、32 桁の 16 進 GUID の標準形式とは少し異なる形式があることに注意してください。 ControlGUID には 5 つのフィールドがありますが、通常のハイフンと中かっこではなく、コンマで区切られ、かっこで囲まれています。たとえば、(84bdb2e9-829e-41b3-b891-02f454bc2bd7) の代わりに(84bdb2e9,829e,41b3,b891,02f454bc2bd7) を指定します。

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 */ \
        )                             
```
ヒント : このコードスニペットをヘッダーファイルにコピーできます。コントロール GUID とフレンドリ名を必ず変更してください。 GUIDgen.exeを使用して、コントロール GUID を生成できます。 Guidgen.exeは Visual Studio に含まれています (ツール > の GUIDの作成)。 Uuidgen.exe ツールを使用することもできます。このツールは、Visual Studio のコマンドプロンプトウィンドウから入手できます (詳細については、「uuidgen.exe/? 」と入力)。
トレースプロバイダーのトレースフラグを定義します。

WPP_CONTROL_GUIDS マクロのWPP_DEFINE_BIT要素は、トレースプロバイダーのトレースフラグを定義します。通常、フラグはますます詳細なレポートレベルを表しますが、トレースメッセージを生成する条件として任意の方法でフラグを使用できます。 WPP_CONTROL_GUIDSの例では、WPP_DEFINE_BITは 4 つのトレースフラグ (MYDRIVER_ALL_INFO、TRACE_DRIVER、TRACE_DEVICE、およびTRACE_QUEUE) を定義しています。

最大 31 個のトレースフラグを定義できます。 WPP は、ビット 0 (0x1)、ビット 1 (0x2)、ビット 2 (0x4)、ビット 3 (0x8) などの順序でビット値を要素に割り当てます。トレースフラグは、ソースコードにトレースメッセージ関数を追加するときに使用します (「手順 5: ドライバーコードをインストルメント化して、適切なポイントでトレースメッセージを生成する」で説明します)。

注: トレースフラグを使用すると、特定のコンポーネント (たとえば、特定の I/O 要求、デバイスまたはドライバーオブジェクトのアクティビティ) をトレースするタイミングを制御できます。トレースフラグをトレースメッセージステートメントに追加します (例: DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). Tracelog などのトレースコントローラーでトレースセッションを作成する場合は、そのセッションでトレースプロバイダーに使用する -flag オプションを指定します。この場合、フラグはビット 1 (0x1) で、TRACE_DRIVER フラグに対応します。トレースセッションを開始すると、トレースフラグを指定するすべてのトレースメッセージがログに書き込まれます。

手順 2: 使用するトレースメッセージ関数を選択し、それらの関数の WPP マクロを定義する

デバッグ出力関数と同様に、トレースメッセージ関数は、トレースメッセージを書き込むコードに追加する関数 (またはマクロ) です。

トレースメッセージ関数の選択

既定のトレースメッセージ関数は DoTraceMessage マクロです。既定の関数を使用する場合は、プロバイダーのトレースフラグ値を使用してメッセージを生成するタイミングを制御できます。トレースフラグの値は、手順 1 でコントロール GUID を作成したときに定義したフラグです。 DoTraceMessageを使用する場合は、既定の WPP マクロが既に定義されているため (WPP_LEVEL_ENABLEDとWPP_LEVEL_LOGGER)、この手順の残りの部分をスキップして手順 5に進むことができます。
KMDF テンプレートまたは UMDF テンプレートのいずれかを使用している場合は、 TraceEvents 関数と、その関数を有効にするために必要な WPP マクロが既に定義されているため、手順 5に進むことができます。
独自のトレースメッセージ関数を作成する場合、または既存のデバッグ出力関数を変換する場合は、この手順の残りの部分に進みます。

トレースメッセージ関数の作成またはカスタマイズ

カスタムトレースメッセージ関数を使用している場合、またはデバッグ出力関数 (KdPrintなど) を変換してトレースメッセージを生成する場合は、トレースプロバイダーでトレースメッセージ関数を識別して有効にする WPP マクロを定義する必要があります。これらのマクロを、プロジェクトに追加した Trace.h ヘッダーファイルに配置します。
トレース関数を有効にする WPP マクロを定義します。

使用する各トレースメッセージ関数には、対応するマクロのペアが必要です。これらのマクロは、トレースプロバイダーを識別し、メッセージを生成する条件を指定します。通常は、既定のWPP_LEVEL_ENABLEDとWPP_LEVEL_LOGGERマクロの観点から、マクロ、 WPP_<condition>_LOGGER および WPP_<condition>_ENABLED のペアを定義します。

使用する各トレースメッセージ関数には、対応するマクロのペアが必要です。これらのマクロは、トレースプロバイダーを識別し、メッセージを生成する条件を指定します。通常は、既定のWPP_LEVEL_ENABLEDとWPP_LEVEL_LOGGERマクロの観点から、マクロ、 WPP_<condition>_LOGGER および WPP_<condition>_ENABLED のペアを定義します。

用語	説明
WPP_CONDITIONS_LOGGER	プロバイダーに関連付けられているトレースセッションを検索し、セッションにハンドルを返すために使用します。
WPP_CONDITIONS_ENABLED	指定した条件でログ記録が有効になっているかどうかを判断するために使用します。

定義した WPP マクロの場合、 CONDITIONS はトレースメッセージ関数がサポートする条件を、関数のパラメーターリストに表示される順序でアンダースコアで区切って表します。たとえば、既定のトレースメッセージ関数 DoTraceMessageでは、条件としてトレースフラグのみがサポートされるため、マクロ名 (WPP_LEVEL_ENABLED) にはパラメーターが 1 つだけ存在します。

注残念ながら、既定のマクロの名前 (WPP_LEVEL_ENABLEDとWPP_LEVEL_LOGGER) はトレースレベルパラメーターを示しているようですが、実際にはトレースフラグを参照します。

カスタムトレースメッセージ関数を使用する場合は、トレースレベルなどの追加の修飾子を設定できます。トレースレベルは Evntrace.h ファイルで定義され、トレースレベルは、トレースメッセージをエラー、警告、および情報メッセージとして分類する便利な方法を提供します。

たとえば、プロジェクトに追加したヘッダーファイルに次のコードスニペットを追加できます。次のコードでは、トレースメッセージを生成する条件としてトレースレベルパラメーターとトレースフラグパラメーターの両方をサポートするトレースメッセージ関数のカスタム WPP マクロを定義します。指定した FLAGS 値に対してログ記録が有効で、有効な LEVEL 値がトレースメッセージ関数呼び出しで使用されるレベル引数以上の場合、 WPP_LEVEL_FLAGS_ENABLED マクロは TRUE を返します。

#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)

次に、WPP 構成ブロック (begin_wpp構成 と end_wpp) でカスタムトレース関数を指定する必要があります。たとえば、Visual Studio で UMDF または KMDF ドライバープロジェクトのテンプレートを使用する場合、テンプレートは TraceEventsというカスタムトレースメッセージ関数の WPP マクロを定義します。 TraceEvents マクロ関数は、メッセージを生成するための条件としてトレースレベルとトレースフラグを使用します。 Trace.h ヘッダーファイルで WPP_LEVEL_FLAGS_ENABLED マクロを定義した場合は、次のマクロ定義を追加できます。

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

WPP 構成ブロックに同様の FUNC 宣言を追加することで、既存のデバッグ print ステートメントをトレースメッセージステートメントに変換することもできます。たとえば、次の例では、既存の KdPrint ステートメントを変換するコードを追加します。また、 FUNC 宣言では、指定したトレースレベルとフラグ {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER} を使用するように KdPrint をグローバルに定義します。デバッガーに出力を送信する代わりに、デバッグ印刷ステートメントがトレースログに送信されます。

//
// 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
//

注KdPrintEx をトレースメッセージ関数に変換する場合は、いくつかの追加の手順を実行する必要があります。 KdPrintと比較して KdPrintEx 関数は 2 つの追加の引数を受け取ります。 KdPrintEx 関数を変換するには、 ComponentID に WPP_DEFINE_BIT を定義し、カスタム WPP_<condition>_LOGGER と WPP_<condition>_ENABLED マクロを定義する必要があります。 KdPrintEx の 2 番目のパラメーターは、レベルがトレースレベルの値に似ているを指定するため、必ずしもそれらを再定義する必要はありません。


#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
//

手順 3: 関連付けられているトレースヘッダーファイル (.h および .tmh) を C または C++ のソースファイルに含める

ヘッダーファイル (trace.h など) でドライバーのコントロール GUID とトレースフラグを定義した場合は、WPP の初期化とアンロード (手順 4) またはトレースメッセージ関数の呼び出しを行うソースファイルにヘッダーファイルを含める必要があります。

さらに、トレースメッセージヘッダーファイル (.tmh) の #include ステートメントを追加する必要があります。ドライバーまたはアプリケーションをビルドすると、WPP プリプロセッサは、トレースメッセージ関数を含む各ソースファイルのトレースメッセージヘッダーファイル (.tmh) を生成します。

/* -- 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 */

手順 4: WPP を初期化してクリーンする適切なコールバック関数にマクロを追加する

ドライバーエントリで WPP を初期化するには

WPP_INIT_TRACING マクロをカーネルモードドライバーまたは UMDF 2.0 ドライバーの DriverEntry ルーチン、またはユーザーモードドライバー (UMDF 1.x) またはアプリケーションの DLLMain ルーチンに追加します。

ドライバー終了時に WPP リソースをクリーンするには

カーネルモードドライバーまたは UMDF 2.0 ドライバーのドライバーアンロードルーチン (DriverContextCleanup や DriverUnloadなど) に、 WPP_CLEANUP マクロを追加します。

ユーザーモードドライバー (UMDF 1.x) またはアプリケーションの場合は、 DLLMain ルーチンに WPP_CLEANUP マクロを追加します。

また、 DriverEntry が失敗した場合に備えて、 WPP_CLEANUP マクロを DriverEntry ルーチンに追加する必要があります。たとえば、 DriverEntry が失敗した場合、ドライバーアンロードルーチンは呼び出されません。次の例では、 WdfDriverCreate の呼び出しを参照してください。

DriverEntryでWPP_INIT_TRACINGとWPP_CLEANUPを使用するカーネルモードドライバーの例


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;

}

DriverContextCleanup でWPP_CLEANUPを使用するカーネルモードドライバーの例



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

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

   // ...

}

DriverEntry でWPP_INIT_TRACINGを使用する UMDF 2.0 ドライバーの例


/
// 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 );

DLLMain での UMDF 1.0 ドライバーのWPP_INIT_TRACINGマクロと WPP_CLEANUP マクロの使用例

/
// 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);
}

手順 5: ドライバーコードをインストルメント化して、適切なポイントでトレースメッセージを生成する

トレースメッセージ関数、トレースフラグ、およびレベルが適切に定義されていれば、任意のトレースメッセージ関数を使用できます。既定のトレースメッセージ関数は DoTraceMessage マクロです。このマクロをコードに追加して、ログファイルにメッセージを書き込むことができます。次の表に、定義済みのトレースメッセージ関数と、トレースメッセージの作成に使用できるデバッグ印刷関数の一部を示します。

トレースメッセージ関数の例	いつ使用するか
DoTraceMessage	これが既定のトレースメッセージ関数です。 DoTraceMessage を使用する利点は、関数が既に定義されていることです。 WPP_CONFIG_GUIDS マクロで指定したトレースフラグを使用できます。 DoTraceMessage を使用する場合の欠点は、関数が受け取る条件付きパラメーター、つまりトレースフラグが 1 つだけであるという点です。トレースレベルを使用する場合、エラーメッセージまたは警告メッセージのみをログに記録するには、 DoDebugTrace マクロを使用するか、トレースフラグとトレースレベルの両方を使用する TraceEvents を使用します。
TraceEvents	Visual Studio で WDF テンプレートを使用してドライバーを作成する場合、これが既定のトレースメッセージ関数です。 TraceEvents を使用する利点は、トレースメッセージ関数、トレースフラグ、およびトレースレベルが既に定義されていることです。さらに、テンプレートには、関数の入力と終了時にログファイルにメッセージを書き込むインストルメンテーションも含まれています。
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx	デバッグ印刷関数を使用する利点は、既存のデバッグ印刷ステートメントを変更する必要がないようにすることです。デバッガーでのメッセージの表示から、ファイル内のトレースメッセージの記録に簡単に切り替えることができます。デバッグ出力関数の 1 つを含むようにトレースメッセージ関数をカスタマイズした場合は、それ以上の作業を行う必要はありません。 Logman または Tracelog、または別のトレースコントローラーを使用してトレースセッションを作成する場合は、プロバイダーのフラグとレベルを指定するだけです。指定した条件を満たすデバッグ印刷ステートメントは、ログに出力されます。

DoTraceMessage ステートメントの使用

デバッグ印刷ルーチンと同様に、 DoTraceMessage マクロをコードに追加します。 DoTraceMessage マクロは、フラグレベル (TraceFlagName) という 3 つのパラメーターを受け取ります。これは、トレースメッセージの書き込み時の条件、 メッセージ 文字列、およびオプションの変数リストを定義します。
```
DoTraceMessage(TraceFlagName, Message, [VariableList... ]
```
たとえば、次の DoTraceMessage ステートメントは、WPP_CONTROL_GUIDSで定義されているTRACE_DRIVER フラグがトレースセッションに対して有効になっている場合に、 DoTraceMessage ステートメントを含む関数の名前を書き込みます。
```
     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );
```
この例では、現在実行中の関数 (%FUNC!) に定義済みの文字列を使用します。 WPP で定義された書式指定文字列の詳細については、「WPP 拡張書式指定文字列とは」を参照してください。
トレースメッセージを生成するには、Logman または Tracelogを使用してトレースプロバイダーのトレースセッションを作成し、TRACE_DRIVER フラグ (ビット 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);

Visual Studio で Windows ドライバーテンプレートを使用している場合は、 Trace.h ヘッダーファイルで TraceEvents マクロが定義されます。

TraceEvents ステートメントの使用

デバッグ印刷ルーチンと同様に、 TraceEvents マクロをコードに追加します。 TraceEvents マクロは、トレースレベル (レベル) とトレースフラグ (フラグ) を受け取ります。トレースフラグは、トレースメッセージの書き込み時の条件、 メッセージ 文字列、およびオプションの変数リストを定義します。
```
TraceEvents(Level, Flags, Message, [VariableList... ]
```
たとえば、次の TraceEvents ステートメントは、トレースレベルパラメーターとトレースフラグパラメーターで指定された条件が満たされたときに、 TraceEvents ステートメントを含む関数の名前を書き込みます。トレースレベルは整数値です。そのトレースセッションに対して指定されたトレースレベル以下の何でもトレースされます。 TRACE_LEVEL_INFORMATIONは Evntrace.h で定義され、値は 4 です。 TRACE_DRIVER フラグ (ビット 1、0x2) は、WPP_CONTROL_GUIDSで定義されます。トレースセッションに対してこのTRACE_DRIVER ビットが設定されていて、トレースレベルが 4 以上の場合、 TraceEvents はトレースメッセージを書き込みます。
```
        TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");
```
この例では、現在実行中の関数 (%FUNC!) に定義済みの文字列を使用します。 WPP で定義された書式指定文字列の詳細については、「WPP 拡張書式指定文字列とは」を参照してください。
トレースメッセージを生成するには、Logman または Tracelog を使用して、トレースプロバイダーのトレースセッションを作成します。 TRACE_LEVEL_INFORMATION (4) 以上のトレースレベルを指定し、TRACE_DRIVER ビット (ビット 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__);

手順 6: Visual Studio プロジェクトを変更して WPP プリプロセッサを実行し、ソリューションをビルドする

WDK では WPP プリプロセッサがサポートされているため、Visual Studio と MSBuild 環境を使用してプリプロセッサを実行できます。

WPP プリプロセッサを実行するには

ソリューションエクスプローラーでドライバープロジェクトを長押し (または右クリック) し、 [プロパティ]を選びます。
プロジェクトプロパティページで、 構成プロパティ をクリックして WPP トレースを選択します。
[全般] で、 [WPP の実行] オプションを [はい] に設定します。
[コマンドライン]で、追加オプションを追加してトレース動作をカスタマイズできます。追加できる内容については、「WPP プリプロセッサ」を参照してください。
ターゲットの構成とプラットフォームのプロジェクトまたはソリューションをビルドします。 WDK を使ったドライバーのビルドを参照してください。

ビルドプロセスの詳細については、「TraceWPP タスクと WDK および Visual Studio のビルド環境」を参照してください。

TraceWPP ツール (TraceWPP.exe) を使用して、ビルド環境とは別にプリプロセッサを実行することもできます。このツールは、WDK の bin/x86 および bin/x64 サブディレクトリにあります。

手順 7: トレースセッションを開始してトレースメッセージをキャプチャして確認する

WPP トレースが正しく設定されていることを確認するには、ドライバーまたはアプリケーションをテストコンピューターにインストールし、トレースメッセージをキャプチャするトレースセッションを作成する必要があります。 Logman、 Tracelog、 TraceView などの任意のトレースコントローラーを使用して、トレースプロバイダーのトレースセッションを作成できます。メッセージをログファイルに書き込んだり、カーネルデバッガーに送信したりできます。使用しているトレースメッセージ関数に応じて、メッセージを生成するトレースフラグとトレースレベルを必ず指定する必要があります。

たとえば、Evntrace.h で定義されているトレースレベルを使用していて、TRACE_LEVEL_INFORMATION (4) 以上をキャプチャする場合は、レベルを 4 に設定する必要があります。トレースセッションのレベルを 4 に設定すると、すべての情報 (4)、警告 (3)、エラー (2)、および重大 (1) メッセージもキャプチャされます。トレースフラグなどの他の条件も満たされていると仮定します。

すべてのメッセージが生成されることを確認するには、トレースレベルとトレースフラグを最大値に設定するだけで、すべてのメッセージが生成されます。トレースフラグはビットマスク (ULONG) を使用するため、すべてのビット (たとえば、0xFFFFFFFF) を設定できます。トレースレベルはバイト値で表されます。たとえば、Logman を使用している場合は、すべてのレベルに対応する0xFFを指定できます。

(例)Logman を使用したトレースセッションの開始

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"

(例)TraceLog を使用したトレースセッションの開始

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

Tracelog コマンドには、イベントトレースログファイルの名前と場所を指定する -f パラメーターが含まれています。フラグセットを指定する -flag パラメーターと、レベル設定を指定する -level パラメーターが含まれています。これらのパラメーターは省略できますが、フラグまたはレベルを設定しない限り、一部のトレースプロバイダーはトレースメッセージを生成しません。トレースレベルは Evntrace.h ファイルで定義され、トレースレベルは、トレースメッセージを重大、エラー、警告、および情報メッセージとして分類する便利な方法を提供します。

次の方法で共有

Windows ドライバーへの WPP ソフトウェアトレースの追加

手順 1: コントロール GUID とトレースフラグを定義する

手順 2: 使用するトレースメッセージ関数を選択し、それらの関数の WPP マクロを定義する

手順 3: 関連付けられているトレースヘッダーファイル (.h および .tmh) を C または C++ のソースファイルに含める

手順 4: WPP を初期化してクリーンする適切なコールバック関数にマクロを追加する

手順 5: ドライバーコードをインストルメント化して、適切なポイントでトレースメッセージを生成する

手順 6: Visual Studio プロジェクトを変更して WPP プリプロセッサを実行し、ソリューションをビルドする

手順 7: トレースセッションを開始してトレースメッセージをキャプチャして確認する

フィードバック

その他のリソース

次の方法で共有

Windows ドライバーへの WPP ソフトウェア トレースの追加

手順 1: コントロール GUID とトレース フラグを定義する

手順 2: 使用するトレース メッセージ関数を選択し、それらの関数の WPP マクロを定義する

手順 3: 関連付けられているトレース ヘッダー ファイル (.h および .tmh) を C または C++ のソース ファイルに含める

手順 4: WPP を初期化してクリーンする適切なコールバック関数にマクロを追加する

手順 5: ドライバー コードをインストルメント化して、適切なポイントでトレース メッセージを生成する

手順 6: Visual Studio プロジェクトを変更して WPP プリプロセッサを実行し、ソリューションをビルドする

手順 7: トレース セッションを開始してトレース メッセージをキャプチャして確認する

フィードバック

その他のリソース

Windows ドライバーへの WPP ソフトウェアトレースの追加

手順 1: コントロール GUID とトレースフラグを定義する

手順 2: 使用するトレースメッセージ関数を選択し、それらの関数の WPP マクロを定義する

手順 3: 関連付けられているトレースヘッダーファイル (.h および .tmh) を C または C++ のソースファイルに含める

手順 5: ドライバーコードをインストルメント化して、適切なポイントでトレースメッセージを生成する

手順 7: トレースセッションを開始してトレースメッセージをキャプチャして確認する