KMDF ログの使用方法

デバッグ中に KMDF ログを表示する

デバッグ セッション中に KMDF ログを表示するには :

1.	KMDF デバッガ拡張機能を読み込んでいない場合、これを読み込みます。
2.	KMDF TMF ファイルの検索パスを設定します。 ファイルは、WdfVersionNumber.tmf という名前で、%wdk%\WDKVersionNumber\tools\tracing\Architecture にあります。検索パスを設定するには、TMF ファイルが存在するフォルダへのパスを後に指定して !wdftmffile デバッガ拡張コマンドを実行します。下記の例では、32 ビット バージョンの Windows を実行しているコンピュータの、WDK (ビルド 6000) に含まれる WDF Version 1.5 の TMF ファイルの検索パスを設定しています。     !wdftmffile%wdk%\6000\tools\tracing\i386\wdf01005.tmf\ TRACE_FORMAT_SEARCH_PATH 環境変数を設定して検索パスを設定することもできます。!wdftmffile コマンドは、環境変数で設定された検索パスよりも優先されます。
3.	ドライバ名を後ろに指定してから !wdflogdump デバッガ拡張コマンドを実行することによって、[Command] ウィンドウにログ ファイルの内容が表示されます。.sys 拡張子は含めないでください。たとえば、Osrusbfx2 の KMDF ログをダンプするには、下記のコマンドを実行します。     !wdflogdump osrusbfx2 図 1 は、!wdflogdump の出力の典型的な例を示す、WinDbg の [Command] ウィンドウのスクリーン ショットです。 図 1. KMDF ログ

下記のように、!wdflogsave コマンドを使用して、KMDF ログの内容をファイルに保存できます。

    !wdflogsave [DriverName [FileName]]

DriverName をドライバの名前に置き換えます。この名前には、.sys 拡張子は含めないでください。ログ ファイルの名前を指定するよう、FileName を置き換えます。.etl 拡張子は含めないでください。FileName を省略した場合、ログは DriverName.etl に書き込まれます。

ページのトップへ

バグ チェック後にログ情報を取得する

システムのバグ チェック後、!wdfcrashdump コマンドを使用して、KMDF のログ情報を表示することもできます。ログ情報は、ドライバによってバグ チェックが生じたこと、または ForceLogsInMiniDump レジストリの値が設定済みであることを KMDF が認識できた場合にのみ使用できます。バグ チェックが生じたときにデバッガが接続されていた場合、!wdfcrashdump デバッガ拡張機能を使用して、KMDF ログ情報をすぐに表示できます。接続されていない場合、メモリ ダンプ ファイルを読み込んで、情報を表示します。

KMDF は、下記のバグ チェック コードが特定のドライバによって発生したかどうかを認識できます。

システムの小さなメモリ ダンプに KMDF ログ情報を含めるには、RegEdit を使用して、ドライバ設定を変更します。この設定は、ドライバの Parameters\Wdf サブキーの値として定義されています。ドライバのキーはドライバ用に名前を付けられ、Wdf サブキーの完全なパスは、次のとおりです。

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
    \DriverName\Parameters\Wdf

システムにより、小さなメモリ ダンプに KMDF ログ情報を含めるには、Wdf サブキーの ForceLogsInMiniDump 値を、ゼロでない値に設定します。

KMDF ログの内容を制御する

KMDF ログは、いくつかの面から制御できます。

ログのサイズ

ドライバの Parameters\Wdf レジストリ サブキーの LogPages 値を設定することにより、ロガーにフレームワークが割り当てるメモリ ページ数を指定できます。LogPages は、1 から 10 までの値に設定できます。これは、ロガーに割り当てられるメモリのページ数を示します。LogPages に値が割り当てられられていない場合、KMDF は、既定値として 1 ページを使用します。

注 :LogPages の値は、要件ではなく要求です。小さなクラッシュ ダンプ ファイルのサイズは制限されているので、ログが大きすぎる場合、オペレーティング システムは、KMDF ログ データを省略する場合があります。

情報レベル

ドライバの Parameters\Wdf レジストリ サブキーで VerboseOn 値を設定することにより、KMDF ログ ファイルに書き込まれる情報量を変更できます。VerboseOn の値がゼロ以外の場合は、フレームワークが詳細な開発者レベルの情報をログに記録します。VerboseOn を設定するとパフォーマンスが下がる可能性があるので、ドライバの開発とデバッグ中のみ、VerboseOn を設定してください。

プレフィックス文字列

KMDF ログの各行の先頭には、トレース メッセージ プレフィックスと呼ばれる文字列が追加されています。トレース ロガーは、このプレフィックスを、ログに書き込まれる各メッセージの先頭に追加します。既定では、プレフィックスにはデータ要素の標準セットが含まれますが、特定の要件を満たすよう、既定の要素を変更することもできます。

プレフィックスの内容は、printf ステートメントで使用されるフォーマット文字列に類似したフォーマット文字列によって指定されます。トーレス プレフィックス文字列の書式は、Windows トレース ツールによって定義されます。詳細については、Windows Driver Kit (WDK) の「Driver Development Tools」の「Trace Message Prefix」のセクションを参照してください。

KMDF ドライバのプレフィックス文字列は、TRACE_FORMAT_PREFIX 環境変数を設定するか、デバッガ拡張コマンドの !wdfsettraceprefix を使用することによって変更できます。設定 TRACE_FORMAT_PREFIX により、行、関数名、モジュール名など、ETW がキャプチャした標準情報の形式を制御できます。プレフィックスの内容は、printf ステートメントと同様の形式文字列によって指定されます。形式文字列を作成する方法の詳細については、WDK の「Trace Message Prefix」を参照してください。

KMDF ドライバのプレフィックス文字列は、TRACE_FORMAT_PREFIX 環境変数を設定するか、!wdfsettraceprefix デバッガ拡張コマンドを使用することによって変更できます。

環境変数を設定するには、下記のようなコマンドを使用します。

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

このコマンドは、トレース メッセージ プレフィックスを下記のように設定します。

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime 

デバッグ中に形式文字列を設定するには、次のように、!wdfsettraceprefix デバッガ拡張機能を使用します。

    !wdfkd.wdfsettraceprefixPrefixString

下記の例では、上記の環境変数と同じ文字列を設定しています。

    !wdfkd.wdfsettraceprefix %2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

ユーザーがすべきこと

詳細情報 :

Windows Driver Foundation のアーキテクチャ

Debugging Tools for Windows

カーネル モード ドライバ フレームワーク (KMDF)

KMDF ドキュメントの下記を参照してください。
Design Guide
    Debugging a Framework-based Driver

Windows Driver Kit
Driver Development Tools セクションの下記の項を参照してください。
    Trace Message Prefix

ページのトップへ