次の方法で共有


KMDF および UMDF 2 ドライバーでのインフライト トレース レコーダー (IFR) の使用

Windows 10 以降では、Windows ソフトウェア トレースの前処理を通じて追加のドライバー デバッグ情報を取得できるように、KMDF ドライバー、または UMDF ドライバーをビルドできます。 この機能は、インフライト トレース レコーダー (IFR) と呼ばれ、KMDF バージョン 1.15 および UMDF バージョン 2.15 以降で使用できます。

インフライト トレース レコーダーは、WPP software トレースの拡張機能です。 WPP トレースとは異なり、インフライト トレース レコーダーは、接続されたトレース コンシューマーなしで引き続き動作します。 フレームワークは循環バッファーにメッセージを書き込み、ドライバーは独自のメッセージを追加することもできます。 各ドライバーには独自のログがあるため、ドライバーに関連付けられている複数のデバイスが 1 つのログを共有します。

ドライバー バイナリで IFR をオンにすると、ドライバーが使われている間、IFR は存在し、動作します。 トレース収集セッションを明示的に開始する必要はありません。

ログはページング不可能なメモリに格納されるため、システムクラッシュ後に回復できます。 さらに、Inflight Trace Recorderログは、責任のあるドライバーが不明な場合やクラッシュがホストのタイムアウトであった場合を除き、ミニダンプ ファイルに含まれます。

インフライト トレース レコーダーを有効にしてドライバーからメッセージを送信する方法

  1. Microsoft Visual Studioで、次の手順を実行します。

    • ドライバー プロジェクトのプロパティ ページを開きます。 ソリューション エクスプローラーで、ドライバー プロジェクトを右クリックし、 [プロパティ] を選択します。 ドライバーのプロパティ ページで、[構成プロパティ]Wpp トレース の順に選びます。 [全般] メニューで、[WPP トレースの実行][はい] に設定します。

    • プロパティ->Wpp Tracing->Function オプションとマクロ オプションに移動し、[Enable WPP Recorder]を選択します。

    • 同じメニューで、トレース情報を含むファイル (Trace.h など) にスキャン構成データを設定します。

  2. WPP マクロを呼び出す各ソース ファイルに、トレース メッセージ ヘッダー (TMH) ファイルを識別する #include ディレクティブを追加します。 ファイル名の形式<driver-source-file-name>.tmh である必要があります。

    たとえば、ドライバーが MyDriver1.cMyDriver2.c という 2 つのソース ファイルで構成されている場合、MyDriver1.c には次のものが含まれている必要があります。

    #include "MyDriver1.tmh"

    さらに MyDriver2.c には次のものが含まれている必要があります。

    #include "MyDriver2.tmh"

    Visual Studio でドライバーをビルドすると、WPP プリプロセッサが .tmh ファイルを生成します。

  3. ヘッダー ファイルで WPP_CONTROL_GUIDS マクロを定義します。 このマクロは、ドライバーのトレース メッセージの GUID フラグと トレース フラグ を定義します。

    Osrusbfx2 ドライバーのサンプルでは、次の例に示すように、Trace.h ヘッダー ファイルに 1 つのコントロール GUID と 7 つのトレース フラグを定義します。

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \
      (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
      WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
      WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
      WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
      WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
      WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
      WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
      WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
      WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
    )
    

    次の点に注意してください。

    • OsrUsbFxTraceGuid は、{d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB} GUID のフレンドリ名です。
    • トレース フラグは、ドライバーがさまざまな種類の I/O 要求を処理する場合に生成されるトレース メッセージを区別するために使用されます。
  4. ドライバー (KMDF と UMDF 2 の両方) は、ドライバー オブジェクトとレジストリ パスを使用してカーネル モード ドライバーのWPP_INIT_TRACINGを呼び出す必要があります (通常は DriverEntry から)。

    WPP_INIT_TRACING( DriverObject, RegistryPath );
    

    トレースを非アクティブ化するには、KMDF ドライバーと UMDF 2 ドライバーの両方で、EvtCleanupCallback または EvtDriverUnload からカーネル モード ドライバーのWPP_CLEANUPを呼び出します。

    WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
    

    WPP_CLEANUP マクロは PDRIVER_OBJECT型のパラメーターを受け取るので、ドライバーの DriverEntry が失敗した場合は、WdfDriverWdmGetDriverObject の呼び出しをスキップし、代わりに WDM ドライバー オブジェクトへのポインターを使用して WPP_CLEANUPを呼び出すことができます。

    UMDF ドライバーは、トレースの初期化とクリーンにこれらのマクロのカーネル モード署名を使用するため、呼び出しは KMDF と UMDF で同じように見えます。

  5. トレース メッセージを作成するには、ドライバーで DoTraceMessage マクロまたはカスタマイズされたバージョンのマクロを使用します。

    次の例は、読み取り要求の処理に特化したコードの一部で、Osrusbfx2 ドライバーが TraceEvents 関数を使用する方法を示しています。

    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        TraceEvents(TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Transfer exceeds %d\n",
                    TEST_BOARD_TRANSFER_BUFFER_SIZE);
    
        status = STATUS_INVALID_PARAMETER;
    }
    

    トレース コントローラーが TRACE_LEVEL_ERROR レベルとDBG_READ トレース フラグを有効にすると、TraceEvents の呼び出しによってトレース メッセージが生成されます。 メッセージには、ドライバー定義定数TEST_BOARD_TRANSFER_BUFFER_SIZEの値が含まれています。

  6. ドライバー ログが使用する循環バッファーのサイズを変更するには、次の レジストリの場所にある LogPages レジストリ値を変更します。

    UMDFでは。

    SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf

    KMDFの場合。

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<YourDriver>\Parameters\Wdf

    これは、割り当てられたログ バッファーのサイズをページ単位で格納する REG_DWORD 型の値です。 有効な値は 0x1 から 0x10 です。

KMDF ドライバーの場合

  1. デバッガーに「.load rcdrkd.dll」と入力し、RCDRKD コマンドをロードします。
  2. !wdfkd.wdfldr 拡張機能を使用して、Windowsドライバーフレームワーク (WDF) に現在動的にバインドされているドライバーに関する情報を表示させます。
  3. ドライバーが提供するメッセージを表示するには、!rcdrkd.rcdrlogdump!rcdrkd.rcdrcrashdump を使用します。
  4. フレームワークが提供するメッセージを表示するには、!wdfkd.wdflogdump または !wdfkd.wdfcrashdump を使用します。

UMDF ドライバーのライブ デバッグ

  1. 現在 WDF に動的にバインドされているドライバーに関する情報を表示するには、 !wdfkd.wdfldr 拡張機能を使用します。 ユーザー モード ドライバーを見つけます。 関連付けられているホスト プロセスを入力します。

  2. !wdfkd.wdflogdump <YourDriverName.dll><Flag> を入力します。ここで、<Flag> は次のとおりです。

    • 0x1 – マージされたフレームワークとドライバーのログ
    • 0x2 – ドライバー ログ
    • 0x3 – フレームワーク ログ

    指定したドライバーのドライバー ログがない場合、拡張機能にはフレームワーク ログのみが表示されます。

UMDF ドライバーのクラッシュ後のインフライト トレース レコーダー ログの表示

  1. WinDbg から[ファイル>クラッシュ ダンプを開く]を選択し、デバッグするミニダンプ ファイルを指定します。

  2. !wdfkd.wdfcrashdump <YourDriverName.dll><process ID of driver host><Option>」と入力します。<オプション>は次のとおりです。

    • 0x1 – マージされたフレームワークとドライバーのログ
    • 0x2 – ドライバー ログ
    • 0x3 – フレームワーク ログ

    ドライバーを指定しない場合、 !wdfcrashdump はすべてのドライバーの情報を表示します。 ホスト プロセスを指定せず、1 つしか存在しない場合、拡張機能は単一のホスト プロセスを使用します。 ホスト プロセスを指定せず、複数ある場合、拡張機能にはアクティブなホスト プロセスが一覧表示されます。

    ミニダンプに格納されているログ情報が入力された名前と一致しない場合、ミニダンプにはドライバーのログが含まれません。

デバッガーが接続されていない場合でも、ドライバーとフレームワークのログにアクセスできます。 方法については、「動画:デバッガーなしでドライバー IFR ログにアクセスする」を参照してください。

ドライバーにトレース メッセージを追加する方法の詳細については、「ドライバーへの WPP マクロの追加」をご参照ください。

UMDF ドライバーのデバッグを有効にする方法

RCDRKD 拡張機能

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

UMDF ドライバーでの WPP ソフトウェア トレースの使用