WPP 预处理器

  • 项目

本部分介绍 Windows 软件跟踪预处理器，通常称为 WPP 预处理器。

调用 WPP 预处理器

可以使用 Visual Studio 和 MSBuild 环境调用 WPP 预处理器。

调用 WPP 预处理器

  1. 在“解决方案资源管理器”中右键单击驱动程序项目，然后单击“ 属性”。

  2. 在项目属性页中，单击“配置属性”，然后单击“WPP 跟踪”

  3. 在 “常规”下，将 “运行 WPP ”选项设置为 “是”。

  4. 在 “命令行”下，可以添加以下选项来自定义跟踪行为。

    例如，在“WPP 跟踪”下，可以指定单个扫描配置文件。

    如果需要提供多个配置文件（例如指定自定义数据类型），请使用 -scan 选项在命令行中引用文件，例如：

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

有关生成过程的详细信息，请参阅 TraceWPP 任务 和 WDK 和 Visual Studio 生成环境。

还可以使用 TraceWPP 工具 (TraceWPP.exe) 运行独立于生成环境的预处理器。 此工具位于 WDK 的 bin/x86 子目录中。

WPP 跟踪常规选项

下表描述了 WPP 预处理器的选项。 可以使用项目的 WPP 跟踪属性页或作为 TraceWPP 工具的参数在 Visual Studio 中配置这些选项。

WPP 跟踪选项 说明

运行 WPP

如果为 true，则调用 WPP。

启用最小重新生成

如果为 true，则执行跟踪的增量生成;如果为 false，则执行重新生成。

函数和宏选项

WPP 跟踪选项 TraceWPP 命令选项 说明

预处理器定义

-D宏

将 #define宏 添加到生成的文件的开头，其中 宏 是宏的名称。

此选项的效果与 /D (定义宏) 编译器选项相同。 包含它可确保定义在 TMH 文件的开头有效。

-D宏=扩展

将 #define宏扩展 添加到生成的文件的开头，其中 宏 是宏的名称， 而扩展 是扩展值。

此选项的效果与 /D (定义宏) 编译器选项相同。 包含它可确保定义在 TMH 文件的开头有效。

跟踪Kernel-Mode组件

-公里

定义跟踪内核模式组件的WPP_KERNEL_MODE宏。 默认情况下，仅跟踪用户模式组件。

启用 Dll 宏

-Dll

定义 WPP_DLL 宏，这会导致在调用WPP_INIT_TRACING时初始化 WPP 数据结构。 否则，结构仅初始化一次。

指定控件 GUID

-ctl：GUID

 定义具有指定控件 GUID 的WPP_CONTROL_GUIDS宏，并WPP_DEFINE_BIT名为“错误”、“异常”和“干扰”的条目。

这是将宏添加到源文件的替代方法。

GUID 表示控件 GUID。

搜索和格式设置选项

WPP 跟踪选项 TraceWPP 命令选项 说明

忽略感叹号

-noshrieks

指示 WPP 忽略感叹号，也称为“shriek”。

用于复杂格式设置，如 %！timestamp！%。 默认情况下，感叹号是必需的，WPP 会尝试解释它们。

格式字符串编号的数值基数

-argbase：Number

为格式字符串的编号建立数字基数，例如“%1！d！， %2！s！”。 默认值为 1。

用于生成跟踪消息的函数

-func：FunctionDescription

指定 DoTraceMessage 宏的替代项。 然后，可以使用这些函数来生成跟踪消息。

例如，可以定义一个函数，该函数指定跟踪消息的标志和级别，例如：

-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)

可以使用 -func 选项的多个实例。

此选项是在本地配置文件中指定函数说明的替代方法。

指定要搜索的字符串

-lookfor：String

指示 WPP 在源文件中搜索指定字符串以启动跟踪。 默认情况下，WPP 搜索字符串“WPP_INIT_TRACING”。

对于正在编写自己的模板的用户，这是一个高级选项。

例如，在 default.tpl 中：

IF FOUND WPP_INIT_TRACING
 INCLUDE um-init.tpl
ENDIF

指定模块名称

-p：String

指定来自此跟踪提供程序的消息的消息 GUID 的备用友好名称。 默认情况下，消息 GUID 的友好名称是在其中生成跟踪提供程序的目录的名称。

默认情况下，消息 GUID 的友好名称显示在变量 %1 表示的跟踪消息前缀中。 可以使用此参数将字符串添加到前缀，以帮助用户标识跟踪提供程序，例如跟踪提供程序的友好名称、包含跟踪提供程序的模块的名称，或者通过创建多个跟踪提供程序实现的项目的名称。 此信息可帮助用户关联位于不同文件或不同路径中的相关跟踪提供程序。

-p 参数需要 Windows Vista 和更高版本的 WDK 的 Windows 驱动程序工具包 (WDK) 中包含的 WPP 版本。 -p 参数适用于 Windows 2000 及更高版本的 Windows。

示例：

-p:TraceDrv
-p:AudioModule

文件选项

WPP 跟踪选项 TraceWPP 命令选项 说明

附加包含目录

-IPath1[;Path2]

指定一个或多个要添加到包含路径中的目录；存在多个目录时，请用分号分隔。 与 -cfgdir 相同。

配置目录

-cfgdir：Path1[;Path2]

指定配置和模板文件的位置。

Path1 和 Path2 表示目录的完全限定路径。 可以指定多个路径。 默认值为本地目录。

文件扩展名

-内线：。ext1[.ext2]

指定 WPP 识别为源文件的文件类型。 WPP 忽略具有不同文件扩展名的文件。

默认情况下，WPP 仅识别 .c、.c++、.cpp 和 .cxx 文件。

此选项允许使用 WPP 的默认设置，而无需删除或重命名 WPP 不使用的资源文件，例如 .rc 和 .mc 文件。

例如，若要将跟踪添加到 C++ 文件和标头 (.h) 文件，请使用以下命令：

-ext：.cpp。CPP.h.H

此外，若要为 C++ 的 TMH 文件和头文件提供不同的名称，请使用 -preserveext 选项。

保留文件扩展名

-preserveext：.ext1[.ext2]

创建 TMH 文件时保留指定的文件扩展名。

默认情况下，所有文件类型的 TMH 文件都命名为 filename.tmh。 如果有多个具有相同名称的源文件，这会导致文件名冲突。

例如，默认情况下，C 文件的 TMH 文件 (.c) 和标头 (.h) 文件将命名为 <filename.tmh>。 通过使用 -preserveext：.c .h，TMH 文件名为 <filename.c.tmh> 和 <filename.h.tmh>。

输出目录

 -odir：path

指定 WPP 创建的输出文件的目录。

Path 是目录的完全限定路径。 默认值为本地目录。

指定模板文件

-gen{ File.tpl }. ext

对于 WPP 处理的每个源文件，在大括号 {}之间指定了名称，请创建另一个具有指定文件扩展名的文件。

File.tpl 表示源文件。 *.ext 表示创建的文件类型及其文件扩展名。

可以指定多个 代 选项。

例如， -gen{um-default.tpl}.tmh 意味着对于 WPP 处理的每个 um-default.tpl 文件，它都会生成 um-default.tmh 文件。

扫描配置数据

-scan：File

在不是配置文件的文件中以及defaultwpp.ini中搜索配置数据（如自定义数据类型）。

在配置数据周围放置begin_wpp配置和end_wpp字符串以标识它。 对配置数据使用与 defaultwpp.ini 中使用的格式相同。

如果将配置数据添加到自定义配置文件，请使用 -ini 参数。

备用配置文件

-defwpp：path

指定备用配置文件。 Wpp 使用此文件而不是defaultwpp.ini文件。

其他配置文件

-ini：Path

指定其他配置文件。 WPP 除了默认文件之外，还使用指定的文件，defaultwpp.ini。

创建新的配置文件来存储用于跟踪的配置数据时，请使用此参数。 如果已将配置数据添加到另一种类型的文件（如源文件或头文件），请使用 -scan 参数。

WPP 生成过程

如果为驱动程序或用户模式应用程序启用了 WPP，则生成驱动程序或应用程序将在编译驱动程序或应用程序文件之前调用 WPP 预处理器。

WPP 生成过程完成以下步骤：

  1. WPP 预处理器处理每个源文件中的 WPP 宏，并为每个源文件创建 跟踪消息头文件 。 不会直接修改源代码。

  2. WPP 预处理器创建跟踪消息头文件后，C 预处理器以正常方式处理跟踪消息头文件中的内置 WPP 宏。