TraceLogging para drivers e componentes do modo kernel

Artigo
06/15/2023

Este tópico descreve como usar a API traceLogging de dentro de drivers e componentes do modo kernel.

Pré-requisitos:

Windows 10
Visual Studio 2013 (ou posterior)
SDK do Windows 10
WDK (Kit de Driver do Windows) para Windows 10

Incluir os arquivos de cabeçalho TraceLogging

Para usar a API TraceLogging, inclua o arquivo de cabeçalho TraceLogging TraceLoggingProvider.h. O outro arquivo de cabeçalho da API traceLogging, TraceLoggingActivity.h, só está disponível para uso em drivers de modo de usuário escritos em C++.

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

Observação

O arquivo wdm.h é necessário para TraceLoggingProvider.h ao desenvolver drivers de modo kernel.

Declarar seu driver como um provedor tracelogging

Adicione a macro TRACELOGGING_DECLARE_PROVIDER para declarar a variável de identificador do provedor. A macro tem a sintaxe :
```
TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
```
A instrução TraceLogging de exemplo a seguir declara a variável chamada g_hProvider.
```
TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
```
A variável que você declara com TRACELOGGING_DECLARE_PROVIDER torna-se o identificador para o provedor quando você chama a macro TRACELOGGING_DEFINE_PROVIDER posteriormente em seu código.

Observação

Talvez você queira colocar essa macro em um arquivo de cabeçalho para que o identificador para o provedor traceLogging esteja disponível globalmente.
Adicione a macro TRACELOGGING_DEFINE_PROVIDER e especifique um nome para o provedor de rastreamento e o identificador do provedor de rastreamento. O identificador é a variável que você declarou na etapa 1. A sintaxe da macro é:
```
TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])
```
Por exemplo, a instrução a seguir define um provedor chamado MyTraceLoggingProviderKM e a atribui ao identificador g_hProvider. O parâmetro providerId é o GUID do provedor ETW.
```
TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
    (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));
```
A macro TRACELOGGING_DEFINE_PROVIDER aloca armazenamento para um provedor e define uma variável correspondente que é o identificador global para o provedor. O nome do provedor deve ser um literal de cadeia de caracteres (não uma variável) e não deve conter nenhum caractere '\0'. O identificador e as cópias do identificador são válidos desde que o identificador original esteja no escopo.

Quando você cria o identificador pela primeira vez com a macro TRACELOGGING_DEFINE_PROVIDER , o provedor está no estado não registrado. Nesse estado, o provedor ignorará todas as chamadas de gravação de rastreamento até que ele seja registrado.

Observação

Para o modo kernel, lembre-se de que, embora os metadados do provedor sejam armazenados explicitamente em TLG_METADATA_SEGMENT (.rdata), as variáveis criadas para o identificador (por exemplo, g_hProvider) e o nome do provedor (por exemplo, "MyTraceLoggingProviderKM") não são explicitamente atribuídas a um segmento e usarão os segmentos implícitos atuais.

A macro TRACELOGGING_DEFINE_PROVIDER espera que as variáveis passadas para ela estejam no pool nãopagado. Se esse ainda não for o caso, o chamador deverá definir o segmento de dados por meio de #pragma data_seg (para uniqueVarName) ou o segmento const por meio de #pragma const_seg (para g_hMyProvider) antes de chamar a macro TRACELOGGING_DEFINE_PROVIDER .

Registrar o driver com TraceLogging

Na função DriverEntry, você deve registrar o provedor TraceLogging. Para registrar o provedor com TraceLogging, adicione a macro TraceLoggingRegister ao DriverEntry:

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

Cancelar o registro do provedor na rotina de descarregamento ou limpeza do driver

Em sua função DriverUnload ou cleanup, cancele o registro do provedor TraceLogging.

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

Registrar eventos em seu código

O TraceLogging fornece macros para registrar eventos em log.

A macro básica é TraceLoggingWrite. Essa macro tem a seguinte sintaxe:

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

Em que g_hProvider é o identificador do provedor que você definiu e "EventName" é um literal de cadeia de caracteres (não uma variável) que você usa para identificar o evento específico. Assim como printf ou DbgPrint, a macro TraceLoggingWrite dá suporte a um número variável de parâmetros adicionais (até 99). Os parâmetros (args) devem ser macros wrapper TraceLogging, como TraceLoggingLevel, TraceLoggingInt32 ou TraceLoggingString. As macros wrapper TraceLogging são definidas em TraceLoggingProvider.h.

Observação

Se você estiver usando C++, poderá usar a macro wrapper TraceLoggingValue para ajustar automaticamente para o tipo. Se você estiver escrevendo seu driver em C, deverá usar as macros de campo específicas do tipo (por exemplo, TraceLoggingInt32 ou TraceLoggingUnicodeString).

O exemplo a seguir registra um evento para o provedor, g_hProvider. O evento é chamado de "MyDriverEntryEvent". A macro usa os wrappers TraceLoggingPointer e TraceLoggingUnicodeString para gravar o ponteiro no objeto do driver e no caminho do registro no log de rastreamento. O wrapper TraceLoggingUnicodeString usa um nome opcional. Neste exemplo, "RegPath" é o nome do valor registryPath. Se nenhum nome for especificado, o valor será usado como o nome.

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

Se você estiver instrumentando um driver no modo kernel (em C), vincule-se a TraceLoggingProvider.h e poderá usar as macros TraceLoggingWrite, TraceLoggingWriteActivity ou TraceLoggingActivityMarker . Para obter exemplos de log de rastreamento, consulte TraceLogging Examples.

Se você estiver instrumentando um driver ou componente escrito em C++, vincule a TraceLoggingProvider.h e TraceLoggingActivity.h. Ao vincular ao cabeçalho C++, você pode registrar eventos com as macros TraceLoggingWriteStart, TraceLoggingWriteStop e TraceLoggingWriteTagged .

Para obter exemplos de como capturar e exibir dados do TraceLogging, consulte Capturar e exibir dados do TraceLogging.

Compartilhar via