Compartir a través de

Grabadora de trazas en vuelo (IFR) para registrar trazas

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:

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

Cómo habilitar el grabador de trazas Inflight 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>-Seguimiento de WPP>-Opciones de función y macro>-Habilitar grabadora de seguimiento en vuelo, seleccione Sí.

Por último, solo para UMDF, hay un paso adicional: en WPP Tracing->Función y Opciones de macro->Definiciones del preprocesador, 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>

Cómo configurar parámetros de la grabadora de trazas Inflight

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

Utilice las siguientes entradas del Registro:

LogPages: REG_DWORD

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

VerboseOn: REG_DWORD

El valor predeterminado 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 luego 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 de inicio y finalización 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 en Agregar el seguimiento de software 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 conductores, 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 bus, es posible que desee que cada dispositivo secundario tenga su propio búfer. A continuación, puede usar el depurador para generar 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:

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 de tostadora.

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 del controlador para cada gestor de registros 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 cómo dirigirse a una versión específica, consulta Compilar controladores para diferentes versiones de Windows.

Cómo ver mensajes de seguimiento en el depurador

Para los controladores KMDF y UMDF, use !wdfkd.wdflogdump como de costumbre. Imprimirá tanto el registro IFR del framework como el registro IFR del controlador.

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

  • Last updated on