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

發行項
10/26/2023

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

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

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

記錄會儲存在不可分頁的記憶體中，因此可在系統當機之後復原。此外，除了負責的驅動程式未決定，或當機是主機逾時時，否則小型傾印檔案中會包含追蹤錄製器記錄。

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

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

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

#include 「MyDriver1.t」

和 MyDriver2.c 必須包含：

#include 「MyDriver2.t」

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

在標頭檔中定義 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，以使用 驅動程式物件和登錄路徑 Kernel-Mode Drivers，通常是來自 DriverEntry：
```
WPP_INIT_TRACING( DriverObject, RegistryPath );
```
若要停用追蹤，KMDF 和 UMDF 2 驅動程式都會從EvtCleanupCallback或EvtDriverUnload呼叫Kernel-Mode Drivers 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追蹤旗標，則TraceEvent 的呼叫會產生追蹤訊息。訊息包含驅動程式定義常數 的值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 Trace Recorder 記錄檔

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

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