在 UMDF 驅動程式中使用 WPP 軟體追蹤

發行項
10/26/2023

WPP 軟體追蹤可讓您新增可協助您偵錯驅動程式的追蹤訊息。此外，架構的事件記錄器會提供數百個您可以檢視的追蹤訊息。

您可以使用 TraceView 或 Tracelog來檢視追蹤訊息。您也可以將追蹤訊息傳送至核心偵錯工具。

將追蹤訊息新增至驅動程式

若要將追蹤訊息新增至架構型驅動程式，您必須：

將 #include 指示詞新增至每個驅動程式的來源檔案，其中包含任何 WPP 宏。這個指示詞必須識別 TTL) 檔案 (追蹤訊息標頭。檔案名的格式必須是 <driver-source-file-name.t> 才能使用。

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

#include "MyDriver1.tmh"

和 MyDriver2.c 必須包含：

#include "MyDriver2.tmh"

當您在 Microsoft Visual Studio 中建置驅動程式時，WPP 預處理器會產生 .t linux 檔案。
在標頭檔中定義 WPP_CONTROL_GUIDS 宏。此宏會定義驅動程式追蹤訊息的 GUID 和追蹤旗標。 (針對每個 WDK 的 UMDF 範例驅動程式，Internal.h 標頭檔包含此宏.)
在驅動程式的 DllMain 常式中包含 WPP_INIT_TRACING 宏。此宏會在驅動程式中啟動軟體追蹤。 (針對每個 WDK 的 UMDF 範例驅動程式，DllSup.h 標頭檔包含此宏.)
在驅動程式的 DllMain 常式中包含 WPP_CLEANUP 宏。此宏會停用驅動程式中的軟體追蹤。 (針對每個 WDK 的 UMDF 範例驅動程式，DllSup.h 標頭檔包含此宏.)
在驅動程式中使用 DoTraceMessage 宏或自訂版本的宏來建立追蹤訊息。 (針對每個 WDK 的 UMDF 範例驅動程式，Internal.h 標頭檔包含自訂宏.)
開啟驅動程式專案的 [屬性頁]。以滑鼠右鍵按一下方案總管中的驅動程式專案，然後選取 [屬性]。在驅動程式的 [屬性頁] 中，選取 [ 組態屬性]，然後選取 [Wpp]。在 [ 一般 ] 功能表下，將 [執行 WPP 追蹤 ] 設定為 [是]。在 [ 檔案選項 ] 功能表下，您也應該指定架構的 WPP 範本檔案，例如：
```
{km-WdfDefault.tpl}*.tmh
```

如需將追蹤訊息新增至驅動程式的詳細資訊，請參閱將 WPP 宏新增至驅動程式。

使用 WPP 軟體追蹤的範例驅動程式

WDK 中的所有 UMDF 範例驅動程式都提供 DllSup.h、Internal.h 和 Sources 檔案，以啟用 WPP 軟體追蹤。其中大部分的範例驅動程式也會使用自訂宏來建立追蹤訊息。

檢視驅動程式的追蹤訊息

如果您已將追蹤訊息新增至驅動程式，則驅動程式是追蹤提供者。您可以使用追蹤控制器，例如 Tracelog來控制追蹤會話，並建立追蹤記錄。您可以使用追蹤取用者，例如 Tracefmt來檢視訊息。

如需如何使用軟體追蹤工具的詳細資訊，請參閱軟體追蹤工具問卷。

檢視 UMDF 追蹤記錄檔

UMDF 記錄檔位於 %ProgramData%*\\Microsoft\\WDF 中。

您可以使用 TraceView 或 Tracelog來檢視 UMDF 記錄檔。這兩個工具都需要追蹤訊息格式 (TMF) 格式化追蹤記錄檔的訊息。 TMF 檔案位於 \tools\tracing 子目錄下的 WDK 中。 (在 TraceView 中，UMDF 會顯示為名稱為「UMDF-Framework Trace」或「Framework Trace」的具名提供者，視 UMDF 版本而定。)

WDF 驗證器可讓您將追蹤訊息傳送至 UMDF 追蹤記錄檔和核心偵錯工具。 (您不應該使用Tracelog中的-kd選項，將追蹤訊息傳送至核心偵錯工具，因為Tracelog可能會中斷 UMDF.) 內的追蹤記錄

您也可以使用 ！wmitrace 偵錯工具延伸模組來檢視偵錯工具中的追蹤訊息：

在 WinDbg 中，附加至裝載驅動程式的 WUDFHost 實例。如需詳細資訊，請參閱如何啟用 UMDF 驅動程式的偵錯。
如果您的驅動程式使用 1.11 版或更新版本，而且您使用的是Windows 8或更新版本的核心偵錯工具，您可以略過此步驟。如果您的驅動程式使用 1.11 之前的 UMDF 版本，請使用 ！wmitrace.tmffile 或 ！wmitrace.searchpath 來指定平臺特定的追蹤訊息格式 (.tmf) 檔案，或 .tmf 檔案的路徑。 .tmf 檔案位於 WDK 的平臺特定子目錄中。
使用 ！wmitrace.logdump 命令來顯示追蹤緩衝區的內容：
```
!wmitrace.logdump WudfTrace
```

控制追蹤訊息

您可以使用 WDF 驗證器提供的使用者介面，或修改登錄值來控制 UMDF 追蹤訊息。您應該盡可能使用 WDF 驗證器 介面，因為登錄值可能會在未來的 UMDF 版本中變更。此外，您不應該在 INF 檔案或驅動程式的程式碼中存取這些值。

目前，您可以修改位於HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF登錄機碼底下的下列登錄值：

LogEnable值可控制 UMDF 是否為驅動程式建立追蹤記錄。如果此值設定為 1，UMDF 會建立追蹤記錄。
LogLevel值會控制 UMDF 追蹤訊息包含的資訊量。 LogLevel的預設值為 3，這會導致 UMDF 追蹤訊息包含錯誤和警告訊息。將此值設定為 7 以包含錯誤和警告訊息，以及非錯誤資訊訊息。將它設定為 15，以包含 UMDF 能夠提供的所有追蹤資訊。
LogKd值可控制 UMDF 是否將追蹤訊息傳送至核心偵錯工具。如果 LogKd 設定為 1，UMDF 就會將其追蹤訊息傳送至核心偵錯工具。
LogFlushPeriodSeconds值會指定追蹤訊息寫入追蹤記錄的頻率，以秒為單位。
LogMinidumpType值包含旗標，指定迷你傾印檔案所包含的資訊類型。如需這些旗標的詳細資訊，請參閱 MINIDUMP_TYPE 列舉。

您可以在HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF登錄機碼下找到更多登錄值。您不應該修改這些值。

共用方式為