トレースのログ記録用のインフライト トレース レコーダー (IFR)

  • [アーティクル]

インフライト トレース レコーダー (IFR) は、カーネル モード ドライバーや UMDF ドライバーなどのトレース プロバイダーが、最新のログ メッセージが保持されるメモリ内循環バッファーのセットを作成できるようにするトレース機能です。 ログ メッセージはデバッガーを使用して表示できます。

IFR は、WPP ソフトウェア トレースの上に構築されています。 WPP 経由の IFR の主な利点は、それが自動的に有効になっているため、トレース セッションを事前に開始する必要がないということです。

適用対象:

  • 最低要件 OS: KMDF および WDM ドライバー開発者向けの Windows 8
  • 最低要件 OS: UMDF (2.15) ドライバー開発者向け Windows 10

Visual Studio でインフライト トレース レコーダーを有効にする方法

まず、「Windows ドライバーへの WPP ソフトウェア トレースの追加」の手順に従います。

次に、[プロジェクト] プロパティ ページの [コンフィギュレーション プロパティ - WPP> トレーシング - 機能>およびマクロオプション - > インフライト トレース レコーダーを有効化] で、[はい] を選択します。

最後に、UMDF の場合のみ、追加の手順が 1 つあります。[WPP トレース> - 関数とマクロ オプション - >プリプロセッサ定義] より、WPP_MACRO_USE_KM_VERSION_FOR_UM=1を追加します。

コマンド ラインからインフライト トレース レコーダーを有効にする方法

.vcxproj ファイルを手動で編集する場合は、次のエントリを設定します。

KMDF または WDM ドライバーの場合:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

UMDF ドライバーの場合:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

インフライト トレース レコーダーのパラメーターを構成する方法

ドライバー のパラメーター キーの下に次の省略可能なレジストリ エントリを設定することで、IFR を構成できます。

次のレジストリ エントリーを使用します。

LogPages: REG_DWORD

既定のログを格納するページ数に設定します。 既定値は 1 です。

VerboseOn: REG_DWORD

既定の設定が 0 の場合、IFR はエラー、警告、および情報イベントをログに記録します。 ログに詳細出力を追加するには、1 に設定します。

WppRecorder_UseTimeStamp: REG_DWORD (WDK ビルド 22557 以降で使用可能)

ドライバーは、このエントリを 1 に設定して、ログ エントリにタイムスタンプを追加し、!rcdrkd.rcdrlogdump または !wdfkd.wdflogdump を使用して表示できるようにします。

WppRecorder_PreciseTimeStamp: REG_DWORD (WDK ビルド 22557 以降で使用可能)

WppRecorder_UseTimeStampに加えて、より正確なタイムスタンプが必要な場合は、上記と同じ構文を使用してWppRecorder_PreciseTimeStampを追加します。

例

次の例では、開始コメントと終了コメントの間に行を追加して、ログ ページの数を 2 に設定し、タイムスタンプを有効にします。

カーネル モード ドライバー (KMDF) 向け:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

UMDF ドライバーの場合:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

既定のログにトレース メッセージを送信する方法

「Windows ドライバーへの WPP ソフトウェア トレースの追加」の手順に従います。 次に例を示します。

  • DriverEntry で、 WPP_INIT_TRACING(DriverObject, RegistryPath)を呼び出します。
  • EvtDriverUnload で、WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver))を呼び出します。

これで、ドライバーは必要に応じてトレース関数を自由に呼び出すようになりました。 例: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

詳細については、「WPP_INIT_TRACINGとWPP_CLEANUP」を参照してください。

カスタム ログにトレース メッセージを送信する方法

これは、カーネル モード ドライバー (KMDF または WDM) にのみ適用されます。

ほとんどのドライバーでは、1 つの既定のログで十分です。 ただし、一部のシナリオでは、個別のエンティティに対して個別のログ バッファーを用意すると便利です。

たとえば、バス ドライバーを記述するときに、各子デバイスに独自のバッファーを持たせたい場合があります。 その後、デバッガーを使用して、特定の子デバイスのログのみをダンプできます。

カスタム ログを設定するには、<WppRecorder.h>をドライバーに含める必要があります。 次に、次の API を呼び出します。

また、ドライバーは、ログ ハンドルを最初のパラメーターとして受け取る新しいトレース マクロを定義する必要もあります。 例については、トースター サンプル ドライバー ページを参照してください。

カスタム ログにタイムスタンプ情報を追加する方法

ドライバーが WppRecorderLogCreate を呼び出して追加のログ ハンドルを作成する場合、一部のログ ハンドルのタイムスタンプを有効にすることはできますが、他のログ ハンドルは有効にできません。

これを行うには、タイムスタンプを使用する必要がある各ログ ハンドルのドライバー コードに 1 行を追加する必要があります。 コード例は、 WppRecorderLogCreate を参照してください。

Note

この機能は、WDK ビルド 22557 以降で使用できます。 特定のリリースをターゲットにする方法については、「Windows のさまざまなバージョンのドライバーのビルド」を参照してください。

デバッガーでトレース メッセージを表示する方法

KMDF ドライバーと UMDF ドライバーの場合は、通常どおり !wdfkd.wdflogdump を使用します。 フレームワーク IFR ログとドライバー IFR ログの両方が出力されます。

WDM ドライバーの場合は、!rcdrkd.rcdrloglist と !rcdrkd.rcdrlogdump を使用します。