How to Set Up a Remote Debug Session Using a Modem

This article was previously published under Q148954
This article has been archived. It is offered "as is" and will no longer be updated.
This article describes the procedures for preparing an X86 Intel-processor-based and RISC-processor-based computer running Windows NTWorkstation or Server for a remote debug session.
- What Is the Need For the Kernel Debugger
- What Is the Process of Remote Debugging
- Configuring a System for Remote Debugging
- Debugger Options
- Editing the BOOT.INI file for Intel x86 Computers
- Changing Firmware Boot Options for RISC Computers
- Preparing the Modem

What Is the Need For the Kernel Debugger

The kernel debugger that comes with Windows NT will produce informationabout the system that is normally not available without the aid of thedebugger. You can enable the kernel debugger from the Windows NT start-upmenu. Enabling the kernel debugger will allow the Windows NT debugger tooutput debugging information to a remote debugger for a remote user toanalyze. This is normally done at the request of a Microsoft customersupport professional for analyzing a fatal error in Windows NT that cannot bediagnosed from the Memory.dmp file or when a Memory.dmp file is notproduced.

What Is the Process of Remote Debugging

The process of Remote debugging happens when two computers are connectedtogether via modems over a phone line. The target computer and the hostcomputer are running the Windows NT kernel debuggers which communicateusing a special debug API and Protocol.

Configuring a System for Remote Debugging

Configuring a system for remote debugging involves changing the bootoptions to tell Windows NT to load the kernel debugger. On an Intelx86 based platform this is done by editing the Boot.ini file. On a RISCbased system (DEC Alpha, MIPS and PPC based processors) this involveschanging the boot options in the firmware menu. You will also need to havea modem and connect it to the appropriate COM port on the target computerand connect an inbound phone line to the modem.

Debugger Options

There are several boot options which can be used in configuring the systemfor debugging. These options are the same on Intel x86 and RISC platforms,although when used on a RISC platform the / is not required:

/DEBUG      - When this option is used, the kernel debugger will be loaded              during boot and kept in memory at all times. This means that              a support professional can dial into the system being debugged              and break into the debugger, even when the system is not              suspended at a Kernel STOP screen./DEBUGPORT  - Specifies the serial port to be used by the kernel              debugger. If no serial port is specified the debugger will              default to COM2 on Intel x86 based computers and to              COM1 on RISC computers./CRASHDEBUG - This option will cause the kernel debugger to be loaded              during boot but swapped out to the pagefile after boot.              As a result, a support professional will not be able to              break into the debugger unless Windows NT is suspended              at a Kernel STOP screen./BAUDRATE   - Sets the Baud rate that the kernel debugger will use.              The default baud rate is 19200. A baud of 9600 is the              normal rate for remote debugging over a modem.				

Whenever DEBUGPORT or BAUDRATE is used, it is not necessary to use DEBUG,as Windows NT assumes that you want the computer to load in DEBUG mode. Atleast one of the above switches must be used to configure a computer forremote debugging, otherwise Windows NT will not load the debugger at all.

Editing the Boot.ini file for Intel x86 Computers

To set up the target computer on an Intel x86 based computer, simply editthe Boot.ini file in the boot partition and add the appropriate debuggeroptions. The Boot.ini file is edited using a standard ASCII text editor. TheBoot.ini file is a file found on the root of the system partition(generally the C drive) and will have the Hidden, System, and Read-Onlyattributes set. These attributes must be changed.

To Change the Attributes of the Boot.ini File

To change the attributes of the Boot.ini file, follow Procedure I or II:

Procedure I:
  1. Type the following at a command prompt:
    attrib -s -h -r c:\boot.ini
  2. Edit BOOT.INI.

    To restore the Read-Only, Hidden, and System attributes when you finish editing the file, type the following at a command prompt:
    attrib +h +r +s c:\boot.ini \
Procedure II:
  1. In File Manager, choose By File Type in the View menu, and thenselect the Show Hidden/System Files box in the By File Type dialogbox, and choose the OK button.
  2. In the File Manager window, select the Boot.ini file, and thenchoose Properties from the File menu.
  3. In the Properties dialog box, clear the Read Only, Hidden, and Systemattribute box and choose the OK button.
  4. Edit the Boot.ini using Notepad or another text editor and add thedebug options as described below.

Configuring the Boot Options in the Boot.ini File

To configure a computer for debugging you must add one of the previousoptions to the Boot.ini. Generally, you will want to add /DEBUG and/BAUDRATE, to lower the baud rate to 9600 and put the computer in debugmode. You should use /DEBUGPORT=COMX if you cannot use the default COMport (COM2) for debugging. The following example shows how to addthese options.

The following is an example of a typical Boot.ini file. Each entry in the[operating systems] section should correspond to the options listed in theboot menu during a normal system startup:

[boot loader]
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT Version 3.5"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT Version 3.5"

To enable the debugger to use COM1 and to communicate at 9600 baud, addthe following or see the example following these step-by-stepinstructions:
  1. Select the startup option that you normally use and add the /DEBUGswitch at the end of the line.
  2. To specify the communications port, add the switch /DEBUGPORT=COM1.
  3. To specify the baud rate, add the switch /BAUDRATE=9600.
The following shows the above Boot.ini file after it has been modified byfollowing steps 1-3 above (NOTE: Line 6 is the rest of line 5 that did notfit on the same line in this article):

[boot loader]
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT Version 3.5"
/debug /debugport=com1 /baudrate=9600
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT Version 3.5"

Changing Firmware Boot Options for RISC Computers

Unlike the Intel x86 computers, which use a Boot.ini file, boot optionson RISC computers are configured through the firmware. The following stepswalk you through configuring the boot options on MIPS-, PPC- and DECAlpha-based computers. Be sure to carry out step 10 for all DEC Alphacomputers before a support professional attempts to dial in and debug thesystem.
  1. Restart the computer. The ARC System screen appears, displaying themain menu from which you can select an action.
  2. On a MIPS and PPC RISC-based system, choose Run Setup to displaythe Setup menu and then choose Manage Startup to display a menu ofthe boot options.
    On a Digital Alpha AXP RISC-based system, choose Supplementary Menu,Set Up the System, and Manage Boot Selection Menu to display a menuof the boot options.
  3. Choose Change a Boot Selection to display a list of the operatingsystems that are installed on this computer.
  4. Choose the Windows NT operating system. If you have more than oneversion of Windows NT installed, select the one that you want todebug. A two-part screen appears for changing the current settingsof the environment variables used to start the RISC-based computer.The environment variable that controls whether or not the RISC-basedcomputer starts up in debug mode is the OSLOADOPTIONS variable.
  5. To edit the value for the OSLOADOPTIONS variable, use the arrow keysto select it from the list of variables. Once selected, it appearsin the Name box at the top of the screen.
  6. Press ENTER to display the Value box.
  7. Type the options you want to add in the Value box, separated byspaces and press ENTER to save them. For example, if you want to turnon DEBUG mode and set the COM port to COM2, you type the following:
    OSLOADOPTIONS debug debugport=com2
    If you do not specify the debug port, the default debug port is set toCOM1.

    Since RISC-based computers allow only a default baud rate of 19200, youdo not need to specify the baud rate.
  8. Press ESC to stop editing.
  9. Based on the type of computer you have, do one of the following:

    - On a MIPS or PPC RISC-based system, choose Return To Main Menu andthen Exit to return to the ARC System screen.


    - On a Digital Alpha AXP RISC-based system, choose the optionSupplementary Menu, save your changes and then choose Boot Menu toreturn to the ARC System screen.
  10. If this is the first time you debug this system you need to carry outadditional configuration steps. For these steps, consult the WindowsNT Resource kit Version 3.51 Update or Update 2, Appendix A.
  11. Restart the computer to run under Windows NT.

Preparing the Modem

To connect to the remote debugger successfully you must connect anexternal modem with auto-answer capabilities to the desired COM port. Mostmodems have this feature, but it is generally disabled. The modem shouldbe set to 9600 baud. For a proper connection, the kernel debugger requiresthat hardware compression as well as error detection and flow control beturned off. Make sure the modem works correctly before proceeding anyfurther. In most cases you will need to configure the modem by connectingto a spare COM port on the target machine or another machine, usingTERMINAL.EXE or some other communication program to send configurationstrings to the modem, then moving the modem to the target computer and COMport without turning off the modem. This is why an internal modem will notwork, as restarting the system will generally reset any of the changes youhave made to the modem settings.

To configure the modem:

NOTE: You can carry out all these steps on the target computer, using the COM port you want to configure as the debug port provided you carrythem out before configuring the debugger on the target system.
  1. Connect a modem with auto-answer capabilities to an available COM porton the target computer or another computer.

    NOTE: Be sure you can move the modem to the target COM port withoutremoving power from the modem.
  2. Run Terminal.exe or some other communications program and configure itto write to the modem.
  3. Set the modem to 9600 baud rate. Consult your modem documentationfor the correct way to do this.
  4. Turn off all hardware compression, flow control, and error detection. For most US Robotics and 3Com modems, type in the following commands to prepare the modem for the debug session. If you are using a modem from another manufacturer, consult your modem documentation for the correct strings to end to the modem.

    AT&F    Set Back to Factory DefaultsAT&H0   Disable Transmit Data Flow ControlAT&I0   Disable Receive Data Flow ControlAT&K0   Disable Data CompressionAT&M0   Disable Error ControlATS0=1  Auto Answer OnAT&D0   Disable Reset Modem on Loss of DTRAT&W    Write to NVRAM						
  5. Enable auto-answer on the modem. This can usually be done by sendingit the string ATS0=1 (the "0" is the number 0, not the letter O).However, you should consult your modem documentation to verify this.
  6. Without removing power from the modem, move it to the correct COMport on the target system.

Additional Reading

For additional information, please see:

- The Windows NT Resource Kit.

- The Microsoft Driver Development Kit.

ntblue prodnt debugref live debug

Article ID: 148954 - Last Review: 12/04/2015 14:26:21 - Revision: 2.2

Microsoft Windows 2000 Server, Microsoft Windows 2000 Advanced Server, Microsoft Windows 2000 Professional Edition, Microsoft Windows 2000 Datacenter Server, Microsoft Windows NT Workstation 3.5, Microsoft Windows NT Workstation 3.51, Microsoft Windows NT Workstation 4.0 Developer Edition, Microsoft Windows NT Server 3.5, Microsoft Windows NT Server 3.51, Microsoft Windows NT Server 4.0 Standard Edition

  • kbnosurvey kbarchive KB148954