偵錯 WDF 驅動程式的登錄值

本文說明 WDF 驅動程式可以設定的登錄值。 它適用于從 UMDF 第 2 版開始的 KMDF 驅動程式和 UMDF 驅動程式。

除非下列各節另有指定，否則下列登錄值位於驅動程式的 Parameters\Wdf 子機碼底下。

• 對於 KMDF 驅動程式，此子機碼位於 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services 驅動程式的服務名稱下。
• 針對 UMDF 驅動程式，此子機碼位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services 驅動程式的服務名稱下。

驅動程式的子機碼一律會使用驅動程式的服務名稱，即使驅動程式二進位檔的檔案名與服務名稱不同也一樣。

DbgBreakOnError

REG_DWORD

如果設定為非零值，當驅動程式呼叫 WdfVerifierDbgBreakPoint時，架構會中斷至偵錯工具。 (如果已設定 VerifierOn 值，即使 DbgBreakOnError 值不存在，架構仍會中斷至偵錯工具。) 請參閱 VerifierOn 一節中的程式碼範例。

DbgPrintOn

REG_DWORD

• 若為 KMDF 驅動程式，請在登錄機碼下 HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics 設定此值。
• 針對 UMDF 驅動程式，請在登錄機碼下 HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics 設定此值。

驅動程式可能需要建立選擇性 的 Diagnostics 子機碼。

如果設定為非零值，架構的載入器會在載入驅動程式並將它系結至架構程式庫的版本，或卸載驅動程式時，將各種訊息傳送至核心偵錯工具。

DbgWaitForSignalTimeoutInSec

REG_DWORD、架構 1.11 版和更新版本

從 Windows 8 開始，當VerifierOn和DbgBreakOnError設定為非零值時，驅動程式可以藉由設定DbgWaitForSignalTimeoutInSec來變更中斷偵錯工具的預設逾時期間。

DebugModeBinaries

僅限 UMDF REG_MULTI_SZ

此登錄值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode 中。

這個值會指定要在偵錯模式中載入的驅動程式二進位檔名稱。 若要啟用驅動程式二進位檔的偵錯模式X.DLL、Y.DLL和Z.DLL，例如，此值會設定為 X.DLL\0Y.DLL\0Z.DLL\0\0 。

DebugModeFlags

REG_DWORD，僅限 UMDF

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

值	描述
0x01	啟用偵錯模式。 此設定會關閉 在 UMDF 驅動程式中使用裝置共用中所述的自動重新開機功能。
0x02	停用裝置共用。 如需裝置共用的詳細資訊，請參閱 在 UMDF 驅動程式中使用裝置共用。
0x04	停用逾時。

當您在 Microsoft Visual Studio 中使用 F5 選項時，所有三個旗標都會設定為已部署的驅動程式。

EnhancedVerifierOptions

REG_DWORD、架構 1.9 版和更新版本

此值包含點陣圖。 每個位都代表使用者可以藉由設定位來啟用的其他驗證程式選項。

位值：

0x1：如果設定，驗證程式會檢查每個驅動程式的事件回呼函式是否執行下列動作：

• 在呼叫的相同 IRQL 上傳回 。 如果值不同， 就會發生錯誤碼0xE WDF_VIOLATION 錯誤檢查。

• 在傳回之前，會結束它輸入的所有 重要區域 。 如果回呼函式在輸入的重要區域內傳回， 就會發生錯誤 碼WDF_VIOLATION錯誤檢查0xF。

0x10000：如果已設定，且驅動程式已啟用 I/O 佇列的 向前進度 ，則架構會針對每個佇列的 I/O 要求模擬低記憶體情況。

0x20000：如果設定，且驅動程式已啟用 I/O 佇列的向前保證進度，架構會針對某些隨機選取的 I/O 要求模擬低記憶體情況。

ForceLogsInMiniDump

REG_DWORD

設定為非零值，讓架構在損毀傾印檔案中包含來自其事件記錄器的資訊。

HostFailKdDebugBreak

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

如果這個值不是零，且核心偵錯工具已連線到機器，則反映器會在終止主機進程之前中斷至核心偵錯工具。 根據預設，Windows 7 和舊版作業系統會停用HostFailKdDebugBreak。 從 Windows 8 開始，預設會啟用HostFailKdDebugBreak。

如果主機進程發生非預期的終止，則反映器也會中斷至核心偵錯工具 (，例如由非 UMDF 元件或因未處理的例外狀況而) 。 如果主機進程中有多個裝置堆疊集區正在終止，則反映器會多次中斷偵錯工具，一次用於裝載進程中載入的每個裝置堆疊。

HostProcessDbgBreakOnDriverLoad (驅動程式特定的)

REG_DWORD UMDF 僅限 UMDF，可與在具有 UMDF 2.31 版或更新版本的目的電腦上執行的任何 UMDF 1.x/2.x 驅動程式搭配運作

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

這個值只會影響指定的 UMDF 驅動程式。

包含以秒為單位的延遲值。 導致 WUDFHost 嘗試在載入驅動程式之後，嘗試連線到偵錯工具指定的秒數。

在指定的延遲期間，主機進程會在一秒內尋找使用者模式偵錯工具一次，並在連接時中斷。 如果未在此期間內附加使用者模式偵錯工具，且 中的高位設定為 (0x80000000) ，架構會嘗試單一嘗試中斷核心模式偵錯工具。 如需範例，請參閱上述 HostProcessDbgBreakOnStart 一節。

若要讓 UMDF 登錄值的變更生效，您必須重新開機電腦。

HostProcessDbgBreakOnDriverLoad (全域)

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. 您可以使用 WDK 中的 WDF 驗證器工具 (WdfVerifier.exe) 加以設定。 此值會影響系統上的所有 UMDF 驅動程式。

Contains a delay value in seconds. 導致 WUDFHost 在載入驅動程式之後延遲指定的秒數。 HostProcessDbgBreakOnDriverLoad的行為與HostProcessDbgBreakOnStart所述的行為相同。

指定HostProcessDbgBreakOnStart或HostProcessDbgBreakOnDriverLoad會導致架構停用其他 UMDF (逾時，例如，隨插即用作業) 。 這表示如果您的驅動程式造成過多逾時，使用這些值可能會導致驅動程式在目標上造成嚴重損毀。

HostProcessDbgBreakOnStart

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. You can set it by using the WDF Verifier tool (WdfVerifier.exe) in the WDK. This value affects all UMDF drivers on the system.

Contains a delay value in seconds. During the specified delay period, the host process looks for the user-mode debugger once a second and breaks in if one is connected. 如果未在此期間內附加使用者模式偵錯工具，且 HostProcessDbgBreakOnStart 中的高位設定為 (0x80000000) ，架構就會嘗試單一嘗試中斷核心模式偵錯工具。 例如：

值	結果
0x00000004	架構會嘗試每秒連線到使用者模式偵錯工具一次 4 秒。 架構永遠不會嘗試連線到核心模式偵錯工具。
0x80000000	架構會嘗試連線到使用者模式偵錯工具。 如果未附加使用者模式偵錯工具，架構會嘗試連線到核心模式偵錯工具。
0x80000004	架構會嘗試每秒連線到使用者模式偵錯工具一次 4 秒。 如果未在 4 秒內附加使用者模式偵錯工具，架構會嘗試連線到核心模式偵錯工具。

您也可以使用 WDF 驗證器工具 (WdfVerifier.exe) 包含在 WDK 中，來設定此登錄值。

LogPages

REG_DWORD

設定為架構指派給其事件記錄器的記憶體分頁數目。 如果值未定義，架構會使用一個頁面的預設值。 您可以設定的最大值是 16，適用于具有 4 KB 大小的記憶體頁面的電腦， (x86 和 amd64 處理器) ，而具有 8 KB 大小記憶體頁面的電腦則為 8 KB 大小的記憶體頁面， (ia64 處理器) 。 (如果指定大量頁面，作業系統可能不會將記錄內容寫入損毀傾印檔案。) 使用 AddService 指示 詞和 AddReg 指示 詞在您的 INF 檔案中設定此值，如下所示：

[xxx.NT.Services]
AddService = yyy, 2, zzz.AddService

[zzz.AddService]
DisplayName   = %aaa\bbb%
ServiceType   = 1
StartType     = 3
ErrorControl  = 1
ServiceBinary = %12%\ddd.SYS
AddReg         = eee.AddReg

[eee.AddReg]
HKR, Parameters\Wdf, LogPages,   0x00010001, 3 ; KMDF IFR size

ObjectLeakDetectionLimit

在某些情況下，架構物件不會正確父代，而且在使用之後不會刪除。 您可以使用 ObjectLeakDetectionLimit 和 ObjectsForLeakDetection 來指定物件數目上限，以及超過此臨界值時應該會發生的情況。

REG_DWORD

指定 ObjectsForLeakDetection 索引鍵中所述之類型的最大物件數目。 若要控制超過此閾值是否應該造成偵錯中斷或錯誤檢查，請設定 DbgBreakOnError 金鑰。 此限制會隨著已安裝的裝置數目進行調整，因此，如果驅動程式建立三個 WDFDEVICE 物件，則限制是 ObjectLeakDetectionLimit中指定的值三倍。

ObjectsForLeakDetection

REG_MULTI_SZ

搭配 ObjectLeakDetectionLimit使用。 列出要驗證的每個類型名稱。 例如，您可以指定 WDFDMATRANSACTION WDFDEVICE。 若要指定所有控制碼類型，請使用 * 作為字串。 如果未指定 ObjectsForLeakDetection 索引鍵，則預設值為監視 WDFREQUEST、WDFWORKITEM、WDFKEY、WDFSTRING、WDFOBJECT 和 WDFDEVICE。

如果您指定 WDFREQUEST，驗證程式只會計算驅動程式所建立的 WDFREQUEST 物件。 此功能目前不支援追蹤 WDFMEMORY 物件類型。

TrackHandles

REG_MULTI_SZ

如果設定為一或多個架構物件控制碼的類型名稱清單，而且已設定 VerifierOn ，則架構會追蹤符合指定控制碼類型之所有物件控制碼的參考。 例如，如果控制碼類型清單包含 「WDFREQUEST WDFQUEUE」 字串，則架構會追蹤所有要求物件和佇列物件的參考。 如果清單包含星號 (「*」) ，架構會追蹤所有物件控制碼。

VerboseOn

REG_DWORD

如果設定為非零值，架構 的事件記錄器 會記錄可協助您偵錯驅動程式的其他資訊，例如進入或結束內部程式碼路徑的專案。 只有在開發驅動程式時，才應該設定此值。 請參閱 VerifierOn中的程式碼範例。

VerifierAllocateFailCount

REG_DWORD

如果設定為 n值，且已設定 VerifierOn ，則架構會在 第 n 次 配置之後，嘗試為驅動程式的物件配置記憶體失敗。 此失敗可協助您測試驅動程式對低記憶體狀況的處理。 例如，如果您將 VerifierAllocateFailCount 設定為 2，則第二個配置之後的每個記憶體配置都會失敗。 VerifierAllocateFailCount的預設值是0xffffffff。 設定 VerifierAllocateFailCount之後，您可以將它設定為 (DWORD) -1 或完全移除值來將其關閉。

請注意，驗證器會計算驅動程式要求的配置，以及架構代表驅動程式要求的配置。 另請注意，驅動程式可能發生的配置數目可能會從某個版本的架構變更為下一個版本。

VerifierOn

REG_DWORD

設定為非零值以啟用 KMDF 驗證器，其會廣泛驗證驅動程式的狀態和函式參數。 當您開發驅動程式時，應該設定 VerifierOn 和 DbgBreakOnError 。 使用 AddService 指示詞 和 AddReg 指示 詞，在 INF 檔案的 Services 區段中設定這些值，例如：

[xxx_Inst.NT.Services]
AddService = xxx,%SPSVCINST_ASSOCSERVICE%,xxx_Service_Inst

[xxx_Service_Inst]
ServiceType   = %SERVICE_KERNEL_DRIVER%
StartType     = %SERVICE_BOOT_START%
ErrorControl  = %SERVICE_ERROR_NORMAL%
LoadOrderGroup = "Base"
ServiceBinary = %12%\xxx.sys
AddReg         = KMDFVerifierAddReg

[KMDFVerifierAddReg]
HKR, Parameters\Wdf,VerifierOn,0x00010001,1
HKR, Parameters\Wdf,VerboseOn,0x00010001,1
HKR, Parameters\Wdf,DbgBreakOnError,0x00010001,1

VerifyDownLevel

REG_DWORD、架構 1.9 版和更新版本

如果設定為非零值，而且驅動程式是以比目前版本還舊的架構版本所建置，則架構的驗證器會包含驅動程式建置之後新增的測試。 如果此值不存在或設定為零，架構的驗證程式只會包含驅動程式建置時存在的測試。

例如，如果您的驅動程式是以架構 1.7 版所建置，而且如果電腦上已安裝 1.9 版的架構，將 VerifyDownLevel 設定為非零，驗證程式就會在驅動程式執行時包含已新增至驗證程式 1.9 版的測試。

VerifyOn

REG_DWORD

設定為非零值，以啟用 Wdfassert.h 中定義的 WDFVERIFY 宏，或設定為零以停用宏。 如果已設定 VerifyerOn 值，VerifyOn 會隱含地設定為非零。