Como habilitar a depuração de um driver UMDF

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

• Copie manualmente o driver para o local de 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 diretório de destino e, em seguida, realize a depuração em modo kernel a partir do host.

Recomendamos realizar todos os testes e o desenvolvimento de drivers UMDF com um depurador de kernel ligado.

Melhores Práticas

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

As seguintes configurações são recomendadas. Você pode definir essas configurações manualmente ou usar a ferramenta WDF Verifier Control Application (WDFVerifier.exe) no WDK para exibir ou alterar essas configurações.

• Habilite o Application Verifier em WUDFHost.exe:

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

  Se ocorrerem exceções, o Application Verifier enviará mensagens de diagnóstico para o depurador e interromperá a execução.

• Se estiver a usar uma sessão de depuração de modo núcleo, defina HostFailKdDebugBreak para que o refletor entre no depurador de modo núcleo antes de encerrar o processo de host do driver. Esta definição está ativada por predefinição a partir do Windows 8.

• Desative o agrupamento ao definir 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 Registo para Depuração de Drivers WDF.

• Reinicie o computador.

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

Usando o WinDbg para anexar manualmente (depuração em modo utilizador)

Na máquina de destino, você pode anexar manualmente o WinDbg à instância de WUDFHost que hospeda o driver. Quando você anexa, você invade o depurador e você pode definir pontos de interrupção em seu 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 do host aguarde algum número de segundos na inicialização do host ou no tempo de carregamento do driver. Esse atraso lhe dá tempo para anexar WinDbg à instância correta do processo WUDFHost.

Siga estes passos:

1. No registro no computador de destino, defina HostProcessDbgBreakOnStart ou HostProcessDbgBreakOnDriverLoad para algum número de segundos e reinicialize.
2. No computador de destino, abra o WinDbg como administrador.
3. No menu Arquivo, escolha Anexar ao processo. Selecione pelo Executávele localize todos os processos com o nome WUDFHost.exe (pode não haver nenhum). Se houver algum processo chamado WUDFHost.exe, anote seus identificadores de processo para referência futura.
4. No Gestor de Dispositivos, ative o controlador.
5. Repita a etapa 2 e localize uma nova instância do WUDFHost.exe. Se não vires uma nova instância do WUDFHost.exe, seleciona Cancelar e seleciona Ligar ao Processamento novamente. Quando você encontrar a nova instância do WUDFHost.exe, selecione-a e selecione OK.

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

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

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

Usando o WinDbg para depurar remotamente a partir de uma máquina anfitriã (depuração no modo kernel)

A partir de um host remoto, estabeleça uma sessão de depuração no modo kernel. Em seguida, defina o processo atual para a instância do Wudfhost que hospeda seu driver. Se estiver a depurar a partir de um depurador remoto do kernel, defina a opção HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad como 0x80000000 para especificar nenhum tempo limite, mas para interromper no depurador do kernel.

Use estas etapas:

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

2. HostFailKdDebugBreak está ativado por padrão se o driver usar UMDF 1.11 ou posterior. Ignore esta etapa.

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

3. Se estiver a depurar problemas relacionados com timeouts, desative HostProcessDbgBreakOnDriverStart e HostProcessDbgBreakOnDriverLoad. (Quando HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad é diferente de zero, a estrutura desabilita os tempos limite para que o refletor não encerre o host enquanto um depurador de modo de usuário está anexado ao processo do 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 (quebra na carga do módulo)

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

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