Partilhar via


Usando o IFR (Inflight Trace Recorder) em drivers KMDF e UMDF 2

A partir do Windows 10, você pode criar seu driver KMDF ou UMDF para que ele obtenha informações extras de depuração de driver por meio do pré-processamento de rastreamento de software Windows. Esse recurso, chamado de IFR (Inflight Trace Recorder), está disponível a partir do KMDF versão 1.15 e do UMDF versão 2.15.

O Inflight Trace Recorder é uma extensão do rastreamento de software WPP. Ao contrário do rastreamento WPP, o Inflight Trace Recorder continua funcionando sem um consumidor de rastreamento anexado. A estrutura grava mensagens em um buffer circular e o driver também pode adicionar suas próprias mensagens. Cada driver tem seu próprio log, portanto, vários dispositivos associados a um driver compartilham um único log.

Se você ativar o IFR no binário do driver, o IFR estará presente e em execução durante o tempo de vida do driver. Você não precisa iniciar uma sessão de coleta de rastreamento explícita.

Os logs são armazenados em memória não paginável, portanto, podem ser recuperados após uma falha do sistema. Além disso, os logs do Gravador de Rastreamento em Andamento são incluídos em arquivos de minidespejo, exceto quando o driver responsável é indeterminado ou se a falha foi um tempo limite do host.

Como ativar o Inflight Trace Recorder e enviar mensagens do seu motorista

  1. No Microsoft Visual Studio, execute as seguintes etapas:

    • Abra as Páginas de Propriedades do seu projeto de driver. Clique com o botão direito do mouse no projeto de driver no Gerenciador de Soluções e selecione Propriedades. Nas Páginas de Propriedades do driver, selecione Propriedades de Configuração e, em seguida , Rastreamento Wpp. No menu Geral , defina Executar Rastreamento WPP como Sim.

    • Navegue até Propriedades-Função> de rastreamento> WPP e Opções de macro e escolha Ativar gravador WPP.

    • No mesmo menu, defina Verificar Dados de Configuração para o arquivo que contém suas informações de rastreamento, por exemplo, Trace.h.

  2. Em cada arquivo de origem que chama uma macro WPP, adicione uma diretiva #include que identifica 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, MyDriver1.c deverá conter:

    #include "MyDriver1.tmh"

    e MyDriver2.c deve conter:

    #include "MyDriver2.tmh"

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

  3. 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.

    O exemplo de driver Osrusbfx2 define um único GUID de controle e sete sinalizadores de rastreamento no arquivo de cabeçalho Trace.h, conforme mostrado no exemplo a seguir:

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \
      (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
      WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
      WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
      WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
      WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
      WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
      WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
      WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
      WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
    )
    

    Neste exemplo:

    • OsrUsbFxTraceGuid é o nome amigável para o GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
    • Os sinalizadores de rastreamento são usados para diferenciar entre mensagens de rastreamento geradas à medida que o driver lida com diferentes tipos de solicitações de E/S.
  4. Seu driver (KMDF e UMDF 2) deve chamar WPP_INIT_TRACING para Drivers no Modo Kernel com o objeto de driver e um caminho do Registro, normalmente de DriverEntry:

    WPP_INIT_TRACING( DriverObject, RegistryPath );
    

    Para desativar o rastreamento, os drivers KMDF e UMDF 2 chamam WPP_CLEANUP para drivers no modo kernel de EvtCleanupCallback ou EvtDriverUnload:

    WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
    

    A macro WPP_CLEANUP usa um parâmetro do tipo PDRIVER_OBJECT, portanto, se o DriverEntry do driver falhar, você poderá ignorar a chamada WdfDriverWdmGetDriverObject e, em vez disso, chamá WPP_CLEANUP com um ponteiro para o objeto de driver WDM.

    Como os drivers UMDF usam as assinaturas do modo kernel dessas macros para inicializar e limpar o rastreamento, as chamadas parecem idênticas para KMDF e UMDF.

  5. Use a macro DoTraceMessage ou uma versão personalizada da macro no driver para criar mensagens de rastreamento.

    O exemplo a seguir mostra como o driver Osrusbfx2 usa sua função TraceEvents em uma parte do código dedicada ao tratamento de solicitações de leitura:

    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        TraceEvents(TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Transfer exceeds %d\n",
                    TEST_BOARD_TRANSFER_BUFFER_SIZE);
    
        status = STATUS_INVALID_PARAMETER;
    }
    

    A chamada para TraceEvents gerará uma mensagem de rastreamento se o controlador de rastreamento habilitar o nível de TRACE_LEVEL_ERROR e o sinalizador de rastreamento DBG_READ . A mensagem inclui o valor da constante definida pelo driver TEST_BOARD_TRANSFER_BUFFER_SIZE.

  6. Para alterar o tamanho do buffer circular que o log do driver usa, modifique o valor do Registro LogPages no seguinte local do Registro:

    Para UMDF:

    SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf

    Para KMDF:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<YourDriver>\Parameters\Wdf

    Esse é um valor do tipo REG_DWORD que contém o tamanho do buffer de log alocado em páginas. Os valores válidos estão entre 0x1 e 0x10.

Para um driver KMDF

  1. Carregue os comandos RCDRKD digitando .load rcdrkd.dll no depurador.
  2. Use a extensão !wdfkd.wdfldr para exibir informações sobre o driver que está atualmente associado dinamicamente ao WDF (Windows Driver Frameworks).
  3. Use !rcdrkd.rcdrlogdump e !rcdrkd.rcdrcrashdump para exibir as mensagens fornecidas pelo driver.
  4. Use !wdfkd.wdflogdump ou !wdfkd.wdfcrashdump para ver as mensagens que a estrutura fornece.

Depuração ao vivo de um driver UMDF

  1. Use a extensão !wdfkd.wdfldr para exibir informações sobre os drivers que estão associados dinamicamente ao WDF no momento. Encontre o driver do modo de usuário. Insira o processo de host associado.

  2. Digite !wdfkd.wdflogdump< YourDriverName.dll><Sinalizador> , em que< Sinalizador> é:

    • 0x1 – Estrutura mesclada e logs de driver
    • 0x2 – Logs do driver
    • 0x3 – Logs da estrutura

    Se não houver nenhum log de driver para o driver especificado, a extensão exibirá apenas o log da estrutura.

Exibindo logs do Gravador de Rastreamento em Andamento após uma falha do driver UMDF

  1. No WinDbg, selecione Despejo de Memória de Abertura de> Arquivo e especifique o arquivo de minidespejo que você gostaria de depurar.

  2. Digite !wdfkd.wdfcrashdump <YourDriverName.dll<>ID do processo da opção> host do driver><, em que <a opção> é:

    • 0x1 – Estrutura mesclada e logs de driver
    • 0x2 – Logs do driver
    • 0x3 – Logs da estrutura

    Se você não especificar um driver, !wdfcrashdump exibirá informações para todos os drivers. Se você não especificar um processo de host e houver apenas um, a extensão usará o processo de host único. Se você não especificar um processo de host e houver mais de um, a extensão listará os processos de host ativos.

    Se as informações de log armazenadas no minidespejo não corresponderem ao nome inserido, o minidespejo não conterá os logs do driver.

Se você não tiver um depurador conectado, ainda poderá acessar os logs do driver e da estrutura. Para saber como, consulte Vídeo: Acessando logs IFR do driver sem um depurador.

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

Como habilitar a depuração de um driver UMDF

Extensões RCDRKD

Usando o Registrador de Eventos da Estrutura

Usando o rastreamento de software WPP em drivers UMDF