Pré-processador WPP

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

Para invocar o pré-processador WPP

Clique com o botão direito do mouse no projeto de driver no Gerenciador de Soluções 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 varredura .

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

Opções gerais de rastreamento 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 WPP	Se verdadeiro, invoca WPP.
Habilite a reconstrução mínima	Se verdadeiro, uma compilação incremental controlada é executada; se false, 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 #defineMacro ao início do arquivo gerado, onde Macro é o nome de uma macro. Esta opção tem o mesmo efeito que a opção de compilador /D (definir uma macro). Ele é incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
	-DExpansão =Macro	Adiciona #defineExpansão de Macro ao início do arquivo gerado, onde Macro é o nome de uma macro e Expansão é o valor expandido. Esta opção tem o mesmo efeito que a opção de compilador /D (definir uma macro). Ele é incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
Componentes de rastreio Kernel-Mode	-km	Define a macro WPP_KERNEL_MODE, que rastreia componentes de modo kernel. Por padrão, apenas 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 WPP sejam inicializadas sempre que WPP_INIT_TRACING é chamada. Caso contrário, as estruturas são inicializadas apenas uma vez.
Especificar GUID de controlador	-ctl:GUID	Define uma macro WPP_CONTROL_GUIDS com o GUID de controle especificado e entradas WPP_DEFINE_BIT chamadas Error, Unusual e Noise. 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	-Noshrieks	Orienta o WPP a ignorar os pontos de exclamação, também conhecidos como "gritos". Usado em formatações complexas, 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 a 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:FunçãoDescriçã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 especifique 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 . Esta opção é uma alternativa para especificar descrições de função em um arquivo de configuração local.
Especificar cadeia de caracteres para procurar	-lookfor: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 procura 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`
Especificar nome do módulo	-p:String	Especifica um nome amigável alternativo para o GUID 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 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 que é implementado criando vários provedores de rastreamento. Essas informações ajudam os usuários a associar provedores de rastreamento relacionados que estão em arquivos diferentes ou caminhos diferentes. O parâmetro -p requer a versão do WPP incluída no Kit de Driver do Windows (WDK) 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	-ICaminho1[;Caminho2]	Especifica um ou mais diretórios a serem adicionados ao caminho de inclusão; separar com ponto e vírgula, se houver mais de um. O mesmo que -cfgdir.
Diretórios de configuração	-cfgdir:Caminho1[;Caminho2]	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 dos arquivos	-ext:.ext1[.ext2]	Especifica os tipos de arquivo que o WPP reconhece como arquivos de origem. 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. Esta opção permite que você use as configurações padrão do WPP sem ter que 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 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, os arquivos TMH para arquivos C (.c) e 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. 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 -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.thm .
Analisar dados de configuração	-scan:Arquivo	Procura 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 config 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 que é 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. Wpp usa esse arquivo em vez do arquivo defaultwpp.ini.
Arquivo de configuração adicional	-ini:Caminho	Especifica um arquivo de configuração adicional. 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 construção 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 WPP antes que os arquivos de driver ou aplicativo sejam compilados.

O processo de compilação 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 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.

Feedback

Esta página foi útil?

Last updated on 2025-07-18