OSRLogoOSRLogoOSRLogo x OSR Custom Development Services

Everything Windows Driver Development

GoToHomePage xLoginx

    Thu, 14 Mar 2019     118020 members


  Online Dump Analyzer
OSR Dev Blog
The NT Insider
The Basics
File Systems
ListServer / Forum
  Express Links
  · The NT Insider Digital Edition - May-June 2016 Now Available!
  · Windows 8.1 Update: VS Express Now Supported
  · HCK Client install on Windows N versions
  · There's a WDFSTRING?
  · When CAN You Call WdfIoQueueP...ously

Tracing Update -- New Tracing Features for Windows

Most of you probably already know that you can include trace statements in your driver, and enable the output dynamically.  This feature, available for drivers built with the Windows XP DDK and later, and supported on platforms starting with Windows 2000, is probably one of the best innovations in driver debugging since, er, WinDbg. (Aside: Yes, I understand that anything to do with WinDbg is a touchy topic, and that there still are still a few folks stuck in the Ice age, but let’s leave that aside for now.)  Anyhow, tracing is a pretty good innovation.  If you haven’t checked it out yet, please do so by reading Without A Trace in the Jan/Feb issue of The NT Insider (you can read the article on line at http://www.osronline.com/article.cfm?id=200).


The Old Way

One of the things that stood in the way (for a while) of our using tracing here at OSR was the tools.  While TracePDB, TraceLog, and TraceFmt seem to work, it would be quite a stretch to call them “convenient.”  Fortunately, Microsoft has rescued us from the inferno of command line utilities, and has given driver writers a GUI-based utility that “does it all.”


One Step to Happiness

Using a utility that’s supplied starting with the Windows Server 2003 DDK, you easily control tracing in your driver and display the trace output from your driver in “real time” in a GUI window.  You can even simultaneously write the binary trace data to disk.  The utility that you use to do this is named TraceView, and it’s located in DDK’s \tools\tracing directory.


Start TraceView, and select “Create a New Log Session” from under the “File” menu.  The “Create New Log Session” dialog box, shown in Figure 1 below, will appear.



Figure 1


From the “Create New Log Session” dialog, click the “Add Provider” button.  This results in the display of the “Provider GUID Control Setup” dialog, shown in Figure 2 below.  In this dialog, you can manually enter the control GUID for your driver that you defined using WPP_DEFINE_GUIDS in your driver’s h file.  You can type the GUID in (or just paste it), point TraceView to a file that contains the GUID, or just point TraceView to your driver’s PDB.  Or, better yet, if you point TraceView to your driver’s PDB file, it will extract the driver control GUID and also all the necessary message formatting information.  If you do not use a PDB file, you will next need to either select the TMF files for your driver or point TraceView to a directory that contains these files.



Figure 2


Once the GUID and format information has been identified, click “Next” in the “Create New log Session” dialog.  You can decide where you want your driver’s trace output sent: Do you want your trace messages interpreted and displayed in real-time via TraceView’s GUI, or do you want the binary trace data to be written to a file, or perhaps both?  Figure 3 shows the dialog selecting Real Time Display. 


Figure 3


At this point, you can optionally click the “Advanced Log Session Options” button to request that an interpreted listing file be created, to specify which tracing messages to enable in your driver, or other such settings.  By default, TraceView enables the low 16 trace messages in your driver (with a flags setting of 0xFFFF).  However, you may alter this dynamically from the TraceView GUI (described later).


Once you’ve finishes specifying your trace log information, click “Finish.”  The display will look similar to that shown in Figure 4.



Figure 4 – The TraceView Display


Assuming you selected real time display, you’ll see two windows displayed.  The upper window shows control information about each of the active trace sessions.  One of the most useful things about this part of the display is that you can click and edit any of the fields that aren’t grayed-out.  For example, you can click-on and change the value for “flags”, to control which trace statements generate output in your driver.


Trace messages from your driver are displayed as they are collected and output in the lower window.  Note that you can re-size or re-arrange the columns in this window.  You can also suppress some columns and turn other on by right clicking on the column header.  Note that some columns (such as, for example, “Component Name”) will by default not have any data in them.  This is to be expected. Event Tracing for Windows is very powerful, and generating data for these columns is optional under certain circumstances. 


New For WinHEC 2003

You know what they say on those cheesy advertisements on late night TV here in the States, right?  They say “But wait!  There’s more!  You didn’t think we’d waste space in our special WinHEC issue just to talk about a DDK tool that’s available in the Windows Server 2003 DDK, right?


TraceView V2.0, Beta 1 is provided in the special release WinHEC DDK.  This version of TraceView has a large number of enhancements, including:


§         Support for Windows 2000 (TraceView V1.x can only be run on Windows XP and later).

§         The ability to copy the contents of the trace output window to the clipboard.

§         The ability to save your trace settings in “workspaces”.

§         The ability to filter and dynamically color-code trace output.  So, for example, you can suppress the display of certain trace events, or set the color of the trace output lines based on the trace data.  This data might include the name of the function generating the trace output, the source code filename in which the module resides, or even the text of the trace message itself.


There are other enhancements in TraceView V2.0, but the ones listed above are the biggies.  Filtering is probably the most powerful feature (and, thankfully, the filter settings are all saved when the workspace is saved).


Using TraceView V2.0 Filters

Figure 5 shows an example of the Manage Filters dialog, showing a fairly sophisticated set of filters.



Figure 5 – Manage Filters with TraceView V2


There are three key things to know about how filters work:

  1. Filters are order dependent.
  2. Text matches are not case sensitive.
  3. Every filter rule contains an implicit “and terminate processing” at the end.  That is, as soon as a particular trace message matches a rule, no more filter processing is performed on that message.


Looking at Figure 5, you can see we color code trace output messages based on a number of different criteria.  The first is, if any trace message output contains the text “error”, that message will be displayed in red.  The second filter rule contains a regular expression.  If the message text matches the regular expression, that message is colored orange.  This line also shows the use of the optional “Description” box in the Manage Filters dialog.  It can be very helpful for adding comments that describe what a particular filter does.  You can see this feature used again in the last rule.  The last rule comprises a multi-line condition (we’ve selected that rule in the upper window; This results in all the lines of the rule are in the lower window).  Remember, the first rule that matches stops all filtering.  So, if a message has both the text “error:” and an email address, the first rule wins, and the message will be displayed in red.


In Summary

Tracing is a whole lot easier to use, and a whole lot more fun, using TraceView.    You’ll find it in the \ddk\tools\tracing directory on the Windows Server 2003 DDK.  A beta release of the new, more powerful, TraceView V2.0 is provided in the WinHEC DDK release.  With many new features, TraceView V2.0 reaches new heights.  Now there really is no reason not to support tracing in your drivers!


Related Articles
Without A Trace? Event Tracing in Windows

User Comments
Rate this article and give us feedback. Do you find anything missing? Share your opinion with the community!
Post Your Comment

"TraceView for AMD64"
I tried traceview 2.0 from 3790.1173 DDK. On running it on amd64 bit machine it prompted for a misssing dll msvcr7.0.dll. Only dll I found with this name for amd64 was under bin\x86 folder. On copying it manually in the path of traceview.exe on amd64 machine, it still keeps prompting for missing .dll, looks like this is not the right one. Is traceview2.0 supported on amd64(Server 2003 64-bit installed) machines?

21-Jul-04, Mamta Gambhir

"Where is version 2.0?"
I didn't get to go to winhec ( last year or this ), so I don't have access to that build of the ddk...But I'm especially interested in 2k support and the ability ot add filters.

I looked in the 3790/4051 builds of the ddk's and the version is still at 1.91.

Thanks. kris

28-May-04, kris reierson

"RE: Or you could use..."
You COULD but then you'd be missing the main point of Event Tracing for Windows.

Read the base article shown in the "Related Articles" link above.

The idea behind ETW is that it avoids the problems that are inherent in DbgPrint (high overhead, strings compiled in your code, timing problems).

So, the point isn't "I can see my output on my current system"... the point is that you can leave the tracing code in your driver when you ship it, and selectively enable it to help you debug problems in the field.

03-Jul-03, Peter Viscarola

"Or you could use..."
DebugView (http://www.sysinternals.com/ntw2k/freeware/debugview.shtml)

DebugView also supports networking so you can see your trace output while running full-screen applications.

01-Jul-03, Stephen Holmes

Post Your Comments.
Print this article.
Email this article.
bottom nav links