UMDF ベースのドライバーでの WPP ソフトウェア トレースの使用
WPP ソフトウェア トレースを使用すると、ドライバーのデバッグに役立つトレース メッセージを追加できます。また、フレームワークのイベント ロガーにも、表示できるトレース メッセージが数多く用意されています。
トレース メッセージを表示するには、TraceView または Tracelog を使用します。トレース メッセージをカーネル デバッガーに送信することもできます。
ドライバーへのトレース メッセージの追加
フレームワークベースのドライバーにトレース メッセージを追加するには、次の操作を行う必要があります。
ドライバーのソース ファイルのうち、WPP マクロを含む各ファイルに、#include ディレクティブを追加します。このディレクティブでは、トレース メッセージ ヘッダー (TMH) ファイルを識別する必要があります。ファイル名は、<ドライバーのソース ファイル名>.tmh の形式で指定する必要があります。
たとえば、ドライバーが MyDriver1.c および MyDriver2.c という 2 つのソース ファイルで構成されている場合、MyDriver1.c では次のように指定する必要があります。
#include "MyDriver1.tmh"
MyDriver2.c では次のように指定する必要があります。
#include "MyDriver2.tmh"
ビルド ユーティリティを実行すると、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 ヘッダー ファイルに含まれています)。
ドライバーの Source ファイルに RUN_WPP ディレクティブを追加します。このディレクティブは、ドライバーで WPP プリプロセッサを実行するようビルド ユーティリティに指示します。
サンプル UMDF ベース ドライバーの Sources ファイルから引用した RUN_WPP ディレクティブの例を次に示します。
RUN_WPP= $(SOURCES) -dll -scan:internal.h
この例を使用すると、カスタマイズされたトレース メッセージ マクロを含む Internal.h で WPP プリプロセッサが文字列 begin_wpp config および end_wpp を検索します。
ドライバーにトレース メッセージを追加する方法の詳細については、「ドライバーへの WPP マクロの追加」(英語の可能性あり) を参照してください。
WPP ソフトウェア トレースを使用するサンプル ドライバー
WDK のすべてのサンプル UMDF ベース ドライバーに、WPP ソフトウェア トレースを有効にする DllSup.h、Internal.h、および Sources の各ファイルが用意されています。また、これらのサンプル ドライバーのほとんどは、カスタマイズされたマクロを使用してトレース メッセージを作成します。
ドライバーのトレース メッセージの表示
ドライバーにトレース メッセージを追加すると、そのドライバーはトレース プロバイダーになります。トレース セッションを制御したり、トレース ログを作成したりするには、Tracelog などのトレース コントローラーを使用します。メッセージを表示するには、Tracefmt などのトレース コンシューマーを使用します。
ソフトウェア トレース ツールの使用方法の詳細については、「ソフトウェア トレース ツールの概要」(英語の可能性あり) を参照してください。
UMDF トレース ログの表示
UMDF のトレース ログは、%windir%\system32\LogFiles\WUDF\WUDFTrace.etl です。トレース ログのメッセージをフォーマットする TMF ファイルは、WDK に含まれています (\tools\tracing サブディレクトリにあります)。TraceView や Tracelog では、これらのファイルが必要になります (Traceview では、UMDF が名前付きプロバイダーとして表示されます。名前は、UMDF のバージョンに応じて "UMDF-Framework Trace" または "Framework Trace" になります)。
WDF Verifier を使用すると、トレース メッセージを UMDF トレース ログとカーネル デバッガーの両方に送信できます (Tracelog の -kd オプションを使用してトレース メッセージをカーネル デバッガーに送信しないでください。UMDF のトレース ログが阻害される可能性があります)。
デバッガーでトレース メッセージを表示するには、!wmitrace デバッガー拡張機能を使用します。
トレース メッセージの制御
UMDF トレース メッセージを制御するには、WDF Verifier のユーザー インターフェイスを使用するか、レジストリ値を変更します。可能であれば WDF Verifier のインターフェイスを使用してください。レジストリ値は、将来のバージョンの UMDF で変更される可能性があります。また、INF ファイルやドライバーのコードでそれらの値にアクセスしないようにしてください。
現在変更できるレジストリ値を以下に示します。これらの値は、HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF レジストリ キーにあります。
LogEnable 値は、UMDF がドライバーのトレース ログを作成するかどうかを制御します。この値を 1 に設定すると、トレース ログが作成されます。
LogLevel 値は、UMDF トレース メッセージに含まれる情報の量を制御します。LogLevel の既定値は 3 で、UMDF トレース メッセージにエラー メッセージと警告メッセージが含まれます。この値を 7 に設定すると、エラー メッセージと警告メッセージに加えて、エラー以外の情報メッセージが含まれます。15 に設定すると、UMDF で提供可能なすべてのトレース情報が含まれます。
LogKd 値は、UMDF がトレース メッセージをカーネル デバッガーに送信するかどうかを制御します。LogKd を 1 に設定すると、トレース メッセージがカーネル デバッガーに送信されます。
LogFlushPeriodSeconds 値は、トレース メッセージをトレース ログに書き込む頻度 (秒) を指定します。
LogMinidumpType 値のフラグは、ミニ ダンプ ファイルが生成される場合にそこに含まれる情報の種類を指定します。これらのフラグの詳細については、MINIDUMP_TYPE 列挙型を参照してください。
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF レジストリ キーにその他のレジストリ値があった場合、それらの値は変更しないでください。