記錄追蹤的 Inflight Trace Recorder (IFR)

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_TRACINGWPP_CLEANUP

如何將追蹤訊息傳送至自定義記錄

這僅適用於 (KMDF 或 WDM) 的核心模式驅動程式。

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

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

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

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

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

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

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

注意

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

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

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

針對WDM驅動程式,請使用 !rcdrkd.rcdrloglist!rcdrkd.rcdrlogdump