Edit

Using WPP Software Tracing in KMDF Drivers

  • Article

WPP software tracing enables you to add tracing messages that help you debug your driver. Additionally, the framework's event logger provides hundreds of tracing messages that you can view.

You can view tracing messages by using TraceView or Tracelog. You can also send trace messages to a kernel debugger.

Adding Tracing Messages to Your Driver

To add tracing messages to your framework-based driver, you must:

  • Add an #include directive to each of your driver's source files that contains any of the WPP macros. This directive must identify a trace message header (TMH) file. The file name must have a format of <driver-source-file-name>.tmh.

    For example, if your driver consists of two source files, called MyDriver1.c and MyDriver2.c, then MyDriver1.c must contain:

    #include "MyDriver1.tmh"

    and MyDriver2.c must contain:

    #include "MyDriver2.tmh"

    When you build your driver in Microsoft Visual Studio, the WPP preprocessor generates the .tmh files.

  • Define a WPP_CONTROL_GUIDS macro in a header file. This macro defines a GUID and trace flags for your driver's tracing messages.

  • Include a WPP_INIT_TRACING macro in your driver's DriverEntry routine. This macro activates software tracing in your driver.

  • Include a WPP_CLEANUP macro in your driver's EvtDriverUnload callback function. This macro deactivates software tracing in your driver.

  • Use the DoTraceMessage macro, or a customized version of the macro, in your driver to create trace messages.

  • Open the Property Pages for your driver project. Right-click the driver project in Solution Explorer and select Properties. In the Property Pages for the driver, click Configuration Properties, and then Wpp Tracing. Under the General menu, set Run WPP Tracing to Yes. Under the File Options menu, you should also specify the framework's WPP template file, for example:

    {km-WdfDefault.tpl}*.tmh

  • To specify additional WPP trace settings for your driver project in Visual Studio, right-click on the driver project in Solutions Explorer. Then follow the link to Properties->Configuration Properties->WPP Tracing.

  • To specify a trace configuration file use the 'Scan Configuration Data' setting. For more than one trace configuration file add it under the 'Command Line'-> 'Additional Options' as follows

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

    For more information about adding tracing messages to your driver, see Adding WPP Macros to a Driver.

Sample Drivers That Use WPP Software Tracing

The AMCC5933, NONPNP, KMDF_FX2, PCIDRV, PLX9x5x, and Serial sample drivers use WPP software tracing.