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.
wddebug_gui is a fully graphical (GUI) version of the Debug Monitor utility for Windows 7/Vista/Server 2008/Server 2003/XP/2000 and Linux.
USB developers should select the
section.![]() | |
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. |
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.
![]() | |
On Windows 7 and Vista, the first time that you enable this option you will need to restart the PC. |
![]() | |
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. |
By default, wddebug_gui logs messages from the
default WinDriver kernel module – windrvr6.sys/.o/.ko. However, you can
also use wddebug_gui to log debug messages
from a renamed version of this driver [12.2], by running
wddebug_gui from the command line with the
driver_name
option:
wddebug_gui <driver_name>
.
![]() | |
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
The wddebug version of the Debug Monitor utility can be executed as a console-mode application on all supported operating systems: Windows, Windows CE, and Linux. To use the console-mode Debug Monitor version, run WinDriver/util/wddebug in the manner explained below.
![]() | |
For console-mode execution on Windows CE, start a command window
(CMD.EXE) on the Windows CE target, and then
run the program WDDEBUG.EXE inside this shell.
You can also execute wddebug via the Windows CE GUI, as explained in section 7.2.2.2. |
wddebug [<driver_name>] [<command>] [<level>] [<sections>]
![]() | |
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 – windrvr6, or a renamed version of this driver (refer to the explanation in section 12.2).
![]() | |
The driver name should be set to the name of the driver file without the file's extension; for example, windrvr6, not windrvr6.sys (on Windows) or windrvr6.o (on Linux). |
<command>
: The Debug Monitor command to execute:
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).
![]() | |
On Windows 7 and Vista, 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.
![]() | |
The on and dbg_on commands can be run
together with the <level> and
<sections> options, described below.
|
dump
: Continuously display ('dump') debug information,
until the user selects to stop.
status
: Display information regarding the running
<driver_name>
driver, 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.
help
: Display usage instructions.
wddebug help
. On Windows CE,
running wddebug
with no arguments activates the utility's
Windows CE GUI version, as explained in section 7.2.2.2.
The following options are applicable only to the on
and
dbg_on
commands:
<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).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 help to view the utility's usage
instructions.
The default debug sections flag is ALL
– sets all the
supported debug sections.
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 driver name is
windrvr6.
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.
status
command, at any time while the Debug Monitor is on, to
view the current debug level and sections, as well as information regarding
the running <driver_name> kernel
module.
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.
off
command.
![]() | |
You can also run wddebug with the
status command while the Debug Monitor is turned off, to view
information regarding the running
<driver_name> driver.
|
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 the default debug sections option.
wddebug dump
wddebug off
wddebug help
As explained above, on all platforms other than
Windows CE, this is equivalent to running
wddebug with no arguments.
On Windows CE, you can also log debug messages by running wddebug without any arguments. This method is designed to enable debug logging on Windows CE platforms that do not have a command-line prompt. On such platforms, you can activate debug logging by double-clicking the wddebug executable; this is equivalent to running the application with no arguments from a command-line prompt.
When executing wddebug without arguments, the user is informed, via a GUI message box, that log messages will be stored in a predetermined log file – wdlog.txt in the root Windows CE directory – and is given the option to cancel or continue.
If the user selects to continue, debug logging is turned on with a trace level
of TRACE
and debug sections ALL
, and the Debug
Monitor begins dumping debug messages to the wdlog.txt log
file. The user can stop the logging and turn off debug logging, at any time,
via a dedicated GUI message box.