Compartir a través de

Uso de la grabadora de seguimiento en la luz (IFR) en los controladores KMDF y UMDF 2

  • Artículo

A partir de Windows 10, puedes compilar el controlador KMDF o UMDF para que obtenga información adicional de depuración de controladores a través del preprocesamiento de seguimiento de software de Windows. Esta característica, denominada Inlight Trace Recorder (IFR), está disponible a partir de kmDF versión 1.15 y UMDF versión 2.15.

Inflight Trace Recorder es una extensión del seguimiento de software de WPP. A diferencia del seguimiento de WPP, la Grabadora de seguimiento de la luz sigue funcionando sin un consumidor de seguimiento asociado. El marco escribe mensajes en un búfer circular y el controlador también puede agregar sus propios mensajes. Cada controlador tiene su propio registro, por lo que varios dispositivos asociados a un controlador comparten un único registro.

Si activa el IFR en el archivo binario del controlador, el IFR está presente y ejecutándose durante la vigencia del controlador. No es necesario iniciar una sesión de recopilación de seguimiento explícita.

Los registros se almacenan en memoria no paginable, por lo que se pueden recuperar después de un bloqueo del sistema. Además, los registros de La grabadora de seguimiento enlight se incluyen en archivos minivolcados, excepto cuando el controlador responsable no está determinado o si el bloqueo era un tiempo de espera de host.

Habilitación de La grabadora de seguimientos en la luz y envío de mensajes desde el controlador

  1. En Microsoft Visual Studio, siga estos pasos:

    • Abra las páginas de propiedades del proyecto de controlador. Haga clic con el botón derecho en el proyecto de controlador en Explorador de soluciones y seleccione Propiedades. En las páginas de propiedades del controlador, seleccione Propiedades de configuración y, a continuación , Seguimiento de Wpp. En el menú General , establezca Ejecutar seguimiento de WPP en Sí.

    • Vaya a Propiedades-Función> de seguimiento de> Wpp y Opciones de macro y elija Habilitar grabadora de WPP.

    • En el mismo menú, establezca Examinar datos de configuración en el archivo que contiene la información de seguimiento, por ejemplo Trace.h.

  2. En cada archivo de origen que llama a una macro de WPP, agregue una directiva #include que identifique un archivo de encabezado de mensaje de seguimiento (TMH). El nombre de archivo debe tener un formato driver-source-file-name.tmh<>.

    Por ejemplo, si el controlador consta de dos archivos de origen, denominados MyDriver1.c y MyDriver2.c, myDriver1.c debe contener:

    #include "MyDriver1.tmh"

    y MyDriver2.c deben contener:

    #include "MyDriver2.tmh"

    Al compilar el controlador en Visual Studio, el preprocesador de WPP genera el .archivos tmh .

  3. Defina una macro WPP_CONTROL_GUIDS en un archivo de encabezado. Esta macro define un GUID y marcas de seguimiento para los mensajes de seguimiento del controlador.

    En el ejemplo de controlador Osrusbfx2 se define un GUID de control único y siete marcas de seguimiento en el archivo de encabezado Trace.h, como se muestra en el ejemplo siguiente:

    #define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \
  (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
  WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
  WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
  WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
  WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
  WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
  WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
  WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
  WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
)

    En este ejemplo:

    • OsrUsbFxTraceGuid es el nombre descriptivo del GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
    • Las marcas de seguimiento se usan para diferenciar entre los mensajes de seguimiento que se generan a medida que el controlador controla diferentes tipos de solicitudes de E/S.

  4. El controlador (tanto KMDF como UMDF 2) debe llamar a WPP_INIT_TRACING para controladores en modo kernel con el objeto driver y una ruta de acceso del Registro, normalmente desde DriverEntry:

    WPP_INIT_TRACING( DriverObject, RegistryPath );

    Para desactivar el seguimiento, los controladores KMDF y UMDF 2 llaman a WPP_CLEANUP para controladores en modo kernel desde EvtCleanupCallback o EvtDriverUnload:

    WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));

    La macro WPP_CLEANUP toma un parámetro de tipo PDRIVER_OBJECT, por lo que si se produce un error en DriverEntry del controlador, puede omitir la llamada a WdfDriverWdmGetDriverObject y, en su lugar, llamar a WPP_CLEANUP con un puntero al objeto de controlador WDM.

    Dado que los controladores de UMDF usan las firmas en modo kernel de estas macros para inicializar y limpiar el seguimiento, las llamadas son idénticas para KMDF y UMDF.

  5. Use la macro DoTraceMessage o una versión personalizada de la macro, en el controlador para crear mensajes de seguimiento.

    En el ejemplo siguiente se muestra cómo el controlador Osrusbfx2 usa su función TraceEvents en una parte del código dedicado a controlar las solicitudes de lectura:

    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
    TraceEvents(TRACE_LEVEL_ERROR,
                DBG_READ,
                "Transfer exceeds %d\n",
                TEST_BOARD_TRANSFER_BUFFER_SIZE);

    status = STATUS_INVALID_PARAMETER;
}

    La llamada a TraceEvents genera un mensaje de seguimiento si el controlador de seguimiento habilita el nivel de TRACE_LEVEL_ERROR y la marca de seguimiento DBG_READ . El mensaje incluye el valor de la constante definida por el controlador TEST_BOARD_TRANSFER_BUFFER_SIZE.

  6. Para cambiar el tamaño del búfer circular que usa el registro de controladores, modifique el valor del Registro LogPages en la siguiente ubicación del Registro:

    Para UMDF:

    SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf

    Para KMDF:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<YourDriver>\Parameters\Wdf

    Este es un valor de tipo REG_DWORD que contiene el tamaño del búfer de registro asignado, en páginas. Los valores válidos están entre 0x1 y 0x10.

Para un controlador KMDF

  1. Cargue los comandos RCDRKD escribiendo .load rcdrkd.dll en el depurador.
  2. Usa la extensión !wdfkd.wdfldr para mostrar información sobre el controlador que está enlazado dinámicamente a Windows Driver Frameworks (WDF).
  3. Use !rcdrkd.rcdrlogdump y !rcdrkd.rcdrcrashdump para ver los mensajes que proporciona el controlador.
  4. Use !wdfkd.wdflogdump o !wdfkd.wdfcrashdump para ver los mensajes que proporciona el marco.

Depuración activa de un controlador UMDF

  1. Use la extensión !wdfkd.wdfldr para mostrar información sobre los controladores que están enlazados dinámicamente a WDF. Busque el controlador en modo de usuario. Escriba el proceso de host asociado.

  2. Escriba !wdfkd.wdflogdump <YourDriverName.dll<>Marca> , donde< Flag> es:

    • 0x1: registros de controladores y marcos combinados
    • 0x2: registros de controladores
    • 0x3: registros del marco

    Si no hay ningún registro de controladores para el controlador especificado, la extensión solo muestra el registro del marco.

Visualización de los registros de la Grabadora de seguimiento en la luz después de que se bloquee un controlador UMDF

  1. En WinDbg, seleccione File-Open> Crash Dump y especifique el archivo de minivolcado que desea depurar.

  2. Escriba !wdfkd.wdfcrashdump <YourDriverName.dll><id. de proceso de la opción host del controlador<>, donde <Option>> es:

    • 0x1: registros de controladores y marcos combinados
    • 0x2: registros de controladores
    • 0x3: registros del marco

    Si no especifica un controlador, !wdfcrashdump muestra información para todos los controladores. Si no especifica un proceso de host y solo hay uno, la extensión usa el proceso de host único. Si no especifica un proceso de host y hay más de uno, la extensión enumera los procesos de host activos.

    Si la información de registro almacenada en el minivolcado no coincide con el nombre especificado, el minivolcado no contiene los registros del controlador.

Si no tiene un depurador conectado, todavía puede acceder a los registros del controlador y del marco de trabajo. Para obtener información sobre cómo hacerlo, consulte Vídeo: Acceso a los registros de IFR del controlador sin un depurador.

Para obtener más información sobre cómo agregar mensajes de seguimiento al controlador, vea Agregar macros de WPP a un controlador.

Cómo habilitar la depuración de un controlador UMDF

Extensiones RCDRKD

Uso del registrador de eventos de Framework

Uso del seguimiento de software de WPP en controladores UMDF