Using WinDbg for Local Kernel Debugging

Setting Up a System for Local Kernel Debugging

To debug Windows NT Executive messages using a local debugging system, you need to prepare the host and target computers and then connect the two computers with an industry-standard null-modem serial cable. Be sure to start the host computer before restarting the target computer.

A standard, commercially available null-modem serial cable has the following configuration:

· Transmit Data connected to Receive Data

· Receive Data connected to Transmit Data

· Ground connected to Ground

For 9-pin and 25-pin D-subminiature connectors, the cable connects as follows:

· Pin 2 to pin 3

· Pin 3 to pin 2

· Pin 7 to pin 7

The WinDbg logic does not depend on any control pins (such as Data Terminal Ready, Data Set Ready, Request To Send, or Clear To Send). However, in the connectors on both ends of the cable, you may have to put a jumper from Data Terminal Ready to Data Set Ready and from Request To Send to Clear To Send.

· On a db9 connector, this would be a jumper from pin 4 to pin 6 and a jumper from pin 7 to pin 8.

· On a db25 connector, this would be a jumper from pin 20 to pin 6 and from pin 4 to pin 5.

Preparing the target computer for local Kernel debugging is the same as for remote Kernel debugging. The only difference is that instead of connecting a modem to one of the target computer's communications ports, you connect a null-modem serial cable. See "Configuring a System for Debugging," earlier in this chapter, for detailed procedures.

Which port you use (COM1 or COM2) depends on what you did to prepare your target and host computers. The default connection is from COM1 of the host computer to COM2 of the target computer. However, you may change that by editing the boot configuration on the target computer or by changing the command line parameters used when you start WinDbg.

The Windows NT Setup program does not install WinDbg as part of the Windows NT installation process. However, you can easily copy the WinDbg program directly onto the hard disk of the host computer. It is distributed on the Windows NT CD-ROM in an uncompressed format under the \SUPPORT\DEBUG directory.

Note If you do not have a CD-ROM drive, the WinDbg program is also available from Microsoft Support Network. You can request that they send you the software on a floppy disk, or ask for instructions on how to download it from CompuServe.

To Copy and Start WinDbg on the host computer

1. Connect the null-modem serial cable to the communications port defined in the BOOT.INI file of the host computer.

Notice that the communications port can be different for the host and target computers.

2. Create a subdirectory called \SYMBOLS on the host computer's hard disk under the directory in which you have installed Windows NT.

3. Copy the debugging symbols from the \SUPPORT\DEBUG\<platform>\SYMBOLS directory on the CD-ROM to the \SYMBOLS directory on the host computer. Platform refers to the hardware platform of the host computer.

4. Copy all the files from the \SUPPORT\DEBUG\<platform> directory on the CD-ROM to the \SYSTEM32 directory on the host computer. This can be done with the xcopy or copy command. Make sure that the following files are copied to the host computer:

EECXXALP.DLL IMAGEHLP.DLL TLLOC.DLL

EECXXMIP.DLL KDEXTALP.DLL TLPIPE.DLL

EECXXX86.DLL KDEXTMIP.DLL TLSER.DLL

EMALP.DLL KDEXTX86.DLL WINDBG.EXE

EMMIP.DLL SHCV.DLL WINDBG.HLP

EMX86.DLL SYMCVT.DLL WINDBGRM.EXE

5. To start WinDbg in Kernel-debug mode from either the command line or the File Run dialog box in Program Manager, type:

<path> windbg -k <target platform> <com port> <speed> -y <symbol path> -v

where:

Path is the path to the WINDBG.EXE file.

-k invokes the Kernel-debug mode.

Target platform refers to the hardware platform of the target computer and corresponds to the name of the directory from which you obtained the WinDbg files, such as I386, MIPS, or ALPHA.

Com port is the port to which you have connected the null-modem serial cable.

Speed is the baud rate.

-y indicates that the next parameter is the symbol path.

Symbol path is the path to the \SYMBOLS directory created in step 2.

The following is an example of such a command:

c:\ windbg -k i386 com1 19200 -y c:\windows\symbols

6. To create a log of the debugging session, from the Options menu, choose Debug.

7. In the Logfile section of the Debugger Options dialog box, you can:

· Select the Open Automatically check box to have WinDbg open a log file whenever it starts. If you want to specify a path and name for the log file, type one in the Name text box.

· Select the Append check box to append new data to an existing log file. Otherwise, the file will be overwritten.

For more information on WinDbg settings, see the online Help file.

To Run a Local Debugging Session

Once you have prepared the two computers and connected them, you can start a debugging session. There can be many objectives for a debugging session; this chapter discusses the objective of collecting information (in the debug-session log file on the host computer) about the events leading up to a particular Windows NT Executive message on the target computer.

Note Once you are in the Kernel-debug mode of WinDbg, you can display a list of commands by typing help or ? at the KD command prompt on the host computer. The Kernel-debug character-mode command-line interface has a vocabulary of about four dozen commands, plus it supports advanced debugging features such as watches and breakpoints. For more information on the commands and advanced features, see the online Help file.

To Quit a Local Debugging Session

Quitting WinDbg on the host computer at the end of a local debugging session will also save the debug-session log file.

To quit WinDbg and save the log file on the host computer

1. From the Run menu, choose Stop Debugging.

2. From the File menu, choose Exit.

3. Restart the target computer.