Función EtwWrite (wdm.h)

Artículo
03/08/2023

La función EtwWrite es una función de seguimiento para publicar eventos en el código del controlador en modo kernel.

Sintaxis

NTSTATUS EtwWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parámetros

[in] RegHandle

Puntero al identificador de registro del proveedor de eventos, que devuelve la función EtwRegister si el registro del proveedor de eventos se realiza correctamente.

[in] EventDescriptor

Puntero a la estructura EVENT_DESCRIPTOR .

[in, optional] ActivityId

Identificador que indica la actividad asociada al evento. ActivityID proporciona una manera de agrupar eventos relacionados y se usa en el seguimiento de un extremo a otro.

[in] UserDataCount

Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData.

[in, optional] UserData

Puntero a la matriz de estructuras de EVENT_DATA_DESCRIPTOR.

Valor devuelto

Si el evento se publicó correctamente, EtwWrite devuelve STATUS_SUCCESS.

Si el puntero al identificador de registro del proveedor de eventos no es válido, EtwWrite devuelve STATUS_INVALID_HANDLE. El proveedor de eventos debe registrarse antes de llamar a EtwWrite . EtwWrite también puede devolver STATUS_INVALID_HANDLE si no puede registrar el evento.

Si el número de estructuras de EVENT_DATA_DESCRIPTOR especificadas en UserDataCount es mayor que el máximo permitido (128), EtwWrite devuelve STATUS_INVALID_PARAMETER.

Si se especifica ActivityID , pero no hay suficiente memoria disponible para registrar los datos asociados al evento, EtwWrite devuelve STATUS_NO_MEMORY.

Si el proveedor no está habilitado para ninguna sesión, EtwWrite devuelve STATUS_SUCCESS y los eventos no se registran.

Los eventos se pueden perder por varias razones; por ejemplo, si la tasa de eventos es demasiado alta o si el tamaño del evento es mayor que el tamaño del búfer. En estos casos, el contador EventsLost , un miembro de la estructura EVENT_TRACE_PROPERTIES del registrador correspondiente, se actualiza con el número de eventos que no se registraron.

Comentarios

La función EtwWrite es el equivalente en modo kernel de la función EventWrite en modo de usuario. Para asegurarse de que hay un consumidor para el evento que está publicando, puede preceder la llamada a EtwWrite con una llamada a EtwEventEnabled o EtwProviderEnabled.

Para poder llamar a la función EtwWrite para publicar un evento, debe registrar el proveedor con EtwRegister. No se debe realizar ninguna llamada de seguimiento que se encuentre fuera del código enlazado por las funciones EtwRegister y EtwUnregister . Para obtener el mejor rendimiento, puede llamar a la función EtwRegister en la rutina DriverEntry y la función EtwUnregister en la rutina DriverUnload .

Si usa el parámetro UserData opcional en la función EtwWrite para registrar datos de eventos adicionales, puede usar la macro EventDataDescCreate para simplificar la creación de las estructuras de EVENT_DATA_DESCRIPTOR. En el ejemplo siguiente se usa la macro EventDataDescCreate para inicializar EVENT_DATA_DESCRIPTOR estructuras con el nombre del dispositivo y su estado. La macro EventDataDescCreate almacena punteros a los datos (es decir, no almacena copias de los datos). Los punteros deben permanecer válidos hasta que se devuelva la llamada a EtwWrite .

Puede llamar a EtwWrite en cualquier IRQL. Sin embargo, cuando IRQL es mayor que APC_LEVEL, los datos pasados a las funciones EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer no deben ser paginables. Es decir, cualquier rutina en modo kernel que se ejecuta en IRQL mayor que APC_LEVEL no puede acceder a la memoria paginable. Los datos pasados a las funciones Etwwrite, EtwwriteEx, EtwwriteString y EtwwriteTransfer deben residir en la memoria del espacio del sistema, independientemente de cuál sea el IRQL.

Ejemplo

 
 //
 // Register the provider with ETW in DriverEntry
 // Unregister the provider in DriverUnload 
    //
 //  Build the EVENT_DATA_DESCRIPTOR structures using 
 //   the EventDataDescCreate macros 
 
 if (RegHandle != (REGHANDLE)NULL) {
 //
 // Log an Event with : DeviceNameLength
 //                      DeviceName
 //                      Status
 //
 
 EventDataDescCreate(&EventDataDescriptor[0],
                            (PVOID)&DeviceName.Length,
 sizeof(USHORT));
 

 EventDataDescCreate(&EventDataDescriptor[1],
                            (PVOID)DeviceName.Buffer,
 DeviceName.Length);
 
 EventDataDescCreate(&EventDataDescriptor[2],
                            (PVOID)&Status,
 sizeof(ULONG));
 
 EtwWrite(RegHandle,            // Handle from EtwRegister
                 &StartEvent,          // EventDescriptor
                 NULL,                 // Activity ID
                 3,                    // Number of data items
 EventDataDescriptor); // Array of data descriptors
    }              

//

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	Cualquier nivel (consulte la sección Comentarios).