Usando o Agente de Eventos da Estrutura

  • Artigo

O WDF inclui um agente de rastreamento interno, às vezes chamado de IFR ( Gravador de Voo ) da estrutura. O agente do WDF cria um log de rastreamento que contém um histórico recente de eventos para cada driver WDF. Os logs de rastreamento acompanham o progresso dos IRPs (pacotes de solicitação de E/S) por meio da estrutura e das solicitações correspondentes por meio de um driver. Cada driver KMDF (Kernel-Mode Driver Framework) e UMDF (User-Mode Driver Framework) tem seu próprio log.

O agente do WDF está sempre habilitado. Para cada log de rastreamento, o agente armazena registros de eventos em um buffer de memória circular. Opcionalmente, você pode ativar o detalhamento, o que faz com que o agente de eventos registre informações adicionais que podem ajudá-lo a depurar seu driver, como entradas em ou saídas de caminhos de código internos. Por padrão, o tamanho do buffer é uma página de memória e o detalhamento é desativado. Você pode alterar o tamanho e o detalhamento do buffer ajustando esses valores no aplicativo WdfVerifier. Observe que ativar o detalhamento pode prejudicar o desempenho do sistema.

Você pode usar extensões do depurador WDF para exibir e salvar o log do WDF durante a depuração interativa. Para exibir o log do WDF durante uma sessão de depuração:

  1. Carregue os símbolos corretos. Você pode usar o comando de depurador .symfix+ para acrescentar o repositório de símbolos públicos da Microsoft ao caminho do símbolo existente. O repositório de símbolos público inclui símbolos para os binários do WDF. Talvez você também queira carregar símbolos para seus símbolos de driver.

    Para obter informações adicionais sobre como obter símbolos de Janela e como definir o caminho do símbolo do depurador, consulte a documentação fornecida com o pacote de Depuração do Windows .

  2. Carregue a biblioteca de extensõesWdfkd.dll no depurador. Se você estiver usando o depurador de kernel, poderá fazer isso usando o comando .load . Para carregar a versão correta do Wdfkd.dll você precisa especificar o caminho totalmente qualificado para a DLL. Por exemplo, você usaria o seguinte caminho em um computador host do depurador baseado em x86:

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    Em seguida, você pode confirmar se a extensão é carregada usando o comando !chain para exibir todas as extensões carregadas.

    Para obter mais informações sobre a extensão do depurador de estrutura, use a extensão !wdfhelp . Para obter mais informações sobre o depurador de kernel, consulte a documentação fornecida com o pacote de Depuração do Windows .

  3. Se o driver usar a versão 1.11 ou posterior da estrutura e você estiver usando o depurador de kernel do Windows 8 ou posterior, ignore esta etapa.

    Se o driver usar uma versão de estrutura anterior à 1.11, use !wdftmffile ou !wdfsearchpath para especificar um arquivo de formato de mensagem de rastreamento específico da plataforma (.tmf) ou um caminho para um arquivo .tmf. Os arquivos .tmf estão localizados em subdiretórios específicos da plataforma no WDK.

    Como os arquivos .tmf são específicos da versão, você deve especificar um arquivo .tmf que corresponda à versão da biblioteca de runtime da estrutura que está em execução no momento. Por exemplo, se o KMDF versão 1.9 estiver em execução no computador host:

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    Você também pode definir o caminho de pesquisa definindo a variável de ambiente TRACE_FORMAT_SEARCH_PATH. O comando !wdftmffile tem precedência sobre o caminho de pesquisa definido pela variável de ambiente.

    Para verificar o número de versão da estrutura, você pode executar o comando de extensão do depurador !wdfldr no depurador do kernel.

  4. Use a extensão !wdflogdump para exibir os registros do agente de eventos. Por exemplo, a captura de tela a seguir de uma janela comando WinDbg mostra um exemplo típico da saída de !wdflogdump:

    Captura de tela da saída da extensão !wdflogdump na janela Comando winDbg.

Cada linha no log da estrutura é precedida por uma cadeia de caracteres chamada prefixo de mensagem de rastreamento. O agente de rastreamento anexa esse prefixo a cada mensagem gravada no log. Por padrão, o prefixo inclui um conjunto padrão de elementos de dados, mas você pode alterar os elementos padrão para atender aos seus requisitos específicos. Você pode alterar a cadeia de caracteres de prefixo para um driver WDF definindo a variável de ambiente TRACE_FORMAT_PREFIX ou usando o comando de extensão do depurador !wdfsettraceprefix .

Para definir a variável de ambiente, use um comando semelhante ao seguinte:

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

Esse comando define o prefixo da mensagem de rastreamento para o seguinte:

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

Você também pode usar o comando de extensão !wdflogsave para salvar os registros do agente de eventos em um arquivo de log de rastreamento de eventos (.etl) que você pode exibir usando TraceView.

Às vezes, você pode usar a extensão do depurador !wdfcrashdump em um despejo de memória para exibir informações de log após as verificações de bug do sistema. As informações de log só estão disponíveis no despejo de memória se a estrutura puder determinar que o driver causou o bug marcar ou se você definiu o valor do registro ForceLogsInMiniDump para o driver.

Se um depurador estiver anexado quando o bug marcar ocorrer, você poderá usar !wdfcrashdump para exibir as informações de log imediatamente ou pode exibir as informações carregando o arquivo de despejo de memória. Devido às limitações de tamanho de um pequeno arquivo de despejo de memória, o log do driver que causou a falha pode não aparecer no despejo.

A estrutura pode determinar se um driver específico causou o seguinte bug marcar códigos:

A partir da versão 2 do UMDF, o UMDF armazena o log de rastreamento UMDF (ou UMDF IFR) na memória não paginada do kernel. A estrutura aloca uma instância ifr por host de driver (Wudfhost).

Para obter mais informações sobre os comandos de extensão do depurador, consulte Extensões do depurador para drivers baseados em estrutura.