Função EtwWrite (wdm.h)

Artigo
03/08/2023

A função EtwWrite é uma função de rastreamento para publicar eventos no código do driver no modo kernel.

Sintaxe

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

Um ponteiro para o identificador de registro do provedor de eventos, que é retornado pela função EtwRegister se o registro do provedor de eventos for bem-sucedido.

[in] EventDescriptor

Um ponteiro para a estrutura EVENT_DESCRIPTOR .

[in, optional] ActivityId

O identificador que indica a atividade associada ao evento. A ActivityID fornece uma maneira de agrupar eventos relacionados e é usada no rastreamento de ponta a ponta.

[in] UserDataCount

O número de estruturas de EVENT_DATA_DESCRIPTOR no UserData.

[in, optional] UserData

Um ponteiro para a matriz de estruturas de EVENT_DATA_DESCRIPTOR.

Retornar valor

Se o evento tiver sido publicado com êxito, EtwWrite retornará STATUS_SUCCESS.

Se o ponteiro para o identificador de registro do provedor de eventos for inválido, EtwWrite retornará STATUS_INVALID_HANDLE. O provedor de eventos deve ser registrado antes que o EtwWrite seja chamado. EtwWrite também poderá retornar STATUS_INVALID_HANDLE se não for possível registrar o evento.

Se o número de estruturas de EVENT_DATA_DESCRIPTOR especificadas em UserDataCount for maior que o máximo permitido (128), EtwWrite retornará STATUS_INVALID_PARAMETER.

Se ActivityID for especificado, mas não houver memória suficiente disponível para registrar os dados associados ao evento, EtwWrite retornará STATUS_NO_MEMORY.

Se o provedor não estiver habilitado para nenhuma sessão, o EtwWrite retornará STATUS_SUCCESS e os eventos não serão registrados.

Os eventos podem ser perdidos por vários motivos; por exemplo, se a taxa de eventos for muito alta ou se o tamanho do evento for maior que o tamanho do buffer. Nesses casos, o contador EventsLost , membro da estrutura EVENT_TRACE_PROPERTIES do agente correspondente, é atualizado com o número de eventos que não foram registrados.

Comentários

A função EtwWrite é o equivalente ao modo kernel da função EventWrite do modo de usuário. Para garantir que haja um consumidor para o evento que você está publicando, você pode preceder a chamada para EtwWrite com uma chamada para EtwEventEnabled ou EtwProviderEnabled.

Antes de chamar a função EtwWrite para publicar um evento, registre o provedor com EtwRegister. Nenhuma chamada de rastreamento deve ser feita que fique fora do código delimitado pelas funções EtwRegister e EtwUnregister . Para obter o melhor desempenho, você pode chamar a função EtwRegister em sua rotina DriverEntry e a função EtwUnregister em sua rotina DriverUnload .

Se você estiver usando o parâmetro UserData opcional na função EtwWrite para registrar dados de evento adicionais, poderá usar a macro EventDataDescCreate para simplificar a criação das estruturas de EVENT_DATA_DESCRIPTOR. O exemplo a seguir usa a macro EventDataDescCreate para inicializar estruturas EVENT_DATA_DESCRIPTOR com o nome do dispositivo e seu status. A macro EventDataDescCreate armazena ponteiros para os dados (ou seja, ele não armazena cópias dos dados). Os ponteiros devem permanecer válidos até que a chamada para EtwWrite retorne.

Você pode chamar EtwWrite em qualquer IRQL. No entanto, quando IRQL é maior que APC_LEVEL, todos os dados passados para as funções EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer não devem ser pagináveis. Ou seja, qualquer rotina de modo kernel em execução no IRQL maior que APC_LEVEL não pode acessar a memória paginável. Os dados passados para as funções EtwWrite, EtwWriteEx, EtwWriteString e EtwWriteTransfer devem residir na memória do espaço do sistema, independentemente do que seja o IRQL.

Exemplo

 
 //
 // 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	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (inclua Wdm.h, Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Qualquer nível (consulte a seção Comentários.)