次の方法で共有

WPP プリプロセッサ

このセクションでは、 Windows ソフトウェア トレース プリプロセッサ (一般に WPP プリプロセッサと呼ばれます) について説明します。

WPP プリプロセッサの呼び出し

WPP プリプロセッサは、Visual Studio と MSBuild 環境を使用して呼び出すことができます。

WPP プリプロセッサを呼び出すには

  1. ソリューション エクスプローラーでドライバー プロジェクトを右クリックし、[プロパティ] をクリックします 。

  2. プロジェクトプロパティページで、構成プロパティ をクリックし、その後 WPP トレース をクリックします。

  3. [ 全般] で、[ WPP の実行 ] オプションを [はい] に設定します。

  4. [コマンド ライン] で、以下のオプションを追加してトレース動作をカスタマイズできます。

    たとえば、 WPP トレースでは、単一の スキャン構成データ ファイルを指定できます。

    カスタム データ型を指定するなど、複数の構成ファイルを指定する必要がある場合は、-scan オプションを使用してコマンド ラインでファイルを参照します。次に例を示します。

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

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

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

WPP トレースの全般オプション

次の表では、WPP プリプロセッサのオプションについて説明します。 これらのオプションは、プロジェクトの WPP トレース プロパティ ページを使用するか、TraceWPP ツールのパラメーターとして Visual Studio で構成できます。

WPP トレース オプション 説明

WPP を実行する

true の場合、WPP を呼び出します。

最小限のリビルドを有効にする

true の場合、追跡された増分ビルドが実行されます。false の場合、再構築が実行されます。

関数とマクロのオプション

WPP トレース オプション TraceWPP コマンド オプション 説明

プリプロセッサの定義

-Dマクロ

生成されたファイルの先頭に#defineマクロを追加します。マクロはマクロの名前です。

このオプションは、 /D (マクロの定義) コンパイラ オプションと同じ効果を持ちます。 TMH ファイルの開始時に定義が有効であることを確認するために含まれています。

-Dマクロ=展開

生成されたファイルの先頭に #defineマクロ展開 を追加します。マクロ はマクロの名前であり、展開 はその展開された値です。

このオプションは、 /D (マクロの定義) コンパイラ オプションと同じ効果を持ちます。 TMH ファイルの開始時に定義が有効であることを確認するために含まれています。

トレース Kernel-Mode コンポーネント

-キロメートル

カーネル モード コンポーネントをトレースするWPP_KERNEL_MODE マクロを定義します。 既定では、ユーザー モード コンポーネントのみがトレースされます。

Dll マクロを有効にする

-dll

WPP_DLL マクロを定義します。これにより、WPP_INIT_TRACINGが呼び出されるたびに WPP データ構造が初期化されます。 それ以外の場合、構造体は 1 回だけ初期化されます。

コントロール GUID の指定

-ctl:GUID

 指定したコントロール GUID と、Error、Unusual、Noise という名前のWPP_DEFINE_BITエントリを使用して、WPP_CONTROL_GUIDS マクロを定義します。

これは、ソース ファイルにマクロを追加する代わりに使用します。

GUID はコントロール GUID を表します。

検索と書式設定のオプション

WPP トレース オプション TraceWPP コマンド オプション 説明

感嘆符を無視する

-noshrieks

"シュリケ" とも呼ばれる感嘆符を無視するよう WPP に指示します。

%!timestamp! などの複雑な書式設定で使用されます。%. 既定では、感嘆符が必要であり、WPP はそれらを解釈しようとします。

書式指定文字列の番号付けの数値ベース

-argbase:Number

"%1!d!, %2!s!" などの書式指定文字列の番号付けの数値ベースを確立します。 既定値は 1 です。

トレース メッセージを生成する関数

-func:FunctionDescription

DoTraceMessage マクロの代替手段を指定します。 これらの関数を使用して、トレース メッセージを生成できます。

たとえば、次のようなトレース メッセージのフラグとレベルの両方を指定する関数を定義できます。

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

func オプションの複数のインスタンスを使用できます。

このオプションは、ローカル構成ファイルで関数の説明を指定する代わりに使用できます。

検索する文字列を指定する

-lookfor:String

トレースを開始するために、指定された文字列のソース ファイルを検索するように WPP に指示します。 既定では、WPP は文字列 "WPP_INIT_TRACING" を検索します。

これは、独自のテンプレートを作成するユーザー向けの高度なオプションです。

たとえば、default.tpl では次のようになります。

IF FOUND WPP_INIT_TRACING
 INCLUDE um-init.tpl
ENDIF

モジュール名の指定

-p:String

このトレース プロバイダーからのメッセージのメッセージ GUID の代替フレンドリ名を指定します。 既定では、メッセージ GUID のフレンドリ名は、トレース プロバイダーがビルドされたディレクトリの名前です。

既定では、メッセージ GUID のフレンドリ名が、変数で表される トレース メッセージ プレフィックス に表示%1。 このパラメーターを使用すると、トレース プロバイダーのフレンドリ名、トレース プロバイダーを含むモジュールの名前、複数のトレース プロバイダーを作成して実装されるプロジェクトの名前など、ユーザーがトレース プロバイダーを識別するのに役立つ文字列をプレフィックスに追加できます。 この情報は、ユーザーが異なるファイルまたは異なるパスにある関連するトレース プロバイダーを関連付けるのに役立ちます。

p パラメーターには、Windows Vista 用 Windows Driver Kit (WDK) およびそれ以降のバージョンの WDK に含まれている WPP のバージョンが必要です。 -p パラメーターは、Windows 2000 以降のバージョンの Windows で動作します。

例：

-p:TraceDrv
-p:AudioModule

ファイル オプション

WPP トレースオプション TraceWPP コマンド オプション 説明

追加のインクルード ディレクトリ

-IPath1[;Path2]

インクルード パスに追加するディレクトリを 1 つ以上指定します。複数指定する場合には、セミコロンで区切ってください。 cfgdir と同じです。

構成ディレクトリ

-cfgdir:Path1[;Path2]

構成ファイルとテンプレート ファイルの場所を指定します。

Path1 と Path2 は、ディレクトリへの完全修飾パスを表します。 複数のパスを指定できます。 既定値はローカル ディレクトリです。

ファイル拡張子

-ext:.ext1[.ext2]

WPP がソース ファイルとして認識するファイルの種類を指定します。 WPP は、別のファイル名拡張子を持つファイルを無視します。

既定では、WPP は .c、.c++、.cpp、および .cxx ファイルのみを認識します。

このオプションを使用すると、WPP で使用しないリソース ファイル (.rc ファイルや .mc ファイルなど) を削除したり名前を変更したりする必要なく、WPP の既定の設定を使用できます。

たとえば、C++ ファイルとヘッダー (.h) ファイルにトレースを追加するには、次のコマンドを使用します。

-ext:.cpp.CPP.h.H

また、C++ ファイルとヘッダー ファイルの TMH ファイルに異なる名前を付けるために、 -preserveext オプションを使用します。

ファイル拡張子を保持する

-preserveext:.ext1[.ext2]

TMH ファイルの作成時に、指定したファイル名拡張子を保持します。

既定では、すべてのファイルの種類の TMH ファイルには filename.tmh という名前が付けられます。 これにより、同じ名前のソース ファイルが複数ある場合に、ファイル名の競合が発生します。

たとえば、既定では、C ファイル (.c) ファイルとヘッダー (.h) ファイルの TMH ファイルには、 <filename>.tmh という名前が付けられます。 -preserveext:.c .h を使用すると、TMH ファイルの名前は <filename>.c.tmh と <filename>.h.tmh になります。

出力ディレクトリ

 -odir:path

WPP によって作成される出力ファイルのディレクトリを指定します。

パス は、ディレクトリへの完全修飾パスです。 既定値はローカル ディレクトリです。

テンプレート ファイルの指定

-gen{ File.tpl }. ext

中かっこ {}間に指定された名前で WPP が処理するすべてのソース ファイルについて、指定したファイル名拡張子を持つ別のファイルを作成します。

File.tpl はソース ファイルを表します。 *.ext は、作成されるファイルの種類とそのファイル名拡張子を表します。

複数の -gen オプションを 指定できます。

たとえば、 -gen{um-default.tpl}.tmh は、WPP が処理するすべての um-default.tpl ファイルについて、 um-default.tmh ファイルを生成することを意味します。

構成データのスキャン

-scan:File

カスタム データ型などの構成データを、構成ファイルではないファイルと defaultwpp.iniで検索します。

begin_wpp configとend_wppという文字列で構成データを囲んで識別します。 構成データには、defaultwpp.iniで使用されるのと同じ形式を使用します。

構成データをカスタム構成ファイルに追加した場合は、 -ini パラメーターを使用します。

代替構成ファイル

-defwpp:path

代替構成ファイルを指定します。 Wpp は、defaultwpp.ini ファイルの代わりにこのファイルを使用します。

追加の構成ファイル

-ini:Path

追加の構成ファイルを指定します。 WPP では、既定のファイル defaultwpp.iniに加えて、指定したファイルが使用されます。

トレース用の構成データを格納する新しい構成ファイルを作成した場合は、このパラメーターを使用します。 構成データをソース ファイルやヘッダー ファイルなどの別の種類のファイルに追加した場合は、 -scan パラメーターを使用します。

WPP ビルド プロセス

ドライバーまたはユーザー モード アプリケーションに対して WPP が有効になっている場合、ドライバーまたはアプリケーションをビルドすると、ドライバーまたはアプリケーション ファイルがコンパイルされる前に WPP プリプロセッサが呼び出されます。

WPP ビルド プロセスでは、次の手順が完了します。

  1. WPP プリプロセッサは、各ソース ファイルの WPP マクロを処理し、各ソース ファイルのトレース メッセージ ヘッダー ファイル を作成します。 ソース コードは直接変更されません。

  2. WPP プリプロセッサがトレース メッセージ ヘッダー ファイルを作成した後、C プリプロセッサは、トレース メッセージ ヘッダー ファイル内の組み込みの WPP マクロを通常の方法で処理します。