WPP Preprocessor

This section describes the Windows Software Trace Preprocessor, commonly known as the WPP preprocessor.

Invoking the WPP Preprocessor

You can invoke the WPP preprocessor using Visual Studio and the MSBuild environment.

To invoke the WPP preprocessor

1. Right-click the driver project in Solutions Explorer and click Properties.

2. In the project property page, click Configuration Properties and click WPP Tracing

3. Under General, set the Run WPP option to Yes.

4. Under Command Line, you can add options below to customize tracing behavior.

   For example, under WPP Tracing, you can specify a single Scan Configuration Data file.

   If you need to provide more than one configuration file, for instance to specify custom data types, reference your file in Command Line using the -scan option, for example:

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

For more information about the build process, see TraceWPP task and WDK and Visual Studio build environment.

You can also run the preprocessor separate from the build environment by using the TraceWPP tool (TraceWPP.exe). This tool is located in the bin/x86 subdirectory of the WDK.

WPP Tracing General Options

The following tables describe the options for the WPP preprocessor. You can configure these options in Visual Studio using the WPP Tracing property page for your project, or as parameters to the TraceWPP tool.

WPP Tracing Option	Description
Run WPP	If true, invokes WPP.
Enable Minimal Rebuild	If true, a tracked incremental build is performed; if false, a rebuild is performed.

Function and Macro Options

WPP Tracing Option	TraceWPP command option	Description
Preprocessor Definitions	-DMacro	Adds #define Macro to the beginning of the generated file where Macro is the name of a macro. This option has the same effect as the /D (define a macro) compiler option. It is included to ensure that defines are valid at the start of the TMH files.
	-DMacro=Expansion	Adds #define Macro Expansion to the beginning of the generated file where Macro is the name of a macro and Expansion is the expanded value. This option has the same effect as the /D (define a macro) compiler option. It is included to ensure that defines are valid at the start of the TMH files.
Trace Kernel-Mode Components	-km	Defines the WPP_KERNEL_MODE macro, which traces kernel-mode components. By default, only user-mode components are traced.
Enable Dll Macro	-dll	Defines the WPP_DLL macro, which causes the WPP data structures to be initialized whenever WPP_INIT_TRACING is called. Otherwise, the structures are initialized only once.
Specify Control GUID	-ctl: GUID	Defines a WPP_CONTROL_GUIDS macro with the specified control GUID and WPP_DEFINE_BIT entries named Error, Unusual, and Noise. This is an alternative to adding the macro to the source file. GUID represents the control GUID.

Search and Formatting Options

WPP Tracing Option	TraceWPP command option	Description
Ignore Exclamation Marks	-noshrieks	Directs WPP to ignore exclamation marks, also known as "shrieks." Used in complex formatting, such as %!timestamp!%. By default, exclamation marks are required and WPP tries to interpret them.
Numeric base for numbering of format strings	-argbase: Number	Establishes a numeric base for numbering of format strings, such as "%1!d!, %2!s!." The default is 1.
Function To Generate Trace Messages	-func: FunctionDescription	Specifies alternatives to the DoTraceMessage macro. These functions can then be used to generate trace messages. For example, you can define a function that specifies both the flags and the level for a trace message, such as: -func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...) You can use multiple instances of the -func option. This option is an alternative to specifying function descriptions in a local configuration file.
Specify String To Search For	-lookfor:String	Directs WPP to search the source files for the specified string to initiate tracing. By default, WPP searches for the string "WPP_INIT_TRACING." This is an advanced option for users who are writing their own templates. For example, in default.tpl: IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF
Specify Module Name	-p: String	Specifies an alternate friendly name for the message GUID of messages from this trace provider. By default, the friendly name of the message GUID is the name of the directory in which the trace provider was built. The friendly name of the message GUID appears, by default, in the trace message prefix that is represented by the variable, %1. You can use this parameter to add a string to the prefix that helps the user to identify the trace provider, such as the friendly name of the trace provider, the name of the module that includes the trace provider, or the name of a project that is implemented by creating several trace providers. This information helps users to associate related trace providers that are in different files or different paths. The -p parameter requires the version of WPP that is included in the Windows Driver Kit (WDK) for Windows Vista and later versions of the WDK. The -p parameter works on Windows 2000 and later versions of Windows. Examples: -p:TraceDrv -p:AudioModule

File Options

WPP Tracing Option	TraceWPP command option	Description
Additional Include Directories	-I Path1[;Path2]	Specifies one or more directories to add to the include path; separate with semi-colons if more than one. Same as -cfgdir.
Configuration Directories	-cfgdir: Path1[;Path2]	Specifies the location of configuration and template files. Path1 and Path2 represent the fully qualified path to a directory. You can specify multiple paths. The default is the local directory.
File Extensions	-ext:. ext1 [.ext2]	Specifies the file types that WPP recognizes as source files. WPP ignores files with a different file name extension. By default, WPP recognizes only .c, .c++, .cpp, and .cxx files. This option allows you to use the default settings for WPP without having to delete or rename resource files that WPP doesn't use, such as .rc and .mc files. For example, to add tracing to C++ files and header (.h) files, use the following command: -ext:.cpp.CPP.h.H Also, to give the TMH files for the C++ and header files different names, use the -preserveext option.
Preserve File Extensions	-preserveext: .ext1[.ext2]	Preserves the specified file name extensions when creating TMH files. By default, TMH files for all file types are named filename.tmh. This caused file name conflicts when you have more than one source file with the same name. For example, by default, TMH files for C files (.c) and header (.h) files would be named <filename>.tmh. By using -preserveext:.c .h, the TMH files are named <filename>.c.tmh and <filename>.h.tmh.
Output Directory	-odir: path	Specifies the directory for the output files that WPP creates. Path is the fully qualified path to the directory. The default is the local directory.
Specify Template File	-gen{ File.tpl }. ext	For every source file that WPP processes with the name specified between braces {}, create another file with the specified file name extension. File.tpl represents the source file. *.ext represents the type of file that is created and its file name extension. You can specify multiple -gen options. For example, -gen{um-default.tpl}.tmh means that for every um-default.tpl file that WPP processes, it produces a um-default.tmh file.
Scan Configuration Data	-scan:File	Searches for configuration data, such as custom data types, in a file that is not a configuration file, as well as in defaultwpp.ini. Place begin_wpp config and end_wpp strings around the configuration data to identify it. Use the same format for the configuration data as is used in defaultwpp.ini. If you added the configuration data to a custom configuration file, use the -ini parameter.
Alternate Configuration File	-defwpp:path	Specifies an alternate configuration file. Wpp uses this file instead of the defaultwpp.ini file.
Additional Configuration File	-ini:Path	Specifies an additional configuration file. WPP uses the specified file in addition to the default file, defaultwpp.ini. Use this parameter when you have created a new configuration file to store configuration data for tracing. If you have added the configuration data to another type of file, such as a source or header file, use the -scan parameter.

WPP Build Process

If WPP is enabled for a driver or user-mode application, building the driver or application invokes the WPP preprocessor before the driver or application files are compiled.

The WPP build process completes the following steps:

1. The WPP preprocessor processes WPP macros in each source file and creates a trace message header file for each source file. The source code is not directly modified.

2. After the WPP preprocessor has created the trace message header files, the C preprocessor processes the built-in WPP macros in the trace message header files in a normal manner.