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.

Put DebugPrint formatted print statements in your Windows 98, Windows Me, Windows NT and Windows 2000 C/C++ driver code. Listen to the driver output in the DebugPrint Monitor user mode application, on the same PC. 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:

• You can only use DebugPrint at DISPATCH_LEVEL IRQL or lower, ie not in interrupt routines.
• When the test driver code starts, it tries to connect to the DebugPrint driver for 5 minutes. This ensures that the DebugPrint driver device is up and running at boot time.
• DebugPrint always transfers characters in single bytes.
• There is no limit to the number of trace messages that the DebugPrint driver stores. As these are stored in nonpaged memory, this could cause a problem if a large number of messages are buffered up without being read by DebugPrint Monitor.

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:

• The standard library MFC42.DLL must be in your system directory.
• The development kit cannot be installed in Windows NT 3.51 or earlier, as NT 3.51 uses the old Program Manager shell. However, DebugPrint does run satisfactorily in NT 3.51. You can either install it "by hand", or contact PHD to get the DbgInstall tool.
• If any test drivers are connected to the DebugPrt driver or if the DebugPrint Monitor is running then you will not be able to uninstall or reinstall the DebugPrt driver.
• Note that you need to have Administrator privileges if you want to install the development kit in NT 4 or Windows 2000. If you do not have sufficient privilege, the dev kit install fails with Internal Error 53.

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.

• Select Start+Programs+DebugPrint+Wdm1Test project to open the Wdm1Test project.
  
• Select Start+Programs+DebugPrint+Wdm1 driver project to open the Wdm1 driver project.

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 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

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.

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.

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

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

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'.

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

PowerDebug Power Management test tool

• Lets you suspend your computer, ie put into standby mode
• On Windows 2000, lets you hibernate the computer
• Displays AC power, DC Battery status and hard disk status
• Displays WM_POWERBROADCAST events

Windows Management Instrumentation (WMI) support

• PowerDeviceEnable (GUID_POWER_DEVICE_WAKE_ENABLE)
• PowerDeviceWakeEnable (GUID_POWER_DEVICE_WAKE_ENABLE)

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

Development kit installation program

DebugPrint Monitor

Test driver code

PowerDebug

Servicer

Known bugs