7.2 Debug Monitor

Debug Monitor is a powerful graphical- and console-mode tool for monitoring all activities handled by the WinDriver kernel (windrvr6.sys/.dll/.o/.ko).
You can use this tool to monitor how each command sent to the kernel is executed.
In addition, WinDriver enables you to print your own debug messages to the Debug Monitor, using the WD_DebugAdd() function  [B.6.6] or the high-level PrintDbgMessage() function [B.7.14].

The Debug Monitor has two modes: graphical mode and console mode. The following sections explain how to operate Debug Monitor in both modes.

7.2.1 Using the Debug Monitor in Graphical Mode - wddebug_gui

The graphical (GUI) version of the Debug Monitor utility - wddebug_gui - is available for Windows 98/Me/2000/XP/Server 2003/Vista and Linux. You may also use the Debug Monitor to debug your Windows CE driver code running on CE emulation on a Windows 2000/XP/Server 2003/Vista platform. For Windows CE targets, use Debug Monitor in console mode [7.2.2].

1. Run the Debug Monitor using either of the following alternative methods:
   • Run WinDriver/util/wddebug_gui.

   • Run the Debug Monitor from the DriverWizard's Tools menu.

   • On Windows, run Start | Programs | WinDriver | Debug Monitor.

   Figure 7.1: Start Debug Monitor

   

2. Set the Debug Monitor's status, trace level and debug sections information from the Debug Options dialogue, which is activated either from the Debug Monitor's View | Debug Options menu or the Debug Options toolbar button.

   Figure 7.2: Debug Options

   
   • Status - Set trace on or off.

   • Section - Choose what part of the WinDriver API you would like to monitor. USB developers should select the USB section.

     ****************************************************************************************

     	TIP
     	Choose carefully those sections that you would like to monitor. Checking more options than necessary could result in an overflow of information, making it harder for you to locate your problem.

     ****************************************************************************************

   • Level - Choose the level of messages you want to see for the resources defined.

     Error

     is the lowest trace level, resulting in minimum output to the screen.

     Trace

     is the highest trace level, displaying every operation the WinDriver kernel performs.

   • Select the Send debug messages to the operating system kernel debugger option if you want debugging messages to be sent to an external kernel debugger as well.

     This option enables you to send to an external kernel debugger all the debug information that is received from WinDriver's kernel module.

     Now run your application, reproduce the problem, and view the debug information in the external kernel debugger's log.

     Windows users can use Microsoft's WinDbg tool, for example, which is freely supplied with Microsoft's Driver Development Kit (DDK) and from Microsoft's web site (Microsoft Debugging Tools page).

3. Once you have defined what you want to trace and on what level, click OK to close the Debug Options window.

4. Activate your program (step-by-step or in one run).

5. Watch the Debug Monitor log for errors or any unexpected messages.

7.2.1.1 Running the Graphical Debug Monitor for a Renamed Driver

By default, the graphical Debug Monitor program - wddebug_gui - logs messages from the windrvr6.sys/.o/.ko driver. However, you can also use wddebug_gui to log debug messages from a renamed driver (see explanation in section 12.2 regarding renaming the windrvr6 driver module) by running wddebug_gui from the command line with the driver_name option:

    wddebug_gui <driver_name>

****************************************************************************************

	NOTE
	The driver name should be set to the name of the driver file without the file's extension; e.g. windrvr6, not windrvr6.sys (on Windows) or windrvr6.o (on Linux).

****************************************************************************************

For example, if you have renamed the default windrvr6.sys driver on Windows to my_driver.sys, you can log messages from your driver by running the Debug Monitor using the following command:

    wddebug_gui my_driver

7.2.2 Using the Debug Monitor in Console Mode - wddebug

The Debug Monitor utility comes in a console-mode version - WinDriver/util/wddebug - which is available for all supported operating systems.

To use the wddebug console-mode version of the Debug Monitor utility on Windows 98/Me/2000/XP/Server 2003/Vista, Windows CE and Linux, run the WinDriver/util/wddebug utility, as explained below.

On Windows CE, start a Windows CE command window (CMD.EXE) on the Windows CE target and then run the program WDDEBUG.EXE inside this shell.

WDDEBUG USAGE

wddebug [<driver_name>] <command> [<level>] [<sections>]

****************************************************************************************

	NOTE
	The wddebug command options must be used in the order in which they appear in the usage demonstration above.

****************************************************************************************

<driver_name> :

The name of the driver to which to apply the command.

The driver name can be set either to windrvr6 (default), or to the name of any driver renamed from the windrvr6 driver module (see explanation in section 12.2).

****************************************************************************************

	NOTE
	The driver name should be set to the name of the driver file without the file's extension; e.g. windrvr6, not windrvr6.sys (on Windows) or windrvr6.o (on Linux).

****************************************************************************************

<command> :

The Debug Monitor command to execute:

• Activation commands:
  • on : Turn the Debug Monitor on.
  • off : Turn the Debug Monitor off.
  • dbg_on : Redirect the debug messages from the Debug Monitor to a kernel debugger and turn the Debug Monitor on (if it was not already turned on).
  • dbg_off : Stop redirecting debug messages from the Debug Monitor to a kernel debugger.

  ****************************************************************************************

  	NOTE
  	The on and dbg_on commands can be run together with the level and/or sections options described below.

  ****************************************************************************************

• dump : Continuously display (''dump'') debug information until the user presses Esc.

• status : Display information regarding the running <driver_name> kernel module; the current Debug Monitor status, including the active debug level and sections (when the Debug Monitor is on); and the size of the debug messages buffer.

****************************************************************************************

	NOTE
	The following options are applicable only to the Debug Monitor on and dbg_on activation commands described above.

****************************************************************************************

<level> :

The debug trace level to set. The level can be set to either of the following flags: ERROR, WARN, INFO or TRACE, where ERROR is the lowest trace level and TRACE is the highest level (displays all messages).
The default debug trace level is ERROR.

<sections> :

The debug sections to set. The debug sections determine what part of the WinDriver API you would like to monitor. For a full list of all supported debug sections, run wddebug with no arguments to view its usage instructions.
The default debug sections flag is ALL - sets all the supported debug sections.

USAGE SEQUENCE

To log messages using wddebug, use this sequence:

• Turn on the Debug Monitor by running wddebug with either the on command, or the dbg_on command - which redirects the debug messages to a kernel debugger before turning on the Debug Monitor.

  You can use the level and/or sections flags to set the debug level and/or sections for the log. If these options are not explicitly set, the default values will be used.

  You can also log messages from a renamed WinDriver driver by preceding the command with the name of the driver (see the <driver_name> option above). The default monitored driver is windrvr6.

• Run wddebug with the dump command to begin dumping debug messages to the command prompt.

  You can turn off the display of the debug messages at any time by pressing Esc in the command prompt.

• Run applications that use the driver, and view the debug messages as they are being logged to the command prompt / the kernel debugger.

• You can run wddebug with the status command at any time while the Debug Monitor is on in order to view the current debug level and sections, as well as information regarding the running <driver_name> kernel module.

• You can use dbg_on and dbg_off to toggle the redirection of debug messages to a kernel debugger at any time while the Debug Monitor is on.

• When you are ready, turn off the Debug Monitor by running wddebug with the off command.

You can also run wddebug with the status command while the Debug Monitor is turned off in order to view information regarding the running <driver_name> kernel module.

EXAMPLE

The following is an example of a typical wddebug usage sequence. Since no <driver_name> is set, the commands are applied to the default driver - windrvr6.

• Turn the Debug Monitor on with the highest trace level for all sections:
  wddebug on TRACE ALL

  Note: This is the same as running ''wddebug on TRACE'', since ALL is default debug sections option.

• Dump the debug messages continuously until you hit Esc:
  wddebug dump

• Use the driver and view the debug messages in the command prompt.

• Turn the Debug Monitor off:
  wddebug off