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:
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
box, type the following:
In the preceding snippet, the
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.
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:
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.
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:
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:
Plug in your device to a USB 3.0 (SuperSpeed) port to capture the trace. The TraceView output should be similar to this image:
For more information and detailed instructions about using TraceView to view existing ETL logs, see Displaying a Trace Log with a PDB File .
The TraceView output should be similar to this image:
Here are some kernel-mode drivers for PCI, USB, HID, and Serial that have TMF information in their public PBDs:
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.