Partilhar via

Adicionar rastreamento de software WPP a um driver do Windows

Para usar o rastreamento de software WPP em um provedor de rastreamento, como um driver de modo kernel ou um aplicativo de modo de usuário, você precisa adicionar código (ou instrumento) aos arquivos de origem do driver e modificar o projeto do driver. Esta seção descreverá essas etapas.

Observação

A forma mais fácil de adicionar rastreamento WPP ao teu driver é usar um dos templates de driver KMDF ou UMDF no Visual Studio. Se você usar os modelos, grande parte do código que você precisa adicionar já está feito para você. No Visual Studio, selecione Arquivo > Novo > Projeto e, em seguida, selecione o driver do Windows (modo de usuário ou modo kernel) projeto WDF. As macros WPP são definidas no arquivo de cabeçalho Trace.h incluído como parte do projeto. Se utilizar um dos modelos, pode avançar para o Passo 5.

Etapa 1: Definir o GUID de controle e os sinalizadores de rastreamento

Cada provedor de rastreamento (como um driver ou aplicativo de modo de usuário) deve ser definido exclusivamente. Para fazer isso, adicione a macro WPP_CONTROL_GUIDS que define um GUID de controle, um identificador e sinalizadores de rastreamento. Isso é feito para que você possa identificar e controlar quando e o que deseja rastrear. Embora cada driver normalmente tenha um GUID de controle separado, um driver pode ter vários GUIDs de controle ou vários drivers podem compartilhar um GUID de controle.

Por conveniência, a macro WPP_CONTROL_GUIDS é normalmente definida em um arquivo de cabeçalho comum. O arquivo de cabeçalho deve ser incluído (#include) em qualquer arquivo de origem que você pretenda instrumentar para rastreamento.

Para adicionar WPP_CONTROL_GUIDS macro ao driver:

  1. Adicione um novo arquivo de cabeçalho C++ ao seu projeto do Visual Studio que você pode usar para definir as macros de rastreamento WPP. Por exemplo, selecione e segure (ou clique com o botão direito do mouse) o driver no Gerenciador de Soluções e selecione Adicionar > Novo Item. Salve o arquivo (como Trace.h, por exemplo).

  2. Adicione uma macro WPP_CONTROL_GUIDS para especificar um nome amigável para o provedor de rastreamento, definir um GUID de controle e definir os sinalizadores de rastreamento que você pode usar para qualificar mensagens de rastreamento específicas.

    A macro WPP_CONTROL_GUIDS tem a seguinte sintaxe:

    Sintaxe para WPP_CONTROL_GUIDS

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID),  \
        WPP_DEFINE_BIT(NameOfTraceFlag1)  \
        WPP_DEFINE_BIT(NameOfTraceFlag2)  \
        .............................   \
        .............................   \
        WPP_DEFINE_BIT(NameOfTraceFlag31) \
        )

    Por exemplo, o código a seguir usa myDriverTraceGuid como o GUIDFriendlyName. Observe que ControlGUID tem um formato ligeiramente diferente do formulário padrão de um GUID hexadecimal de 32 dígitos. O ControlGUID tem os cinco campos, mas eles são separados por vírgulas e entre parênteses, em vez dos habituais hífenes e chaves encaracoladas. Por exemplo, você especifica ((84bdb2e9,829e,41b3,b891,02f454bc2bd7) em vez de {84bdb2e9-829e-41b3-b891-02f454bc2bd7}.

    Exemplo de uma declaração WPP_CONTROL_GUIDS

    #define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        )

    Observação

    Pode copiar este excerto de código para um ficheiro de cabeçalho. Certifique-se de alterar o GUID de controle e o nome amigável. Você pode usar GUIDgen.exe para gerar o GUID de controle. O Guidgen.exe está incluído no Visual Studio (Tools > Create GUID). Você também pode usar a ferramenta Uuidgen.exe, que está disponível na janela do prompt de comando do Visual Studio (digite uuidgen.exe /? para obter mais informações).

  3. Defina os sinalizadores de rastreamento para seu provedor de rastreamento.

    Os elementos WPP_DEFINE_BIT da macro WPP_CONTROL_GUIDS definem os sinalizadores de rastreamento para o provedor de rastreamento. Normalmente, os sinalizadores representam níveis de relatório cada vez mais detalhados, mas você pode usá-los da maneira que quiser como condições para gerar mensagens de rastreamento. No exemplo WPP_CONTROL_GUIDS, o WPP_DEFINE_BIT define quatro sinalizadores de rastreamento (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE e TRACE_QUEUE).

    Você pode definir até 31 sinalizadores de rastreamento. WPP atribui valores de bit aos elementos na ordem em que aparecem, por exemplo, bit 0 (0x1), bit 1 (0x2), bit 2 (0x4), bit 3 (0x8) e assim por diante. Você usa os sinalizadores de rastreamento quando adiciona funções de mensagem de rastreamento ao código-fonte (descrito em Etapa 5: Instrumente o código do driver para gerar mensagens de rastreamento em pontos apropriados).

    Observação

    Usando as bandeiras de rastreamento, pode controlar quando rastrear componentes específicos (por exemplo, solicitações de E/S específicas ou atividades de objetos de dispositivo ou controlador). Você adiciona o sinalizador de rastreamento à instrução da mensagem de rastreamento (por exemplo, DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). Ao criar uma sessão de rastreamento com um controlador de rastreamento, como o Tracelog, você especifica a opção -flag a ser usada para o provedor de rastreamento nessa sessão, nesse caso, o sinalizador é o bit 1 (0x1), que corresponde ao sinalizador TRACE_DRIVER. Quando você inicia a sessão de rastreamento, todas as mensagens de rastreamento que especificam esse sinalizador de rastreamento são gravadas no log.

Etapa 2: Escolha quais funções de mensagem de rastreamento você pretende usar e defina as macros WPP para essas funções

Como uma função de impressão de depuração, uma função de mensagem de rastreamento é uma função (ou macro) que você adiciona ao seu código para escrever mensagens de rastreamento.

Escolher uma função de mensagem de rastreio

  • A função de mensagem de rastreamento padrão é a macro DoTraceMessage . Se você usar a função padrão, poderá controlar quando gerar mensagens usando os valores de Sinalizador de Rastreamento para seu provedor. Os valores de Sinalizadores de Rastreamento são os sinalizadores definidos quando você criou o GUID de controle na Etapa 1. Se você usar DoTraceMessage, as macros WPP padrão já estão definidas para você (WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER), então você pode pular o restante desta etapa e ir para a Etapa 5.

  • Se você estiver usando um dos modelos KMDF ou UMDF, a função TraceEvents e as macros WPP necessárias já estão definidas para habilitar essa função, para que você possa pular para a Etapa 5.

  • Se você estiver criando sua própria função de mensagem de rastreamento ou convertendo a função de impressão de depuração existente, continue com o restante desta etapa.

Criação ou personalização de uma função de mensagem de rastreio

  1. Se estiver a usar funções de mensagens de rastreamento personalizadas ou quiser converter funções de impressão para depuração (por exemplo, KdPrint) para gerar mensagens de rastreamento, precisará definir macros WPP que identifiquem e ativem as funções de mensagens de rastreamento no seu fornecedor de rastreamento. Coloque essas macros no arquivo de cabeçalho Trace.h que você adicionou ao seu projeto.

  2. Defina as macros WPP para habilitar a função de rastreamento.

    Cada função de mensagem de rastreamento que você usa deve ter um par correspondente de macros. Essas macros identificam o provedor de rastreamento e especificam as condições que geram as mensagens. Normalmente, define-se um par de macros, WPP_<condição>_LOGGER e WPP_<condição>_ENABLED em termos das macros padrão WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER.

Período Descrição
WPP_CONDIÇÕES_LOGGER Usado para localizar a sessão de rastreamento associada ao provedor e retorna um identificador para a sessão.
WPP_CONDIÇÕES_ENABLED Usado para determinar se o registo de logs está ativado com a condição especificada.

Para as macros WPP que você definir, as CONDIÇÕES representam as condições suportadas pela função de mensagem de rastreamento, na ordem em que aparecem na lista de parâmetros da função, separadas por sublinhados. Por exemplo, a função de mensagem de rastreamento padrão, DoTraceMessage, suporta apenas Trace Flag como a condição, portanto, há apenas um parâmetro nos nomes de macro (WPP_LEVEL_ENABLED).

Observação

Infelizmente, os nomes das macros padrão (WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER) parecem indicar o parâmetro Trace Level , mas na verdade referem-se à Trace Flag.

Se você usar uma função de mensagem de rastreamento personalizada, poderá definir qualificadores adicionais, como o Nível de Rastreamento. O Nível de Rastreamento é definido no arquivo Evntrace.h e os níveis de rastreamento fornecem uma maneira conveniente de classificar as mensagens de rastreamento como mensagens de erro, aviso e informações.

Por exemplo, você pode adicionar o seguinte trecho de código ao arquivo de cabeçalho que você adicionou ao seu projeto. O código seguinte define as macros WPP personalizadas para uma função de mensagem de rastreamento que suporta tanto parâmetros de Nível de Rastreamento como de Flag de Rastreamento como condições para gerar mensagens de rastreamento. A macro WPP_LEVEL_FLAGS_ENABLED devolve TRUE se o registo estiver ativado para o valor FLAGS especificado e o valor LEVEL ativado for maior ou igual ao argumento level usado na chamada de função de mensagem de rastreio.

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

Em seguida, você precisa especificar as funções de rastreamento personalizadas no bloco de configuração WPP (begin_wpp configuração e end_wpp) Por exemplo, se você usar o modelo para projetos de driver UMDF ou KMDF no Visual Studio, o modelo definirá as macros WPP para uma função de mensagem de rastreamento personalizada chamada TraceEvents. A função de macro TraceEvents usa Trace Level e Trace Flag como condições para gerar mensagens. Se você tiver definido a macro WPP_LEVEL_FLAGS_ENABLED no arquivo de cabeçalho Trace.h, poderá adicionar a seguinte definição de macro.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

Você também pode converter instruções de impressão de depuração existentes em instruções de mensagens de rastreamento adicionando uma declaração FUNC semelhante no bloco de configuração WPP. Por exemplo, o exemplo a seguir adiciona o código para converter as instruções KdPrint existentes. A declaração FUNC também define globalmente o KdPrint para usar o nível de rastreio especificado e a flag {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}. Em vez de enviar a saída para o depurador, as declarações de impressão de depuração são enviadas para o registo de rastreio.

//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatibility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//

Observação

Se quiseres converter o KdPrintEx numa função de mensagem de rastreamento, precisas de dar alguns passos extra. Em comparação com KdPrint, a função KdPrintEx usa dois argumentos adicionais. Para converter a função KdPrintEx , você precisa definir um WPP_DEFINE_BIT para o ComponentID e definir macros personalizadas WPP_<condição>_LOGGER e WPP_<condição>_ENABLED . O segundo parâmetro para KdPrintEx especifica que o nível de é semelhante aos valores de Nível de Rastreamento , portanto, você não precisa necessariamente redefini-los.


#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(\
    myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \    /* change GUID for your provider */
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID)      /* bit  4 = 0x00000010 */\         /* Added for the ComponentID param of KdPrintEx */
    )

#define WPP_Flags_LEVEL_LOGGER(Flags, level)                                  \
    WPP_LEVEL_LOGGER(Flags)

#define WPP_Flags_LEVEL_ENABLED(Flags, level)                                 \
    (WPP_LEVEL_ENABLED(Flags) && \
    WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)



//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));   
// end_wpp
//

Etapa 3: Inclua os arquivos de cabeçalho de rastreamento associados (.h e .tmh) em seus arquivos de origem C ou C++

Se definiu o GUID de controlo e os sinalizadores de rastreio para o seu controlador num ficheiro de cabeçalho (por exemplo, trace.h), necessitará incluir o ficheiro de cabeçalho nos ficheiros de origem onde irá inicializar e descarregar o WPP (Etapa 4) ou chamar funções de mensagens de rastreio.

Além disso, você precisa adicionar uma instrução #include para Trace Message Header File (.tmh). Quando você cria o driver ou aplicativo, o pré-processador WPP gera os arquivos de cabeçalho de mensagem de rastreamento (.tmh) para cada arquivo de origem que contém funções de mensagem de rastreamento.

/* -- driver.c  - include the *.tmh file that is generated by WPP --*/

#include "trace.h"     /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh"  /* this file is auto-generated */

Etapa 4: Adicionar macros às funções de retorno de chamada apropriadas para inicializar e limpar o WPP

Para inicializar o WPP na introdução do driver

  • Adicione a macro WPP_INIT_TRACING à rotina DriverEntry de um driver de modo kernel ou driver UMDF 2.0 ou à rotina DLLMain de um driver de modo de usuário (UMDF 1.x) ou aplicativo.

Para limpar os recursos do WPP na saída do condutor

  • Adicione a macro WPP_CLEANUP à rotina de descarregamento do driver (por exemplo, DriverContextCleanup ou DriverUnload) de um driver de modo kernel ou driver UMDF 2.0.

    Para um driver de modo de usuário (UMDF 1.x) ou aplicativo, adicione a macro WPP_CLEANUP à rotina DLLMain .

    Você também deve adicionar a macro WPP_CLEANUP à rotina DriverEntry caso o DriverEntry falhe. Por exemplo, se o DriverEntry falhar, a rotina de descarregamento do driver não será chamada. Consulte a chamada para WdfDriverCreate no exemplo a seguir.

Exemplo de um driver de modo kernel usando WPP_INIT_TRACING e WPP_CLEANUP em DriverEntry


NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{  

          //  ... 

                //
    // Initialize WPP Tracing in DriverEntry
    //
    WPP_INIT_TRACING( DriverObject, RegistryPath );

                //  ...


 //
    // Create a framework driver object to represent our driver.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes, // Driver Object Attributes
        &config,          // Driver Config Info
        WDF_NO_HANDLE // hDriver
        );

    if (!NT_SUCCESS(status)) {

        TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDriverCreate failed with status 0x%x\n", status);
        //
        // Cleanup tracing here because DriverContextCleanup will not be called
        // as we have failed to create WDFDRIVER object itself.
        // Please note that if you return failure from DriverEntry after the
        // WDFDRIVER object is created successfully, you don't have to
        // call WPP cleanup because in those cases DriverContextCleanup
        // will be executed when the framework deletes the DriverObject.
        //
        WPP_CLEANUP(DriverObject);

    }

                return status;

}

Exemplo de um driver de modo kernel usando WPP_CLEANUP em DriverContextCleanup



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

Exemplo de driver UMDF 2.0 usando WPP_INIT_TRACING em DriverEntry


/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"


 // Initialize WPP Tracing in the DriverEntry routine
 //
    WPP_INIT_TRACING( MYDRIVER_TRACING_ID );

Exemplo de utilização das macros WPP_INIT_TRACING e WPP_CLEANUP pelo driver UMDF 1.0 no DLLMain

/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"


//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
// 

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);              // Initialize WPP tracing

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();                                                                                                              // Deactivate and cleanup WPP tracing
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Passo 5: Instrumente o código do driver para gerar mensagens de rastreamento em pontos apropriados

Você pode usar qualquer função de mensagem de rastreamento escolhida, desde que a função de mensagem de rastreamento, os sinalizadores de rastreamento e os níveis sejam definidos adequadamente. A função de mensagem de rastreamento padrão é a macro DoTraceMessage . Você pode adicionar essa macro ao seu código para gravar mensagens no arquivo de log. A tabela a seguir lista algumas das funções de mensagem de rastreio pré-estabelecidas e as funções de impressão de depuração que pode usar para criar mensagens de rastreio.

Exemplo de funções de mensagem de rastreamento Quando utilizar
DoTraceMessage Esta é a função de mensagem de rastreamento padrão. A vantagem de usar DoTraceMessage é que a função já está definida para você. Você pode usar os sinalizadores de rastreamento especificados na macro WPP_CONFIG_GUIDS. A desvantagem de usar DoTraceMessage, é que a função usa apenas um parâmetro condicional, ou seja, sinalizadores de rastreamento. Se você quiser usar níveis de rastreamento, para registrar apenas mensagens de erro ou aviso, você pode usar a macro DoDebugTrace ou usar TraceEvents, que usa sinalizadores de rastreamento e níveis de rastreamento.
TraceEvents Se você criar um driver usando modelos WDF no Visual Studio, essa é a função de mensagem de rastreamento padrão. A vantagem de usar TraceEvents é que a função de mensagem de rastreamento, os sinalizadores de rastreamento e o Nível de Rastreamento já estão definidos para você. Além disso, os modelos também incluem instrumentação que grava mensagens no arquivo de log após a entrada e saída da função.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx A vantagem de usar as funções de impressão de depuração é que não precisais modificar as instruções de impressão de depuração existentes. Você pode alternar facilmente da visualização de mensagens no depurador para a gravação de mensagens de rastreamento em um arquivo. Se personalizaste a função de mensagem de seguimento para incluir uma das funções de impressão de depuração, não precisas fazer mais nenhum trabalho. Ao criar uma sessão de rastreamento com o Logman ou o Tracelog, ou outro controlador de rastreamento, basta especificar os sinalizadores e os níveis para seu provedor. Quaisquer declarações de debug que atendam às condições especificadas são registradas no log.

Utilização de declarações DoTraceMessage

  1. Adicione a macro DoTraceMessage ao seu código como faria com uma rotina de impressão de depuração. A macro DoTraceMessage usa 3 parâmetros: o nível do sinalizador (TraceFlagName), que define a condição quando a mensagem de rastreamento é gravada, a cadeia de caracteres Message e a lista de variáveis opcionais.

    DoTraceMessage(TraceFlagName, Message, [VariableList... ])

    Por exemplo, a instrução DoTraceMessage a seguir grava o nome da função que contém a instrução DoTraceMessage quando o sinalizador TRACE_DRIVER, conforme definido em WPP_CONTROL_GUIDS, está habilitado para a sessão de rastreamento.

         DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

    O exemplo utiliza uma cadeia pré-definida para a função atualmente em execução (%FUNC!). Para obter mais informações sobre cadeias de caracteres de especificação de formato definido pelo WPP, consulte O que são as cadeias de caracteres de especificação de formato estendido do WPP?

  2. Para gerar a mensagem de rastreamento, crie uma sessão de rastreamento para seu provedor de rastreamento, usando Logman ou Tracelog, e especifique um sinalizador de rastreamento que defina o sinalizador de TRACE_DRIVER (bit 1, 0x2).

//
//  DoTraceMessage examples
// 

     ...

// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2), 
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.

     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

     ...

// writes the name of the function, the line number, and the error code 

      DoTraceMessage(
            TRACE_DRIVER,
            "[%s] Failed at %d (error code= %d)\n",
            __FUNCTION__,
            __LINE__,
            dwLastError);

Utilização de declarações TraceEvents

Se estiver a usar os modelos de drivers do Windows no Visual Studio, a macro TraceEvents está definida para si no ficheiro de cabeçalho Trace.h.

  1. Adicione a macro TraceEvents ao seu código como se fosse uma rotina de impressão de depuração. A macro TraceEvents usa os seguintes parâmetros: o nível de rastreamento (Level) e o sinalizador de rastreamento (Flags), que definem a condição quando a mensagem de rastreamento é gravada, a cadeia de caracteres Message e a lista de variáveis opcionais.

    TraceEvents(Level, Flags, Message, [VariableList... ])

    Por exemplo, a instrução TraceEvents a seguir grava o nome da função que contém a instrução TraceEvents quando as condições especificadas nos parâmetros Trace Level e Trace Flag são atendidas. O Nível de Rastreamento é um valor inteiro; qualquer coisa no Nível de Rastreamento especificado para essa sessão de rastreamento ou abaixo dele será rastreada. O TRACE_LEVEL_INFORMATION é definido em Evntrace.h e tem o valor 4. O sinalizador TRACE_DRIVER (bit 1, 0x2) é definido em WPP_CONTROL_GUIDS. Se esse bit de TRACE_DRIVER estiver definido para a sessão de rastreamento e o Nível de Rastreamento for 4 ou superior, TraceEvents gravará a mensagem de rastreamento.

            TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

    O exemplo utiliza uma cadeia pré-definida para a função atualmente em execução (%FUNC!). Para obter mais informações sobre cadeias de caracteres de especificação de formato definido pelo WPP, consulte O que são as cadeias de caracteres de especificação de formato estendido do WPP?

  2. Para gerar a mensagem de rastreamento, crie uma sessão de rastreamento para seu provedor de rastreamento, usando Logman ou Tracelog. Especifique um nível de rastreamento para TRACE_LEVEL_INFORMATION (4) ou superior e especifique um nível de rastreamento que defina o TRACE_DRIVER bit (bit 1, 0x2).

//
//  TraceEvents examples
// 


    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

//


    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                       "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");

    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                "Built %s %s\n", __DATE__, __TIME__);

Etapa 6: Modificar o projeto do Visual Studio para executar o pré-processador WPP e criar a solução

O WDK fornece suporte para o pré-processador WPP, para que você possa executar o pré-processador usando o Visual Studio e o ambiente MSBuild.

Para executar o pré-processador WPP

  1. Selecione e segure (ou clique com o botão direito do mouse) o projeto de driver no Gerenciador de Soluções e selecione Propriedades.
  2. Na página de propriedades do projeto, selecione Propriedades de configuração e selecione Rastreamento WPP.
  3. Em Geral, defina a opção Executar WPP como Sim.
  4. Em Linha de Comando, adicione opções adicionais para personalizar o comportamento de rastreamento. Para obter informações sobre o que você pode adicionar, consulte Pré-processador WPP.
  5. Crie o projeto ou a solução para sua configuração e plataforma de destino. Consulte Criando um driver com o WDK.

Para obter informações sobre o processo de compilação, consulte Tarefa TraceWPP e Ambiente de compilação WDK e Visual Studio.

Você também pode executar o pré-processador separadamente do ambiente de compilação usando a ferramenta TraceWPP (TraceWPP.exe). Esta ferramenta está localizada no subdiretório bin/x86 e bin/x64 do WDK.

Etapa 7: Iniciar uma sessão de rastreamento para capturar e verificar suas mensagens de rastreamento

Para verificar se você configurou o rastreamento WPP corretamente, você deve instalar seu driver ou aplicativo em um computador de teste e, em seguida, criar uma sessão de rastreamento para capturar as mensagens de rastreamento. Você pode criar uma sessão de rastreamento para seu provedor de rastreamento, usando qualquer controlador de rastreamento, como Logman, Tracelog ou TraceView. Você pode ter as mensagens gravadas em um arquivo de log ou enviadas para um depurador do kernel. Dependendo das funções de mensagem de rastreamento que você está usando, você precisa especificar os sinalizadores de rastreamento e os níveis de rastreamento que gerarão as mensagens.

Por exemplo, se você estiver usando os níveis de rastreamento definidos em Evntrace.h e quiser capturar TRACE_LEVEL_INFORMATION (4) ou superior, será necessário definir o nível como 4. Quando você define o nível como 4 para a sessão de rastreamento, todas as mensagens informativas (4), de aviso (3), de erro (2) e críticas (1) também serão capturadas, supondo que quaisquer outras condições, como sinalizadores de rastreamento, também sejam satisfeitas.

Para verificar se todas as suas mensagens foram geradas, basta definir o nível de rastreamento e os sinalizadores de rastreamento para valores máximos para que todas as mensagens sejam geradas. Os sinalizadores de rastreamento usam uma máscara de bits (ULONG), para que você possa definir todos os bits (por exemplo, 0xFFFFFFFF). Os níveis de rastreamento são representados por um valor de byte. Por exemplo, se você estiver usando o Logman, poderá especificar 0xFF para cobrir todos os níveis.

(Exemplo) Iniciando uma sessão de rastreamento usando o Logman

logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl 

logman start "myWPP_session"

logman stop "myWPP_session"

(Exemplo) Iniciando uma sessão de rastreamento usando o TraceLog

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

O comando Tracelog inclui o parâmetro -f para especificar o nome e o local do arquivo de log de rastreamento de eventos. Ele inclui o parâmetro -flag para especificar o conjunto de sinalizadores e o parâmetro -level para especificar a configuração de nível. Você pode omitir esses parâmetros, mas alguns provedores de rastreamento não geram mensagens de rastreamento, a menos que você defina o sinalizador ou o nível. O Nível de Traço é definido no ficheiro Evntrace.h, e os níveis de traço fornecem uma forma conveniente de classificar as mensagens de rastreio como críticas, de erro, de aviso e informativas.

  • Last updated on