UMDF ドライバーでの WPP ソフトウェア トレースの使用
WPP ソフトウェア トレース を使用すると、ドライバーのデバッグに役立つトレース メッセージを追加できます。 さらに、フレームワークの イベント ロガー には、表示できる数百のトレース メッセージが用意されています。
TraceView または Tracelog を使用して、トレース メッセージを表示できます。 また、カーネル デバッガー にトレース メッセージを送信することもできます。
ドライバーへのトレース メッセージの追加
フレームワーク ベースのドライバーにトレース メッセージを追加するには、次の操作を行う必要があります。
WPP マクロのいずれかを含むドライバーの各ソース ファイルに #include ディレクティブを追加します。 このディレクティブは、トレース メッセージ ヘッダー (TMH) ファイルを識別する必要があります。 ファイル名の形式 <driver-source-file-name>.tmh である必要があります。
たとえば、ドライバーが MyDriver1.c と MyDriver2.c という 2 つのソース ファイルで構成されている場合、MyDriver1.c には次のものが含まれている必要があります。
#include "MyDriver1.tmh"さらに MyDriver2.c には次のものが含まれている必要があります。
#include "MyDriver2.tmh"Microsoft Visual Studio でドライバーをビルドすると、WPP プリプロセッサが .tmh ファイルを生成します。
ヘッダー ファイルで WPP_CONTROL_GUIDS マクロを定義します。 このマクロは、ドライバーのトレース メッセージの GUID フラグと トレース フラグ を定義します。 (WDK の UMDF ベースのサンプル ドライバーごとに、Internal.h ヘッダー ファイルにこのマクロが含まれています)。
ドライバーの DllMain ルーチンに WPP_INIT_TRACING マクロを含めます。 このマクロは、ドライバーのソフトウェア トレースをアクティブにします。 (WDK の UMDF ベースのサンプル ドライバーごとに、DllSup.h ヘッダー ファイルにこのマクロが含まれています)。
ドライバーの DllMain ルーチンにWPP_CLEANUP マクロを含めます。 このマクロは、ドライバーのソフトウェア トレースを無効にします。 (WDK の UMDF ベースのサンプル ドライバーごとに、DllSup.h ヘッダー ファイルにこのマクロが含まれています)。
トレース メッセージを作成するには、ドライバーで DoTraceMessage マクロまたはカスタマイズされたバージョンのマクロを使用します。 (WDK の UMDF ベースのサンプル ドライバーごとに、Internal.h ヘッダー ファイルにこのカスタマイズされたマクロが含まれています)。
ドライバー プロジェクトのプロパティ ページを開きます。 ソリューション エクスプローラーで、ドライバー プロジェクトを右クリックし、 [プロパティ] を選択します。 ドライバーのプロパティ ページで、[構成プロパティ]、[Wpp] の順に選びます。 [全般] メニューの [WPP トレースの実行] を [はい] に設定します。 [ファイル オプション] メニューで、フレームワークの WPP テンプレート ファイルも指定する必要があります。次に例を示します。
{km-WdfDefault.tpl}*.tmh
ドライバーにトレース メッセージを追加する方法の詳細については、「ドライバーへの WPP マクロの追加」をご参照ください。
WPP ソフトウェア トレースを使用するサンプル ドライバー
WDK 内のすべての UMDF ベースのサンプル ドライバーには、WPP ソフトウェア トレースを有効にする DllSup.h、Internal.h、Sources ファイルが用意されています。 これらのサンプル ドライバーのほとんどは、カスタマイズされたマクロを使用してトレース メッセージを作成します。
ドライバーのトレース メッセージの表示
ドライバーにトレース メッセージを追加した場合、ドライバーは トレース プロバイダーです。 Tracelog などのトレース コントローラーを使って、トレース セッションを制御し、トレース ログを作成できます。 Tracefmt などのトレース コンシューマーを使用して、メッセージを表示できます。
ソフトウェア トレース ツールの使用方法の詳細については、「ソフトウェア トレース ツールの調査」をご参照ください。
UMDF トレース ログの表示
UMDF ログ ソリューション ファイルの保存先は %ProgramData%*\\Microsoft\\WDFです。
UMDF ログ ファイルは、TraceView または Tracelog を使用して表示できます。 どちらのツールにも、トレース ログのメッセージを書式設定するトレース メッセージ形式 (TMF) ファイルが必要です。 TMF ファイルは、WDK の \tools\tracing サブディレクトリにあります。 (TraceView では、UMDF は、UMDF のバージョンに応じて、「UMDF-Framework トレース」 または 「フレームワーク トレース」 という名前の名前のプロバイダーとして表示されます)。
WDF 検証ツール を使用すると、UMDF トレース ログとカーネル デバッガーの両方にトレース メッセージを送信できます。 (Tracelog では UMDF 内のトレース ログが中断される可能性があるため、Tracelog の -kd オプションを使用してカーネル デバッガーにトレース メッセージを送信しないでください)。
!wmitrace デバッガー拡張機能を使用して、デバッガーでトレース メッセージを表示することもできます。
WinDbg で、ドライバーをホストする WUDFHost のインスタンスにアタッチします。 詳細については、「UMDF ドライバーのデバッグを有効にする方法」をご参照ください。
ドライバーがバージョン 1.11 以降を使用していて、Windows 8 以降のカーネル デバッガーを使用している場合は、この手順をスキップできます。 ドライバーで 1.11 より前のバージョンの UMDF を使用している場合は、!wmitrace.tmffile または !wmitrace.searchpath を使用して、プラットフォーム固有のトレース メッセージ形式 (.tmf) ファイル、または .tmf ファイルへのパスを指定します。 .tmf ファイルは、WDK のプラットフォーム固有のサブディレクトリにあります。
トレース バッファーの内容を表示するには、!wmitrace.logdump コマンドを使用します。
!wmitrace.logdump WudfTrace
トレース メッセージの制御
UMDF トレース メッセージは、WDF 検証ツールが提供するユーザー インターフェイスを使用するか、レジストリ値を変更して制御できます。 将来のバージョンの UMDF でレジストリ値が変更される可能性があるため、可能な場合は WDF 検証ツール インターフェイスを使用する必要があります。 さらに、INF ファイルまたはドライバーのコード内でこれらの値にアクセスしないでください。
現在、HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF レジストリ キーの下にある次のレジストリ値を変更できます。
LogEnable 値は、UMDF がドライバーのトレース ログを作成するかどうかを制御します。 この値を 1 に設定すると、UMDF によってトレース ログが作成されます。
LogLevel 値は、UMDF トレース メッセージに含まれる情報の量を制御します。 LogLevel の既定値は 3 で、UMDF トレース メッセージにエラー メッセージと警告メッセージが含まれます。 エラー メッセージと警告メッセージに加えて、エラー以外の情報メッセージを含めるには、この値を 7 に設定します。 UMDF が提供できるすべてのトレース情報を含めるには、15 に設定します。
LogKd 値は、UMDF がカーネル デバッガーにトレース メッセージを送信するかどうかを制御します。 LogKd が 1 に設定されている場合、UMDF はカーネル デバッガーにそのトレース メッセージを送信します。
LogFlushPeriodSeconds 値は、トレース メッセージをトレース ログに書き込む頻度を秒単位で指定します。
LogMinidumpType 値には、ミニ ダンプ ファイルが生成された場合に含める情報の種類を指定するフラグが含まれています。 これらのフラグの詳細については、MINIDUMP_TYPE 列挙体をご参照ください。
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF レジストリ キーには、その他のレジストリ値があります。 これらの値は変更しないでください。