调试 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

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

设置为框架分配给其事件日志器内存页数。 如果未定义该值，框架将使用一个页面的默认值。 对于具有 4 KB 大小的内存页（x86 和 amd64 处理器）的计算机，可以设置的最大值为 16，对于具有 8 千字节大小的内存页（ia64 处理器）的计算机，最大值为 8。 (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 隐式设置为非零。