TraceLogging para drivers e componentes de modo núcleo

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

Pré-requisitos:

• Windows 10
• Visual Studio 2013 (ou posterior)
• Windows 10 SDK
• Kit de driver do Windows (WDK) 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> 

Declare o seu driver como um provedor TraceLogging

1. Adicione a macro TRACELOGGING_DECLARE_PROVIDER para declarar a variável de identificador do provedor. A macro tem a sintaxe:

   TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
   

   O exemplo a seguir instrução TraceLogging declara a variável chamada g_hProvider.

   TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
   

   A variável que você declara com TRACELOGGING_DECLARE_PROVIDER se torna 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.

2. 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 declarada 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 o 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.

   Ao criar o identificador pela primeira vez com a macro TRACELOGGING_DEFINE_PROVIDER, o provedor fica no estado não registrado. Nesse estado, o provedor ignorará quaisquer chamadas de gravação de rastreamento até que seja registrado.

   Observação

   Para o modo kernel, esteja ciente de que, embora os metadados do provedor sejam explicitamente armazenados no 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 recebem explicitamente 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ão paginado. Se este ainda não for o caso, o chamador deve definir o segmento de dados via #pragma data_seg (para uniqueVarName) ou o segmento const via #pragma const_seg (para g_hMyProvider) antes de chamar a macro TRACELOGGING_DEFINE_PROVIDER .

Registre o controlador com TraceLogging

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

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

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

Na função DriverUnload ou de limpeza, desregiste o provedor TraceLogging.

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

Registrar eventos em seu código

TraceLogging fornece macros para registrar eventos.

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

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

Onde g_hProvider é o identificador para o 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. Como printf ou DbgPrint, a macro TraceLoggingWrite suporta 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 do wrapper TraceLogging são definidas em TraceLoggingProvider.h.

O exemplo a seguir registra um evento para o provedor, g_hProvider. O evento é chamado de "MyDriverEntryEvent". A macro faz uso dos wrappers TraceLoggingPointer e TraceLoggingUnicodeString para gravar o ponteiro no objeto do driver e o caminho do Registro no log de rastreamento. O wrapper TraceLoggingUnicodeString tem 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 de 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 Exemplos de TraceLogging.

Se você estiver instrumentando um driver ou componente escrito em C++, vincule-se 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.