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 do 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 a tarefa TraceWPP e o 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 de Rastreamento do WPP para seu projeto ou como parâmetros para a ferramenta TraceWPP.

Opção de rastreamento do WPP	Descrição
Executar WPP	Caso verdadeiro, invocará o WPP.
Habilitar recompilação mínima	Se for true, um build incremental acompanhado será executado; se for falso, uma recompilação será executada.

Opções de função e macro

Opção de rastreamento do WPP	Opção de comando TraceWPP	Descrição
Definições do Pré-processador	-DMacro	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 é 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 é incluído para garantir que as definições sejam válidas no início dos arquivos TMH.
Rastrear componentes de Kernel-Mode	-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 do WPP sejam inicializadas sempre que WPP_INIT_TRACING for chamado. 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 as entradas guid de controle e WPP_DEFINE_BIT especificadas chamadas Erro, Incomum e Ruído. Essa é uma alternativa para adicionar a macro ao arquivo de origem. O GUID representa o GUID de controle.

Opções de pesquisa e formatação

Opção de rastreamento do WPP	Opção de comando TraceWPP	Descrição
Ignorar pontos de exclamação	-noshrieks	Orienta o WPP a ignorar pontos de exclamação, também conhecidos como "gritos". Usado em formatação complexa, como %!timestamp!%. Por padrão, 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 à 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 para pesquisar	-lookfor:String	Orienta o WPP a pesquisar os arquivos de origem para que a cadeia de caracteres especificada inicie o rastreamento. Por padrão, o WPP faz a busca pela string "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 alternativo mais apropriado para o GUID da mensagem destinado ao 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 (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 do WPP	Opção de comando TraceWPP	Descrição
Diretórios de Inclusão Adicionais	-IPath1[;Path2]	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[;Path2]	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 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 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. O caminho é o caminho totalmente especificado 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 -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.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 config 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 em 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: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 você 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 cabeçalho, use o parâmetro -scan .

Processo de build do WPP

Se o WPP estiver habilitado para um driver ou aplicativo no 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 internas do WPP nos arquivos de cabeçalho da mensagem de rastreamento de maneira normal.

Comentários

Esta página foi útil?

Last updated on 2025-07-18