IFR (Inflight Trace Recorder) para registro em log de rastreamentos

Artigo
06/15/2023

O IFR (Gravador de Rastreamento inflight) é 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 em que as mensagens de log mais recentes são preservadas. As mensagens de log podem ser exibidas usando um depurador.

O IFR é criado com base no 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 driver KMDF e WDM
Sistema operacional mínimo: Windows 10 para desenvolvedores de driver UMDF (2.15)

Como habilitar o Inflight Trace Recorder no Visual Studio

Primeiro, siga as etapas em Adicionando rastreamento de software WPP a um Driver do Windows.

Em seguida, na página de propriedades Projeto, em Propriedades de Configuração-WPP> Tracing-Function e Opções de> Macro-Habilitar> Gravador de Rastreamento de Simulação, selecione Sim.

Por fim, somente para UMDF, há uma etapa adicional: em WPP Tracing-Function> e Macro Options-Preprocessor> Definitions, adicione WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Como habilitar o Inflight Trace Recorder na 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 parâmetros do Inflight Trace Recorder

Você pode configurar o IFR definindo as seguintes entradas opcionais do Registro na chave de parâmetro do driver.

Use as seguintes entradas do Registro:

LogPages: REG_DWORD

Defina como 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 como um para adicionar uma saída detalhada ao log.

WppRecorder_UseTimeStamp: REG_DWORD (disponível a partir do WDK build 22557)

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

WppRecorder_PreciseTimeStamp: REG_DWORD (disponível a partir do WDK build 22557)

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 inicial e final para definir o número de páginas de log como dois e ativar carimbos de data/hora.

Para um driver no 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 está livre para 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 no modo kernel (KMDF ou WDM).

Para a maioria dos drivers, o log padrão único é 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 ônibus, talvez você queira que cada dispositivo filho tenha seu próprio buffer. Em seguida, você pode usar o depurador para despejar somente o log de um dispositivo filho específico.

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

WppRecorderLogCreate para criar mais de um buffer de log
WppRecorderLogDelete antes de chamar WPP_CLEANUP.
WppRecorderLogSetIdentifier para definir um identificador de cadeia de caracteres para um log de gravador especificado (opcional)
WppRecorderConfigure para desabilitar o log padrão (opcional)

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 da Torradeira.

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

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

Para fazer isso, você precisa adicionar uma única linha ao código do driver para cada identificador de log que deve usar carimbos de data/hora. 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 versões diferentes do Windows.

Como exibir mensagens de rastreamento no depurador

Para drivers KMDF e UMDF, use !wdfkd.wdflogdump como de costume. Ele imprimirá o log IFR da estrutura e o log IFR do driver.

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

Compartilhar via