Pré-processador WPP

Artigo
06/15/2023

Esta seção descreve o pré-processador de rastreamento de software do Windows, comumente conhecido como o pré-processador WPP.

Invocando o pré-processador WPP

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

Para invocar o pré-processador WPP

Clique com o botão direito do mouse no projeto de driver em Soluções Explorer e clique em Propriedades.
Na página de propriedades do projeto, clique em Propriedades de Configuração e clique em Rastreamento WPP
Em Geral, defina a opção Executar WPP como Sim.
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 TraceWPP task e WDK and Visual Studio build environment.

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 WPP para seu projeto ou como parâmetros para a ferramenta TraceWPP.

Opção de rastreamento WPP	Descrição
Executar o WPP	Se for true, invocará o WPP.
Habilitar Recompilação Mínima	Se for true, uma compilação incremental controlada será executada; se false, uma recompilaçã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	Macro -D	Adiciona #defineMacro ao início do arquivo gerado em que Macro é o nome de uma macro. Essa opção tem o mesmo efeito que a opção do compilador /D (definir uma macro). Ele está incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
	Expansão da macro=-D	Adiciona #defineExpansão de Macro ao início do arquivo gerado, em que 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 está incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
Componentes de Kernel-Mode de rastreamento	-km	Define a macro WPP_KERNEL_MODE, que rastreia componentes do modo kernel. Por padrão, somente os componentes do modo de usuário são rastreados.
Habilitar macro DLL	-Dll	Define a macro WPP_DLL, que faz com que as estruturas de dados WPP sejam inicializadas sempre que WPP_INIT_TRACING é chamado. Caso contrário, as estruturas serão inicializadas apenas uma vez.
Especificar GUID de Controle	-ctl:GUID	Define uma macro WPP_CONTROL_GUIDS com o GUID de controle e as entradas de WPP_DEFINE_BIT especificadas denominadas Erro, Incomum e Ruído. Essa é 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	-noshrieks	Direciona o WPP a ignorar 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:Number	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:FunctionDescription	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	-lookfor:String	Direciona o WPP para pesquisar os arquivos de origem para que a cadeia de caracteres especificada inicie o rastreamento. Por padrão, o WPP pesquisa a cadeia de caracteres "WPP_INIT_TRACING". Essa é 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`
Especificar o nome do módulo	-p:String	Especifica um nome amigável alternativo para o GUID da mensagem de mensagens 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 de 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 diferentes arquivos ou caminhos diferentes. O parâmetro -p requer a versão do WPP incluída no WDK (Kit de Driver do Windows) 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	-IPath1[;Caminho2]	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:Path1[;Caminho2]	Especifica o local dos arquivos de configuração e de 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 recurso 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 aos arquivos TMH para os arquivos C++ e de cabeçalho nomes diferentes, 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 causou conflitos de nome de arquivo quando você tem mais de um arquivo de origem com o mesmo nome. Por exemplo, por padrão, 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:path	Especifica o diretório para os arquivos de saída que o WPP cria. Path é o caminho totalmente qualificado para o diretório. O padrão é o diretório local.
Especificar arquivo de modelo	-gen{ File.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 que é criado e sua extensão de nome de arquivo. Você pode especificar várias opções de geração* . 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.tmh .
Verificar dados de configuração	-scan:File	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 em torno dos dados de configuração para identificá-los. Use o mesmo formato para os dados de configuração usados 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:path	Especifica um arquivo de configuração alternativo. O Wpp usa esse arquivo em vez do arquivo defaultwpp.ini.
Arquivo de configuração adicional	-ini:Path	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ê adicionou 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 build do WPP

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

O processo de build do WPP conclui as seguintes etapas:

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.
Depois que o pré-processador WPP tiver criado os arquivos de cabeçalho de mensagem de rastreamento, o pré-processador C processará as macros WPP internas nos arquivos de cabeçalho de mensagem de rastreamento de maneira normal.

Compartilhar via