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

ФлагиРежимаОтладки

REG_DWORD, только UMDF

Это значение реестра находится в HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

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

Опции улучшенной проверки

REG_DWORD, версии фреймворка 1.9 и выше

Это значение содержит растровое изображение. Каждый бит представляет дополнительный параметр проверки, который пользователи могут включить, задав бит.

Битовые значения:

0x1. Если задано, проверятель проверяет, выполняется ли каждая из функций обратного вызова событий драйвера:

• Возвращается на тот же IRQL, на котором был вызван. Если значения отличаются, проверка ошибки WDF_VIOLATION возникает с кодом ошибки 0xE.

• Перед возвращением он выходит из всех критически важных регионов, в которые входит. Если функция обратного вызова завершается в критическом регионе, в который вошла, возникает проверка на ошибку WDF_VIOLATION с кодом 0xF.

0x10000: Если задано, и драйвер включил гарантированный ход выполнения для очереди ввода-вывода, фреймворк имитирует ситуацию с низкой памятью для каждого запроса ввода-вывода в очереди.

0x20000. Если задано, и если драйвер включил гарантированный ход выполнения для очереди ввода-вывода, платформа имитирует ситуацию с низкой памятью для некоторых случайных выбранных запросов ввода-вывода.

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 (глобальный)

REG_DWORD, только UMDF

Это значение реестра находится в HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Его можно задать с помощью средства проверки WDF (WdfVerifier.exe) в WDK. Это значение влияет на все драйверы UMDF в системе.

Содержит значение задержки в секундах. Заставляет WUDFHost отложить указанное количество секунд после загрузки драйвера. Поведение HostProcessDbgBreakOnDriverLoad в противном случае совпадает с тем, что описано для HostProcessDbgBreakOnStart.

Указание hostProcessDbgBreakOnStart или HostProcessDbgBreakOnDriverLoad приводит к отключению платформы других тайм-аутов UMDF (например, операций Plug and Play). Это означает, что если ваш драйвер вызывает чрезмерные тайм-ауты, использование этих значений может привести к тому, что ваш драйвер вызовет смертельный сбой в целевой системе.

HostProcessDbgBreakOnStart

REG_DWORD, только UMDF

Это значение реестра находится в HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Его можно задать с помощью средства проверки WDF (WdfVerifier.exe) в WDK. Это значение влияет на все драйверы UMDF в системе.

Содержит значение задержки в секундах. В течение указанного периода задержки основной процесс один раз в секунду ищет отладчик пользовательского режима и останавливается, если он подключен. Если отладчик в пользовательском режиме не подключен в течение этого периода, а высокий бит в HostProcessDbgBreakOnStart установлен (0x80000000), платформа делает попытку войти в отладчик режима ядра. Рассмотрим пример.

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

LogPages

REG_DWORD

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

КоличествоНеудачныхВыделенийПроверяющего

REG_DWORD

Если задано значение n и включен параметр VerifierOn, платформа завершает неудачей каждую попытку выделить память для объектов драйвера после n-го выделения. Этот сбой помогает протестировать обработку драйвера условий с низкой памятью. Например, если задать значение VerifierAllocateFailCount равным 2, каждое выделение памяти после второго выделения завершится ошибкой. Значением по умолчанию для VerifierAllocateFailCount является 0xffffffff. После настройки VerifierAllocateFailCount его можно отключить, установив для него значение (DWORD) -1 или полностью удалив значение.

Обратите внимание, что проверяющий подсчитывает как выделения, запрашиваемые драйвером, так и выделения, запрашиваемые платформой от имени драйвера. Кроме того, обратите внимание, что количество выделений, которые могут возникнуть для драйвера, может измениться от одного выпуска фреймворка к следующему.

VerifierOn

REG_DWORD

Задайте значение, отличное от нуля, чтобы включить средство проверки KMDF, которое тщательно проверяет состояние и параметры функции драйвера. При разработке драйвера необходимо задать VerifierOn и DbgBreakOnError . Используйте директиву AddService и директиву AddReg , чтобы задать эти значения в разделе "Службы" INF-файла, например:

[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

Проверить нижний уровень

REG_DWORD, платформы версии 1.9 и более поздних версий

Если задано значение, отличное от нуля, и если драйвер был создан с версией платформы, старше текущей версии, средство проверки платформы включает тесты, добавленные после сборки драйвера. Если это значение не существует или равно нулю, средство проверки платформы включает только тесты, которые существовали при построении драйвера.

Например, если драйвер был создан с версией 1.7 фреймворка, и если на компьютере установлена версия 1.9 фреймворка, установка VerifyDownLevel ненулевого значения приводит к тому, что средство проверки включает тесты, добавленные в версию 1.9 средства проверки, когда запускается драйвер.

VerifyOn

REG_DWORD

Задайте значение, отличное от нуля, чтобы включить макрос WDFVERIFY , определенный в Wdfassert.h, или установите значение нулю, чтобы отключить макрос. Если задано значение VerifierOn, ПроверкаOn неявно имеет значение nonzero.