Authored by Eliyas Yakub [MSFT] and Robert Zhao [MSFT]

Most Microsoft-provided drivers, included in Windows, enable WPP tracing for debugging purposes. It’s easier to debug when there are trace messages available. The source binary contains trace messages, however to parse them in a readable form, you need formatting instructions. Those instructions are included in the associated private symbol file. They were not in the public symbol file, until Windows 8.

Note    There are two types of symbol files (PDB): private PDBs and public PDBs. A private PDB is intended for internal use whereas a public PDB is used by the consumers of your binary.

A private PDB is a symbol file that contains private symbol data and has all debugging information. This type of PDB also contains a public symbol table, which is a subset of private symbol data. A public PDB only contains the public symbol table. The build process generates the public PDB by removing the private symbol data from the private PDB. That is done for security reasons. For more information, see Public and Private Symbols.

Before Windows 8, it was not possible to include formatting information (contained in TMF files) in public PDBs. As a workaround, the TMF files had to be updated and uploaded frequently so that they were in-sync with the associated symbol files. For more information about that mechanism, read our previous blog post, that describes how to collect and parse WPP tracing from Microsoft-provided driver, Winusb.sys. 

In Windows 8, the build and other WPP utilities have been enhanced to include trace messages in public PDBs. You can use the symbol file to capture WPP trace messages without worrying about out-of-sync TMF and symbol files.

In this blog post, we’ll describe:

Including TMF information in public PDB files

During the build process, the WPP preprocessor creates a TMH file for each source file that contains WPP trace macros. A TMH file contains trace messages, annotations, and formatting instructions for the PDB file. The build process uses TMH and source files to include WPP trace messages and formatting instructions into the PDB file. The trace message formatting instructions are contained in the PDB and can be extracted into TMF files either by the build process or manually (by using TracePdb.exe).

In order to make some of those WPP trace messages public, special markers are required for each message. The markers are indicated by the –public switch in the WPP command line. In Windows 8, the switch –public:<funcName> was added to the WPP preprocessor so that it can  keep <funcName> trace annotations in the public PDB file. 

To specify that switch, in your project settings in Visual Studio, select WPP Tracing->Command Line. On the right pane, in the Additional Options box, type the following: -func:DoTrace(FLAGS,MSG,...) \
-public:DoTrace \
-func:TraceEnter(LEVEL,MSG,…)

In the preceding snippet, the –public switch declares this trace macro as public:
DoTrace(InfoFlag, “This is number %d”, 5);

This trace macro is declared as private:
TraceEnter(InfoFlag, “This is enter %d”, 5);

The annotations generated from the –public macros are not stripped by post-build scripts while generating public symbols. Annotations, found in the TMH files, are declared with the “PUBLIC_TMF:” argument, which prevents trace message formatting instructions from being removed from the public PDB files. For example, an annotation that is declared as __annotation (L"TMF:", L"..Message contents"), is removed by post-build scripts, while an annotation declared as __annotation(L"TMF:", L"Message contents", L”PUBLIC_TMF:”) appear in the public symbol files.

For more information about TMF and TMH files, see Trace Message Format File and Trace Message Header File.

Capturing WPP traces

After building the PDB files with the TMF files, let’s capture WPP trace messages. These examples use the Usbhub3.sys driver to demonstrate the capture process.

To capture WPP trace messages:

  1. Get the PDB file for the binary that contains WPP trace messages.

    This command downloads the PDB that matches the specified binary file to the specified local directory. For more information about Microsoft symbol servers, see Use the Microsoft Symbol Server to obtain debug symbol files.

    Symchk.exe <binary file> /s SRV*<local directory to download symbols to>*<symbol server>

    The SymChk.exe utility is included with the Debugging Tools for Windows package.

    For this example, get the PDB file from Microsoft’s public symbol server for the Usbhub3.sys binary.

    C:\Symbols> symchk C:\windows\system32\drivers\USBHUB3.SYS /s SRV*C:\Symbols*http://msdl.microsoft.com/downloads/symbols
     
    SYMCHK: FAILED files = 0
    SYMCHK: PASSED + IGNORED files = 1
    
  2. Capture WPP trace messages. You need these tools:
    • Logman is located under %SystemRoot%\System32.
    • TraceView is included in the Windows Driver Kit (WDK) that can be download from this Web site.

Capturing WPP Traces – Logman

Logman requires a provider control GUID. That GUID is used by various tools to capture WPP traces. To obtain the GUID from the PDB file:

  1. Generate MOF file from the PDB file.
  2. Obtain control GUID from the MOF file.

This command uses TracePdb to generate TMF and MOF files. The MOF file is a text file that contains information about available trace levels and flags. In that file there is a line beginning with the text “guid.” The GUID string found on that line is the control GUID.

Tracepdb.exe –f <PdbFileName>

Note: The GUID-like string after the Usbhub3.pdb is not the actual control GUID.

C:\Symbols\usbhub3.pdb\615C8CDF22AC4981BB401198E1401C8E2> tracepdb -f .\usbhub3.pdb
 
Microsoft (R) TracePDB.Exe (6.2.9200.16384)
¬ Microsoft Corporation. All rights reserved.
 
tracepdb : info BNP0000: WPPFMT generating C:\Symbols\usbhub3.pdb\615C8CDF22AC4981BB401198E1401C8E2\749f920d-df37-7bf8-0256-e5c753a59da1.tmf for .\usbhub3.pdb
…
tracepdb : info BNP0000: WPPFMT generating C:\Symbols\usbhub3.pdb\615C8CDF22AC4981BB401198E1401C8E2\010c9ba0-ef1b-f21c-407c-ab69a04c7445.tmf for .\usbhub3.pdb

 

This example generates TMF files and a MOF file from Usbhub3.pdb. Here is a part of Usbhub3.mof with the control GUID used for WPP tracing.

//
// WPP Generated File
// PDB:  .\usbhub3.pdb
// PDB:  Last Updated :2012-8-9:23:35:32:0 (UTC) [tracepdb]
//
 
//ModuleName = usbhub3USBHUB3 (Init called in Function _DriverEntry@8)
[Dynamic,
 Description("usbhub3_USBHUB3"),
 guid("{6E6CC2C5-8110-490e-9905-9F2ED700E455}"),
 locale("MS\\0x409")]
…

Notice the line that starts with “guid”, this is the control GUID.

…
guid("{6E6CC2C5-8110-490e-9905-9F2ED700E455}"),
…

Next, capture the trace as shown here:

logman start -ets UsbHub3Trace -p {6E6CC2C5-8110-490e-9905-9F2ED700E455} 0xffffffff 0x04  -o “C:\WPP Traces\usbHub3.etl”
…
<Connect your USB device to a SuperSpeed port>
…
logman stop -ets UsbHub3Trace

Capturing WPP Traces –TraceView

Save ETL traces and view them in real-time by using TraceView. For more information and detailed instructions, see Create a Trace Session with a PDB File.

  1. Start TraceView.
  2. On the File menu, click Create New Log Session.
  3. Click Add Provider->Click PDB (Debug Information) File, and then type the path to the PDB symbol file. For this example, PDB is set to: C:\Symbols\usbhub3.pdb\615C8CDF22AC4981BB401198E1401C8E2\usbhub3.pdb
  4. Click Next.
  5. Enter Log Session Name. This example sets it to UsbHub3.
  6. To save captured traces to a file, check the Log Trace Event Data To File option and set the file name. In this example, it’s C:\WPP Traces\usbHub3.etl.
  7. Click Set Flags and Level->Level and then Information.
  8. Click OK and then Finish.

Plug in your device to a USB 3.0 (SuperSpeed) port to capture the trace. The TraceView output should be similar to this image:

Reading ETL logs using TraceView

For more information and detailed instructions about using TraceView to view existing ETL logs, see Displaying a Trace Log with a PDB File.

  1. Start TraceView.
  2. On the File menu, click Open Existing Log File.
  3. In the Log File Name box, type the path and name of an event trace log file (.etl). For this example, in TraceView, Log File Name box is name of the captured event trace log file, C:\WPP Traces\usbHub3.etl.
  4. Click OK.
  5. Click PDB (Debug Information) File and type the path to the PDB file that was used to directly or indirectly (by using control GUID) capture the WPP traces. For this example it’s C:\Symbols\usbhub3.pdb\615C8CDF22AC4981BB401198E1401C8E2\usbhub3.pdb.
  6. Click OK.

The TraceView output should be similar to this image:

Microsoft-provided drivers that have TMF information in their public symbol files

Here are some kernel-mode drivers for PCI, USB, HID, and Serial that have TMF information in their public PBDs:

usbccgp.sys

USBHUB3.sys

UCX01000.sys

USBXHCI.sys

winusb.sys

 

hidclass.sys

hidi2c.sys

hidusb.sys

kbdhid.sys

mouhid.sys

 

SerCx.sys

SerCx2.sys

SpbCx.sys

msgpioclx.sys

msgpiowin32.sys

 

pci.sys

1394ohci.sys