TraceLogging para drivers e componentes do modo kernel

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> 

Declarar 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)
   

   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.

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 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.

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.