在 KMDF 和 UMDF 2 驅動程式中使用 Inflight Trace Recorder （IFR）

發行項
07/08/2024

從 Windows 10 開始，您可以建置 KMDF 或 UMDF 驅動程式，以便透過 Windows 軟體追蹤前置處理取得額外的驅動程式偵錯資訊。此功能稱為 Inflight Trace Recorder （IFR），從 KMDF 1.15 版和 UMDF 2.15 版開始提供。

Inflight Trace Recorder 是 WPP 軟體追蹤的延伸模組。不同於 WPP 追蹤，Inflight 追蹤錄製器會繼續運作，而不需要附加的追蹤取用者。架構會將訊息寫入循環緩衝區，而您的驅動程式也可以新增自己的訊息。每個驅動程式都有自己的記錄檔，因此與驅動程式相關聯的多個裝置會共用單一記錄。

如果您在驅動程式二進位檔中開啟 IFR，則 IFR 會出現並在驅動程式存留期間執行。您不需要啟動明確的追蹤收集工作階段。

記錄會儲存在無法分頁的記憶體中，因此可在系統損毀之後復原。此外，除了責任驅動程式未確定或當機是主機逾時時，小型傾印檔案中會包含 Inflight Trace Recorder 記錄檔。

如何啟用 Inflight 追蹤錄製器，並從驅動程式傳送訊息

在 Microsoft Visual Studio 中，執行下列步驟：
- 開啟驅動程式專案的 [屬性頁]。以滑鼠右鍵按兩下方案總管中的驅動程式項目，然後選取 [屬性]。在驅動程式的 [屬性頁] 中，選取 [組態屬性]，然後選取 [Wpp 追蹤]。在 [一般] 功能表上，將 [執行 WPP 追蹤] 設定為 [是]。
- 流覽至 Properties-Wpp> 追蹤函>式和宏選項，然後選擇 [啟用 WPP 錄製器]。
- 在相同的功能表上，將 [掃描組態數據] 設定為包含追蹤信息的檔案，例如 Trace.h。
在每個呼叫 WPP 宏的來源檔案中，新增可識別追蹤訊息標頭（TMH）檔案的 #include 指示詞。檔名的格式必須是 <driver-source-file-name.tmh。>

例如，如果您的驅動程式包含兩個原始程式檔，稱為 MyDriver1.c 和 MyDriver2.c，則 MyDriver1.c 必須包含：

#include “MyDriver1.tmh”

和 MyDriver2.c 必須包含：

#include “MyDriver2.tmh”

當您在 Visual Studio 中建置驅動程式時，WPP 預處理器會產生。tmh 檔案。

在頭檔中定義WPP_CONTROL_GUIDS宏。此宏會定義驅動程序追蹤訊息的 GUID 和追蹤旗標。

Osrusbfx2 驅動程式範例會定義 Trace.h 頭檔中的單一控件 GUID 和七個追蹤旗標，如下列範例所示：

#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 Driver Frameworks （WDF）之驅動程式的相關信息。
使用 ！rcdrkd.rcdrlogdump 和 ！rcdrkd.rcdrcrashdump 來檢視驅動程式所提供的訊息。
使用 ！wdfkd.wdflogdump 或 ！wdfkd.wdfcrashdump 來查看架構所提供的訊息。

UMDF 驅動程式的即時偵錯

使用！wdfkd.wdfldr 延伸模組來顯示目前動態系結至 WDF 之驅動程式的相關信息。尋找您的使用者模式驅動程式。輸入相關聯的主機進程。
輸入 ！wdfkd.wdflogdump< YourDriverName.dll<>Flag ，其中< Flag>> 為：
- 0x1 – 合併架構和驅動程序記錄
- 0x2 – 驅動程序記錄
- 0x3 – 架構記錄
如果指定的驅動程式沒有驅動程序記錄檔，擴充功能只會顯示架構記錄檔。

在 UMDF 驅動程式當機後檢視 Inflight 追蹤錄製器記錄檔

從 WinDbg 中，選取 [ 檔案開啟>損毀傾印]，並指定您想要偵錯的小型傾印檔案。
輸入！wdfkd.wdfcrashdump <YourDriverName.dll<>驅動程式主機<>選項的進程標識符，其中 <Option>> 為：
- 0x1 – 合併架構和驅動程序記錄
- 0x2 – 驅動程序記錄
- 0x3 – 架構記錄
如果您未指定驅動程式， ！wdfcrashdump 會顯示所有驅動程序的資訊。如果您未指定主機進程，而且只有一個，擴充功能會使用單一主機進程。如果您未指定主機進程且有多個，擴充功能會列出作用中的主機進程。

如果儲存在迷你傾印中的記錄資訊不符合輸入的名稱，則小型傾印不包含驅動程式的記錄檔。