KernelDebugRef - Debugging a Remote System
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
The OS/2 Kernel Debugger allows OS/2 developers to diagnose problems quickly, but only if they have access to the system that demonstrates the problem. Installing a modem on the target debug system allows the developers to call the target system by telephone to interact with it.
Although the Kernel Debugger will work with nearly any modem, configuration details are unique to each modem. This section will describe the setup of several modems, and give general guidelines for setting up other modems.
In addition to installing the Kernel Debugger on your own system you will need the following items:
Debug Support - The Target System
The target system is the computer you wish to debug. This computer should have the Kernel Debugger and symbols installed on it. However, if you want to use the target system to configure the modem you must configure the modem before you install the Kernel Debugger. The debugger interferes with communications programs running on the same serial port. If you have another computer available, you can configure the modem on that computer, and then move the modem to the target system.
Debug Support - Modems
Most asynchronous modems are suitable for use as a remote-debug modem. For best performance, the modem should:
- Support auto-answer operation
- Support locked DTE speed at 9600 bps
- Allow connections at CCITT V.32 (9600 bps) and V.22bis (2400 bps)
- Support error-correction (MNP or V.42)
- Save configuration in case of a power-outage.
Debug Support - Modem Data Cables
The configuration of the cable used to connect the modem to the target system is not important. Any serial data cable should have the connections required by the Kernel Debugger. Ensure that you do not use a null-modem cable. A null-modem cable is made to connect a DTE to a DTE (a computer is DTE, and a modem is DCE). A normal cable connects a DTE to a DCE. Use either a 25-to-25 pin cable (for connection to the built-in serial port on a PS/2) or a 25-to-9 pin cable (for connection to a 9-pin serial port).
Required connections for remote debug cable:
25-to-25 Pin Cable
MODEM COMPUTER
DB25P DB25J
ÚÄ¿ ÚÄ¿
³2ÃÄÄÄÄÄÄÄÄÄÄÄ´2³
³3ÃÄÄÄÄÄÄÄÄÄÄÄ´3³
³7ÃÄÄÄÄÄÄÄÄÄÄÄ´7³
ÀÄÙ ÀÄÙ
25-to-9 Pin Cable
MODEM COMPUTER
DB25P DB9J
ÚÄ¿ ÚÄ¿
³2ÃÄÄÄÄÄÄÄÄÄÄÄ´3³
³3ÃÄÄÄÄÄÄÄÄÄÄÄ´2³
³7ÃÄÄÄÄÄÄÄÄÄÄÄ´5³
ÀÄÙ ÀÄÙ
- Note
- The 25-to-9 pin cable reverses pins 2 and 3. Do not confuse this with a null-modem cable. The signals on a 25-to-9 pin cable are normally reversed.
Debug Support - Analog Dial-In Lines
In order to call the modem and connect to the target system, you will need a standard voice-grade telephone line that can be direct-dialed. A connection can be made if the line must go through a switchboard, but it makes it more difficult for the person doing the debugging. Digital telephone lines will not work with the modem.
Debug Support - Communications Software
Use any terminal software that can communicate at 9600 bps, such as the Softerm Custom software that comes with the OS/2 operating system.
Debug Support - Configuring Remote Debug
After you have assembled the required items, follow these steps to prepare the target system for remote debugging:
1.Connect the modem to the target system.
Connect one end of the serial cable to the modem, and the other end to the serial port on the target system. If the target system has more than one serial port, connect the cable to the port configured as COM2 (the Kernel Debugger uses COM2 by default). With PS/2 systems, the Reference Diskette can tell you which port is configured as COM2. Connect the telephone line to the modem, and turn on the modem.
2.Program the modem for DEBUG operation:
Programming the modem may be a complex process, depending on the type of modem and the intended use. There are two ways to program the modem:
- Quick programming for single debug use
- Full programming for "permanent" debug use
The "quick" method is simple, but the modem will not be programmed to recover from loss of power or repeated calls. The "full" method allows the modem to be programmed once, and then used whenever debugging is needed.
The "quick" programming is performed by the Kernel Debugger itself. When the Kernel Debugger boots, it will find and process the file "KDB.INI" in the root directory of the startup drive. This file can contain startup commands for the debugger, one of which can be a modem initialization string. For this reason, the modem must be connected and turned on when the target machine is started, and cannot be turned off until debugging is complete. To use "quick" programming, create a KDB.INI file in the root directory of the startup drive (using the OS/2 System Editor). The first line of the file should be:
B 9600t 2 (Set debugger for 9600 bps, comm port 2)
The second line is the modem initialization string, which is unique to each type of modem. The commands in the initialization string must:
- Activate auto-answer
- Lock the DTE at 9600 bps
- Activate XON/XOFF flow control
- Ignore the DTR signal (not supplied by the Kernel Debugger)
- Suppress result codes
The last line of the KDB.INI file can contain other debugging commands. The last command should be G, which tells the debugger to continue running after processing the KDB.INI file. Without theG, the debugger will stop after processing the KDB.INI file, and you will have to manually enter the G to continue.
The "quick" programming strings for several popular modems are as follows. The string is in the form: ? "modem string", which instructs the Kernel Debugger to send the quoted string to the modem during initialization.
? "AT&F E0 Q1 &B1 &H2 &I2 &D0 S0=1" US Robotics HST and Dual Standard
? "AT&F2 E0 Q2 &D0 &K4 S0=1" Supra FAX/Modem V.32bis
? "AT&F E0 Q1 \Q1 S0=1" Intel 14.4EX
To use "Full" programming, you will configure the modem with the same features as in "quick" programming, but the settings will be stored in the modem's firmware (or set in modem switches). However, determining how to store these settings can be difficult. A thorough study of the modem manual may be required. To program the modem, use a terminal emulation program (for example, the SOFTERM program that is supplied with OS/2). When programming the modem, set the terminal program for 9600 bps operation, and type the appropriate modem string. Since the initialization string instructs the modem to suppress result codes, the modem will not return a response. The "FULL" programming strings for several modems are:
AT&F &B1 &H2 &I2 &W US Robotics HST and Dual Standard
AT&F2 E0 Q2 &D0 &K4 S0=1 &W Supra FAX/Modem V.32bis
AT&F E0 Q1 \Q1 S0=1 &W Intel 14.4EX
- Note
- The US Robotics and HST Dual Standard do not store all settings, but have external switches instead. After programming the modem, set the switches as follows:
1=ON (DTR forced ON)
2=don't care (result code type)
3=OFF (result code suppressed)
4=ON (command echo suppressed)
5=OFF (auto-answer enabled)
6=don't care (carrier detect function)
7=ON (result code in originate mode only)
8=ON (AT commands enabled)
9=ON (don't disconnect for +++)
10=OFF (load NVRAM at power-on)
QUAD=OFF (normal connect - ON if null modem cable used)
When the modem is connected and programmed, the system will be ready for remote debugging. Re-start the system with the Kernel Debugger installed. When the telephone rings, the debug modem will answer the phone and establish connection with the caller. The modem-to-kernel speed should remain at 9600 bps (the default speed used by the Kernel Debugger), but the modem-to-modem speed can be whatever is used by the remote modem. If both modems support error correction, correction will be used.
Debug Support - Limitations
Since the modem communicates with the target system at 9600 bps, but can communicate with the remote modem at any speed, the modem must use flow control to avoid data overruns. The only flow control supported by the Kernel Debugger is XON/XOFF. The only problem this causes is when the remote user wants to pause a continuous data display by pressing Ctrl+S. If the modem has also sent a Ctrl+S, the one from the user will be ignored. You may have to press Ctrl+S several times before the display pauses. This is not a problem if the remote user's communications program supports a "scroll-back buffer," in which case there is no reason to pause the display with Ctrl+S.
Debug Support - Trouble-Shooting
If, after following these directions, you cannot establish a remote debug connection, this guide may help:
| Symptom | Problem | Solution |
|---|---|---|
| Modem rings but doesn't answer | Modem is not set for auto-answer | check modem programming (look for AA light on modem). |
| Phone line not connected to modem | Plug in telephone line to modem. | |
| Modem answers, but Kernel Debugger does not respond | RETAIL kernel installed | Remove RETAIL kernel and install DEBUG kernel. |
| Data cable not connected properly | Connect data cable from modem to target machine. plug into COM2 if target machine has more than one serial port. | |
| remote modem sees meaningless data on screen, unable to control debug session | Modem not locked at 9600 bps | check modem configuration. |
| Kernel Debugger not operating at 9600 bps | Add .B 9600T to KDB.INI file (create file if needed, in root directory of boot drive). Re-boot target machine. |