Updated: 11 December 1998 |
OpenVMS Alpha System Analysis Tools Manual
Previous | Contents | Index |
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:
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. The system code debugger 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 the system code debugger to the location of the source code files. For an example of the SET SOURCE command, see Section 7.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 the system code debugger cannot find one of the images through this search path, a warning message is displayed. The system code debugger will continue initialization as long as it finds at least one image. If the system code debugger 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.
7.5 Starting the System Code Debugger
To start the system code debugger on the host side, enter the following command:
$ DEBUG/KEEP |
The system code debugger displays the DBG> prompt. With the DBGHK$IMAGE_PATH logical name defined, you can invoke the CONNECT command and optional qualifiers /PASSWORD and /IMAGE_PATH.
To use the CONNECT command and 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, the system code debugger 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, the system code debugger gets 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.
7.6 Summary of System Code Debugger Commands
In general, any OpenVMS debugger command can be used in the system code debugger. For a complete list, refer to the OpenVMS Debugger Manual. The following are a few examples.
In addition, the OpenVMS debugger command SDA can be used 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.
7.7 Using System Dump Analyzer Commands
Once a connection has been established to the target system, the commands listed in the previous section can be used to examine the target system. In addition, some System Dump Analyzer (SDA) commands, such as SHOW SUMMARY and SHOW DEVICE, can be used. 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 |
SDA may be reentered 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 the System Code Debugger.
The system code debugger and the target kernel on the target system use a private Ethernet protocol to communicate. For the two systems to see each other, they have to be on the same Ethernet segment.
The network portion of the target system finds the first Ethernet
device and communicates through it. The network portion of the host
system also finds the first Ethernet device and communicates through
it. However, if for some reason, the system code debugger picks the
wrong device, you can override this by defining the logical
DBGHK$ADAPTOR to the template device name for the appropriate adaptor.
7.9 Troubleshooting Checklist
If you have trouble starting a connection, perform the following tasks to correct the problem:
There are three possible network errors:
The netfail error message has a status code that can be one of the following values:
Value | Status |
---|---|
2, 4, 6 | Internal network error, submit a problem report to Compaq. |
8,10,14,16,18,20,26,28,34,38 | Network protocol error, submit a problem report to Compaq. |
22,24 | Too many errors on the network device most likely due to congestion. Reduce the network traffic or switch to another network backbone. |
30 | Target system scratch memory not available. Check DBGTK_SCRATCH. If increasing this value does not help, submit a problem report to Compaq. |
32 | Ran out of target system scratch memory. Increase value of DBGTK_SCRATCH. |
All others | There should not be any other network error codes printed. If one occurs that does not match the above, submit a problem report to Compaq. |
Accessing OpenVMS executive images' symbols is not always
straightforward with the system code debugger. Only a subset of the
symbols may be accessible at one time and in some cases, the symbol
value the debugger currently has may be stale. To understand these
problems and their solutions, you must understand how the debugger
maintains its symbol tables and what symbols exist in the OpenVMS
executive images. The following sections briefly summarize these topics.
7.11.1 Overview of How the OpenVMS Debugger Maintains Symbols
The debugger can access symbols from any image in the OpenVMS loaded system image list by either reading in the .DSF or .EXE file for that particular image. The .EXE file only contains information about symbols that are part of the symbol vector for that image. The current image symbols for any set module are defined. (You can tell if you have the .DSF or .EXE file by doing a SHOW MODULE. If there are no modules, you have the .EXE file.) This includes any symbols in the SYS$BASE_IMAGE.EXE symbol vector for which the code or data resides in the current image. However, a user cannot access a symbol that is part of the SYS$BASE_IMAGE.EXE symbol vector that resides in another image.
In general, at any one point in time, the debugger can only access the symbols from one image. It does this to reduce the time it takes to search for a symbol in a table. To load the symbols for a particular image, use the SET IMAGE command. When you set an image, the debugger loads all the symbols from the new image and makes that image the current image. The symbols from the previous image are in memory, but the debugger will not look through it to translate symbols. To remove symbols from memory for an image, use the CANCEL IMAGE command (which does not work on the main image, SYS$BASE_IMAGE).
There is a set of modules for each image the debugger accesses. The symbol tables in the image that are part of these modules are not loaded with the SET IMAGE command. Instead they can be loaded with the SET MODULE module-name or SET MODULE/ALL commands. As they are loaded, a new symbol table is created in memory under the symbol table for the image. Figure 7-1 shows what this looks like.
Figure 7-1 Maintaining Symbols
When the debugger needs to look up a symbol name, it first looks at the current image to find the information. If it does not find it there, it then looks into the appropriate module. It determines which module is appropriate by looking at the module range symbols which are part of the image symbol table.
To see what symbols are currently loaded, use the debugger's SHOW
SYMBOL command. This command has a few options to get more than just
the symbol name and value. (See the OpenVMS Debugger Manual for more details.)
7.11.2 Overview of OpenVMS Executive Image Symbols
Depending on whether the debugger has access to the .DSF or .EXE file, different kinds of symbols could be loaded. Most users will have the .EXE file for the OpenVMS executive images and a .DSF file for their private images---that is, the images they are debugging.
The OpenVMS executive consists of two base images, SYS$BASE_IMAGE.EXE and SYS$PUBLIC_VECTORS.EXE, and a number of separately loadable executive images.
The two base images contain symbol vectors. For SYS$BASE_IMAGE.EXE, the symbol vector is used to define symbols accessible by all the separately loadable images. This allows these images to communicate with each other through cross-image routine calls and memory references. For SYS$PUBLIC_VECTORS.EXE, the symbol vector is used to define the OpenVMS system services. Because these symbol vectors are in the .EXE and the .DSF files, the debugger can load these symbols no matter which one the user has.
All images in the OpenVMS executive also contain global and local
symbols. However, none of these symbols ever gets into the .EXE file
for the image. These symbols are put in the specific modules section of
the .DSF file if that module was compiled /DEBUG and the image was
linked /DSF.
7.11.3 Possible Problems You May Encounter
SET IMAGE EXEC_INIT SET MODULE/ALL SET MODULE SHARE$SYS$BASE_IMAGE |
7.12 Sample System Code Debugging Session
This section provides a sample session that shows the use of some
OpenVMS debugger commands as they apply to the system code debugger.
The examples in this session show how to work with C code that has been
linked into the SYSTEM_DEBUG execlet. It is called as an initialization
routine for SYSTEM_DEBUG.
To reproduce this sample session, you need access to the SYSTEM_DEBUG.DSF matching the SYSTEM_DEBUG.EXE file on your target system and to the source file C_TEST_ROUTINES.C, which is available in SYS$EXAMPLES. The target system is booted with the command bootflags 0, 8004, so it stops at an initial breakpoint, and the devices DKB200,ESA0.
Example 7-1 Booting the Target System |
---|
>>> b -fl 0,8004 dkb200,esa0 INIT-S-CPU... INIT-S-RESET_TC... INIT-S-ASIC... INIT-S-MEM... INIT-S-NVR... INIT-S-SCC... INIT-S-NI... INIT-S-SCSI... INIT-S-ISDN... INIT-S-TC0... AUDIT_BOOT_STARTS ... AUDIT_CHECKSUM_GOOD AUDIT_LOAD_BEGINS AUDIT_LOAD_DONE %SYSBOOT-I-GCTFIL, Using a configuration file to boot as a Galaxy instance. OpenVMS (TM) Alpha Operating System, Version V7.2 DBGTK: Initialization succeeded. Remote system debugging is now possible. DBGTK: Waiting at breakpoint for connection from remote host. |
The example continues by invoking the system code debugger's character cell interface on the host system.
Example 7-2 Invoking the System Code Debugger |
---|
$ define dbg$decw$display " " $ debug/keep OpenVMS Alpha Debug64 Version V7.2-019 DBG> |
Use the CONNECT command to connect to the target system. In this example, a password is not set up, and the logical name DBGHK$IMAGE_PATH is used for the image path; so the command qualifiers /PASSWORD and /IMAGE_PATH are not being used. You may need to use them.
When you have connected to the target system, the DEBUG prompt is displayed. Enter the SHOW IMAGE command to see what has been loaded. Because you are reaching a breakpoint early in the boot process, there are very few images. See Example 7-3. Notice that SYS$BASE_IMAGE has an asterisk next to it. This is the currently set image, and all symbols currently loaded in the debugger come from that image.
Example 7-3 Connecting to the Target System |
---|
DBG> connect %node_name TSTSYS %DEBUG-I-INIBRK, target system interrupted %DEBUG-I-DYNMODSET, setting module SYSTEM_ROUTINES DBG> show image image name set base address end address ERRORLOG no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80084000 FFFFFFFF80086FFF NPRW1 FFFFFFFF80CA3600 FFFFFFFF80CA3BFF EXEC_INIT no FFFFFFFF8306E000 FFFFFFFF830A2000 *SYS$BASE_IMAGE yes 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80002000 FFFFFFFF8000EDFF NPRW1 FFFFFFFF80C05C00 FFFFFFFF80C2AFFF SYS$CNBTDRIVER no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF8001A000 FFFFFFFF8001AFFF NPRW1 FFFFFFFF80C2D600 FFFFFFFF80C2D9FF SYS$CPU_ROUTINES_0402 no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80010000 FFFFFFFF800191FF NPRW1 FFFFFFFF80C2B000 FFFFFFFF80C2D5FF SYS$ESBTDRIVER no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF8002C000 FFFFFFFF8002E1FF NPRW1 FFFFFFFF80C30C00 FFFFFFFF80C30FFF SYS$NISCA_BTDRIVER no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF8001C000 FFFFFFFF8002ADFF NPRW1 FFFFFFFF80C2DA00 FFFFFFFF80C30BFF SYS$OPDRIVER no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80030000 FFFFFFFF800337FF NPRW1 FFFFFFFF80C31000 FFFFFFFF80C319FF SYS$PUBLIC_VECTORS no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80000000 FFFFFFFF80001FFF NPRW1 FFFFFFFF80C00000 FFFFFFFF80C05BFF SYSTEM_DEBUG no FFFFFFFF82FFE000 FFFFFFFF83056000 SYSTEM_PRIMITIVES_MIN no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80034000 FFFFFFFF800775FF NPRW1 FFFFFFFF80C31A00 FFFFFFFF80CA11FF SYSTEM_SYNCHRONIZATION_UNI no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80078000 FFFFFFFF800835FF NPRW1 FFFFFFFF80CA1200 FFFFFFFF80CA35FF total images: 12 bytes allocated: 1517736 |
Example 7-4 shows the target system's console display during the connect sequence. Note that for security reasons, the name of the host system, the user's name, and process ID are displayed.
Example 7-4 Target System Connection Display |
---|
DBGTK: Connection attempt from host HSTSYS user GUEST process 2E801C2F DBGTK: Connection attempt succeeded |
To set a breakpoint at the first routine in the C_TEST_ROUTINES module of the SYSTEM_DEBUG.EXE execlet, do the following:
Example 7-5 Setting a Breakpoint |
---|
DBG> set image system_debug DBG> show module module name symbols language size AUX_TARGET no C 15928 BUFSRV_TARGET no C 11288 BUGCHECK_CODES no BLISS 26064 CRTLPRINTF no C 29920 C_TEST_ROUTINES no C 3808 FATAL_EXC no C 1592 HIGH_ADDRESS no C 372 LIB$CALLING_STANDARD_AUX no MACRO64 1680 LINMGR_TARGET no C 13320 LOW_ADDRESS no C 368 OBJMGR no C 5040 PLUMGR no C 19796 POOL no C 116 PROTOMGR_TARGET no C 17868 SOCMGR no C 3324 SYS$DOINIT no AMACRO 81740 TARGET_KERNEL no C 207244 TMRMGR_TARGET no C 3516 XDELTA no BLISS 189940 XDELTA_ISRS no MACRO64 2428 total modules: 20. bytes allocated: 1585168. DBG> set module c_test_routines DBG> show module c_test_routines module name symbols size C_TEST_ROUTINES yes 3808 total C modules: 1. bytes allocated: 1592264. DBG> set language c DBG> show symbol test_c_code* routine C_TEST_ROUTINES\test_c_code5 routine C_TEST_ROUTINES\test_c_code4 routine C_TEST_ROUTINES\test_c_code3 routine C_TEST_ROUTINES\test_c_code2 routine C_TEST_ROUTINES\test_c_code DBG> set break test_c_code |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6549PRO_027.HTML
|