Debugging Printer Driver in User-mode

(with WinDBG and WinDBGRm)

Jan 29, 1997
Web posted at: 11:30 p.m. EDT

This information is provided "as is", there is no support or guarantee from this WEB Site.

Go to Menu page

Back to J&K Home Page

The information in this article applies to:

- Microsoft Win32 Device Development Kit (DDK) for Windows NT version 3.1. - 3.51

SUMMARY

This article describes the prerequisites and steps to do source level debugging of a Windows NT version 3.1 - 3.51 printer driver such as the PostScript driver, PSCRIPT.DLL, using the WINDBG version 3.1 debugger and WINDBGRM version 3.1 remote debugger utilities which are included with the Microsoft Win32 Software Development Kit (SDK) for Windows NT version 3.1. This information is to be used in addition to Chapters 12 and 13 of the "Tools User's Guide" from the Microsoft Win32 SDK.

The Win32 DDK includes source code for the Windows NT 3.1 PostScript printer driver, the Build utility, and a MAKEFILE.DEF build macros file.

REQUIREMENTS FOR REMOTE DEBUGGING

Two computers are required to perform remote debugging. Remote debugging of printer drivers with WINDBG is required because WINDBG attaches to, and occassionally halts, the Win32 client-server subsystem process CSRSS.EXE that owns printer drivers. CSRSS.EXE also handles local procedure calls (LPCs), and when halted cannot handle LPCs or input, which effectively freezes the debugger "host" computer. However, the "target" computer running the driver to be debugged and WINDBGRM can communicate to the host via network or null-modem serial communications to resume host operation.

Information on the configuration of the two computers can be found on pages 411-413 of the "Tools User's Guide."

You must run Windows NT with administrative priviledges on the host to have the priviledges necessary for remote debugging with WINDBG. The target can be used with either user level or administrative level priviledges.

You may use either the free or checked build of Windows NT on either or both computers.

CONFIGURING THE SYSTEMS FOR REMOTE DEBUGGING

To allow WINDBG to debug CSRSS.EXE from the target computer, you must run REGEDT32.EXE and modify the following flag in the registry of the target computer:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SessionManager

Double-click the GlobalFlag, and change it from 0x211a0000 to 0x21120000. (Flag 0x00080000 disables the ability to debug the affected computer's CSRSS.EXE. Do not modify this flag on the host to prevent accidentally attaching WINDBG to the host's CSRSS.EXE file, which will hang the host.) You must shut down and reboot the target computer for this setting to take effect.

Use Print Manager or the printer setup in Control Panel to configure the target machine for the printer you will be using. Be sure to connect the printer to a local port or FILE:, but not a network printer, so that your printer driver may be used during later debugging.

NOTE: Before initiating remote debugging, it is recommended that you save any open files and exit any nonessential applications.

Configure the target and host computers' communication transport as described on pages 412 and 413 of the "Tools User's Guide." The TL*.DLL communications DLLs are installed in the Win32 SDK's BIN directory, typically \MSTOOLS\BIN. For speed and usability reasons, Microsoft recommends using network named pipes instead of a null-modem serial connection between the target computer and the host computer.

VERIFYING PROPER CONFIGURATION

Perform the following steps in the order listed to verify that both computers are configured properly for remote debugging:

On The Host

1. Start WINDBGRM on the target computer with the /c option, or select its Connect! menu, which will cause a "Connecting" window to pop up.

2. From the Options menu, choose the appropriate Transport DLL. (Select the Default Transport Layer check box in the Transport DLL dialog to retain this transport for future sessions.)

On The Target

1. Start WINDBG on the host computer.

2. Configure the matching communications settings in the Transport Layer drop-down combo box by choosing Debug from the Options menu, and choosing Debugger DLLs.

3. In WINDBG, pop up a Command Window by choosing Command from the Window menu.

4. At the Command Window prompt, enter ".attach -1" to attach to the CSRSS.EXE process. If connecting to the target machine is successful, the "Connecting" window on the target will disappear immediately, and "Module load: csrss.exe (symbols converted and loaded)" will be displayed on the host's WINDBG Command Window.

5. If WINDBG prompts you with a request for the location of CSRSS.EXE or CSRSRV.DLL, you must provide it the path to these executables so that the printer driver will be properly loaded later. If CSRSS.EXE and CSRSRV.DLL do not have their own symbols, you will need to load them anyway. Numerous other modules will then be loaded. You can choose the Ignore button when prompted for DLLs you do not need to debug. Checked drivers and modules that you have symbols for should be displayed as having their symbols converted and loaded.

6. When the system DLLs are loaded, the WINDBG Command Window on the host will report "Process attached -- stopped" and provide a prompt. Be sure that the above connection and other steps work before proceeding.

NOTE: Version 3.1 of WINDBG and WINDBGRM cannot detach from an attached process, and therefore there is no convenient way to end a debugging session. No matter what you do to end the session, you will probably hang the target machine and have to power cycle. On the host, you may be able to close WINDBG; if not, you should be able to terminate WINDBG by choosing End Task from Windows NT's Task List. (Press CTRL+ESC or double-click in unused screen space to bring up the Task List.) The CSRSS.EXE task should remain loaded for future debugging sessions without rebooting the host, although other explicitly attached processes may be closed when WINDBG exits, as can be seen with the PVIEW utility included with the Win32 SDK. If the closed process was loaded at boot time, you will need to shut down and reboot. WINDBG for future versions of Windows NT should be able to detach from attached processes.

7. To inform WINDBG where *.DBG symbol files can be found for host system components, specify the path in the Search Path field of the User DLL Defaults dialog box (found by choosing Debug from the Options menu, choosing User DLLs, and choosing Defaults).

8. On the host machine, choose Save As from WINDBG'S Program menu to save a workspace that will include your communications configuration so that you can retrieve it by choosing Open from the Program menu.

BUILDING AND LOADING A CHECKED DRIVER

1. Launch the Win32 DDK's Checked Build Environment. Enter "set" at its command prompt, and verify that the following environment variables are properly set for use by the DDK's Build utility (BUILD.EXE)and MAKEFILE.DEF macros for correctly compiling and linking WINDBG symbol

information:

MSC_OPTIMIZATION=/Od /Oi

NTDEBUG=ntsd

NTDEBUGTYPE=windbg

2. If you are using the 32-bit C compiler from the Win32 SDK instead of the

separate 32-bit Microsoft VC++ retail product, also set the following:

NTSDK=1

You can set these environment variables through the Control Panel's System dialog box, by entering "set" commands at the command prompt, or in a batch file prior to building.

3. In a console window, change to the DDK directory SRC\PRINT\LIB and type "build". For the PostScript driver, you can do the same for SRC\PRINT\PSCRPTUI. Then change to the printer driver's source directory, such as SRC\PRINT\PSCRIPT, and run Build (for example, "build - cef") to rebuild all and create a BUILD.LOG file, and perhaps to create BUILD.WRN and BUILD.ERR files for severe warning or error messages. Assuming the build is error free, the location of the newly built, checked driver will be in the Build console output (for example, in \DDK\LIB\I386\CHECKED).

NOTE: The paths to the binaries that you want symbol information for must be exactly the same, including drive letter, on both target and host machines in order for WINDBG to find and use the symbolic information.

4. On both the host and target, change to the directory containing the existing driver (such as \WINDOWS\SYSTEM32\SPOOL\DRIVERS\W32X86 for the i86 PostScript driver PSCRIPT.DLL). For printer drivers, this will be something similar to C:\WINDOWS\SYSTEM32\SPOOL\DRIVERS\W32X86.

5. Save the original driver. If you have not printed since booting up, you can delete the driver; otherwise, you can rename it.

6. Copy the newly built checked driver into the appropriate directory on both the target and host. The copy on the target will be run during later debugging; the copy on the host will be used by WINDBG for getting debugging information. (A future version of WINDBG may allow communicating symbolic information from the target to the host.) More sophisticated methods of installing the driver are possible, but are not covered in this article.

DEBUGGING

Keep in mind that you will be running the checked driver, and the application that prints, on the target computer running WINDBGRM. The host computer running WINDBG is for debugging.

1. Connect WINDBGRM on the target with WINDBG on the host as noted above if not already connected.

2. On the host, in WINDBG'S Command Window, set break points such as:

> bp {,enable.c,PSCRIPT.DLL}DrvEnableDriver

NOTE: There are no spaces between the close brace and the DrvEnableDriver() function. This break point will be uninstantiated until the printer driver is loaded for printing.

3. Enter "g" in WINDBG's Command Window on the host (or press the F5 key or the arrow tool on the toolbar) to continue.

4. On the target, run a printing application such as Notepad and print. (This assumes the correct printer is already selected and connected to a local port or to FILE: as noted above.) Before printing starts, WINDBG's Command Window on the host should show that the printer driver and its symbols are loaded.

5. WINDBG on the host will break several times for exceptions; to continue, you can enter "gn" in the command window to ignore the (typically harmless) exceptions.

6. When a break point is hit, a source window should pop up in WINDBG on the host, providing you with source level debugging of your printer driver similar to local source level debugging of applications or DLLs, but interacting with the debuggee on the target instead of the WINDBG host.