Valores do Registro para depuração de drivers WDF
Este artigo descreve os valores do Registro que um driver WDF pode definir. Ele se aplica a drivers KMDF e drivers UMDF começando com UMDF versão 2.
A menos que especificado de outra forma nas seções abaixo, os valores do Registro a seguir estão localizados sob a subchave de Parameters\Wdf um driver.
- Para um driver KMDF, essa subchave está localizada em
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services, sob o nome de serviço do driver. - Para um driver UMDF, essa subchave está localizada em
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services, sob o nome do serviço do driver.
A subchave para o driver sempre usa o nome de serviço do driver, mesmo que o nome do arquivo do binário do driver seja diferente do nome do serviço.
DbgBreakOnError
REG_DWORD
Se definido como um valor diferente de zero, a estrutura será dividida no depurador quando um driver chamar WdfVerifierDbgBreakPoint. (Se o valor VerifierOn for definido, a estrutura será dividida no depurador mesmo que o valor DbgBreakOnError não exista.) Consulte o exemplo de código na seção VerifierOn .
DbgPrintOn
REG_DWORD
- Para um driver KMDF, defina esse valor na chave do
HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\DiagnosticsRegistro. - Para um driver UMDF, defina esse valor na chave do
HKLM\System\CurrentControlSet\Control\Wdf\Umdf\DiagnosticsRegistro.
O driver pode precisar criar a subchave de Diagnóstico opcional.
Se definido como um valor diferente de zero, o carregador da estrutura enviará uma variedade de mensagens para o depurador de kernel enquanto ele estiver carregando um driver e associando-o a uma versão da biblioteca da estrutura ou enquanto ele estiver descarregando um driver.
DbgWaitForSignalTimeoutInSec
REG_DWORD, versões de estrutura 1.11 e posteriores
Começando no Windows 8, quando VerifierOn e DbgBreakOnError são definidos como valores diferentes de zero, o driver pode alterar o período de tempo limite padrão para invadir o depurador definindo DbgWaitForSignalTimeoutInSec.
DebugModeBinaries
REG_MULTI_SZ, somente UMDF
Esse valor do Registro está localizado em HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.
Esse valor especifica os nomes dos binários de driver a serem carregados no modo de depuração. Para habilitar o modo de depuração para binários de driver X.DLL, Y.DLL e Z.DLL, por exemplo, esse valor seria definido X.DLL\0Y.DLL\0Z.DLL\0\0como .
DebugModeFlags
REG_DWORD, somente UMDF
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.
| Valor | Descrição |
|---|---|
| 0x01 | Habilitar o modo de depuração. Essa configuração desativa a funcionalidade de reinicialização automática descrita em Usando o pool de dispositivos em drivers UMDF. |
| 0x02 | Desabilitar o pool de dispositivos. Para obter mais informações sobre o pool de dispositivos, consulte Usando o pool de dispositivos em drivers UMDF. |
| 0x04 | Desabilitar tempos limite. |
Quando você usa a opção F5 no Microsoft Visual Studio, todos os três sinalizadores são definidos para o driver implantado.
EnhancedVerifierOptions
REG_DWORD, versões de estrutura 1.9 e posteriores
Esse valor contém um bitmap. Cada bit representa uma opção de verificador adicional que os usuários podem habilitar definindo o bit.
Valores de bit:
0x1: se definido, o verificador verifica se cada uma das funções de retorno de chamada de evento do driver faz o seguinte:
Retorna no mesmo IRQL no qual foi chamado. Se os valores forem diferentes, uma verificação de bug WDF_VIOLATION ocorrerá com um código de erro de 0xE.
Antes de retornar, sai de todas as regiões críticas que ele insere. Se a função de retorno de chamada retornar dentro de uma região crítica que inseriu, uma verificação de bug WDF_VIOLATION ocorrerá com um código de erro de 0xF.
0x10000: se definido e se o driver tiver habilitado o progresso de encaminhamento garantido para uma fila de E/S, a estrutura simula uma situação de memória insuficiente para cada uma das solicitações de E/S da fila.
0x20000: se definido e se o driver tiver habilitado o progresso de encaminhamento garantido para uma fila de E/S, a estrutura simula uma situação de baixa memória para algumas solicitações de E/S selecionadas aleatoriamente.
ForceLogsInMiniDump
REG_DWORD
Defina como um valor diferente de zero para fazer com que a estrutura inclua informações de seu agente de eventos em arquivos de despejo de memória.
HostFailKdDebugBreak
REG_DWORD, UMDF-only
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.
Se esse valor for diferente de zero e um depurador de kernel estiver conectado ao computador, o refletor será dividido no depurador de kernel antes de encerrar o processo de host. HostFailKdDebugBreak está desabilitado por padrão no Windows 7 e em sistemas operacionais anteriores. A partir do Windows 8, HostFailKdDebugBreak está habilitado por padrão.
O refletor também será dividido no depurador de kernel se houver um encerramento inesperado do processo de host (por exemplo, por um componente não UMDF ou devido a uma exceção sem tratamento). Se houver várias pilhas de dispositivos em pool no processo de host que está sendo encerrado, o refletor será dividido no depurador várias vezes, uma vez para cada pilha de dispositivo carregada no processo de host.
HostProcessDbgBreakOnDriverLoad (específico do driver)
REG_DWORD, somente UMDF, funciona com qualquer driver UMDF 1.x/2.x em execução em um computador de destino com UMDF versão 2.31 ou posterior
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.
Esse valor afeta apenas o driver UMDF especificado.
Contém um valor de atraso em segundos. Faz com que WUDFHost tente se conectar a um depurador pelo número especificado de segundos após o driver ter sido carregado.
Durante o período de atraso especificado, o processo de host procura o depurador de modo de usuário uma vez por segundo e interrompe se um estiver conectado. Se um depurador de modo de usuário não estiver anexado dentro desse período e o bit alto em for definido (0x80000000), a estrutura fará uma única tentativa de invadir o depurador do modo kernel. Consulte a seção em HostProcessDbgBreakOnStart acima para obter exemplos.
Para que as alterações nos valores do Registro UMDF entrem em vigor, você deve reinicializar o computador.
HostProcessDbgBreakOnDriverLoad (global)
REG_DWORD, UMDF-only
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Você pode defini-lo usando a ferramenta Verificador do WDF (WdfVerifier.exe) no WDK. Esse valor afeta todos os drivers UMDF no sistema.
Contains a delay value in seconds. Faz com que WUDFHost atrase o número especificado de segundos após o driver ter sido carregado. O comportamento de HostProcessDbgBreakOnDriverLoad é o mesmo descrito para HostProcessDbgBreakOnStart.
Especificar HostProcessDbgBreakOnStart ou HostProcessDbgBreakOnDriverLoad faz com que a estrutura desabilite outros tempos limite de UMDF (por exemplo, operações de Plug and Play). Isso significa que, se o driver causar tempos limite excessivos, o uso desses valores poderá resultar em seu driver causando uma falha fatal no destino.
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. Se um depurador de modo de usuário não estiver anexado dentro desse período e o bit alto em HostProcessDbgBreakOnStart estiver definido (0x80000000), a estrutura fará uma única tentativa de invadir o depurador do modo kernel. Por exemplo:
| Valor | Result |
|---|---|
| 0x00000004 | A estrutura tenta se conectar ao depurador do modo de usuário uma vez por segundo por 4 segundos. A estrutura nunca tenta se conectar ao depurador do modo kernel. |
| 0x80000000 | A estrutura faz uma única tentativa de se conectar ao depurador do modo de usuário. Se o depurador do modo de usuário não estiver anexado, a estrutura tentará se conectar ao depurador do modo kernel. |
| 0x80000004 | A estrutura tenta se conectar ao depurador do modo de usuário uma vez por segundo por 4 segundos. Se o depurador do modo de usuário não estiver anexado dentro de 4 segundos, a estrutura tentará se conectar ao depurador do modo kernel. |
Você também pode definir esse valor do Registro usando a ferramenta Verificador do WDF (WdfVerifier.exe) incluída no WDK.
LogPages
REG_DWORD
Defina como o número de páginas de memória que a estrutura atribui ao agente de eventos. Se o valor for indefinido, a estrutura usará um valor padrão de uma página. O valor máximo que você pode definir é 16 para computadores que têm páginas de memória do tamanho de 4 quilobytes (processadores x86 e amd64) e 8 para computadores com páginas de memória do tamanho de 8 quilobytes (processadores ia64). (O sistema operacional pode não gravar o conteúdo do log em um arquivo de despejo de memória se um grande número de páginas for especificado.) Use a diretiva AddService e a diretiva AddReg para definir esse valor no arquivo INF da seguinte maneira:
[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
Em alguns casos, os objetos de estrutura são incorretamente paiizados e não excluídos após o uso. Você pode usar ObjectLeakDetectionLimit e ObjectsForLeakDetection para especificar um número máximo de objetos e o que deve acontecer quando esse limite for excedido.
REG_DWORD
Especifica o número máximo de objetos dos tipos descritos na chave ObjectsForLeakDetection . Para controlar se exceder esse limite deve causar uma quebra de depuração ou uma verificação de bugs, defina a chave DbgBreakOnError . O limite é dimensionado com o número de dispositivos instalados, portanto, se o driver criar três objetos WDFDEVICE, o limite será três vezes o valor especificado em ObjectLeakDetectionLimit.
ObjectsForLeakDetection
REG_MULTI_SZ
Use com ObjectLeakDetectionLimit. Lista cada nome de tipo a ser verificado. Por exemplo, você pode especificar WDFDMATRANSACTION WDFDEVICE. Para especificar todos os tipos de identificador, use * como a cadeia de caracteres. Se a chave ObjectsForLeakDetection não for especificada, o padrão será monitorar WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT e WDFDEVICE.
Se você especificar WDFREQUEST, o verificador conta apenas objetos WDFREQUEST que o driver cria. Atualmente, esse recurso não dá suporte ao acompanhamento do tipo de objeto WDFMEMORY.
TrackHandles
REG_MULTI_SZ
Se definido como uma lista de um ou mais nomes de tipo de identificadores de objeto de estrutura e se VerifierOn estiver definido, a estrutura rastreará referências a todos os identificadores de objeto que correspondem aos tipos de identificador especificados. Por exemplo, se a lista de tipos de identificador consistir na cadeia de caracteres "WDFREQUEST WDFQUEUE", a estrutura rastreará referências a todos os objetos de solicitação e objetos de fila. Se a lista contiver um asterisco ("*"), a estrutura rastreará todos os identificadores de objeto.
VerboseOn
REG_DWORD
Se definido como um valor diferente de zero, o agente de eventos da estrutura registrará informações adicionais que podem ajudá-lo a depurar seu driver, como entradas em ou saídas de caminhos de código internos. Você deve definir esse valor somente enquanto estiver desenvolvendo seu driver. Consulte o exemplo de código em VerifierOn.
VerifierAllocateFailCount
REG_DWORD
Se definido como um valor n e se VerifierOn estiver definido, a estrutura falhará em todas as tentativas de alocar memória para os objetos do driver após a nª alocação. Essa falha ajuda você a testar o tratamento do driver de condições de memória baixa. Por exemplo, se você definir VerifierAllocateFailCount como 2, todas as alocações de memória após a segunda alocação falharão. O valor padrão para VerifierAllocateFailCount é 0xffffffff. Depois de definir VerifierAllocateFailCount, você pode desativá-lo definindo-o como (DWORD) -1 ou removendo o valor completamente.
Observe que o verificador conta as alocações que o driver solicita e as alocações que a estrutura solicita em nome do driver. Observe também que o número de alocações que podem ocorrer para o driver pode mudar de uma versão da estrutura para a próxima.
VerifierOn
REG_DWORD
Defina como um valor diferente de zero para habilitar o Verificador KMDF, que valida extensivamente os parâmetros de estado e função de um driver. Você deve definir VerifierOn e DbgBreakOnError ao desenvolver seu driver. Use a diretiva AddService e a diretiva AddReg para definir esses valores na seção Serviços do arquivo INF, por exemplo:
[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, versões de estrutura 1.9 e posteriores
Se definido como um valor diferente de zero e se o driver tiver sido criado com uma versão da estrutura mais antiga que a versão atual, o verificador da estrutura incluirá testes que foram adicionados depois que o driver foi criado. Se esse valor não existir ou for definido como zero, o verificador da estrutura incluirá apenas os testes que existiam quando o driver foi criado.
Por exemplo, se o driver foi criado com a versão 1.7 da estrutura e se a versão 1.9 da estrutura estiver instalada no computador, definir VerifyDownLevel como diferente de zero fará com que o verificador inclua testes que foram adicionados à versão 1.9 do verificador quando o driver é executado.
VerifyOn
REG_DWORD
Defina como um valor diferente de zero para habilitar a macro WDFVERIFY definida em Wdfassert.h ou defina como zero para desabilitar a macro. Se o valor VerifierOn estiver definido, VerifyOn será definido implicitamente como diferente de zero.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de