Inflight Trace Recorder (IFR) para registro de rastreamentos

O IFR (Gravador de Rastreamento de Inflight) é um recurso de rastreamento que permite que um provedor de rastreamento, como um driver no modo kernel ou um driver UMDF, crie um conjunto de buffers circulares na memória em que as mensagens de log mais recentes sejam 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 em relação ao 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 drivers UMDF (2.15)

Como habilitar o Inflight Trace Recorder no Visual Studio

Primeiro, siga as etapas em Adicionar Rastreamento de Software WPP a um driver do 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.

Por fim, somente para UMDF, há uma etapa adicional: em WPP Tracing->Função e Opções de Macro->Definições de Pré-processador, 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 os parâmetros do Gravador de Rastreamento Inflight

Você pode configurar o IFR definindo as seguintes entradas opcionais do registro na Chave Parâmetro do driver.

Use as seguintes entradas do Registro:

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

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

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

WppRecorder_PreciseTimeStamp: REG_DWORD (disponível a partir do build 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 de início e de término para definir o número de páginas de log como duas e ativar carimbos de data/hora.

Para um driver em 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 sobre como adicionar o rastreamento de software WPP a um Driver do Windows. Por exemplo:

• No DriverEntry, chame WPP_INIT_TRACING(DriverObject, RegistryPath).
• No 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 em 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 exportar 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 determinado (opcional)
• WppRecorderConfigure para desabilitar o log padrão (opcional)

O driver também precisa definir uma nova macro de rastreamento que utiliza o manipulador de log como primeiro parâmetro. Para obter um exemplo, consulte o Driver de Amostra 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.

Como exibir mensagens de rastreamento no depurador

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

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