Starting the Debugger

The Kernel debuggers are started from the command line, using the name of the executable as the command. They support the following command-line options:

-b

Causes the debugger to stop execution on target computer as soon as possible, by causing a debug breakpoint (INT 3).

-c

Causes the debugger to request a resync on connect. Resynchronization ensures that the host and target computers are communicating in sequence.

-m

Causes the debugger to monitor modem control lines. The debugger is only active when the CD (carrier detect) line is active; otherwise, the debugger is in terminal mode.

-n

Causes symbols to be loaded immediately, rather than in a deferred mode.

-v

Verbose mode; displays more information about such things as when symbols are loaded.

-x

Causes the debugger to break in when an exception first occurs, rather than letting the application or module that caused the exception deal with it.

The most commonly used switches are -v (verbose) and -m (for modem debugging).

Generally, the best way to start the debugger is to create a batch file with the necessary commands to set the environment variables followed by the command to start the correct KD debugger.

If the host computer is on a network, you might choose to use the REMOTE.EXE utility included with the Windows NT Resource Kit to start the debugger. REMOTE.EXE is a server/client utility that provides remote network access via named pipes to applications that use STDIN and STDOUT for input and output. This allows users at other computers on the network to connect to your Kernel debugging session and either view the debugging information or enter commands themselves. The syntax for starting the server end of the remote session is as follows:

remote /s "command" Unique_Id [/f foreground_color|/b background_color]

For example:


REMOTE /S "i386kd -v" debug

The server session is ended with @K.

To interact with this session from some other computer, use the remote /c command. The syntax of this command is as follows:

remote /c ServerName Unique_Id [/l lines_to_get|/f foreground_color|/b background_color]

To exit from the remote session, leaving the debugger running on the remote system, use @Q.

For example, if a session with id debug had been started on the computer \\Server1 by using the remote /s command, you could connect to it with the command


REMOTE /C server1 debug

For more information on using the remote command, see the RKTOOLS. HLP file on the Windows NT Resource Kit CD.

Examples

Let us suppose the following:

A sample batch file might be as follows:


REM Local debugging batch file
set _NT_DEBUG_PORT=com2
set _NT_DEBUG_BAUD_RATE=19200
set _NT_SYMBOL_PATH=e:\support\debug\i386\symbols
SET _NT_LOG_FILE_OPEN=c:\temp\debug.log
remote /s "i386kd -v" debug

The last line of the batch file uses the REMOTE utility to start the debugger. This lets people on Windows NT computers who are networked to the host computer (and who have a copy of REMOTE.EXE) connect to the debug session using the following command:

remote /c computername debug

where computername is the name of the host computer.

To allow remote debugging, begin with the batch file in the previous example, change the baud rate to 9600, and add the -m switch to the last line. The result is as follows:


REM remote debugging batch file
set _NT_DEBUG_PORT=com2
set _NT_DEBUG_BAUD_RATE=9600
set _NT_SYMBOL_PATH=e:\support\debug\i386\symbols
SET _NT_LOG_FILE_OPEN=c:\temp\debug.log
remote /s "i386kd -v -m" debug

The batch file should be executed from the directory that contains the debugger files.

When you start the debugger, one of two screens appears, depending upon whether you are doing local debugging or remote debugging.

When doing local debugging, the following screen appears:


**************************************
***********     REMOTE    ************
***********     SERVER    ************
**************************************
To Connect: Remote /C BANSIDHE debug

Microsoft(R) Windows NT Kernel Debugger
Version 3.5
(C) 1991-1994 Microsoft Corp.

Symbol search path is:
KD: waiting to connect...

Once at this screen, you can use ctrl+c to break in to the target computer, if it is still running. If the target is currently stopped at a blue screen, you will most likely break in automatically. If you have any problems, try using a ctrl+r to force a resync between the host and target computers.

If you are doing remote debugging, the same screen appears, with the following extra line:


KD: No carrier detect - in terminal mode

In this case, the debugger is in terminal mode, and you can issue any of the standard AT commands to your modem. Begin by sending commands to disable hardware compression, flow control, and error correction. These commands will vary from modem to modem, so consult your modem documentation. Once you connect to the target system and have a carrier detect signal, you are returned to the debugger.