Windows software trace preprocessor


The Windows software trace preprocessor is a preprocessor that simplifies the use of WMI event tracing to implement efficient software tracing in drivers and applications that target Windows 2000 and later operating systems. WPP was created by Microsoft and is included in the Windows DDK. Although WPP is wide in its applicability, it is not included in the Windows SDK, and therefore is primarily used for drivers and driver support software produced by software vendors that purchase the Windows DDK.

Background

Software tracing is a specialized use of logging to record information about a program's execution. This information is commonly used for debugging. In contrast to event logging, the primary purpose of which is to produce records of events that can be audited by system administrators or analyzed by management tools, software tracing is primarily a debugging aid for software developers. As such, many of the non-functional requirements of event logging, such as localizability or a standards-based output format, are explicitly non-goals for most applications of software tracing. On the other hand, software tracing has special requirements for performance that are not generally as important in event logging. For example, one common use of software tracing, in/out tracing, produces output at the entry point and return of functions or methods so that a developer can visually follow the execution path, often including parameters and return values, in a debugger or text-based log file. This type of tracing, although useful for developers, can greatly hurt performance of a software product if it cannot be disabled.
Additional considerations special to software tracing include the following:
Due to the first two considerations, traditional methods of software tracing use conditional compilation to enable or disable tracing at compile-time. For example, using the C preprocessor, one might define a macro DebugOut as follows:
#ifdef _DEBUG
#define DebugOut \
DebugPrintf
#else
#define DebugOut
#endif
where TO_STRING is a macro that converts the line number to a string and DebugPrintf is a printf-like function that might for example output text to the debugger.
Then, the following code:
DebugOut;
would produce output similar to the following on debug builds only:
SomeFunction Error 217 occurred
Another technique for certain types of tracing is to use instrumentation. While this technique can address many of the major concerns, it is not always available.
WMI event tracing is an example of a technology that addresses in particular performance of tracing in performance-critical code such as drivers. It can also address the concern of controlling the distribution of sensitive trace information by letting a developer define the human-readable tracing data separately from the code so that it is not built into the product. However, there are some important limitations:
WPP is run prior to compilation, and generates a trace message header for each file that it processes. This header must then be explicitly included into the source file, for example:
// File: file.cxx
// This file is an example of using WPP
#include "file.tmh"
WPP's understanding of C/C++ syntax is very limited. In particular, it does not expand macros, nor does it handle pragmas or perform any semantic analysis.
A developer specifies one or more tracing macros that WPP should handle, via a configuration file, special annotations in comments, command line parameters, or some combination of these methods. Each time WPP encounters one of the macros that it is supposed to handle, it generates a trace message macro. In other words, if for example DoTrace is a tracing macro, WPP will generate a separate macro for each occurrence of DoTrace. The generated trace message macros are disambiguated by file name and line number, and, using various preprocessor tricks, WPP in turn defines the original tracing macro so that it will expand the appropriate trace message macro at each occurrence.
How trace message macros are generated by WPP depends on a template file. The default template files included with WPP specify that the string of a trace message should be included in an annotation. These strings are not included in the compiled code, but are included in the debugger symbol file in a format that tools included with WPP can understand. The trace message macros also include the logic for enabling or disabling tracing via flags and the calls to WMI event tracing APIs.

Limitations

#define CheckForErrors \
if \

then WPP will not generate the trace message macros for DoTrace where CheckForErrors occurs. WPP provides an ad hoc workaround for this issue, but there still exists a small class of macros that cannot be expressed even using the workaround.