Registrador de seguimiento (IFR) para registrar seguimientos

Artículo
10/26/2023

Inflight Trace Recorder (IFR) es una característica de seguimiento que permite a un proveedor de seguimiento, como un controlador en modo kernel o un controlador UMDF, crear un conjunto de búferes circulares en memoria donde se conservan los mensajes de registro más recientes. Los mensajes de registro se pueden ver mediante un depurador.

IFR se basa en el seguimiento de software de WPP. La principal ventaja de IFR sobre WPP es que se activa automáticamente y no es necesario iniciar las sesiones de seguimiento de antemano.

Se aplica a:

So mínimo: Windows 8 para desarrolladores de controladores KMDF y WDM
So mínimo: Windows 10 para desarrolladores de controladores de UMDF (2.15)

Habilitación de la grabadora de seguimientos en Visual Studio

En primer lugar, siga los pasos descritos en Agregar seguimiento de software de WPP a un controlador de Windows.

A continuación, en la página de propiedades Del proyecto, en Propiedades de configuración-Función> de> seguimiento de WPP y Opciones de macro-Habilitar> grabadora de seguimiento en claro, seleccione Sí.

Por último, solo para UMDF, hay un paso adicional: en WpP Tracing-Function and Macro Options-Preprocessor>> Definitions, agregue WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Cómo habilitar Inflight Trace Recorder desde la línea de comandos

Si edita el archivo .vcxproj manualmente, establezca las siguientes entradas:

Para un controlador KMDF o WDM:

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

Para un controlador UMDF:

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

Configuración de parámetros de La grabadora de seguimiento en la luz

Puede configurar el IFR estableciendo las siguientes entradas opcionales del Registro en la clave Parameter del controlador.

Use las siguientes entradas del Registro:

LogPages: REG_DWORD

Establezca en el número de páginas para almacenar el registro predeterminado. El valor predeterminado es uno.

VerboseOn: REG_DWORD

La configuración predeterminada de cero hace que el IFR registre errores, advertencias y eventos informativos. Establezca en uno para agregar una salida detallada al registro.

WppRecorder_UseTimeStamp: REG_DWORD (disponible a partir de la compilación 22557 de WDK)

Los controladores establecen esta entrada en una para agregar marcas de tiempo a entradas de registro que, a continuación, se pueden ver mediante !rcdrkd.rcdrlogdump o !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (disponible a partir de la compilación 22557 de WDK)

Si desea marcas de tiempo más precisas, además de WppRecorder_UseTimeStamp, agregue WppRecorder_PreciseTimeStamp con la misma sintaxis mostrada anteriormente.

Ejemplos

En los ejemplos siguientes, agregue las líneas entre los comentarios inicial y final para establecer el número de páginas de registro en dos y activar las marcas de tiempo.

Para un controlador en 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 un controlador 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

Envío de mensajes de seguimiento al registro predeterminado

Siga las instrucciones de Agregar seguimiento de software de WPP a un controlador de Windows. Por ejemplo:

En DriverEntry, llame a WPP_INIT_TRACING(DriverObject, RegistryPath).
En EvtDriverUnload, llame a WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Ahora el controlador es libre de llamar a la función de seguimiento según sea necesario. Por ejemplo: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Para obtener más información, consulta WPP_INIT_TRACING y WPP_CLEANUP.

Envío de mensajes de seguimiento a un registro personalizado

Esto solo se aplica a los controladores en modo kernel (KMDF o WDM).

Para la mayoría de los controladores, el registro predeterminado único es lo suficientemente bueno. Sin embargo, en algunos escenarios, resulta útil tener búferes de registro independientes para entidades distintas.

Por ejemplo, al escribir un controlador de autobús, es posible que quiera que cada dispositivo secundario tenga su propio búfer. A continuación, puede usar el depurador para volcar solo el registro de un dispositivo secundario específico.

Para configurar registros personalizados, el controlador debe incluir <WppRecorder.h>. A continuación, llame a las SIGUIENTES API:

WppRecorderLogCreate para crear más de un búfer de registro
WppRecorderLogDelete antes de llamar a WPP_CLEANUP.
WppRecorderLogSetIdentifier para establecer un identificador de cadena para un registro de grabadora determinado (opcional)
WppRecorderConfigure para deshabilitar el registro predeterminado (opcional)

El controlador también debe definir una nueva macro de seguimiento que tome el identificador de registro como primer parámetro. Para obtener un ejemplo, consulte el controlador de ejemplo del tostador.

Cómo agregar información de marca de tiempo a un registro personalizado

Si el controlador llama a WppRecorderLogCreate para crear identificadores de registro adicionales, es posible habilitar marcas de tiempo para algunos identificadores de registro, pero no para otros.

Para ello, debe agregar una sola línea al código de controlador para cada identificador de registro que debe usar marcas de tiempo. Para obtener un ejemplo de código, vea WppRecorderLogCreate.

Nota

Esta funcionalidad está disponible a partir de la compilación 22557 de WDK. Para obtener información sobre el destino de una versión específica, consulta Building Drivers for Different Versions of Windows.

Visualización de mensajes de seguimiento en el depurador

En el caso de los controladores KMDF y UMDF, use !wdfkd.wdflogdump como de costumbre. Imprimirá el registro de IFR del marco y el registro ifr del controlador.

Para los controladores WDM, use !rcdrkd.rcdrloglist y !rcdrkd.rcdrlogdump.

Compartir vía