Debugging Printer Drivers with WINDBG and WINDBGRM
  
PSS ID Number: Q107727
Article last modified on 09-18-1995
 
3.10
 
WINDOWS
 

----------------------------------------------------------------------
The information in this article applies to:
 
 - Microsoft Win32 Device Development Kit (DDK) for Windows NT,
   version 3.1
----------------------------------------------------------------------
 
SUMMARY
=======
 
This article describes the prerequisites and steps to do source level
debugging of a Windows NT version 3.1 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
4. menu.
 
5. 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.
 
6. 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.
 
7. 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.
 
8. 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).
 
9. 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.
 
Additional reference words: 3.10
KBCategory: kbprg
KBSubcategory:
=============================================================================
Copyright Microsoft Corporation 1995.
