Partilhar via

Gravador de rastreio a bordo (IFR) para registo de vestígios

O Inflight Trace Recorder (IFR) é um recurso de rastreamento que permite que um provedor de rastreamento, como um driver de modo kernel ou um driver UMDF, crie um conjunto de buffers circulares na memória onde as mensagens de log mais recentes são preservadas. As mensagens de log podem ser visualizadas usando um depurador.

IFR é construído sobre o rastreamento de software WPP. O principal benefício do IFR sobre o WPP é que ele é ativado automaticamente e você não precisa iniciar sessões de rastreamento com antecedência.

Aplica-se a:

  • Sistema operacional mínimo: Windows 8 para desenvolvedores de drivers KMDF e WDM
  • SO mínimo: Windows 10 para desenvolvedores de drivers UMDF (2.15)

Como habilitar o gravador de rastreamento de bordo no Visual Studio

Primeiro, siga as etapas em Adicionando rastreio de software WPP a um driver no Windows.

Em seguida, na página de propriedades do projeto, em Propriedades de Configuração-Rastreamento WPP-Opções de Função e Macro-Habilitar Gravador de Rastreamento em Voo, selecione Sim.

Finalmente, apenas para UMDF, há uma etapa adicional: em WPP Tracing->Function and Macro Options->Preprocessor Definitions, adicione WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Como ativar o Inflight Trace Recorder a partir da linha de comando

Se você editar o arquivo .vcxproj manualmente, defina as seguintes entradas:

Para um driver KMDF ou WDM:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

Para um driver UMDF:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Como configurar os parâmetros do Inflight Trace Recorder

Você pode configurar o IFR definindo as seguintes entradas opcionais de registo na chave Parameter do driver.

Utilize as seguintes entradas dos Registos:

LogPages: REG_DWORD

Defina o número de páginas para armazenar o log padrão. O padrão é um.

VerboseOn: REG_DWORD

A configuração padrão de zero faz com que o IFR registre erros, avisos e eventos informativos. Defina para um para adicionar saída detalhada ao log.

WppRecorder_UseTimeStamp: REG_DWORD (disponível a partir da compilação 22557 do WDK)

Os drivers definem essa entrada como uma para adicionar carimbos de data/hora às entradas de log que podem ser visualizadas usando !rcdrkd.rcdrlogdump ou !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (disponível a partir da compilação 22557 do WDK)

Se você quiser carimbos de data/hora mais precisos, além de WppRecorder_UseTimeStamp, adicione WppRecorder_PreciseTimeStamp usando a mesma sintaxe mostrada acima.

Exemplos

Nos exemplos a seguir, adicione as linhas entre os comentários iniciais e finais para definir o número de páginas de log como duas e ativar os carimbos de data/hora.

Para um driver de modo kernel:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

Para um driver UMDF:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

Como enviar mensagens de rastreamento para o log padrão

Siga as instruções em Adicionando rastreamento de software WPP a um driver do Windows. Por exemplo:

  • Em DriverEntry, chame WPP_INIT_TRACING(DriverObject, RegistryPath).
  • Em EvtDriverUnload, chame WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Agora, o driver pode chamar a função de rastreamento conforme necessário. Por exemplo: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Para obter mais informações, consulte WPP_INIT_TRACING e WPP_CLEANUP.

Como enviar mensagens de rastreamento para um log personalizado

Isso só se aplica a drivers de modo kernel (KMDF ou WDM).

Para a maioria dos drivers, o único log padrão é bom o suficiente. No entanto, em alguns cenários, é útil ter buffers de log separados para entidades distintas.

Por exemplo, ao escrever um driver de barramento, você pode querer que cada dispositivo filho tenha seu próprio buffer. Em seguida, pode utilizar o depurador para exportar apenas o registo de um dispositivo filho específico.

Para configurar logs personalizados, o driver deve incluir <WppRecorder.h>. Em seguida, chame as seguintes APIs:

O driver também precisa definir uma nova macro de rastreamento que usa o identificador de log como o primeiro parâmetro. Para obter um exemplo, consulte o Driver de Exemplo Toaster.

Como adicionar informações de carimbo de data/hora a um log personalizado

Se o driver chamar WppRecorderLogCreate para criar identificadores de log adicionais, é possível habilitar carimbos de data/hora para alguns identificadores de log, mas não para outros.

Para fazer isso, é necessário adicionar uma única linha ao código do driver para cada identificador de log que deve usar time stamps. Para obter um exemplo de código, consulte WppRecorderLogCreate.

Observação

Essa funcionalidade está disponível a partir do WDK build 22557. Para obter informações sobre como direcionar uma versão específica, consulte Criando drivers para diferentes versões do Windows.

Como exibir mensagens de rastreamento no depurador

Para controladores KMDF e UMDF, utilize !wdfkd.wdflogdump como de costume. Ele imprimirá tanto o log IFR do framework quanto o log IFR do driver.

Para os drivers WDM, use !rcdrkd.rcdrloglist e !rcdrkd.rcdrlogdump.

  • Last updated on