Como habilitar a depuração de um driver UMDF

Você pode usar as configurações a seguir para depurar um driver do UMDF (User-Mode Driver Framework) durante o desenvolvimento. Todas as configurações envolvem dois computadores, um host e um destino.

• Copie manualmente o driver para o destino. Execute a depuração no modo de usuário no destino. Nesse cenário, você se associa manualmente a uma instância do processo de host do driver em execução no destino.
• Copie manualmente o driver para o destino e realize a depuração em modo kernel a partir do host.

Recomendamos fazer todo o teste e desenvolvimento de driver UMDF com um depurador de kernel anexado.

Práticas recomendadas

Recomendamos fazer todos os testes de driver UMDF com um depurador de kernel conectado.

As configurações a seguir são recomendadas. Você pode definir essas configurações manualmente ou usar a ferramenta Aplicativo de Controle do Verificador do WDF (WDFVerifier.exe) no WDK para exibir ou alterar essas configurações.

• Habilitar o Verificador de Aplicativos no WUDFHost.exe:

  AppVerif –enable Heaps Exceptions Handles Locks Memory TLS Leak –for WudfHost.exe
  

  Se ocorrerem exceções, o Verificador de Aplicativos enviará mensagens de diagnóstico para o depurador e causará uma interrupção.

• Se você estiver usando uma sessão de depuração em modo kernel, defina HostFailKdDebugBreak para que o refletor interrompa o depurador em modo kernel antes de encerrar o processo de host do driver. Essa configuração é habilitada por padrão a partir do Windows 8.

• Desabilite o pool definindo UmdfHostProcessSharing como ProcessSharingDisabled. Para obter informações, consulte Especificando diretivas do WDF em arquivos INF.

• Por padrão, quando um dispositivo UMDF falha, a estrutura tenta reiniciá-lo até cinco vezes. Você pode desativar a reinicialização automática definindo DebugModeFlags como 0x01. Para mais informações, consulte Valores do Registro para Depuração de Drivers WDF.

• Reinicialize o computador.

• Para depurar problemas de driver UMDF, examine Determinando o motivo pelo qual o refletor encerrou o processo do host e Depurar falhas de driver UMDF

Usando o WinDbg para anexar manualmente (depuração em modo usuário)

No computador de destino, você pode anexar manualmente o WinDbg à instância do WUDFHost que hospeda o driver. Ao anexar, você entra no depurador e pode definir breakpoints no driver.

Como a inicialização do driver ocorre logo após o carregamento do WUDFHost, você não pode anexar manualmente a tempo de depurar o código de inicialização. Em vez disso, defina um valor do Registro para fazer com que o processo de host aguarde alguns segundos na inicialização do host ou no tempo de carregamento do driver. Esse atraso lhe dá tempo suficiente para anexar o WinDbg à instância correta do processo WUDFHost.

Siga estas etapas:

1. No registro no computador de destino, defina HostProcessDbgBreakOnStart ou HostProcessDbgBreakOnDriverLoad como alguns segundos e reinicialize.
2. No computador de destino, abra o WinDbg como Administrador.
3. No menu Arquivo , escolha Anexar ao Processo. Selecione Por Executável e localize todos os processos cujo nome é WUDFHost.exe (talvez nenhum esteja presente). Se houver processos nomeados WUDFHost.exe, anote seus identificadores de processo para referência futura.
4. No Gerenciador de Dispositivos, habilite o driver do dispositivo.
5. Repita a etapa 2 e localize uma nova instância de WUDFHost.exe. Se você não vir uma nova instância de WUDFHost.exe, selecione Cancelar e escolha Anexar ao Processo novamente. Quando encontrar a nova instância do WUDFHost.exe, selecione-a e selecione OK.

Se pool de dispositivos estiver em uso e você definir o valor do registro HostProcessDbgBreakOnDriverLoad, poderá ver interrupções do depurador devido ao carregamento de outros drivers. Você pode desativar o pool de dispositivos usando o modo de depuração UMDF.

Para usar o modo de depuração, use a opção F5 no Visual Studio ou defina os valores DebugModeFlags e DebugModeBinaries no registro.

Para obter informações detalhadas sobre valores de registro do UMDF, consulte Valores do Registro para depuração de drivers WDF (KMDF e UMDF).

Usando o WinDbg para depurar remotamente de uma máquina host (depuração em modo kernel)

Em um host remoto, estabeleça uma sessão de depuração em modo kernel. Em seguida, defina o processo atual para a instância do Wudfhost que hospeda seu driver. Se você estiver depurando com um depurador de kernel remoto, configure HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad para 0x80000000 para não haver tempo limite, mas entrar no depurador de kernel.

Use estas etapas:

1. Desabilite o pooling. Ative DebugModeFlags e liste seu driver em DebugModeBinaries.

2. Se o driver usar UMDF 1.11 ou posterior, HostFailKdDebugBreak será habilitado por padrão. Ignore esta etapa.

   Se o driver usar UMDF 1.9 ou anterior, defina HostFailKdDebugBreak como 1.

3. Se você estiver depurando problemas relacionados a timeouts, desative HostProcessDbgBreakOnDriverStart e HostProcessDbgBreakOnDriverLoad. (Quando HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad não é zero, a estrutura desabilita tempos limite para que o refletor não encerre o host enquanto um depurador do modo de usuário estiver anexado ao processo de host.) Se você precisar depurar o código de inicialização do driver, em vez de usar esses dois valores, tente emitir o seguinte comando no WinDbg antes que o driver carregue: sxe ld:MyDriver.dll (interromper a carga do módulo)

4. Reinicialize se você fez alterações no Registro.

5. Dependendo das seleções feitas nas etapas anteriores, o depurador de kernel remoto é interrompido quando o driver carrega ou descarrega no destino.