How to Run a Software Trace Session

A software trace session requires the following three components:

• A trace controller to enable tracing and connect the provider with the consumer.

• A trace provider to generate trace messages.

• A trace consumer to format and display the messages.

TraceView, which is used in the following examples, acts as both a controller and a consumer. You can also use separate applications for the trace consumer and trace controller. This section describes how to use TraceView with the two USB samples-first to prepare a sample and then to view trace logs in a software trace session.

Prepare the Sample

Before starting the trace session, you must build and install the sample and generate the TMF and control GUID (.ctl) files. The procedure for Fx2_Driver is identical to the one for Osrusbfx2 except for some name changes.

To Prepare the Sample

1. Build and install the sample on your test system.

   Chapter 19, "How to Build WDF Drivers," describes build instructions.

2. Build and install the test application on your test system.

3. If you have not installed the WDK on your test system, copy TraceView from your development system to a convenient location on your test system.

4. In the command window, use cd to move to the target folder and then run Tracepdb to generate TMF files from the sample's symbol file, as follows for the x86 environment:

   • WinDDk\BuildNumber\tools\tracing\i386\tracepdb -f samplename.pdb -p path

   If you are using a 64-bit system, use the version of Tracepdb in the \x64 or \ia64 folders instead of the \i386 folder.

   The resulting TMF file is stored at path. The file's name consists of a GUID with a .tmf file name extension. If you are already in the target folder, just use "." for path.

    Note  In Windows Server 2003 and earlier versions, you must copy the Dbghelp.dll file from the %wdk%\bin\Platform directory of the WDK into the directory in which Tracepdb.exe is located.

5. Create a CTL file for the sample.

   This is a text file with a single line of text that contains the control GUID and provider name from WPP_DEFINE_CONTROL_GUID. The file can have any name you prefer, but it must have a .ctl extension.

   For the Fx2_Driver sample, the CTL file should contain the following:

    da5fbdfd,1eae,4ecf,b426,a3818f325ddb WudfOsrUsbFx2TraceGuid 

   For the Osrusbfx2 sample, the CTL file should contain the following:

    d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB OsrUsbFxTraceGuid 

View a Driver Trace Log by Using TraceView

Trace logs can be viewed in real time or stored in a log file to be viewed later. This section describes the process of using TraceView to view a trace log in real time and to view a trace log file.

Chapter 22, "How to Debug WDF Drivers," provides an explanation of how to configure WinDbg to view a real-time trace log.

How to Create and View a Trace Log File

One way to handle trace messages is to store them in a trace log file. You can then use a trace consumer to view the file later. This section shows how to store the trace messages from Fx2_Driver in a trace log file and then view them by using TraceView.

To Start the Trace Session

1. Install Fx2_Driver and TraceView on your test computer.

2. Run TraceView by double-clicking it in Windows Explorer or by using a command line.

   In Windows Vista and later versions, you must run TraceView with elevated privileges.

3. On the File menu, click Create New Log Session, and then click Add Provider.

4. In the Provider Control GUID Setup dialog box, select CTL (Control GUID) File and enter the sample's CTL file path, and then click OK.

5. In the Format Information Source Select dialog box, select Select TMF Files, and then click OK.

6. In the Trace Format Information Setup dialog box, click Add.

7. In the File Open dialog box, enter the TMF files that you created earlier.

8. In the Trace Format Information Setup dialog box, click Done.

9. In the Create New Log Session dialog box, click Next.

10. On the Log Session Options page, select Log Trace Event Data To File, specify a name for the log file, and then click Finish to complete setting up the trace session.

The Fx2_Driver sample has trace messages only in its loading and startup code. To generate a trace message log, unplug the device and plug it back in.

To View the Messages in the Log File

1. Run TraceView.

2. On the File menu, click Open Existing Log File.

3. In the Log File Selection dialog box, enter the trace log file that you created in the previous procedure, and then click OK.

4. In the Format Information Setup dialog box, specify the project's TMF files, and then click Done to view the trace message log.

Figure 11-2 shows a trace log file for Fx2_Driver, produced by unplugging and replugging the device while the trace session is running.

Figure 11-2: Viewing a trace log file by using TraceView

How to View a Trace Log in Real Time

Viewing a trace log in real time is often convenient to see how the driver responds to different events. This section describes a simple trace session with the Osrusbfx2 sample.

To Start the Trace Session

1. Install the Osrusbfx2 driver, the test application, and TraceView on your test computer.

2. Run TraceView.

3. On the File menu, click Create New Log Session, and then click Add Provider.

4. In the Provider Control GUID Setup dialog box, select CTL (Control GUID) File, enter the sample's CTL file path, and then click OK.

5. In the Format Information Source Select dialog box, select the Select TMF Files option, and then click OK.

6. In the Trace Format Information Setup dialog box, click Add.

7. In the File Open dialog box, enter the TMF files that you created earlier, and then click Done.

8. In the Create New Log Session dialog box, click Next.

9. On the Log Session Options page, select Real Time Display, and then click Finish to complete setting up the trace session.

You can also choose to have the messages stored in a trace log file in addition to viewing them in real time.

To Generate Trace Messages

• Run the test application and change one of the device features.

Figure 11-3 shows the trace messages that are produced by lighting two lights on the light bar of the OSR USB FX2 Learning Kit device.

Figure 11-3: A real-time TraceView session for Osrusbfx2

View the Frameworks Trace Log by Using the Core Tracing Tools

The Tracelog and Tracefmt core tracing tools are less convenient than TraceView. However, they are more robust, which makes them the preferred tools in some situations. This section shows how to use the core tracing tools to view trace messages from the KMDF runtime.

To Use Tracelog to View Messages from the KMDF Runtime

• Open a command window and run the following commands, which set several environment variables and create a folder for the trace log file.

Listing 11-3: Tracelog commands to set environment variables

 set TRACE_NAME=WDF set TRACE_LOG_PATH=%SystemRoot%\Tracing\%TRACE_NAME% set _PROVIDER_GUID=# set TMFFILE=wdf01005.tmf set TRACE_FORMAT_PREFIX=%%2!-20.20s!%%!FUNC!- set TRACE_FLAGS=0xffff set TRACE_LEVEL=5 md "%TRACE_LOG_PATH%" 

You should modify the highlighted parts of the commands, especially the GUID and the TMF file name, to use values appropriate for your driver. If you are running Tracelog on a Windows Vista system, you must open the command window with elevated privileges.

To Start a Tracelog Session

• Run the following command:

  • tracelog -start "%TRACE_NAME%" -seq 10 -rt -guid %_PROVIDER_GUID% -flags

  • %TRACE_FLAGS% -level %TRACE_LEVEL% -f

  • "%TRACE_LOG_PATH%\%TRACE_NAME%.etl"

By default, the messages are placed in a trace log file named %TRACE_NAME% that is placed in the %TRACE_LOG_PATH% folder. You can also view the messages in real time. To do so, after you have started a Tracelog session, run the Tracefmt tool.

To Run the Tracefmt Tool to View Messages in Real Time

• Run the following command:

  • tracefmt -rt "%TRACE_NAME%" -tmf "%TMFFILE%" -display

Tracefmt displays the messages in the command window as they are generated, using the formatting information in the specified TMF file. Listing 11-4 shows how Tracelog and Tracefmt display some of the framework trace messages that were generated by lighting two of the lights on the OSR USB FX2 device's light bar.

Listing 11-4: A real-time trace session using Tracelog and Tracefmt

 C:\WinDDK\6000\tools\tracing\i386>tracefmt.exe -rt "%TRACE_NAME%" -tmf "%TMFFILE %" -display Setting RealTime mode for  WDF Examining wdf01005.tmf for message formats,  97 found. Searching for TMF files on path: (null) FxPkgGeneral_cpp424 FxPkgGeneral::Dispatch- WDFDEVICE 0x6C3BC458     !devobj 0x93C44810 0x00000000(IRP_MJ_CREATE) IRP 0x9061A008 FxPkgIo_cpp97       FxPkgIo::Dispatch- WDFDEVICE 0x6C3BC458     !devobj 0x93C44810 0x0000000e(IRP_MJ_DEVICE_CONTROL), IRP_MN 0,     IRP 0x9331FED8 FxDevice_cpp1646    FxDevice::AllocateRequestMemory- Allocating     FxRequest* 9048E308, WDFREQUEST 6FB71CF0 FxIoQueue_cpp1696   FxIoQueue::QueueRequest- Queuing WDFREQUEST     0x6FB71CF0 on WDFQUEUE 0x6C3BAFB0 FxIoQueue_cpp2085   FxIoQueue::DispatchEvents- Thread 9E867AC0     is processing WDFQUEUE 0x6C3BAFB0 PowerPolicyStateMachFxPkgPnp::PowerPolicyCancelWaitWake-     Successfully got WaitWake irp 93C49750 for cancelling PowerPolicyStateMachFxPkgPnp::_PowerPolicyWaitWakeCompletionRoutine-     Completion of WaitWake irp 93C49750, 0xc0000120(STATUS_CANCELLED) PowerPolicyStateMachFxPkgPnp::_PowerPolicyWaitWakeCompletionRoutine-     Not completing WaitWake irp 93C49750 in completion routine PowerPolicyStateMachFxPkgPnp::PowerPolicyCancelWaitWake- Cancel of     irp 93C49750 returned 1 FxPkgPnp_cpp494     FxPkgPnp::Dispatch- WDFDEVICE 0x6C3BC458     !devobj 0x93C44810 IRP_MJ_POWER, Minor 0x2  IRP 0x93C49750 PowerPolicyStateMachFxPkgPnp::PowerPolicySendDevicePowerRequest-     Requesting D0 irp, 0x00000103(STATUS_PENDING) FxIoTarget_cpp158   FxIoTarget::SubmitPendedRequest- Sending     WDFREQUEST 6CE5CCC8, Irp 931A52F8 FxIoTarget_cpp158   FxIoTarget::SubmitPendedRequest- Sending     WDFREQUEST 6C3BB268, Irp 93C49B38 FxIoQueue_cpp2085   FxIoQueue::DispatchEvents- Thread 820FBD78     is processing WDFQUEUE 0x6C3BAFB0 FxIoQueue_cpp2170   FxIoQueue::DispatchEvents- WDFQUEUE     0x6C3BAFB0 Power Transition State 0x0000000a(FxIoQueuePowerRestarting) 

To Flush the Trace Buffer and View the Messages Without Stopping the Session

1. Run the following command to flush the buffer:

   • tracelog -flush "%TRACE_NAME%"

2. Then run this command:

   • tracefmt "%TRACE_LOG_PATH%\%TRACE_NAME%.etl" -tmf %TMFFILE% -

   • nosummary -o "%TRACE_LOG_PATH%\%COMPUTERNAME%-

   • %TRACE_NAME%.txt"

3. Finally, run this command to dump the messages in a file:

   • @echo Tracelog dumped to %TRACE_LOG_PATH%\%COMPUTERNAME%-TRACE_NAME%.txt

To Stop the Trace Session

• Run the following command:

  • tracelog -stop "%TRACE_NAME%"