How to include and view WPP trace messages in a driver’s public PDB files

This post has been republished via RSS; it originally appeared at: Microsoft USB Blog articles.

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:

• How to include formatting instructions in public PDBs so that your consumers can easily debug, and obtain information about the module.


• How to obtain WPP traces with the public symbol file .


• A list of Microsoft-provided bus drivers and some in-box driver class drivers that include TMF information in their public PDBs .

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.

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.

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

Next, capture the trace as shown here:

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: