Compartilhar via


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\Diagnostics Registro.
  • Para um driver UMDF, defina esse valor na chave do HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics Registro.

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:

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 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.