Windows Driver Kit: Driver Development Tools
WPP Preprocessor
This section describes the Windows Software Trace Preprocessor, commonly known as the WPP preprocessor.
Invoking the WPP Preprocessor
The WPP preprocessor is integrated into the Windows Driver Kit (WDK) build environment. To invoke the default operation of the WPP preprocessor, add the following line to the end of the driver's sources file:
RUN_WPP= $(sources) -km
You can also run the preprocessor separate from the build environment by using Tracewpp (Tracewpp.exe), a tool included in the WDK in the /bin/x86 directory.
Run_WPP Options
The following tables describe the options for the WPP. You can use these options with the Run_WPP directive or as command-line parameters to Tracewpp, a tool included in the WDK in the /bin/x86 directory).
Function and Macro Options
| -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.
|
| -dll | Defines the WPP_DLL macro. When this macro is defined, the WPP data structures are initialized whenever WPP_INIT_TRACING is called. Otherwise, the structures are initialized only once. |
| ‑D Macro | 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 insure that defines are valid at the start of the TMH files..
|
| ‑D Macro=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 insure that defines are valid at the start of the TMH files.
|
| -km | Defines the WPP_KERNEL_MODE macro, which traces kernel-mode components. By default, only user-mode components are traced. |
Search and Formatting Options
| -argbase:Number | Establishes a numeric base for numbering of format strings, such as "%1!d!, %2!s!." The default is 1. |
| ‑func:FunctionDescription | Specifies alternatives to the DoTraceMessage function. 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.
|
| -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`
|
| -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.
|
| -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
| -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.
|
| -defwpp:Path | Specifies an alternate configuration file. WPP uses this file instead of the defaultwpp.ini file (%SYSTEMROOT%\WINDDK\Version\wppconfig\rev1\defaultwpp.ini).
To direct WPP to use a customized configuration file in addition to defaultwpp.ini, use the –ini option.
|
| -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 $(SOURCES) as an input to 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:
RUN_WPP=-ext:.cpp.CPP.h.H
Also, to give the TMH files for the C++ and header files different names, use the -preserveext option.
|
| -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.
|
| -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.
|
| -IPath1[;Path2] | Same as –cfgdir. |
| -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.
|
| -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.
|
| -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.
|
WPP Build Process
If a driver's sources file contains the RUN_WPP directive, running the Build utility in the WDK invokes the WPP preprocessor before compiling the driver files. The WPP build process has the following two steps:
- 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.
- 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.