Viewing Debug Trace
==============================================================================

There are 2 types of traces produced by UsbDk components - driver and
user mode.

UsbDk driver uses Windows WPP facilities to trace code execution.
Both debug and release versions of the driver contain trace points
that my be activated at run time. In order to activate and view traces
use tracing scripts from Tools/Trace subfolder of UsbDk source tree.

UsbDk user mode components output trace logs into Windows debug stream
that may be watched by DbgView utility.

Getting User Mode Text Traces (for debugging and sharing, no PDB files needed)
==============================================================================

* Getting Traces of user mode UsbDk components as easy as running DbgView from
  http://live.sysinternals.com/Dbgview.exe

Getting Driver Text Traces (for debugging, requires UsbDk driver's PDB file)
==============================================================================

* Copy Tools/Trace subfolder from the driver source tree to the target machine
* Copy UsbDk.pdb from corresponding build tree subfolder to Trace folder on
  the target machine, this should be done after each driver recompilation
  (i.e. Install_Debug\x64\Win7Debug\UsbDk.pdb for Windows 7 64-bit Debug build)
* Download dbgview from http://live.sysinternals.com/Dbgview.exe
  and put to Trace folder on the target machine
* Copy traceview.exe from WDK install location on build machine
  (usually C:\Program Files (x86)\Windows Kits\10\Tools\x64\traceview.exe)
  to Trace folder on the target machine
* Run UsbDkTrace.bat script from Trace folder on the target machine
* Keep pressing ENTER until dbgview window appears on the screen
* Accept dbgview license (shown on the first run only)
* In case everything configured properly log in DbgView should look like:
  ...
  [UsbDk]UsbDkEvtDeviceAdd Entry
  [UsbDk]CRegText::Dump ID: USB\VID_46F4&PID_0001
  [UsbDk]UsbDkSendUrbSynchronously Send URB IRP Error 0xc00000bb(STATUS_NOT_SUPPORTED)
  [UsbDk]UsbDkWdmUsbDeviceIsHub Cannot query device descriptor
  [UsbDk]UsbDkEvtDeviceAdd Exit 0xc00000bb(STATUS_NOT_SUPPORTED)
  ...
* In case trace contains entries without format information, i.e.
  ...
  Unknown( 10): GUID=f07e9b42-334e-a0c9-a179-65db113c0bcc (No Format Information found).
  ...

  make sure correct PDB for your build and system was copied to Trace folder
  on the target machine.

Getting Driver Binary Traces using Logman (for sending trace logs to developers)
==============================================================================
* Copy Tools/Trace subfolder from the driver source tree to the target machine
* Run UsbDkLogman.bat as administrator
* Follow instructions

Converting binary trace file to text using UsbDk.tmf file from UsbDk release
==============================================================================
* Copy tracefmt.exe from WDK install location on build machine
  (usually C:\Program Files (x86)\Windows Kits\8.1\bin\x64\tracefmt.exe)
  to Trace folder on the target machine
* Do the conversion, for example:
  tracefmt.exe usbdk.etl -o usbdk.txt -nosummary -tmf "c:\Program Files\UsbDk Runtime Library\UsbDk.tmf"

Getting Driver Binary Traces using TraceView (for sending trace logs to developers, no PDB required)
==============================================================================

* Copy Tools/Trace subfolder from the driver source tree to the target machine
* Copy traceview.exe from WDK install location on build machine
  (usually C:\Program Files (x86)\Windows Kits\8.1\Tools\x64\traceview.exe)
  to Trace folder on the target machine
* Run UsbDkTraceToFile.bat script from Trace folder on the target machine
* Press ENTER once
* Perform the scenario being traced
* Press ENTER a few times in UsbDkTraceToFile.bat console Window until it closes
* In case everything configured properly trace log will be saved to UsbDkTrace.etl
  file in the Trace foder

Recording permanent Driver Binary trace (from system start until turned off and the system rebooted)
====================================================================================================

To Enable:

* Copy Tools/Trace subfolder from the driver source tree to the target machine
* Right mouse button click on UsbDk-Autologger-On.reg -> Merge
* Restart the system
* The system will write binary log file automatically to %windir%\System32\LogFiles\WMI\UsbDk.etl
* Note that the system overwrites the file after each reboot
* Collect the log file at any time (data is flushed to the disk automatically with possible delay of 2-4 seconds)

To Disable:

* Right mouse button click on UsbDk-Autologger-Off.reg -> Merge
* Restart the system

Converting Driver Binary Traces to Text (using driver's PDB file from private build)
==============================================================================

* Place the binary trace obtained (UsbDkTrace.etl) to Tools/Trace
  folder of UsbDk source tree
* Copy tracepdb.exe and tracefmt.exe utilities from WDK binaries location
  (usually C:\Program Files (x86)\Windows Kits\10\bin\x64\)
  to Tools/Trace folder of UsbDk source tree
* Copy UsbDk.pdb that corresponds to the binary trace obtained to Tools/Trace 
  folder of UsbDk source tree
  (i.e. Install_Debug\x64\Win7Debug\UsbDk.pdb for Windows 7 64-bit Debug build)
* Run UsbDkTextLog.bat
* In case everything configured properly output should look like
  ...
  [UsbDk]UsbDkEvtDeviceAdd Entry
  [UsbDk]CRegText::Dump ID: USB\VID_46F4&PID_0001
  [UsbDk]UsbDkSendUrbSynchronously Send URB IRP Error 0xc00000bb(STATUS_NOT_SUPPORTED)
  [UsbDk]UsbDkWdmUsbDeviceIsHub Cannot query device descriptor
  [UsbDk]UsbDkEvtDeviceAdd Exit 0xc00000bb(STATUS_NOT_SUPPORTED)
  ...
* In case trace contains entries without format information, i.e.
  ...
  Unknown( 15): GUID=f07e9b42-334e-a0c9-a179-65db113c0bcc (No Format Information found).
  Unknown( 10): GUID=1cd39459-da07-54dd-2d59-4231cc92623c (No Format Information found).
  Unknown( 27): GUID=7a1906df-695f-0ca8-bad8-f8eac5a401a8 (No Format Information found).
  Unknown( 23): GUID=7a1906df-695f-0ca8-bad8-f8eac5a401a8 (No Format Information found).
  Unknown( 17): GUID=f07e9b42-334e-a0c9-a179-65db113c0bcc (No Format Information found).
  ...
  make sure correct PDB was provided.