Usando o rastreamento de software WPP em drivers UMDF

  • Artigo

O rastreamento de software do WPP permite adicionar mensagens de rastreamento que ajudam você a depurar seu driver. Além disso, o agente de eventos da estrutura fornece centenas de mensagens de rastreamento que você pode exibir.

Você pode exibir mensagens de rastreamento usando TraceView ou Tracelog. Você também pode enviar mensagens de rastreamento para um depurador de kernel.

Adicionando mensagens de rastreamento ao seu driver

Para adicionar mensagens de rastreamento ao driver baseado em estrutura, você deve:

  • Adicione uma diretiva #include a cada um dos arquivos de origem do driver que contém qualquer uma das macros do WPP. Essa diretiva deve identificar um arquivo TMH (cabeçalho de mensagem de rastreamento). O nome do arquivo deve ter um formato de <driver-source-file-name.tmh>.

    Por exemplo, se o driver consistir em dois arquivos de origem, chamados MyDriver1.c e MyDriver2.c, o MyDriver1.c deverá conter:

    #include "MyDriver1.tmh"

    e MyDriver2.c devem conter:

    #include "MyDriver2.tmh"

    Quando você cria o driver no Microsoft Visual Studio, o pré-processador WPP gera os arquivos .tmh.

  • Defina uma macro WPP_CONTROL_GUIDS em um arquivo de cabeçalho. Essa macro define um GUID e sinalizadores de rastreamento para as mensagens de rastreamento do driver. (Para cada um dos drivers de exemplo baseados em UMDF do WDK, o arquivo de cabeçalho Internal.h inclui essa macro.)

  • Inclua uma macro WPP_INIT_TRACING na rotina DllMain do driver. Essa macro ativa o rastreamento de software no driver. (Para cada um dos drivers de exemplo baseados em UMDF do WDK, o arquivo de cabeçalho DllSup.h inclui essa macro.)

  • Inclua uma macro WPP_CLEANUP na rotina DllMain do driver. Essa macro desativa o rastreamento de software em seu driver. (Para cada um dos drivers de exemplo baseados em UMDF do WDK, o arquivo de cabeçalho DllSup.h inclui essa macro.)

  • Use a macro DoTraceMessage ou uma versão personalizada da macro no driver para criar mensagens de rastreamento. (Para cada um dos drivers de exemplo baseados em UMDF do WDK, o arquivo de cabeçalho Internal.h inclui uma macro personalizada.)

  • Abra as Páginas de Propriedades para seu projeto de driver. Clique com o botão direito do mouse no projeto do driver no Gerenciador de Soluções e selecione Propriedades. Nas Páginas de Propriedades do driver, selecione Propriedades de Configuração e Wpp. No menu Geral , defina Executar Rastreamento WPP como Sim. No menu Opções de Arquivo , você também deve especificar o arquivo de modelo WPP da estrutura, por exemplo:

    {km-WdfDefault.tpl}*.tmh

Para obter mais informações sobre como adicionar mensagens de rastreamento ao driver, consulte Adicionando macros WPP a um driver.

Drivers de exemplo que usam rastreamento de software WPP

Todos os drivers de exemplo baseados em UMDF no WDK fornecem arquivos DllSup.h, Internal.h e Sources que habilitam o rastreamento de software WPP. A maioria desses drivers de exemplo também usa uma macro personalizada para criar mensagens de rastreamento.

Exibindo mensagens de rastreamento do driver

Se você adicionou mensagens de rastreamento ao driver, o driver é um provedor de rastreamento. Você pode usar um controlador de rastreamento, como Tracelog, para controlar uma sessão de rastreamento e criar um log de rastreamento. Você pode usar um consumidor de rastreamento, como Tracefmt, para exibir as mensagens.

Para obter mais informações sobre como usar as ferramentas de rastreamento de software, consulte Pesquisa de ferramentas de rastreamento de software.

Exibindo o log de rastreamento umdf

O arquivo de log UMDF está localizado em %ProgramData%*\\Microsoft\\WDF.

Você pode exibir o arquivo de log UMDF usando TraceView ou Tracelog. Ambas as ferramentas exigem arquivos TMF (formato de mensagem de rastreamento) que formatam as mensagens do log de rastreamento. Os arquivos TMF estão disponíveis no WDK, no subdiretório \tools\tracing. (Em TraceView, o UMDF aparece como um provedor nomeado com o nome de "Rastreamento do UMDF-Framework" ou "Rastreamento de Estrutura", dependendo da versão do UMDF.)

O Verificador do WDF permite que você envie mensagens de rastreamento para o log de rastreamento do UMDF e o depurador de kernel. (Você não deve enviar mensagens de rastreamento para o depurador de kernel usando a opção -kd no Tracelog, pois o Tracelog pode interromper o log de rastreamento no UMDF.)

Você também pode usar a extensão de depurador !wmitrace para exibir as mensagens de rastreamento no depurador:

  1. No WinDbg, anexe à instância do WUDFHost que hospeda o driver. Para obter mais informações, confira Como habilitar a depuração de um driver UMDF.

  2. Se o driver usar a versão 1.11 ou posterior e você estiver usando o depurador de kernel de Windows 8 ou posterior, você poderá ignorar esta etapa. Se o driver usar uma versão do UMDF anterior à 1.11, use !wmitrace.tmffile ou !wmitrace.searchpath 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.

  3. Use o comando !wmitrace.logdump para exibir o conteúdo dos buffers de rastreamento:

    !wmitrace.logdump WudfTrace

Controlando mensagens de rastreamento

Você pode controlar mensagens de rastreamento umdf com a interface do usuário que o Verificador WDF fornece ou modificando valores do Registro. Você deve usar a interface verificador do WDF quando possível, pois os valores do Registro podem ser alterados em versões futuras do UMDF. Além disso, você não deve acessar esses valores em arquivos INF ou no código do driver.

Atualmente, você pode modificar os seguintes valores do Registro, que estão localizados na chave do registro HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF:

  • O valor LogEnable controla se o UMDF cria um log de rastreamento para o driver. Se esse valor for definido como 1, o UMDF criará um log de rastreamento.

  • O valor LogLevel controla a quantidade de informações que as mensagens de rastreamento UMDF contêm. O valor padrão para LogLevel é 3, o que faz com que as mensagens de rastreamento UMDF contenham mensagens de erro e aviso. Defina esse valor como 7 para incluir mensagens de erro e aviso, além de mensagens informativas sem erro. Defina-o como 15 para incluir todas as informações de rastreamento que o UMDF é capaz de fornecer.

  • O valor do LogKd controla se o UMDF envia mensagens de rastreamento para o depurador de kernel. Se o LogKd estiver definido como 1, o UMDF enviará suas mensagens de rastreamento para o depurador de kernel.

  • O valor LogFlushPeriodSeconds especifica com que frequência, em segundos, as mensagens de rastreamento são gravadas no log de rastreamento.

  • O valor LogMinidumpType contém sinalizadores que especificam o tipo de informação que um arquivo de mini-despejo, se produzido, conterá. Para obter mais informações sobre esses sinalizadores, consulte a enumeração MINIDUMP_TYPE .

Você pode encontrar mais valores do Registro na chave do Registro HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF. Você não deve modificar esses valores.