用于调试 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 设置此值。

驱动程序可能需要创建可选的 “诊断” 子项。

如果设置为非零值，则框架的加载程序会在加载驱动程序并将其绑定到框架库的某个版本或卸载驱动程序时向内核调试器发送各种消息。

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

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

Value 说明
0x01 启用调试模式。 此设置关闭在 UMDF 驱动程序中使用设备池中所述的自动重启功能。
0x02 禁用设备池。 有关设备池的详细信息，请参阅 在 UMDF 驱动程序中使用设备池。
0x04 禁用超时。

在 Microsoft Visual Studio 中使用 F5 选项时，会为部署的驱动程序设置所有三个标志。

EnhancedVerifierOptions

REG_DWORD框架版本 1.9 及更高版本

此值包含位图。 每个位表示用户可通过设置位启用的附加验证程序选项。

位值：

0x1：如果设置，验证程序将检查每个驱动程序的事件回调函数是否执行以下操作：

  • 在调用它的同一 IRQL 处返回 。 如果值不同， 则会进行WDF_VIOLATION bug 检查，错误代码为 0xE。

  • 在返回之前，退出它进入的所有 关键区域 。 如果回调函数在它输入的关键区域内返回，则会进行 WDF_VIOLATION bug 检查，错误代码为 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 版本为 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 秒内未附加用户模式调试器，框架会尝试连接到内核模式调试器。

还可以通过使用 WDK 中包含的 WDF 验证程序工具 (WdfVerifier.exe) 来设置此注册表值。

LogPages

REG_DWORD

将 设置为框架分配给其事件记录器中的内存页数。 如果值未定义，则框架使用默认值一页。 对于具有 4 千字节大小的内存页的计算机 (x86 和 amd64 处理器) ，可以设置的最大值为 16;对于具有 8 千字节大小的内存页的计算机 (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 键中描述的类型的最大对象数。 若要控制超过此阈值是否应导致调试中断或 bug 检查，请设置 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 宏，或设置为零以禁用宏。 如果设置了 VerifierOn 值，则 VerifyOn 将隐式设置为非零值。