フレームワークのイベント ロガーの使用

  • [アーティクル]

WDF には内部トレース ロガーが含まれています。これは、フレームワークの インフライト レコーダー (IFR) と呼ばれることもあります。 WDF ロガーは、各 WDF ドライバーのイベントの最近の履歴を含むトレース ログを作成します。 トレース ログは、フレームワークを介した I/O 要求パケット (IRPs) の進行状況と、ドライバーを介した対応する要求を追跡します。 各カーネル モード ドライバー フレームワーク (KMDF) とユーザー モード ドライバー フレームワーク (UMDF) ドライバーには、独自のログがあります。

WDF ロガーは常に有効です。 トレース ログごとに、ロガーはイベント レコードを循環メモリ バッファーに格納します。 必要に応じて、詳細度を有効にできます。これにより、イベント ロガーは、内部コード パスへのエントリや内部コード パスからの終了など、ドライバーのデバッグに役立つ追加情報を記録できます。 デフォルトでは、バッファーのサイズは 1 つのメモリ ページであり、詳細度はオフになっています。 バッファーのサイズと詳細度を変更するには、WdfVerifier アプリケーション内でこれらの値を調整します。 詳細度をオンにすると、システムのパフォーマンスが低下する可能性があることがありますので、ご注意ください。

WDF デバッガー拡張機能を使用して、対話型デバッグ中に WDF ログを表示および保存できます。 デバッグ セッション中に WDF ログを表示する方法

  1. 正しいシンボルを読み込みます。 .symfix+ デバッガー コマンドを使用して、Microsoft パブリック シンボル ストアを既存のシンボル パスに追加できます。 パブリック シンボル ストアには、WDF バイナリのシンボルが含まれています。 ドライバー シンボルのシンボルを読み込むこともできます。

    ウィンドウ シンボルを取得する方法とデバッガーのシンボル パスを設定する方法の詳細については、Windows デバッグ パッケージに付属 のドキュメントを参照してください。

  2. Wdfkd.dll 拡張機能ライブラリをデバッガーに読み込みます。 カーネル デバッガーを使用している場合は、.load コマンドを使用してこれを行うことができます。 正しいバージョンのWdfkd.dllを読み込むには、DLL への完全修飾パスを指定する必要があります。 たとえば、x86 ベースのデバッガー ホスト コンピューターで次のパスを使用します。

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    次に、!chain コマンドを使用して、読み込まれたすべての拡張機能を表示することで、拡張機能が読み込まれたことを確認できます。

    フレームワーク デバッガー拡張機能の詳細については、!wdfhelp 拡張機能を使用します。 カーネル デバッガーの詳細については、Windows デバッグ パッケージに付属のドキュメントを参照してください。

  3. ドライバーがフレームワーク バージョン 1.11 以降を使用していて、Windows 8 以降のカーネル デバッガーを使用している場合は、この手順をスキップできます。

    ドライバーで 1.11 より前のフレームワーク バージョンの UMDF を使用している場合は、!wdftmffile または !wdfsearchpath を使用して、プラットフォーム固有のトレース メッセージ形式 (.tmf) ファイル、または .tmf ファイルへのパスを指定します。 .tmf ファイルは、WDK のプラットフォーム固有のサブディレクトリにあります。

    .tmf ファイルはバージョン固有であるため、現在実行中のフレームワークのランタイム ライブラリのバージョンに対応する .tmf ファイルを指定する必要があります。 たとえば、KMDF バージョン 1.9 がホスト コンピューターで実行されている場合は、次のようになります。

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    TRACE_FORMAT_SEARCH_PATH 環境変数を設定して、検索パスを設定することもできます。 !wdftmffile コマンドは、環境変数によって設定された検索パスよりも優先されます。

    フレームワークのバージョン番号を確認するには、カーネル デバッガーから !wdfldr デバッガー拡張機能コマンドを実行します。

  4. イベント ロガーのレコードを 表示するには、!wdflogdump 拡張機能を使用します。 たとえば、WinDbg コマンド ウィンドウの次のスクリーンショットは、!wdflogdump の出力の一般的な例を示しています。

    Screenshot of !wdflogdump extension output in WinDbg Command window.

フレームワークのログの各行の前には、トレース メッセージ プレフィックスと呼ばれる文字列が付きます。 トレース ロガーは、ログに書き込まれる各メッセージの先頭にこのプレフィックスを付加します。 既定では、プレフィックスには標準のデータ要素セットが含まれますが、特定の要件に合わせて既定の要素を変更できます。 WDF ドライバーのプレフィックス文字列は、TRACE_FORMAT_PREFIX 環境変数を設定するか、!wdfsettraceprefix デバッガー拡張機能コマンドを使用して変更できます。

環境変数をクラスター名に設定するには、次のコマンドに類似するコマンドを使用します。

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

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

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

!wdflogsave 拡張コマンドを使用して、TraceView を使用して表示できるイベント トレース ログ (.etl) ファイルにイベント ロガーのレコードを保存することもできます。

時折、クラッシュ ダンプで !wdfcrashdump デバッガー拡張機能を使用して、システム バグのチェック後にログ情報を表示することができます。 ログ情報は、ドライバーがバグ チェックの原因となったとフレームワークが判断できる場合、またはドライバーの ForceLogsInMiniDump レジストリ値を設定した場合にのみ、クラッシュ ダンプで使用できます。

バグチェックが発生したときにデバッガーがアタッチされている場合は、!wdfcrashdump を使用してログ情報をただちに表示するか、メモリ ダンプ ファイルを読み込んで情報を表示できます。 小さなメモリ ダンプ ファイルのサイズ制限により、クラッシュの原因となったドライバーのログがダンプに表示されない可能性があります。

フレームワークは、特定のドライバーが原因で次のバグチェック コードが発生したかどうかを判断できます。

UMDF バージョン 2 以降、UMDF は UMDF トレース ログ (または UMDF IFR) をカーネルの非ページ メモリに格納します。 フレームワークは、ドライバー ホスト (Wudfhost) インスタンスごとに 1 つの IFR を割り当てます。

デバッガー拡張機能コマンドの詳細については、「Framework ベースのドライバーのデバッガー拡張機能」を参照してください。