Compartilhar via

Como habilitar a depuração de um driver UMDF

  • Artigo

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ê anexa manualmente a uma instância do processo de host do driver em execução no destino.
  • Copie manualmente o driver para o destino e execute a depuração no modo kernel do host.

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

Práticas recomendadas

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

Veja a seguir as configurações recomendadas. Você pode defini-los manualmente ou usar a ferramenta aplicativo de controle 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 interromperá.

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

  • Desabilite o pooling definindo UmdfHostProcessSharing como ProcessSharingDisabled. Para obter informações, consulte Especificando diretivas 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 obter mais informações, consulte Valores do Registro para depurar drivers WDF.

  • Reinicie o computador.

  • Para depurar problemas de driver UMDF, examine Determinando por que o refletor encerrou o processo de host e depurando falhas do driver UMDF

Usando o WinDbg para anexar manualmente (depuração no modo de 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 pontos de interrupção no driver.

Como a inicialização do driver ocorre logo após o carregamento do WUDFHost, não é viável anexar manualmente a tempo de depurar o código de inicialização. Em vez disso, você pode definir 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 dá tempo 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 WinDbg como Administrador.
  3. No menu Arquivo , escolha Anexar ao Processo. Selecione Por Executável e localize todos os processos nomeados WUDFHost.exe (pode não haver nenhum). Se houver processos chamados WUDFHost.exe, anote seus identificadores de processo para referência futura.
  4. Em Gerenciador de Dispositivos, habilite o driver.
  5. Repita a etapa 2 e localize uma nova instância do WUDFHost.exe. Se você não vir uma nova instância do WUDFHost.exe, clique em Cancelar e escolha Anexar ao Processo novamente. Quando encontrar a nova instância do WUDFHost.exe, selecione-a e clique em OK.

Se o pool de dispositivos estiver em uso e você definir o valor do registro HostProcessDbgBreakOnDriverLoad , poderá ver quebras de 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 UMDF, consulte Valores do Registro para depuração de drivers WDF (KMDF e UMDF).

Usando o WinDbg para depurar remotamente de um computador host (depuração no modo kernel)

Em um host remoto, estabeleça uma sessão de depuração no modo kernel e defina o processo atual para a instância do Wudfhost que hospeda o driver. Se você estiver depurando de um depurador de kernel remoto, poderá definir HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad como 0x80000000 para não especificar tempo limite, mas invadir o depurador de kernel.

Siga estas etapas:

  1. Desabilitar 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 tempos limite, desative HostProcessDbgBreakOnDriverStart e HostProcessDbgBreakOnDriverLoad. (Quando HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad não é zero, a estrutura desabilita tempos limite para que o refletor não termine 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 seja carregado: sxe ld:MyDriver.dll (interromper a carga do módulo)

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

  5. Dependendo das seleções feitas acima, o depurador de kernel remoto deve entrar quando o driver carregar ou descarregar no destino.