Vídeo: Depurando o driver com o código-fonte do WDF

Este tópico contém um tutorial em vídeo que mostra como depurar o driver do WDF (Windows Driver Frameworks) com acesso total ao código-fonte do WDF. Após o vídeo está o procedimento passo a passo seguido no vídeo, para referência conveniente.

A depuração de origem do WDF permite que você explore livremente o código do framework sem precisar baixar o código-fonte do WDF. O depurador baixa automaticamente a versão correta do WDF do GitHub.

Por exemplo, se você estiver usando o WinDbg para depurar seu driver WDF em um computador Windows 10 e o depurador estiver interrompido no código do framework na pilha de chamadas, você poderá clicar duas vezes no frame do WDF na visualização da pilha de chamadas, e o WinDbg baixará automaticamente e abrirá o arquivo de origem do WDF relevante na linha correspondente. Em seguida, você pode percorrer o código e definir pontos de interrupção.

Esse recurso está disponível para sistemas de destino que executam versões públicas do Windows 10, Technical Preview build 10041 ou posterior. Esses builds têm arquivos de símbolo indexados de origem privada para KMDF (Wdf01000.sys) e UMDF (Wudfx02000.dll) disponíveis no Servidor de Símbolos Públicos da Microsoft. A depuração no nível do código-fonte do código WDF só está disponível no WinDbg e não no depurador do Visual Studio.

Início Rápido

Inicie uma sessão de depuração do kernel do WinDbg com a máquina de destino, interrompa a execução e siga os seguintes passos:

1. Defina o caminho de símbolo padrão usando .symfix. Isso define o caminho do símbolo para apontar para o servidor de símbolo em https://msdl.microsoft.com/download/symbols.

   kd> .symfix

2. Defina o caminho de origem padrão usando .srcfix. Isso define o caminho de origem como srv*, que informa ao depurador para recuperar arquivos de origem de locais especificados nos arquivos de símbolo dos módulos de destino.

   kd> .srcfix
   Source search path is: SRV*
   

3. Recarregue os símbolos usando .reload e confirme que os símbolos Wdf01000.sys (ou Wudfx02000.dll para UMDF) são indexados pela origem. Conforme mostrado na saída de !lmi abaixo, o Wdf01000.sys PDB é indexado de origem. Se o seu não estiver, consulte a seção Configuração do WinDbg abaixo.

   kd> .reload
   ...
   
   kd> !lmi wdf01000.sys
   Loaded Module Info: [wdf01000.sys] 
   ...
   Load Report: private symbols & lines, source indexed 
   C:\...\Wdf01000.pdb\...\Wdf01000.pdb
   

4. Está tudo pronto para você! Uma maneira fácil de percorrer o código-fonte do WDF é definir um ponto de interrupção na rotina de expedição IRP da estrutura e, em seguida, percorrer o restante do código. Como um sistema Windows tem muitos drivers KMDF internos, o WDF é sempre carregado e em funcionamento, portanto, esse ponto de interrupção será atingido imediatamente (sem a necessidade de carregar seu próprio driver).

   kd> bp Wdf01000!FxDevice::DispatchWithLock
   kd> g
   Breakpoint 0 hit
   Wdf01000!FxDevice::DispatchWithLock:
   87131670 8bff mov edi,edi 
   

Se isso não funcionar, confira as etapas de Instalação do WinDbg abaixo.

Instalação do WinDbg

Se o exemplo acima não funcionou conforme o esperado, talvez seja necessário executar uma ou mais das instruções abaixo.

Habilitar depuração do modo fonte

Verifique se a depuração no modo de origem está habilitada. Abra o menu Depurar e confirme se o Modo de Origem está marcado.

Limpar cache de símbolos obsoletos

Se você depurou anteriormente drivers WDF para o mesmo destino do Windows, talvez esteja usando os símbolos WDF armazenados em cache localmente que não foram indexados de origem. Você pode verificar isso com o comando !lmi:

kd> !lmi Wdf01000.sys
Loaded Module Info: [wdf01000.sys]
...
Load Report: private symbols & lines, not source indexed
C:\...\Wdf01000.pdb\...\Wdf01000.pdb

De acordo com o Relatório de Carga acima, wdf01000.pdb não é indexado na fonte. Isso significa que o cache de símbolos WinDbg local está obsoleto. Para corrigir isso, descarregue o PDB do WinDbg, limpe o cache local (seu caminho pode diferir conforme a saída do comando !lmi acima) e recarregue o PDB:

kd> .reload /u Wdf01000.sys

CMD> del
C:\...\Wdf01000.pdb\...\Wdf01000.pdb

kd> .reload Wdf01000.sys

Agora, execute !lmi para verificar novamente: o PDB deve aparecer como indexado pela origem e uma janela de código-fonte deve aparecer.

kd> !lmi Wdf01000.sys
Loaded Module Info: [wdf01000.sys]
...
Load Report: private symbols & lines, source indexed
C:\...\Wdf01000.pdb\...\Wdf01000.pdb 

Você pode usar a depuração no nível do código-fonte do WDF não apenas para depuração dinâmica e análise de despejos de memória, mas também para saber mais sobre os internos da estrutura definindo pontos de interrupção em funções principais como o dispatcher IRP e explorando os caminhos de código subsequentes.