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

[アーティクル]
07/08/2024

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

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

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

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

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

Microsoft Visual Studioで、次の手順を実行します。
- ドライバープロジェクトのプロパティページを開きます。ソリューションエクスプローラーで、ドライバープロジェクトを右クリックし、 [プロパティ] を選択します。ドライバーのプロパティページで、[構成プロパティ]、Wpp トレース の順に選びます。 [全般] メニューで、[WPP トレースの実行] を [はい] に設定します。
- プロパティ->Wpp Tracing->Function オプションとマクロオプションに移動し、[Enable WPP Recorder]を選択します。
- 同じメニューで、トレース情報を含むファイル (Trace.h など) にスキャン構成データを設定します。
WPP マクロを呼び出す各ソースファイルに、トレースメッセージヘッダー (TMH) ファイルを識別する #include ディレクティブを追加します。ファイル名の形式<driver-source-file-name>.tmh である必要があります。

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

#include "MyDriver1.tmh"

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

#include "MyDriver2.tmh"

Visual Studio でドライバーをビルドすると、WPP プリプロセッサが .tmh ファイルを生成します。
ヘッダーファイルで 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 要求を処理する場合に生成されるトレースメッセージを区別するために使用されます。
ドライバー (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 で同じように見えます。
トレースメッセージを作成するには、ドライバーで 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の値が含まれています。
ドライバーログが使用する循環バッファーのサイズを変更するには、次のレジストリの場所にある 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 ドライバーの場合

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

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

現在 WDF に動的にバインドされているドライバーに関する情報を表示するには、 !wdfkd.wdfldr 拡張機能を使用します。ユーザーモードドライバーを見つけます。関連付けられているホストプロセスを入力します。
!wdfkd.wdflogdump <YourDriverName.dll><Flag> を入力します。ここで、<Flag> は次のとおりです。
- 0x1 – マージされたフレームワークとドライバーのログ
- 0x2 – ドライバーログ
- 0x3 – フレームワークログ
指定したドライバーのドライバーログがない場合、拡張機能にはフレームワークログのみが表示されます。

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

WinDbg から[ファイル>クラッシュダンプを開く]を選択し、デバッグするミニダンプファイルを指定します。
「!wdfkd.wdfcrashdump <YourDriverName.dll><process ID of driver host><Option>」と入力します。<オプション>は次のとおりです。
- 0x1 – マージされたフレームワークとドライバーのログ
- 0x2 – ドライバーログ
- 0x3 – フレームワークログ
ドライバーを指定しない場合、 !wdfcrashdump はすべてのドライバーの情報を表示します。ホストプロセスを指定せず、1 つしか存在しない場合、拡張機能は単一のホストプロセスを使用します。ホストプロセスを指定せず、複数ある場合、拡張機能にはアクティブなホストプロセスが一覧表示されます。

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

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

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

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

RCDRKD 拡張機能

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

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

次の方法で共有

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

フィードバック

その他のリソース

次の方法で共有

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

関連記事

フィードバック

その他のリソース

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