Значения реестра для отладки драйверов 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.

При использовании параметра F5 в Microsoft Visual Studio все три флага задаются для развернутого драйвера.

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}. Его можно задать с помощью средства проверки WDF (WdfVerifier.exe) в WDK. Это значение влияет на все драйверы 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}. Его можно задать с помощью средства проверки WDF (WdfVerifier.exe) в WDK. Это значение влияет на все драйверы 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:

Вы также можете задать это значение реестра с помощью средства проверки WDF (WdfVerifier.exe), включенного в WDK.

LogPages

REG_DWORD

Задайте количество страниц памяти, которые платформа назначает средству ведения журнала событий. Если значение не определено, платформа использует значение по умолчанию одной страницы. Максимальное значение, которое можно задать, — 16 для компьютеров с 4-килобайтами памяти (процессоры x86 и amd64) и 8 для компьютеров с 8-килобайтами памяти (процессоры 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, ПроверкаOn неявно имеет значение nonzero.