Compartir a través de

Valores del Registro para depurar controladores WDF

  • Artículo

En este artículo se describen los valores del Registro que puede establecer un controlador WDF. Se aplica a los controladores KMDF y a los controladores UMDF a partir de la versión 2 de UMDF.

A menos que se especifique lo contrario en las secciones siguientes, los siguientes valores del Registro se encuentran en la subclave de Parameters\Wdf un controlador.

  • Para un controlador KMDF, esta subclave se encuentra en , bajo HKEY_LOCAL_MACHINE\System\CurrentControlSet\Servicesel nombre del servicio del controlador.
  • Para un controlador UMDF, esta subclave se encuentra en , bajo HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Servicesel nombre del servicio del controlador.

La subclave del controlador siempre usa el nombre del servicio del controlador, incluso si el nombre de archivo del binario del controlador difiere del nombre del servicio.

DbgBreakOnError

REG_DWORD

Si se establece en un valor distinto de cero, el marco se divide en el depurador cuando un controlador llama a WdfVerifierDbgBreakPoint. (Si se establece el valor VerifierOn , el marco se divide en el depurador incluso si el valor DbgBreakOnError no existe). Consulte el ejemplo de código en la sección VerifierOn .

DbgPrintOn

REG_DWORD

  • Para un controlador KMDF, establezca este valor en la clave del HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics Registro.
  • Para un controlador UMDF, establezca este valor en la clave del HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics Registro.

Es posible que el controlador tenga que crear la subclave diagnostics opcional.

Si se establece en un valor distinto de cero, el cargador del marco envía una variedad de mensajes al depurador del kernel mientras carga un controlador y lo enlaza a una versión de la biblioteca de marcos o mientras descarga un controlador.

DbgWaitForSignalTimeoutInSec

REG_DWORD, versiones 1.11 y posteriores del marco

A partir de Windows 8, cuando VerifierOn y DbgBreakOnError se establecen en valores distintos de cero, el controlador puede cambiar el período de tiempo de espera predeterminado para dividir en el depurador estableciendo DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, solo UMDF

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Este valor especifica los nombres de los archivos binarios del controlador que se van a cargar en modo de depuración. Para habilitar el modo de depuración para los archivos binarios de controladores X.DLL, Y.DLL y Z.DLL, por ejemplo, este valor se establecería en X.DLL\0Y.DLL\0Z.DLL\0\0.

DebugModeFlags

REG_DWORD, solo UMDF

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Value Descripción
0x01 Habilite el modo de depuración. Esta configuración desactiva la funcionalidad de reinicio automático descrita en Uso de la agrupación de dispositivos en controladores UMDF.
0x02 Deshabilite la agrupación de dispositivos. Para obtener más información sobre la agrupación de dispositivos, consulte Uso de la agrupación de dispositivos en controladores UMDF.
0x04 Deshabilite los tiempos de espera.

Cuando se usa la opción F5 en Microsoft Visual Studio, las tres marcas se establecen para el controlador implementado.

EnhancedVerifierOptions

REG_DWORD, versiones 1.9 y posteriores del marco

Este valor contiene un mapa de bits. Cada bit representa una opción de comprobador adicional que los usuarios pueden habilitar estableciendo el bit.

Valores de bits:

0x1: si se establece, el comprobador comprueba si cada una de las funciones de devolución de llamada de evento del controlador hace lo siguiente:

  • Devuelve en el mismo IRQL en el que se llamó. Si los valores son diferentes, se produce una comprobación de errores de WDF_VIOLATION con un código de error de 0xE.

  • Antes de devolver, sale de todas las regiones críticas que entra. Si la función de devolución de llamada vuelve dentro de una región crítica que especificó, se produce una comprobación de errores de WDF_VIOLATION con un código de error de 0xF.

0x10000: si se establece y si el controlador ha habilitado el progreso hacia delante garantizado para una cola de E/S, el marco simula una situación de memoria baja para cada una de las solicitudes de E/S de la cola.

0x20000: si se establece y si el controlador ha habilitado el progreso hacia delante garantizado para una cola de E/S, el marco simula una situación de memoria baja para algunas solicitudes de E/S seleccionadas aleatoriamente.

ForceLogsInMiniDump

REG_DWORD

Establézcalo en un valor distinto de cero para que el marco incluya información de su registrador de eventos en archivos de volcado de memoria.

HostFailKdDebugBreak

REG_DWORD, solo UMDF

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

Si este valor es distinto de cero y un depurador de kernel está conectado a la máquina, el reflector se divide en el depurador de kernel antes de finalizar el proceso de host. HostFailKdDebugBreak está deshabilitado de forma predeterminada en Windows 7 y en sistemas operativos anteriores. A partir de Windows 8, HostFailKdDebugBreak está habilitado de forma predeterminada.

El reflector también se divide en el depurador de kernel si hay una terminación inesperada del proceso de host (por ejemplo, por un componente que no es UMDF o debido a una excepción no controlada). Si hay varias pilas de dispositivos agrupadas en el proceso de host que se está finalizando, el reflector se divide en el depurador varias veces, una vez para cada pila de dispositivos cargada en el proceso de host.

HostProcessDbgBreakOnDriverLoad (específico del controlador)

REG_DWORD, solo UMDF, funciona con cualquier controlador UMDF 1.x/2.x que se ejecute en un equipo de destino con la versión 2.31 o posterior de UMDF.

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

Este valor afecta solo al controlador UMDF especificado.

Contiene un valor de retraso en segundos. Hace que WUDFHost intente conectarse a un depurador durante el número de segundos especificado después de cargar el controlador.

Durante el período de retraso especificado, el proceso de host busca el depurador en modo de usuario una vez por segundo y se interrumpe si uno está conectado. Si un depurador en modo de usuario no está asociado en este período y el bit alto de se establece (0x80000000), el marco realiza un único intento de interrumpir el depurador en modo kernel. Consulte la sección sobre HostProcessDbgBreakOnStart anterior para obtener ejemplos.

Para que los cambios en los valores del Registro umDF surtan efecto, debe reiniciar el equipo.

HostProcessDbgBreakOnDriverLoad (global)

REG_DWORD, solo UMDF

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Puede establecerlo mediante la herramienta Comprobador de WDF (WdfVerifier.exe) en WDK. Este valor afecta a todos los controladores UMDF del sistema.

Contiene un valor de retraso en segundos. Hace que WUDFHost retrase el número especificado de segundos después de cargar el controlador. El comportamiento de HostProcessDbgBreakOnDriverLoad es el mismo que el descrito para HostProcessDbgBreakOnStart.

Especificar HostProcessDbgBreakOnStart o HostProcessDbgBreakOnDriverLoad hace que el marco de trabajo deshabilite otros tiempos de espera de UMDF (por ejemplo, Plug and Play operaciones). Esto significa que si el controlador provoca tiempos de espera excesivos, el uso de estos valores podría provocar un accidente grave en el destino.

HostProcessDbgBreakOnStart

REG_DWORD, solo UMDF

Este valor del Registro se encuentra en HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Puede establecerlo mediante la herramienta Comprobador de WDF (WdfVerifier.exe) en WDK. Este valor afecta a todos los controladores UMDF del sistema.

Contiene un valor de retraso en segundos. Durante el período de retraso especificado, el proceso de host busca el depurador en modo de usuario una vez por segundo y se interrumpe si uno está conectado. Si un depurador en modo de usuario no está asociado en este período y el bit alto de HostProcessDbgBreakOnStart se establece (0x80000000), el marco realiza un único intento de interrumpir el depurador en modo kernel. Por ejemplo:

Value Resultado
0x00000004 El marco intenta conectarse al depurador en modo de usuario una vez por segundo durante 4 segundos. El marco nunca intenta conectarse al depurador en modo kernel.
0x80000000 El marco realiza un único intento de conectarse al depurador en modo de usuario. Si el depurador en modo de usuario no está asociado, el marco intenta conectarse al depurador en modo kernel.
0x80000004 El marco intenta conectarse al depurador en modo de usuario una vez por segundo durante 4 segundos. Si el depurador en modo de usuario no está asociado en un plazo de 4 segundos, el marco intenta conectarse al depurador en modo kernel.

También puede establecer este valor del Registro mediante la herramienta Comprobador de WDF (WdfVerifier.exe) que se incluye en el WDK.

LogPages

REG_DWORD

Establezca en el número de páginas de memoria que el marco asigna a su registrador de eventos. Si el valor no está definido, el marco usa un valor predeterminado de una página. El valor máximo que se puede establecer es 16 para equipos que tienen páginas de memoria de 4 kilobytes (procesadores x86 y amd64) y 8 para equipos que tienen páginas de memoria de 8 kilobytes (procesadores ia64). (Es posible que el sistema operativo no escriba el contenido del registro en un archivo de volcado de memoria si se especifica un gran número de páginas). Use la directiva AddService y la directiva AddReg para establecer este valor en el archivo INF, como se indica a continuación:

[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

En algunos casos, los objetos de marco están primarios incorrectamente y no se eliminan después de su uso. Puede usar ObjectLeakDetectionLimit y ObjectsForLeakDetection para especificar un número máximo de objetos y lo que debe ocurrir cuando se supera este umbral.

REG_DWORD

Especifica el número máximo de objetos de los tipos descritos en la clave ObjectsForLeakDetection . Para controlar si superar este umbral debe provocar una interrupción de depuración o una comprobación de errores, establezca la clave DbgBreakOnError . El límite se escala con el número de dispositivos instalados, por lo que si el controlador crea tres objetos WDFDEVICE, el límite es tres veces el valor especificado en ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

Use con ObjectLeakDetectionLimit. Enumera cada nombre de tipo que se va a comprobar. Por ejemplo, podría especificar WDFDMATRANSACTION WDFDEVICE. Para especificar todos los tipos de identificador, use * como cadena. Si no se especifica la clave ObjectsForLeakDetection, el valor predeterminado es supervisar WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT y WDFDEVICE.

Si especifica WDFREQUEST, el comprobador solo cuenta los objetos WDFREQUEST que crea el controlador. Esta característica no admite actualmente el seguimiento del tipo de objeto WDFMEMORY.

TrackHandles

REG_MULTI_SZ

Si se establece en una lista de uno o varios nombres de tipo de identificadores de objeto de marco y, si se establece VerifierOn , el marco realiza un seguimiento de las referencias a todos los identificadores de objeto que coinciden con los tipos de identificador especificados. Por ejemplo, si la lista de tipos de identificador consta de la cadena "WDFREQUEST WDFQUEUE", el marco realiza un seguimiento de las referencias a todos los objetos de solicitud y objetos de cola. Si la lista contiene un asterisco ("*"), el marco realiza un seguimiento de todos los identificadores de objeto.

VerboseOn

REG_DWORD

Si se establece en un valor distinto de cero, el registrador de eventos del marco registra información adicional que puede ayudarle a depurar el controlador, como entradas en o salidas de rutas de código internas. Solo debe establecer este valor mientras desarrolla el controlador. Consulte el ejemplo de código en VerifierOn.

VerifierAllocateFailCount

REG_DWORD

Si se establece en un valor n y si se establece VerifierOn, se produce un error en cada intento de asignar memoria para los objetos del controlador después de la asignación n. Este error le ayuda a probar el control del controlador de condiciones de poca memoria. Por ejemplo, si establece VerifierAllocateFailCount en 2, se producirá un error en cada asignación de memoria después de la segunda asignación. El valor predeterminado de VerifierAllocateFailCount es 0xffffffff. Después de establecer VerifierAllocateFailCount, puede desactivarlo estableciendo en (DWORD) -1 o quitando el valor por completo.

Tenga en cuenta que el comprobador cuenta las asignaciones que solicita el controlador y las asignaciones que solicita el marco en nombre del controlador. Tenga en cuenta también que el número de asignaciones que se pueden producir para el controlador puede cambiar de una versión del marco a la siguiente.

VerifierOn

REG_DWORD

Se establece en un valor distinto de cero para habilitar el comprobador de KMDF, que valida ampliamente los parámetros de estado y función de un controlador. Debe establecer VerifierOn y DbgBreakOnError al desarrollar el controlador. Use la directiva AddService y la directiva AddReg para establecer estos valores en la sección Servicios del archivo INF, por ejemplo:

[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, versiones 1.9 y posteriores del marco

Si se establece en un valor distinto de cero y si el controlador se creó con una versión del marco anterior a la versión actual, el comprobador del marco incluye pruebas que se agregaron después de compilar el controlador. Si este valor no existe o se establece en cero, el comprobador del marco incluye solo las pruebas que existían cuando se creó el controlador.

Por ejemplo, si el controlador se creó con la versión 1.7 del marco de trabajo y si la versión 1.9 del marco está instalada en el equipo, al establecer VerifyDownLevel en distinto de cero, el comprobador incluirá pruebas que se agregaron a la versión 1.9 del comprobador cuando se ejecuta el controlador.

VerifyOn

REG_DWORD

Establezca en un valor distinto de cero para habilitar la macro WDFVERIFY definida en Wdfassert.h o establecida en cero para deshabilitar la macro. Si se establece el valor verifierOn, VerifyOn se establece implícitamente en distinto de cero.