7.2. Debug Monitor

Debug Monitor is a powerful graphical- and console-mode tool for monitoring all activities handled by the WinDriver kernel.
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 comes in two versions:

Both Debug Monitor versions are provided in the WinDriver/util directory

7.2.1. The wddebug_gui Utility

wddebug_gui is a fully graphical (GUI) version of the Debug Monitor utility for Windows and Linux.

  1. Run the Debug Monitor using either of the following methods:
    • Run WinDriver/util/wddebug_gui
    • Run the Debug Monitor from DriverWizard's Tools menu.
    • On Windows, run Start | Programs | WinDriver | Debug Monitor.

    Figure 7.1. Start Debug Monitor

    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

    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.
    • Send debug messages to the operating system kernel debugger

      Select this option to send the debug messages received from the WinDriver kernel module to an external kernel debugger, in addition to the Debug Monitor.

      [Note]
      On Windows 7 and higher, the first time that you enable this option you will need to restart the PC.
      [Tip]
      A free Windows kernel debugger, WinDbg, is distributed with the Windows Driver Kit (WDK) and is part of the Debugging Tools for Windows package, distributed via the Microsoft web site.
  3. Once you have defined what you want to trace and on what level, click OK to close the Debug Options window.
  4. Optionally make additional configurations via the Debug Monitor menus and toolbar.
    [Tip]
    When debugging OS crashes or hangs, it's useful to auto-save the Debug Monitor log, via the File –> Toggle Auto-Save menu option (available also via a toolbar icon), in addition to sending the debug messages to the OS kernel debugger (see Step 2).
  5. Run your application (step-by-step or in one run).
    [Tip]
    You can use the Edit –> Add Custom Message... menu option (available also via a toolbar icon) to add custom messages to the log. This is especially useful for clearly marking different execution sections in the log.
  6. Watch the Debug Monitor log (or the kernel debugger log, if enabled) for errors or any unexpected messages.

7.2.1.1. Running wddebug_gui for a Renamed Driver

By default, wddebug_gui logs messages from the default WinDriver kernel module — windrvr1260.sys/.dll/.o/.ko. However, you can also use wddebug_gui to log debug messages from a renamed version of this driver [11.2], by running wddebug_gui from the command line with the driver_name argument: 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., windrvr1260, not windrvr1260.sys (on Windows) or windrvr1260.o (on Linux).

For example, if you have renamed the default windrvr1260.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. The wddebug Utility

7.2.2.1. Console-Mode wddebug Execution

The wddebug version of the Debug Monitor utility can be executed as a console-mode application on all supported operating systems: Windows, and Linux. To use the console-mode Debug Monitor version, run WinDriver/util/wddebug in the manner explained below.

wddebug console-mode usage

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

[Note]
The wddebug arguments must be provided in the order in which they appear in the usage statement above.

  • <driver_name> — The name of the driver to which to apply the command.

    The driver name should be set to the name of the WinDriver kernel module — windrvr1260 (default), or a renamed version of this driver (refer to the explanation in Section 11.2).

    [Note]
    The driver name should be set to the name of the driver file without the file's extension; e.g., windrvr1260, not windrvr1260.sys (on Windows) or windrvr1260.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).
        [Note]
        On Windows 7 and higher, the first time that you enable this option you will need to restart the PC.
      • dbg_off — Stop redirecting debug messages from the Debug Monitor to a kernel debugger.
      [Note]
      The on and dbg_on commands can be used together with the <level> and <sections> arguments.
    • dump — Continuously send ("dump") debug information to the command prompt, until the user selects to stop (by following the instructions displayed in the command prompt).
    • status — Display information regarding the running driver (<driver_name>), 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.
    • clock_on — Add a timestamp to each debug message. The timestamps are relative to the driver-load time, or to the time of the last clock_reset command.
    • clock_off — Do not add timestamps to the debug messages.
    • clock_reset — Reset the debug-messages timestamps clock.
    • sect_info_on — Add section(s) information to each debug message.
    • sect_info_off — Do not add section(s) information to the debug messages.
    • help — Display usage instructions.
    • No arguments (including no commands) — This is equivalent to running 'wddebug help'.

The following arguments are applicable only with the on or dbg_on commands:

  • <level> — The debug trace level to set — one of the following flags: ERROR, WARN, INFO, or TRACE (default).
    ERROR is the lowest trace level and TRACE is the highest level (displays all messages).
    [Note]
    When the <sections> argument is set, the <level> argument must be set as well (no default).
  • <sections> — The debug sections — i.e., the WinDriver API sections — to monitor.
    This argument can be set either to ALL (default) — to monitor all the supported debug sections — or to a quoted string that contains a combination of any of the supported debug-section flags (run 'wddebug help' to see the full list).

Usage Sequence

To log messages using wddebug, use the following sequence:

  • Turn on the Debug Monitor by running wddebug with either the on or dbg_on command; the latter redirects the debug messages to the OS kernel debugger before turning on the Debug Monitor.

    You can use the <level> and <sections> arguments to set the debug level and sections for the log. If these arguments are not explicitly set, the default values will be used; (note that if you set the sections you must also set the level).

    You can also log messages from a renamed WinDriver driver by preceding the command with the name of the driver (default: windrvr1260) — see the <driver_name> argument.

  • If you did not select to redirect the debug messages to the OS kernel debugger (using the dbg_on command), 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 following the instructions displayed 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.
  • At any time while the Debug Monitor is running, you can run wddebug with the following commands:
  • When you are ready, turn off the Debug Monitor by running wddebug with the off command.
    [Note]
    The status command can be used to view information regarding the running WinDriver driver even when the Debug Monitor is off.
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 — windrvr1260.

  • 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', because ALL is the default <sections> value.
  • Dump the debug messages continuously to the command prompt or a file, until the user selects to stop:
    wddebug dump
    wddebug dump <filename>
  • Use the driver and view the debug messages in the command prompt.
  • Turn the Debug Monitor off:
    wddebug off