|
HP OpenVMS Systems Documentation |
|
OpenVMS Alpha System Analysis Tools Manual
Part 2
Part II describes the System Code Debugger (SCD) and the System Dump
Debugger (SDD). It presents how to use SCD and SDD by doing the
following:
|
Debugging optimized code is much more difficult and is not recommended unless you know the Alpha architecture well. The instructions are reordered so much that single-stepping by source line will look like you are randomly jumping all over the code. Also note that you cannot access all variables. SCD reports that they are optimized away. |
$ LINK/EXE=EXE$:MY_EXECLET/DSF=EXE$:MY_EXECLET OPTIONS_FILE/OPT |
The target kernel is controlled by flags and devices specified when the system is booted, by XDELTA commands, by a configuration file, and by several system parameters. The following sections contain more information about these items.
The form of the boot command varies depending on the type of OpenVMS Alpha system you are using. However, all boot commands have the concept of boot flags and boot devices as well as a way to save the default boot flags and devices. This section uses syntax from a DEC 3000 Model 400 Alpha Workstation in examples.
To use SCD, you must specify an Ethernet device with the boot command on the target system. The target system uses this device to communicate with the host debugger. It is currently a restriction that this device must not be used for anything else (either for booting or network software such as DECnet, TCP/IP products, and LAT products). Thus, you must also specify a different device from which to boot. For example, the following command will boot a DEC 3000 Model 400 from the DKB100 disk, and SCD will use the ESA0 Ethernet device.
>>> boot dkb100,esa0 |
To find out the Ethernet devices available on your system, enter the following command:
>>> show device |
In addition to devices, you can also specify flags on the boot command line. Boot flags are specified as a hex number; each bit of the number represents a true or false value for a flag. The following flag values are relevant to the system code debugger.
The following command boots a DEC 3000 Model 400 from disk DKA0, enables SCD, defaults to using XDELTA, and takes the initial system boot breakpoints.
>>> boot dka0,esa0 -fl 0,8006 |
You can set these devices and flags to be the default values so that you will not have to specify them each time you boot the system. On a DEC 3000 Model 400, use the following commands:
>>> set bootdef_dev dka0,esa0 >>> set boot_osflags 0,8006 |
The SCD target system reads a configuration file in SYS$SYSTEM named DBGTK$CONFIG.SYS. The first line of this file contains a default password, which must be specified by the host debug system to connect to the target. The default password may be the null string; in this case the host must supply the null string as the password (/PASSWORD="") on the connect command as described in Section 8.5, or no password at all. Other lines in this file are reserved by Compaq. Note that you must create this file because Compaq does not supply it. If this file does not exist, you can only run SCD by specifying a default password with the XDELTA ;R command described in the following section.
When the system is booted with both the XDELTA boot flag and the SCD boot flag, the following two additional XDELTA commands are enabled:
The optional integer argument n controls the behavior of
the ;R command as follows:
| Value of N | Action |
|---|---|
| +1 | Gives control to SCD by simulating a call to INI$BRK |
| +2 | Returns to XDELTA after changing the password. 2;R without a password is a no-op |
| 0 | Performs the default action |
| -1 | Changes the password, breaks any existing connection to SCD, and then simulates a call to INI$BRK (which will wait for a new connection to be established and then give control to SCD) |
| -2 | Returns to XDELTA after changing the password and breaking an existing connection |
It is always SCD on the host system that initiates a connection to the target kernel. When SCD initiates this connection, the target kernel accepts or rejects the connection based on whether the remote debugger presents it with a node name and password that matches the password in the target system (either the default password from the SYS$SYSTEM:DBGTK$CONFIG.SYS file, or a different password specified via XDELTA). SCD obtains the node name from the SCSNODE system parameter.
The target kernel can accept a connection from SCD any time the system
is running below IPL 22, or if XDELTA is in control (at IPL 31).
However, the target kernel actually waits at IPL 31 for a connection
from the SCD host in two cases: when it has no existing connection to
an SCD host and (1) it receives a breakpoint caused by a call to
INI$BRK (including either of the initial breakpoints), or (2) when you
enter a 1;R or -1;R command to XDELTA.
8.3.2 Interactions Between XDELTA and the Target Kernel/System Code Debugger
XDELTA and the target kernel are integrated into the same system. Normally, you choose to use one or the other. However, XDELTA and the target kernel can be used together. This section explains how they interoperate.
The XDELTA boot flag controls which debugger (XDELTA or the SCD target kernel) gets control first. If it is not set, the target kernel gets control first, and it is not possible to use XDELTA without rebooting. If it is set, XDELTA gets control first, but you can use XDELTA commands to switch to the target kernel and to switch INI$BRK behavior such that the target kernel gets control when INI$BRK is called.
Breakpoints always stick to the debugger that set them; for example, if you set a breakpoint at location "A" with XDELTA, and then you enter the commands 1;K (switch INI$BRK to the system code debugger) and ;R (start using the system code debugger) then, from SCD, you can set a breakpoint at location "B". If the system executes the breakpoint at A, XDELTA reports a breakpoint, and SCD will see nothing (though you could switch to SCD by issuing the XDELTA ;R command). If the system executes the breakpoint at B, SCD will get control and report a breakpoint (you cannot switch to XDELTA from SCD).
Notice that if you examine location A with SCD, or location B with XDELTA, you will see a BPT instruction, not the instruction that was originally there. This is because neither debugger has any information about the breakpoints set by the other debugger.
One useful way to use both debuggers together is when you have a system that exhibits a failure only after hours or days of heavy use. In this case, you can boot the system with SCD enabled (8000), but with XDELTA the default (0002) and with initial breakpoints enabled (0004). When you reach the initial breakpoint, set an XDELTA breakpoint at a location that will only be reached when the error occurs. Then proceed. When the error breakpoint is reached, possibly days later, then you can set up a remote system to debug it and enter the ;R command to XDELTA to switch control to SCD.
Here is another technique to use when you do not know where to put an
error breakpoint as previously mentioned. Boot the system with only the
SCD boot flag set. When you see that the error has occurred, halt the
system and initiate an IPL 14 interrupt, as you would to start XDELTA.
The target kernel will get control and wait for a connection for SCD.
8.4 Setting Up the Host System
To set up the host system, you need access to all system images and drivers that are loaded (or can be loaded) on the target system. You should have access to a source listings kit or a copy of the following directories:
SYS$LOADABLE_IMAGES:
SYS$LIBRARY:
SYS$MESSAGE:
You need all the .EXE files in those directories. The .DSF files are available with the OpenVMS Alpha source listings kit.
Optionally, you need access to the source files for the images to be debugged. SCD will look for the source files in the directory where they were compiled. If your build system and host system are different, you must use the SET SOURCE command to point SCD to the location of the source code files. For an example of the SET SOURCE command, see Section 8.12.
Before making a connection to the target system, you must set up the logical name DBGHK$IMAGE_PATH, which must be set up as a search list to the area where the system images or .DSF files are kept. For example, if the copies are in the following directories:
DEVICE:[SYS$LDR] DEVICE:[SYSLIB] DEVICE:[SYSMSG] |
$ define dbghk$image_path DEVICE:[SYS$LDR],DEVICE:[SYSLIB],DEVICE:[SYSMSG] |
This works well for debugging using all the images normally loaded on a given system. However, you might be using the debugger to test new code in an execlet or a new driver. Because that image is most likely in your default directory, you must define the logical name as follows:
$ define dbghk$image_path [],DEVICE:[SYS$LDR],DEVICE:[SYSLIB],DEVICE:[SYSMSG] |
If SCD cannot find one of the images through this search path, a warning message is displayed. SCD will continue initialization as long as it finds at least one image. If SCD cannot find the SYS$BASE_IMAGE file, which is the OpenVMS Alpha operating system's main image file, an error message is displayed and the debugger exits.
If and when this happens, check the directory for the image files and
compare it to what is loaded on the target system.
8.5 Starting the System Code Debugger
To start SCD on the host side, enter the following command:
$ DEBUG/KEEP |
SCD displays the DBG> prompt. With the DBGHK$IMAGE_PATH logical name defined, you can invoke the CONNECT command and the optional qualifiers /PASSWORD and /IMAGE_PATH.
To use the CONNECT command and the optional qualifiers (/PASSWORD and /IMAGE_PATH) to connect to the node with name <node-name>, enter the following command:
DBG> CONNECT %NODE_NAME node-name /PASSWORD="password" |
If a password has been set up on the target system, you must use the /PASSWORD qualifier. If a password is not specified, a zero length string is passed to the target system as the password.
The /IMAGE_PATH qualifier is also optional. If you do not use this qualifier, SCD uses the DBGHK$IMAGE_PATH logical name as the default. The /IMAGE_PATH qualifier is a quick way to change the logical name. However, when you use it, you cannot specify a search list. You can use only a logical name or a device and directory, although the logical name can be a search list.
Usually, SCD obtains the source file name from the object file. This is
put there by the compiler when the source is compiled with the /DEBUG
qualifier. The SET SOURCE command can take a list of paths as a
parameter. It treats them as a search list.
8.6 Summary of System Code Debugger Commands
In general, any OpenVMS debugger command can be used in SCD. For a complete list, refer to the OpenVMS Debugger Manual. The following are a few examples:
You can also use the OpenVMS debugger command SDA to examine the target
system with System Dump Analyzer semantics. This command, which is not
available when debugging user programs, is described in the next
section.
8.7 Using System Dump Analyzer Commands
Once a connection has been established to the target system, you can use the commands listed in the previous section to examine the target system. You can also use some System Dump Analyzer (SDA) commands, such as SHOW SUMMARY and SHOW DEVICE. This feature allows the system programmer to take advantage of the strengths of both the OpenVMS Debugger and SDA to examine the state of the target system and to debug system programs such as device drivers.
To obtain access to SDA commands, you simply type "SDA" at the OpenVMS Debugger prompt ("DBG>") at any time after a connection has been established to the target system. SDA initializes itself and then outputs the "SDA>" prompt. Enter SDA commands as required. (See Chapter 4 for more information.) To return to the OpenVMS Debugger, you enter "EXIT" at the "SDA>" prompt. Optionally, you may invoke SDA to perform a single command and then return immediately to the OpenVMS Debugger, as in the following example:
DBG>SDA SHOW SUMMARY |
You may reenter SDA at any time, with or without the optional SDA command. Once SDA has been initialized, the SDA> prompt is output more quickly on subsequent occasions.
Note that there are some limitations on the use of SDA from within SCD.
| Previous | Next | Contents | Index |