記錄追蹤的 Inflight Trace Recorder (IFR)

發行項
02/06/2024

Inflight Trace Recorder (IFR) 是一項追蹤功能，可讓追蹤提供者，例如內核模式驅動程式或 UMDF 驅動程式，建立一組記憶體內部迴圈緩衝區，其中會保留最新的記錄訊息。您可以使用除錯程式來檢視記錄訊息。

IFR 建置於 WPP 軟體追蹤之上。 IFR over WPP 的主要優點是它會自動開啟，而且您不需要事先啟動追蹤會話。

適用範圍：

最低 OS：適用於 KMDF 和 WDM 驅動程式開發人員的 Windows 8
最低 OS：適用於 UMDF (2.15) 驅動程式開發人員的 Windows 10

如何在 Visual Studio 中啟用 Inflight 追蹤錄製器

首先，請遵循將 WPP 軟體追蹤新增至 Windows 驅動程式中的步驟。

接下來，在 [專案] 屬性頁的 [ 組態屬性->WPP 追蹤函>式] 和 [宏選項啟用> Inflight 追蹤錄製器] 底下，選取 [ 是]。

最後，針對 UMDF，有一個額外的步驟：在 WPP 追蹤函>式和宏選項預>處理器定義下，新增 WPP_MACRO_USE_KM_VERSION_FOR_UM=1。

如何從命令行啟用 Inflight Trace Recorder

如果您手動編輯.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>

如何設定 Inflight 追蹤錄製器參數

您可以在驅動程式的參數機碼下設定下列選擇性登錄專案，以設定IFR。

使用下列登入專案：

LogPages：REG_DWORD

設定為要儲存預設記錄檔的頁數。預設值為 1。

VerboseOn： REG_DWORD

預設值為零會導致 IFR 記錄錯誤、警告和參考事件。設定為，以將詳細資訊輸出新增至記錄檔。

WppRecorder_UseTimeStamp： 從 WDK 組建 22557) 開始，REG_DWORD (可用

驅動程式會將這個項目設定為一個專案，以將時間戳新增至記錄專案，然後使用 ！rcdrkd.rcdrlogdump 或 ！wdfkd.wdflogdump 檢視。

WppRecorder_PreciseTimeStamp：從 WDK 組建 22557) 開始，REG_DWORD (可用

如果您想要更精確的時間戳，除了 WppRecorder_UseTimeStamp，請使用上面所示的相同語法來新增 WppRecorder_PreciseTimeStamp 。

範例

在下列範例中，新增開始和結束批注之間的行，將記錄頁數設定為兩個，然後開啟時間戳。

針對核心模式驅動程式：

[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

如何將追蹤訊息傳送至默認記錄檔

遵循將 WPP 軟體追蹤新增至 Windows 驅動程式中的指示。例如：

在 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) 的核心模式驅動程式。

對於大部分的驅動程式，單一默認記錄檔就夠好。不過，在某些案例中，針對不同實體有個別的記錄緩衝區會很有説明。

例如，撰寫總線驅動程式時，您可能會希望每個子裝置都有自己的緩衝區。然後，您可以使用調試程式，只傾印特定子裝置的記錄檔。

若要設定自訂記錄，驅動程式必須包含 <WppRecorder.h>。然後呼叫下列 API：

WppRecorderLogCreate 以建立多個記錄緩衝區
呼叫 WPP_CLEANUP 之前，WppRecorderLogDelete。
WppRecorderLogSetIdentifier 為指定的錄製器記錄檔設定字串標識符， (選擇性)
WppRecorderConfigure 停用預設記錄檔 (選擇性)

驅動程式也需要定義新的追蹤宏，以使用記錄句柄作為第一個參數。如需範例，請參閱 Toaster範例驅動程式。

如何將時間戳資訊新增至自定義記錄檔

如果您的驅動程式呼叫 WppRecorderLogCreate 來建立其他記錄句柄，您可以啟用某些記錄句柄的時間戳，但不能啟用其他記錄句柄的時間戳。

若要這樣做，您必須為每個應該使用時間戳的記錄句柄，將單行新增至驅動程序程序代碼。如需程式代碼範例，請參閱 WppRecorderLogCreate。

注意

此功能可從 WDK 組建 22557 開始提供。如需以特定版本為目標的詳細資訊，請參閱建置不同 Windows 版本的驅動程式。

如何在調試程式中檢視追蹤訊息

針對 KMDF 和 UMDF 驅動程式，請如往常使用 ！wdfkd.wdflogdump 。它會列印架構 IFR 記錄檔和驅動程式 IFR 記錄檔。

針對WDM驅動程式，請使用 ！rcdrkd.rcdrloglist 和 ！rcdrkd.rcdrlogdump。

共用方式為