Значения реестра для отладки драйверов WDF

В этой статье описываются значения реестра, которые может задать драйвер WDF. Он применяется к драйверам KMDF и драйверам UMDF, начиная с UMDF версии 2.

Если в разделах ниже не указано иное, следующие значения реестра находятся в подразделе 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 разделе реестра.

Драйверу может потребоваться создать дополнительный подраздел 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.

Значение	Описание
0x01	Включите режим отладки. Этот параметр отключает функцию автоматического перезапуска, описанную в разделе Использование пулов устройств в драйверах UMDF.
0x02	Отключение пула устройств. Дополнительные сведения о пуле устройств см. в статье Использование пулов устройств в драйверах UMDF.
0x04	Отключите время ожидания.

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

EnhancedVerifierOptions

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

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

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

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

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

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

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

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

ForceLogsInMiniDump

REG_DWORD

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

HostFailKdDebugBreak

REG_DWORD, UMDF-only

This registry value is located in 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 или более поздней.

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

Contains a delay value in seconds. Вызывает задержку WUDFHost на указанное количество секунд после загрузки драйвера. В противном случае поведение HostProcessDbgBreakOnDriverLoad такое же, как описано для HostProcessDbgBreakOnStart.

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

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 секунд, платформа пытается подключиться к отладчику режима ядра.

Это значение реестра также можно задать с помощью средства проверки 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

В некоторых случаях объекты платформы неправильно родительские и не удаляются после использования. С помощью ObjectLeakDetectionLimit и ObjectsForLeakDetection можно указать максимальное количество объектов и то, что должно произойти при превышении этого порогового значения.

REG_DWORD

Задает максимальное количество объектов типов, описанных в разделе ObjectsForLeakDetection . Чтобы определить, должно ли превышение этого порога вызывать прерывание отладки или проверку ошибок, задайте ключ 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-файла, например:

[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 в значение nonzero приведет к тому, что проверяющий будет включать тесты, добавленные в версию 1.9 средства проверки при запуске драйвера.

VerifyOn

REG_DWORD

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