Pré-processador WPP

Esta seção descreve o Pré-processador de Rastreamento de Software Windows, comumente conhecido como pré-processador WPP.

Invocando o pré-processador WPP

Você pode invocar o pré-processador WPP usando o Visual Studio e o ambiente MSBuild.

Para invocar o pré-processador WPP

1. Clique com o botão direito do mouse no projeto de driver no Gerenciador de Soluções e clique em Propriedades.

2. Na página de propriedades do projeto, clique em Propriedades de Configuração e clique em Rastreamento WPP

3. Em Geral, defina a opção Executar WPP como Sim.

4. Em Linha de Comando, você pode adicionar opções abaixo para personalizar o comportamento de rastreamento.

   Por exemplo, em Rastreamento WPP, você pode especificar um único arquivo de dados de configuração de verificação.

   Se você precisar fornecer mais de um arquivo de configuração, por exemplo, para especificar tipos de dados personalizados, faça referência ao arquivo na Linha de Comando usando a opção -scan , por exemplo:

   -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
   

Para obter mais informações sobre o processo de build, consulte Tarefa TraceWPP e ambiente de build do WDK e do Visual Studio.

Você também pode executar o pré-processador separado do ambiente de build usando a ferramenta TraceWPP (TraceWPP.exe). Essa ferramenta está localizada no subdiretório bin/x86 do WDK.

Opções gerais de rastreamento do WPP

As tabelas a seguir descrevem as opções para o pré-processador WPP. Você pode configurar essas opções no Visual Studio usando a página de propriedades Rastreamento do WPP para seu projeto ou como parâmetros para a ferramenta TraceWPP.

Opção de rastreamento WPP	Descrição
Executar o WPP	Se true, invoca o WPP.
Habilitar reconstrução mínima	Se true, uma compilação incremental rastreada será executada; Se for falso, uma reconstrução será executada.

Opções de função e macro

Opção de rastreamento WPP	Opção de comando TraceWPP	Descrição
Definições do Pré-processador	-DMacro	Adiciona #define macro ao início do arquivo gerado, onde Macro é o nome de uma macro. Essa opção tem o mesmo efeito que a opção do compilador /D (definir uma macro). Ele é incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
	-DMacro Expansão=	Adiciona #define Expansão de Macro ao início do arquivo gerado, onde Macro é o nome de uma macro e Expansão é o valor expandido. Essa opção tem o mesmo efeito que a opção do compilador /D (definir uma macro). Ele é incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
Rastrear componentes do modo kernel	-km	Define a macro WPP_KERNEL_MODE, que rastreia os componentes do modo kernel. Por padrão, somente os componentes do modo de usuário são rastreados.
Ativar macro Dll	-Dll	Define a macro WPP_DLL, que faz com que as estruturas de dados do WPP sejam inicializadas sempre que WPP_INIT_TRACING é chamada. Caso contrário, as estruturas serão inicializadas apenas uma vez.
Especificar o GUID de controle	-ctl: GUID	Define uma macro WPP_CONTROL_GUIDS com o GUID de controle especificado e WPP_DEFINE_BIT entradas chamadas Erro, Incomum e Ruído. Esta é uma alternativa para adicionar a macro ao arquivo de origem. GUID representa o GUID de controle.

Opções de pesquisa e formatação

Opção de rastreamento WPP	Opção de comando TraceWPP	Descrição
Ignorar pontos de exclamação	-gritos	Orienta o WPP a ignorar os pontos de exclamação, também conhecidos como "gritos". Usado em formatação complexa, como %!timestamp!%. Por padrão, os pontos de exclamação são necessários e o WPP tenta interpretá-los.
Base numérica para numeração de cadeias de caracteres de formato	-argbase: Número	Estabelece uma base numérica para numeração de cadeias de caracteres de formato, como "%1!d!, %2!s!". O padrão é 1.
Função para gerar mensagens de rastreamento	-func: Descrição da função	Especifica alternativas para a macro DoTraceMessage. Essas funções podem ser usadas para gerar mensagens de rastreamento. Por exemplo, você pode definir uma função que especifica os sinalizadores e o nível de uma mensagem de rastreamento, como: -func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...) Você pode usar várias instâncias da opção -func . Essa opção é uma alternativa para especificar descrições de função em um arquivo de configuração local.
Especificar cadeia de caracteres a ser pesquisada	-procurar:String	Direciona o WPP para pesquisar os arquivos de origem para a cadeia de caracteres especificada para iniciar o rastreamento. Por padrão, o WPP pesquisa a cadeia de caracteres "WPP_INIT_TRACING". Esta é uma opção avançada para usuários que estão escrevendo seus próprios modelos. Por exemplo, em default.tpl: IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF
Especifique o nome do módulo	-p: Cadeia de caracteres	Especifica um nome amigável alternativo para o GUID da mensagem desse provedor de rastreamento. Por padrão, o nome amigável do GUID da mensagem é o nome do diretório no qual o provedor de rastreamento foi criado. O nome amigável do GUID da mensagem aparece, por padrão, no prefixo da mensagem de rastreamento representado pela variável %1. Você pode usar esse parâmetro para adicionar uma cadeia de caracteres ao prefixo que ajuda o usuário a identificar o provedor de rastreamento, como o nome amigável do provedor de rastreamento, o nome do módulo que inclui o provedor de rastreamento ou o nome de um projeto implementado pela criação de vários provedores de rastreamento. Essas informações ajudam os usuários a associar provedores de rastreamento relacionados que estão em arquivos ou caminhos diferentes. O parâmetro -p requer a versão do WPP incluída no WDK (Windows Driver Kit) para Windows Vista e versões posteriores do WDK. O parâmetro -p funciona no Windows 2000 e versões posteriores do Windows. Exemplos: -p:TraceDrv -p:AudioModule

Opções de arquivo

Opção de rastreamento WPP	Opção de comando TraceWPP	Descrição
Diretórios de Inclusão Adicionais	-I Caminho1[;Caminho 2]	Especifica um ou mais diretórios a serem adicionados ao caminho de inclusão, separados por ponto e vírgula no caso de mais de um. O mesmo que -cfgdir.
Diretórios de configuração	-cfgdir: Caminho1[;Caminho 2]	Especifica o local dos arquivos de configuração e modelo. Path1 e Path2 representam o caminho totalmente qualificado para um diretório. Você pode especificar vários caminhos. O padrão é o diretório local.
Extensões de arquivo	-Ext:. ext1 [.ext2]	Especifica os tipos de arquivo que o WPP reconhece como arquivos de origem. O WPP ignora arquivos com uma extensão de nome de arquivo diferente. Por padrão, o WPP reconhece apenas arquivos .c, .c++, .cpp e .cxx. Essa opção permite que você use as configurações padrão do WPP sem precisar excluir ou renomear arquivos de recursos que o WPP não usa, como arquivos .rc e .mc. Por exemplo, para adicionar rastreamento a arquivos C++ e arquivos de cabeçalho (.h), use o seguinte comando: -ext:.cpp. CPP.h.H Além disso, para dar nomes diferentes aos arquivos TMH para os arquivos C++ e de cabeçalho, use a opção -preserveext .
Preservar extensões de arquivo	-preserveext: .ext1[.ext2]	Preserva as extensões de nome de arquivo especificadas ao criar arquivos TMH. Por padrão, os arquivos TMH para todos os tipos de arquivo são nomeados filename.tmh. Isso causava conflitos de nome de arquivo quando você tinha mais de um arquivo de origem com o mesmo nome. Por exemplo, por padrão, os arquivos TMH para arquivos C (.c) e arquivos de cabeçalho (.h) seriam nomeados <filename.tmh>. Usando -preserveext:.c .h, os arquivos TMH são nomeados <filename.c.tmh> e <filename.h.tmh>.
Diretório de saída	-odir: caminho	Especifica o diretório para os arquivos de saída que o WPP cria. Caminho é o caminho totalmente qualificado para o diretório. O padrão é o diretório local.
Especificar arquivo de modelo	-gen{ Arquivo.tpl }. ext	Para cada arquivo de origem que o WPP processa com o nome especificado entre chaves {}, crie outro arquivo com a extensão de nome de arquivo especificada. File.tpl representa o arquivo de origem. *.ext representa o tipo de arquivo criado e sua extensão de nome de arquivo. Você pode especificar várias opções de -gen . Por exemplo, -gen{um-default.tpl}.tmh significa que, para cada arquivo um-default.tpl que o WPP processa, ele produz um arquivo um-default.tdh.
Dados de configuração de varredura	-digitalização:Arquivo	Pesquisa dados de configuração, como tipos de dados personalizados, em um arquivo que não é um arquivo de configuração, bem como em defaultwpp.ini. Coloque begin_wpp configuração e end_wpp cadeias de caracteres ao redor dos dados de configuração para identificá-los. Use o mesmo formato para os dados de configuração usado no defaultwpp.ini. Se você adicionou os dados de configuração a um arquivo de configuração personalizado, use o parâmetro -ini .
Arquivo de configuração alternativo	-defwpp: caminho	Especifica um arquivo de configuração alternativo. O Wpp usa esse arquivo em vez do arquivo defaultwpp.ini.
Arquivo de configuração adicional	-ini:Caminho	Especifica um arquivo de configuração adicional. O WPP usa o arquivo especificado além do arquivo padrão, defaultwpp.ini. Use esse parâmetro quando tiver criado um novo arquivo de configuração para armazenar dados de configuração para rastreamento. Se você tiver adicionado os dados de configuração a outro tipo de arquivo, como um arquivo de origem ou de cabeçalho, use o parâmetro -scan .

Processo de construção do WPP

Se o WPP estiver habilitado para um driver ou aplicativo de modo de usuário, a criação do driver ou aplicativo invocará o pré-processador do WPP antes que os arquivos de driver ou aplicativo sejam compilados.

O processo de compilação do WPP conclui as seguintes etapas:

1. O pré-processador WPP processa macros WPP em cada arquivo de origem e cria um arquivo de cabeçalho de mensagem de rastreamento para cada arquivo de origem. O código-fonte não é modificado diretamente.

2. Depois que o pré-processador WPP tiver criado os arquivos de cabeçalho da mensagem de rastreamento, o pré-processador C processará as macros WPP internas nos arquivos de cabeçalho da mensagem de rastreamento de maneira normal.