Compartir a través de

TraceLogging para componentes y controladores en modo kernel

  • Artículo

En este tema se describe cómo usar la API TraceLogging desde los componentes y controladores en modo kernel.

Requisitos previos:

  • Windows 10
  • Visual Studio 2013 (o posterior)
  • Windows 10 SDK
  • Kit de controladores de Windows (WDK) para Windows 10

Incluir los archivos de encabezado tracelogging

Para usar la API TraceLogging, incluya el archivo de encabezado TraceLoggingProvider.h. El otro archivo de encabezado de la API TraceLogging, TraceLoggingActivity.h, solo está disponible para su uso en controladores en modo de usuario escritos en C++.

#include <wdm.h>
#include <TraceLoggingProvider.h>

Nota

El archivo wdm.h es necesario para TraceLoggingProvider.h al desarrollar controladores de modo kernel.

Declarar el controlador como proveedor de TraceLogging

  1. Agregue la macro TRACELOGGING_DECLARE_PROVIDER para declarar la variable de identificador del proveedor. La macro tiene la sintaxis:

    TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)

    La siguiente instrucción TraceLogging de ejemplo declara la variable denominada g_hProvider.

    TRACELOGGING_DECLARE_PROVIDER(g_hProvider);

    La variable que declara con TRACELOGGING_DECLARE_PROVIDER se convierte en el identificador del proveedor al llamar a la macro TRACELOGGING_DEFINE_PROVIDER más adelante en el código.

    Nota

    Es posible que desee colocar esta macro en un archivo de encabezado para que el identificador del proveedor TraceLogging esté disponible globalmente.

  2. Agregue la macro TRACELOGGING_DEFINE_PROVIDER y especifique un nombre para el proveedor de seguimiento y el identificador del proveedor de seguimiento. El identificador es la variable que declaró en el paso 1. La sintaxis de la macro es:

    TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])

    Por ejemplo, la siguiente instrucción define un proveedor llamado MyTraceLoggingProviderKM y lo asigna al identificador g_hProvider. El parámetro providerId es el GUID del proveedor ETW.

    TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
    (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));

    La macro TRACELOGGING_DEFINE_PROVIDER asigna almacenamiento para un proveedor y define una variable correspondiente que es el identificador global del proveedor. El nombre del proveedor debe ser un literal de cadena (no una variable) y no debe contener ningún carácter '\0'. El identificador y las copias del identificador son válidos siempre que el identificador original esté en el ámbito.

    Al crear por primera vez el identificador con la macro TRACELOGGING_DEFINE_PROVIDER , el proveedor se encuentra en estado no registrado. En este estado, el proveedor omitirá las llamadas de escritura de seguimiento hasta que se registre.

    Nota

    Para el modo kernel, tenga en cuenta que, aunque los metadatos del proveedor se almacenan explícitamente en TLG_METADATA_SEGMENT (.rdata), las variables que cree para el identificador (por ejemplo, g_hProvider) y el nombre del proveedor (por ejemplo, "MyTraceLoggingProviderKM") no se asignan explícitamente a un segmento y usarán los segmentos implícitos actuales.

La macro TRACELOGGING_DEFINE_PROVIDER espera que las variables que se le pasen estén en el grupo no paginado. Si este no es el caso, el autor de la llamada debe establecer el segmento de datos a través de #pragma data_seg (para uniqueVarName) o el segmento const a través de #pragma const_seg (para g_hMyProvider) antes de llamar a la macro TRACELOGGING_DEFINE_PROVIDER .

Registro del controlador con TraceLogging

En la función DriverEntry , debe registrar el proveedor tracelogging. Para registrar el proveedor con TraceLogging, agregue la macro TraceLoggingRegister a DriverEntry:

// Register the TraceLogging provider in the DriverEntry method.
TraceLoggingRegister(g_hProvider);

Anulación del registro del proveedor en la rutina de descarga o limpieza del controlador

En la función DriverUnload o cleanup, anule el registro del proveedor TraceLogging.

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hProvider);

Registrar eventos en el código

TraceLogging proporciona macros para registrar eventos.

La macro básica es TraceLoggingWrite. Esta macro tiene la siguiente sintaxis:

TraceLoggingWrite(g_hProvider, "EventName", args...)

Donde g_hProvider es el identificador del proveedor que definió y "EventName" es un literal de cadena (no una variable) que se usa para identificar el evento específico. Al igual que printf o DbgPrint, la macro TraceLoggingWrite admite un número variable de parámetros adicionales (hasta 99). Los parámetros (argumentos) deben ser macros contenedoras de TraceLogging, como TraceLoggingLevel, TraceLoggingInt32 o TraceLoggingString. Las macros contenedoras TraceLogging se definen en TraceLoggingProvider.h.

Nota

Si usa C++, puede usar la macro contenedora TraceLoggingValue para ajustar automáticamente el tipo. Si está escribiendo el controlador en C, debe usar las macros de campo específicas del tipo (por ejemplo, TraceLoggingInt32 o TraceLoggingUnicodeString).

En el ejemplo siguiente se registra un evento para el proveedor, g_hProvider. El evento se denomina "MyDriverEntryEvent". La macro usa los contenedores TraceLoggingPointer y TraceLoggingUnicodeString para escribir el puntero en el objeto de controlador y la ruta de acceso del Registro al registro de seguimiento. El contenedor TraceLoggingUnicodeString toma un nombre opcional. En este ejemplo, "RegPath" es el nombre del valor de RegistryPath. Si no se especifica ningún nombre, el valor se usa como nombre.

TraceLoggingWrite(
        g_hProvider,
        "MyDriverEntryEvent",
        TraceLoggingPointer(DriverObject),
        TraceLoggingUnicodeString(RegistryPath, "RegPath")); 
);

Si va a instrumentar un controlador en modo kernel (en C), se vincula a TraceLoggingProvider.h y puede usar las macros TraceLoggingWrite, TraceLoggingWriteActivity o TraceLoggingActivityMarker . Para obtener ejemplos de registro de seguimiento, consulte Ejemplos de seguimiento.

Si va a instrumentar un controlador o componente escrito en C++, se vincula a TraceLoggingProvider.h y TraceLoggingActivity.h. Al vincular al encabezado de C++, puede registrar eventos con las macros TraceLoggingWriteStart, TraceLoggingWriteStop y TraceLoggingWriteTagged .

Para obtener ejemplos de cómo capturar y ver los datos de TraceLogging, consulte Capture and view TraceLogging data (Capturar y ver datos de TraceLogging).