DebugPrint trace tool DebugPrint  Device Driver Trace tool
for Windows 98, Me, NT and 2000

"Listen to your driver..."

Product information
Installation instructions
DebugPrint Monitor
Using in your driver
PowerDebug
Servicer
Version info Known bugs


PHD Director, Chris Cant's book on WDM Device Drivers is available now.

USE OF DEBUGPRINT IS ENTIRELY AT YOUR OWN RISK.
Easy to use Put DebugPrint formatted print statements in your Windows 98, Windows Me, Windows NT and Windows 2000 C/C++ driver code.
Easy to use Listen to the driver output in the DebugPrint Monitor user mode application, on the same PC.
Easy to use This version works in Windows NT.

Last modified: 29 March 2001.

Version 1.1.0c  Read me
DebugPrint Monitor 1.1.0
Now includes the PowerDebug application to test Power Management and Servicer to manage NT devices.

© Copyright 1998-2000 PHD Computer Consultants Ltd

There is no evaluation version of DebugPrint.

DebugPrint is no longer for sale (20 February 2003)


  • DebugPrint driver traces
  • Formatted print statements
    • Most basic types
    • Prints IRPs
    • Prints UNICODE_STRINGs
    • Prints LARGE_INTEGERs
  • Traces stored if monitor not running
  • Traces at or below DISPATCH_LEVEL IRQL
  • For Windows 98, Me, NT and 2000 x86

  • Full example provided

  • DebugPrint Monitor
  • Displays traces from all running drivers
  • Displays Driver name, timestamp and message
  • Saves and loads trace events in .dpm files
  • Saves its configuration
  • For Windows 98, Me, NT and 2000 x86

  • PowerDebug
  • Suspends or hibernates your computer
  • Displays AC, DC and Disk status
  • Displays power events

  • Servicer
  • Lets you start or stop NT style drivers easily


Product Information

DebugPrint helps you write device drivers for Windows 98, Windows Me, Windows NT and Windows 2000. You can include "print" trace statements in your driver C/C++ code. These print statements are viewed using the DebugPrint Monitor user mode application.

Example code snippet
DriverEntry(...)
{
    DebugPrintInit("Wdm1 free");
    ...
    DebugPrint("RegistryPath is %T",RegistryPath);
    ...
}

Read(...)
{
    ...
    DebugPrint("IRP %I.  Reading %u bytes from %x",
        Irp,
        IrpStack->Parameters.Read.Length,
        Irp->AssociatedIrp.SystemBuffer);
    ...
}

Unload()
{
    ...
    DebugPrintClose();
}
Your driver makes simple calls to the DebugPrint routines. The main useful function, DebugPrint, works like printf. You specify a print format string, getting the values from the remaining parameters. DebugPrint prints most basic types, including wide strings, UNICODE_STRINGs, __int64, LARGE_INTEGERs and basic IRP information.

The trace statements normally only appear in your "checked" debug build. However, you can specify that they are included in the "free" retail build as well.

DebugPrint Monitor is a standard Win32 user mode application which displays trace events from any number of drivers, as they arrive. You can store the trace events in .dpm files and load them again later.

The DebugPrint tools run on a single computer so there is no complicated set up of two computers.

Installing the DebugPrint development kit installs the necessary DebugPrt device driver. This stores the events as they are written by the test drivers, and makes the events available to DebugPrint Monitor when it is ready.

Notes:



If you have installed the version of DebugPrint that came with Chris Cant's book (Writing Windows WDM Device Drivers) you must remove the DebugPrint device before you install this latest version. In the Device Manager, select Other Devices and then uninstall DebugPrint.

Installation instructions

The DebugPrint development kit is supplied as an executable, named dbgpt110.exe (or similar). Run dbgpt110.exe to install the DebugPrint development kit and install the DebugPrt device driver. If you are running Windows 98, you will need to restart your computer before the DebugPrt driver is loaded. You can uninstall the development kit and the DebugPrt driver using Add/Remove Programs in the Control Panel.

Notes:

Quick Checks

Check that the driver has been installed sucessfully by running the DebugPrint Monitor (select Start+Programs+DebugPrint+DebugPrint Monitor). Two event messages should be shown, one saying that the Monitor program has started, and the next saying that the DebugPrint driver has started.
If the Monitor events says that it could not open the DebugPrint driver, try rebooting.

[NT/W2000 only] Check the Servicer tool by selecting Start+Programs+DebugPrint+Servicer tool. Type "DebugPrt" into the Driver box and press Lookup; its Status should show as "Running".

[W98/W2000 only] Check out the PowerDebug tool by selecting Start+Programs+DebugPrint+PowerDebug tool. Press Suspend to attempt to suspend your computer. In W2000, you can press Hibernate to attempt to hibernate your computer.

Wdm1 example

The example driver Wdm1 includes DebugPrint statements which appear in the "checked" build. The Wdm1 driver source is in the Wdm1 subdirectory. The driver executables are in further subdirectories.

The Wdm1 driver only runs in Windows 98 and Windows 2000. Install Wdm1 as follows:
Installing Wdm1
Windows 98 Windows 2000
  • Open the Control Panel
  • Select "Add New Hardware"
  • Click Next twice
  • If uninstalled devices show, select "No, the device isn't in the list" and click Next
  • Select "No, I want to select hardware from a list" and click Next.
  • Select "Other Devices" and click Next.
  • Click "Have Disk", Browse to the Wdm1 sys directory, eg C:\Program Files\DebugPrint\Wdm1\Sys and click OK.
  • Select the model "DebugPrint: Wdm1 Example, checked build" model, and click Next.
  • Click Finish to install the driver.
  • Open the Control Panel
  • Select "Add/Remove Hardware" and click Next
  • Select "Add/Troubleshoot a device" and click Next
  • Select "Add a device" and click Next
  • Select "No, I want to select hardware from a list" and click Next.
  • Select "Other Devices" and click Next.
  • Click "Have Disk", Browse to the Wdm1 sys directory, eg C:\Program Files\DebugPrint\Wdm1\Sys and click OK.
  • Select the model "DebugPrint: Wdm1 Example, checked build" model, and click Next.
  • Click Next and then Finish to install the driver.
Check that the Wdm1 driver has been installed by looking at the Device Manager. In the "Other devices" category, you should see the Wdm1 driver listed.

Run the DebugPrint Monitor (if it is not already running). You should see a few start up messages from the "Wdm1 checked" driver.

If you now run the Wdm1Test user mode program, you should see more messages appearing in the DebugPrint Monitor output. Run Wdm1Test by selecting Start+Programs+DebugPrint+Run Wdm1Test.

Wdm1 project

DebugPrint includes the full source of the Wdm1 driver and the Wdm1Test program. Visual Studio 97 project files are supplied for these C++ projects. Note carefully that you must have the Windows 98 or Windows 2000 DDK installed correctly if you wish to recompile the Wdm1 driver. Further, you will have to copy the Wdm1 project into a directory which has a path that does not a space in. (The standard installation location, C:\Program Files\DebugPrint\Wdm1\sys does contain a space and so is not acceptible.)
You must then alter the Project settings for the build process to work from within Visual Studio. In the General tab, edit the "Build command line" setting. For example, if you copied the Wdm1 driver project to the C:\Wdm1\sys directory then make this the command line:
MakeDrvr %DDKROOT% c: c:\Wdm1\sys checked
Replace "checked" with "free" for the free build. If you use a different drive, then replace the "c:" parameter with the drive that you do use.


DebugPrint Monitor instructions

The DebugPrint Monitor is very easy to use. When started, it begins listening for DebugPrint trace events. If any trace events are buffered up, then these are read and displayed first.

The Monitor displays one event per line. It has columns for the driver name, a timestamp and the actual trace message. The latest event is always scrolled into view.

Use the Edit+Delete events menu or X on the toolbar to clear all the events from the display. Use the View+Show milliseconds and View+Show date menu options to change which portions of the timestamp are displayed. Note that the first event always shows the date.

You can save the current list of events in a .dpm file. This is an ASCII text file with the columns separated by tab characters. You can reload .dpm files.

The Monitor remembers its position on the screen and the column widths.

Printing is not yet supported.



Using in your driver

It is straight forward to use DebugPrint in your driver.

Copy the DebugPrint.c and DebugPrint.h files from the Wdm1 example source code. Include DebugPrint.h in your driver's main header file. Amend your SOURCES file (or equivalent) so that DebugPrint.c is built. If writing an NT style driver, change DebugPrint.c so that it includes ntddk.h rather than wdm.h (or vice versa).

Make calls to the DebugPrint functions detailed below in your driver code. DebugPrintInit must be called at PASSIVE_LEVEL IRQL, eg from your DriverEntry routine. The other routines can be called at DISPATCH_LEVEL IRQL or lower, ie in most driver code, but not in interrupt handling code.

By default the DebugPrint source only does its prints in the "checked" debug build. However, you can force it to work in the "free" build by setting the DEBUGPRINT preprocessor variable to 1 before you include DebugPrint.h, eg:
#define DEBUGPRINT 1

The DebugPrint functions will never overflow the internal output buffer that they allocate. All wide characters are simply cast to single byte ANSI characters when they are put in the output string.

DebugPrint calls should only introduce very minor delays into the execution of your driver. The main work of the DebugPrint calls takes place in a system thread which runs in the background at a low realtime priority.


DebugPrintInit
void DebugPrintInit(IN char* DriverName)
PASSIVE_LEVEL IRQL
Parameters
DriverName
ANSI driver name string
DebugPrintInit

Use DebugPrintInit to initialise the connection to the DebugPrint driver, passing the name of your driver.

You typically use DebugPrintInit in your DriverEntry routine. If you subsequently exit DriverEntry with an error status, make sure that you call DebugPrintClose first.


DebugPrintClose
void DebugPrintClose()
PASSIVE_LEVEL IRQL
DebugPrintClose

Use DebugPrintClose to close the connection to the DebugPrint driver. You typically use DebugPrintClose in your driver unload routine.


DebugPrintMsg
void DebugPrintMsg(IN char* Msg)
DISPATCH_LEVEL IRQL or lower
Parameters
Msg
ANSI string to print
DebugPrintMsg

Use DebugPrintMsg to send a simple ANSI string as a print trace.


DebugPrint
void DebugPrint(IN const char* format, ... )
DISPATCH_LEVEL IRQL or lower
Parameters
format
ANSI format specification string
...
values to match format specifiers
DebugPrint

DebugPrint is the main trace function which lets you produce a print trace, built using the format specification string combined with the following parameters.

Be very very careful to ensure that the parameters match the format specifier characters. Failure to get this right could very easily result in an access violation. Be careful to use the correct upper or lower case format specifier type character. Line feed and carriage return characters in the format string are ignored.

This routine allocates a 100 character buffer for the output string. Use DebugPrint2 if you want to specify the buffer size yourself.
Format Specifiers Type Default width
%c ANSI char char
%C Wide char wchar_t
%d, %i Signed integer in decimal int
%D __int64 in decimal __int64
%I IRP major and minor codes PIRP
%l %*l %nl __int64 in hexadecimal __int64 16
%L %*L %nL LARGE_INTEGER in hexadecimal LARGE_INTEGER 16
%s %*s %ns NULL-terminated ANSI char string char*
%S %*S %nS NULL-terminated Wide char string wchar_t*
%T UNICODE_STRING PUNICODE_STRING
%u ULONG in decimal ULONG
%x %*x %nx ULONG in hexadecimal ULONG 8
The %l, %L, %s, %S and %x format specifier characters let you use one or more modifier characters to specify the maximum output width. The * modifier takes the maximum size from the next integer parameter to DebugPrint. The n modifier specifies the exact output width, where n is one or more characters between '1' and '9'.


DebugPrint2
void DebugPrint2(IN int max, IN const char* format, ... )
DISPATCH_LEVEL IRQL or lower
Parameters
max
Size of buffer to allocate for output string
format
ANSI format specification string
...
values to match format specifiers
DebugPrint2

This version of DebugPrint lets you specify the size of internal buffer to allocate for the output string.


PowerDebug Power Management test tool

The PowerDebug user mode application lets you test the following aspects of Power Management on your computer.

Windows Management Instrumentation (WMI) support

If your driver can power itself down or wake the system up from a sleeping state, then it should support the following WMI data blocks: If these are supported then the device properties includes a Power Management tab which lets the user enable or disable these options.

Servicer device driver management tool

In Windows 2000 it is less easy to stop and start 'NT style' device drivers. In Windows NT you can use the Control Panel Devices applet to do this job.

The Servicer program lets you start and stop 'NT style' device drivers. It should not be used to start and stop Plug and Play WDM device drivers.

Type the name of the driver into the text box. Press Lookup to see if the driver is running. Its status is shown below. Press Stop to start the driver and press Stop to stop the driver. Press OK to exit.


Version Information

DebugPrint driver

1.1.0 April 24 1999 Non-WDM version that works in Windows NT as well
Works in checked Windows builds
New installation program supplied
1.03 February 16 1999 Code made a tiny bit smaller
1.02 November 25 1998 Started event generated with version number
1.01 November 20 1998 Won't be removed if any open handles
Accesses locked
1.00 October 22 1998 Release

Development kit installation program

1.1.0b June 21 1999 Development kit installation routine works even better in W2000 Beta 3
Uninstall routine also updated for W2000b3
1.1.0a June 16 1999 Development kit installation routine works better in W2000 Beta 3

DebugPrint Monitor

1.1.0 March 31 1999 Opens handle to new driver with fixed symbolic link name
Displays time correctly in Windows 98
1.03 January 22 1999 View+Show milliseconds and View+Show date menu options added
1.02 November 25 1998 Starting message has version number
1.01 November 20 1998 Delete events X in toolbar
States operating system in start monitoring message.
1.00 October 22 1998 Release

Test driver code

1.06 May 19 1999 DebugPrintClose must now be called at PASSIVE_LEVEL IRQL
ThreadExiting ensures that thread completes before DebugPrintClose exits
IRP_MN_QUERY_LEGACY_BUS_INFORMATION printed
1.05 April 26 1999 DebugPrint.c altered so that it will compile in NT4
DebugPrint.c DebugPrintClose checks DebugPrintStarted
Device interface only enabled when device started
Revised installation INF files
1.04 February 16 1999 Code made a tiny bit smaller
1.03 January 22 1999 %l, %L and %D format specifiers added
All fixed width modifiers n can now be greater than 9.
1.02 December 28 1998 %*s, %*S, %*x modifier added
%ns, %nS, %nx modifier added, where n in range 1 to 9.
1.01 December 21 1998 DriverName now allocated from NonPagedPool
Correct sizeof() tests used.
December 7 1998 Thread delays for 10 seconds to let DebugPrint driver start
Clear any remaining events when DebugPrintClose called or thread ends

PowerDebug

1.01 March 31 1999 Renamed from Wdm2Power
1.00 December 12 1998 Release

Servicer

1.0.0.4 June 21 1999 Better lookup in Windows 2000 Beta 3
1.00 March 31 1999 Release


Known bugs

Dev kit installation program September 13 1999 The installation fails with Internal Error 53 if you try to install DebugPrint without Administrator privileges.


Other great PHD products
PHD Computer Consultants Ltd makes no representations or warranties about the suitability of the software, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. PHD shall not be liable for any damages suffered by a user as a result of using, modifying or distributing the software or its derivatives.