共用方式為

偵錯 WDF 驅動程式的註冊表值

  • 發行項

本文說明 WDF 驅動程式可以設定的登錄值。 它適用於 KMDF 驅動程式和從 UMDF 第 2 版開始的 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 登錄機碼下設定此值。

驅動程式可能需要建立可選的 診斷 子機碼。

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

DbgWaitForSignalTimeoutInSec

REG_DWORD，框架版本 1.11 和更新版本

從 Windows 8 開始，當 VerifierOn 和 DbgBreakOnError 設為非零值時，驅動程式可以藉由設定 DbgWaitForSignalTimeoutInSec來變更進入調試器的預設逾時期限。

DebugModeBinaries

REG_MULTI_SZ，僅限UMDF

此登入值位於 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

這個登錄值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode。

價值 說明
0x01 啟用偵錯模式。 這個設定會關閉在 UMDF 驅動程式中使用裝置池化所述的自動重新啟動功能。
0x02 停用裝置共用。 如需裝置共用的詳細資訊，請參閱在 UMDF 驅動程式中使用裝置共用 。
0x04 停用超時。

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

EnhancedVerifierOptions (增強驗證器選項)

REG_DWORD，框架版本 1.9 和更新版本

這個值包含位圖。 每個位元代表使用者可以透過設定位元來啟用的其他驗證選項。

位值：

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

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

  • 返回之前，會退出所有已進入的 關鍵區域。 如果回呼函式在輸入的重要區域內傳回，就會發生錯誤碼為 0xF WDF_VIOLATION 錯誤檢查。

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

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

ForceLogsInMiniDump

REG_DWORD

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

HostFailKdDebugBreak

REG_DWORD，僅限UMDF

此登入值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF。

如果此值不是零，且核心偵錯器已連線到電腦，反射器會在終止主機程序之前進入核心偵錯器。 HostFailKdDebugBreak 在 Windows 7 和較早期的作業系統中預設會被停用。 從 Windows 8 開始，預設會啟用 hostFailKdDebugBreak。

如果主機流程發生非預期的終止，反射器也會進入核心除錯器（例如由於非 UMDF 元件或未處理的例外）。 如果正在終止的主機進程中有多個裝置堆疊集區，反射器會多次進入調試器，每次針對載入主機進程的每個裝置堆疊。

HostProcessDbgBreakOnDriverLoad（特定於驅動程式）

REG_DWORD，僅限 UMDF，適用於目標電腦上執行的任何 UMDF 1.x/2.x 驅動程式，UMDF 2.31 版 或更新版本

此登錄值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf。

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

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

在指定的延遲期間，主機程序每秒會檢查一次是否有使用者模式偵錯器連接，如果有連接就執行中斷操作。 如果未在此期間內附加使用者模式調試程式，且在某處的高位（0x80000000）已設定，則架構會嘗試一次進入內核模式調試程式。 如需範例，請參閱上述 HostProcessDbgBreakOnStart 一節。

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

HostProcessDbgBreakOnDriverLoad （global）

REG_DWORD，僅限UMDF

此登錄值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}。 您可以使用 WDK 中的 WDF 驗證器工具 （WdfVerifier.exe） 加以設定。 此值會影響系統上的所有UMDF驅動程式。

包含以秒為單位的延遲值。 導致 WUDFHost 在載入驅動程式之後延遲指定的秒數。 HostProcessDbgBreakOnDriverLoad 的行為，與 HostProcessDbgBreakOnStart中所述的行為相同。

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

HostProcessDbgBreakOnStart

REG_DWORD，僅限UMDF

此登錄值位於 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}。 您可以使用 WDK 中的 WDF 驗證器工具 （WdfVerifier.exe） 加以設定。 此值會影響系統上的所有UMDF驅動程式。

包含以秒為單位的延遲值。 在指定的延遲期間，主機進程會每秒尋找使用者模式調試程式一次，並在連接時中斷。 如果未在此期間內附加使用者模式調試程式，且 HostProcessDbgBreakOnStart 中的高位已設定 （0x80000000），架構會嘗試中斷內核模式調試程式。 例如：

價值 結果
0x00000004 架構會嘗試每秒連線一次到使用者模式調試工具，持續4秒。 架構永遠不會嘗試連線到內核模式調試程式。
0x80000000 此架構會僅嘗試一次連接到使用者模式偵錯工具。 如果未附加使用者模式調試程式，架構會嘗試連線到內核模式調試程式。
0x80000004 框架會在 4 秒內每秒嘗試連線至使用者模式除錯工具一次。 如果使用者模式調試程式未在 4 秒內附加，架構會嘗試連線到內核模式調試程式。

您也可以使用 WDK 中包含的 WDF 驗證器工具（WdfVerifier.exe）來設定此登錄值。

LogPages

REG_DWORD

設定為架構指派給其事件記錄器之內存頁數。 如果值未定義，架構會使用一頁的預設值。 您可以設定的最大值是 16，適用於具有 4 KB 大小記憶體頁面的電腦（x86 和 amd64 處理器），以及最大值是 8，適用於具有 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 中所指定值的三倍，。

漏水檢測物件

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 巨集，或設置為零以停用該巨集。 如果已設定 VerifierOn 值，VerifyOn 會隱含地設定為非零值。