偵錯 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

If set to a nonzero value, the framework breaks into the debugger when a driver calls WdfVerifierDbgBreakPoint. (If the VerifierOn value is set, the framework breaks into the debugger even if the DbgBreakOnError value does not exist.) See the code example in the VerifierOn section.

DbgPrintOn

REG_DWORD

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

The driver might need to create the optional Diagnostics subkey.

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

DbgWaitForSignalTimeoutInSec

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

Starting in Windows 8, when VerifierOn and DbgBreakOnError are set to nonzero values, the driver can change the default timeout period for breaking into the debugger by setting DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, UMDF-only

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

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

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

EnhancedVerifierOptions

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

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

Bit values:

0x1: If set, the verifier checks whether each of the driver's event callback functions does the following:

• 傳回其呼叫所在的相同 IRQL。 If the values are different, a WDF_VIOLATION bug check occurs with an error code of 0xE.

• Before returning, exits all critical regions that it enters. If the callback function returns within a critical region that it entered, a WDF_VIOLATION bug check occurs with an error code of 0xF.

0x10000: If set, and if the driver has enabled guaranteed forward progress for an I/O queue, the framework simulates a low-memory situation for each of the queue's I/O requests.

0x20000: If set, and if the driver has enabled guaranteed forward progress for an I/O queue, the framework simulates a low-memory situation for some randomly selected I/O requests.

ForceLogsInMiniDump

REG_DWORD

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

HostFailKdDebugBreak

REG_DWORD, UMDF-only

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

如果此值不是零，且核心偵錯器已連線到電腦，反射器會在終止主機程序之前進入核心偵錯器。 HostFailKdDebugBreak is disabled by default in Windows 7 and earlier operating systems. Starting in Windows 8, HostFailKdDebugBreak is enabled by default.

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

HostProcessDbgBreakOnDriverLoad (driver-specific)

REG_DWORD, UMDF-only, works with any UMDF 1.x/2.x driver running on a target computer with UMDF version 2.31 or later

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

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

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

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

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

HostProcessDbgBreakOnDriverLoad (global)

REG_DWORD, UMDF-only

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

包含以秒為單位的延遲值。 導致 WUDFHost 在載入驅動程式之後延遲指定的秒數。 The behavior for HostProcessDbgBreakOnDriverLoad is otherwise the same as that described for HostProcessDbgBreakOnStart.

Specifying HostProcessDbgBreakOnStart or HostProcessDbgBreakOnDriverLoad causes the framework to disable other UMDF timeouts (for example, Plug and Play operations). 這表示如果您的驅動程式造成過多逾時，使用這些值可能會導致您的驅動程式造成目標嚴重當機。

HostProcessDbgBreakOnStart

REG_DWORD, UMDF-only

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

包含以秒為單位的延遲值。 在指定的延遲期間，主機程序每秒會檢查一次是否有使用者模式偵錯器連接，如果有連接就執行中斷操作。 If a user-mode debugger is not attached within this period and the high bit in HostProcessDbgBreakOnStart is set (0x80000000), the framework makes a single attempt to break into the kernel-mode debugger. For example:

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

LogPages

REG_DWORD

設定為架構指派給其事件記錄器之內存頁數。 如果值未定義，架構會使用一頁的預設值。 您可以設定的最大值是 16，適用於具有 4 KB 大小記憶體頁面的電腦（x86 和 amd64 處理器），以及最大值是 8，適用於具有 8 KB 大小記憶體頁面的電腦（ia64 處理器）。 (The operating system might not write the log contents to a crash dump file if a large number of pages is specified.) Use the AddService directive and the AddReg directive to set this value in your INF file, as follows:

[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

在某些情況下，架構物件未正確與父物件關聯，且在使用後未被刪除。 You can use ObjectLeakDetectionLimit and ObjectsForLeakDetection to specify a maximum number of objects and what should happen when this threshold is exceeded.

REG_DWORD

Specifies the maximum number of objects of the types described in the ObjectsForLeakDetection key. To control whether exceeding this threshold should cause a debug break or a bugcheck, set the DbgBreakOnError key. The limit scales with the number of devices installed, so if the driver creates three WDFDEVICE objects, the limit is three times the value specified in ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

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

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

TrackHandles

REG_MULTI_SZ

If set to a list of one or more type names of framework object handles, and if VerifierOn is set, the framework tracks references to all object handles that match the specified handle types. 例如，如果句柄類型清單包含 「WDFREQUEST WDFQUEUE」 字串，則架構會追蹤所有要求物件和佇列對象的參考。 如果清單包含星號（"*"），架構會追蹤所有物件控制碼。

VerboseOn

REG_DWORD

If set to a nonzero value, the framework's event logger records additional information that can help you debug your driver, such as entries into or exits from internal code paths. 只有在開發驅動程式時，才應該設定此值。 See the code example in VerifierOn.

VerifierAllocateFailCount

REG_DWORD

If set to a value n, and if VerifierOn is set, the framework fails every attempt to allocate memory for the driver's objects after the nth allocation. 此失敗可協助您測試驅動程式對低記憶體狀況的處理。 For example, if you set VerifierAllocateFailCount to 2, every memory allocation after the second allocation will fail. The default value for VerifierAllocateFailCount is 0xffffffff. After setting VerifierAllocateFailCount, you can turn it off by setting it to (DWORD) -1 or removing the value altogether.

請注意，驗證器會計算驅動程式要求的配置，以及架構代表驅動程式要求的配置。 請注意，驅動程式的配置數目可能會隨著框架的各個版本而變動。

VerifierOn

REG_DWORD

Set to a nonzero value to enable KMDF Verifier, which extensively validates a driver's state and function parameters. You should set VerifierOn and DbgBreakOnError when you are developing your driver. Use the AddService directive and the AddReg directive to set these values in the Services section of the INF file, for example:

[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 和更新版本

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

For example, if your driver was built with version 1.7 of the framework, and if version 1.9 of the framework is installed on the computer, setting VerifyDownLevel to nonzero causes the verifier to include tests that were added to version 1.9 of the verifier when your driver runs.

VerifyOn

REG_DWORD

Set to a nonzero value to enable the WDFVERIFY macro that is defined in Wdfassert.h, or set to zero to disable the macro. 如果已設定 VerifierOn 值，VerifyOn 會隱含地設定為非零值。