 |
OpenVMS Alpha System Analysis Tools Manual
9.5 Starting the System Code Debugger
To start SCD on the host side, enter the following command:
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.
9.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:
- Commands to manipulate the source display, such as TYPE and SCROLL.
- Commands used in OpenVMS debugger command programs, such as DO and
IF.
- Commands that affect output formats, such as SET RADIX.
- Commands that manipulate symbols and scope, such as EVALUATE, SET
LANGUAGE, and CANCEL SCOPE. Note that the debugger SHOW IMAGE command
is equivalent to the XDELTA ;L command, and the debugger DEFINE command
is equivalent to the XDELTA ;X command.
- Commands that cause code to be executed, such as STEP and GO. Note
that the debugger STEP command is equivalent to the XDELTA S and O
commands, and the debugger GO command is equivalent to the XDELTA ;P
and ;G commands.
- Commands that manipulate breakpoints, such as SET BREAK and CANCEL
BREAK. These commands are equivalent to the XDELTA ;B command. However,
unlike XDELTA, there is no limit on the number of breakpoints in SCD.
- Commands that affect memory, such as DEPOSIT and EXAMINE. These
commands are equivalent to the XDELTA /,!,[,",' commands.
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.
9.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:
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.
- You cannot switch between processes, whether requested explicitly
(SET PROCESS <name>) or implicitly (SHOW PROCESS <name>).
The exception to this is that access to the system process is possible.
- You cannot switch between CPUs.
- SDA has no knowledge of the OpenVMS debugger's Motif or Windows
interfaces. Therefore, all SDA input and output occurs at the terminal
or window where the OpenVMS debugger was originally invoked. Also,
while using SDA, the OpenVMS debugger window is not refreshed; you must
exit SDA to allow the OpenVMS debugger window to be refreshed.
- When you invoke SDA from SCD with an immediate command, and that
command produces a full screen of output, SDA displays the message
"Press RETURN for more." followed by the "SDA>" prompt before
continuing. If you enter another SDA command at this prompt, SDA does
not automatically return to SCD upon completion. To do this, you must
enter an EXIT command.
9.8 System Code Debugger Network Information
The SCD host and the target kernel 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, SCD picks the wrong device, you can
override this by defining the logical DBGHK$ADAPTOR to the template
device name for the appropriate adaptor.
9.9 Troubleshooting Checklist
If you have trouble starting a connection, perform the following tasks
to correct the problem:
- Check SCSNODE on the target system.
It must match the name you
are using in the host CONNECT command.
- Make sure that both the Ethernet and boot device are on the boot
command.
- Make sure that the host system is using the correct Ethernet
device, and that the host and target systems are connected to the same
Ethernet segment.
- Check the version of the operating system and make sure that both
the host and target systems are running the same version of the OpenVMS
Alpha operating system.
9.10 Troubleshooting Network Failures
There are three possible network errors:
- NETRETRY
Indicates the system code debugger connection is lost
- SENDRETRY
Indicates a message send failure
- NETFAIL
Results from the two previous 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 previous ones, submit a problem report
to Compaq.
|
9.11 Access to Symbols in OpenVMS Executive Images
Accessing OpenVMS executive images' symbols is not always
straightforward with SCD. 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.
9.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 reading in either the .DSF or .EXE file for that
particular image. The .EXE file contains information only 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, you 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 access only 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 them 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 9-1 shows what this looks like.
Figure 9-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 the symbols that are currently loaded, use the debugger's SHOW
SYMBOL command. This command has a few options to obtain more than just
the symbol name and value. (See the OpenVMS Debugger Manual for more details.)
9.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 you have.
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 module's section
of the .DSF file if that module was compiled using /DEBUG and the image
was linked using /DSF.
9.11.3 Possible Problems You May Encounter
- Access to All Executive Image Symbols
When the
current image is not SYS$BASE_IMAGE, but one of the separately loaded
images, the debugger does not have access to any of the symbols in the
SYS$BASE_IMAGE symbol vector. This means you cannot access (set
breakpoints, and so on) any of the cross-image routines or data cells.
The only symbols you have access to are the ones defined by the current
image.
If the debugger has access only to the .EXE file, then only
symbols that have vectors in the base image are accessible. For .DSF
files, the current image symbols for any set module are defined. (You
can tell if you have the .DSF or .EXE by using the SHOW MODULE
command---if there are no modules you have the .EXE). This includes any
symbols in the SYS$BASE_IMAGE.EXE symbol vector for which the code or
data resides in the current image. However, the user cannot access a
symbol that is part of the SYS$BASE_IMAGE.EXE symbol vector that
resides in another image. For example, if you are in one image and you
want to set a breakpoint in a cross-image routine from another image,
you do not have access to the symbol. Of course, if you know in which
image it is defined, you can do a SET IMAGE, SET MODULE/ALL, and then a
SET BREAK.
There is a debugger workaround for this problem. The
debugger and SCD let you use the SET MODULE command on an image by
prefixing the image name with SHARE$ (SHARE$SYS$BASE_IMAGE, for
example). This treats that image as a module which is part of the
current image. In the previous figure, think of it as another module in
the module list for an image. Note, however, that only the symbols for
the symbol vector are loaded. None of the symbols for the modules of
the SHARE$xxx image are loaded. Therefore, this command is only useful
for base images.
So, in other words, by doing SET MODULE
SHARE$SYS$BASE_IMAGE, the debugger gives you access to all cross-image
symbols for the OpenVMS executive.
- Stale Data from the Symbol Vector
When an
OpenVMS executive based image is loaded, the values in the symbol
vectors are only correct for information that resides in that based
image. For all symbols that are defined in the separately loaded
images, the based image contains a pointer to a placeholder location.
For routine symbols this is a routine that just returns "an image not
loaded" failure code. A symbol vector entry is fixed to contain the
real symbol address when the image in which the data resides is loaded.
Therefore, if you do a SET IMAGE command to a base image before all
the symbol entries are corrected, the SET IMAGE obtains the placeholder
value for those symbols. Then, once the image containing the real data
is loaded, the debugger will still have the placeholder value. This
means that you are looking at stale data. One solution to this is to
make sure to do a SET IMAGE command on the base image in order to get
the most up-to-date symbol vector loaded into memory.
The CANCEL
IMAGE/SET IMAGE combination does not currently work for SYS$BASE_IMAGE
because it is the main image and DEBUG does not allow you to CANCEL the
main image. Therefore, if you connect to the target system early in the
boot process, you will have stale data as part of the SYS$BASE_IMAGE
symbol table. However, the SET MODULE SHARE$xxx command always reloads
the information from the symbol vector. So, to solve this problem you
could SET IMAGE to an image other than SYS$BASE_IMAGE and then use the
CANCEL MODULE SHARE$SYS$BASE_IMAGE and SET MODULE SHARE$SYS$BASE_IMAGE
commands to do the same thing. The only other solution is to always
connect to the target system once all images are loaded that define the
real data for values in the symbol vectors. You could also enter the
following commands, and you would obtain the latest values from the
symbol vector:
SET IMAGE EXEC_INIT
SET MODULE/ALL
SET MODULE SHARE$SYS$BASE_IMAGE
|
- Problems with SYS$BASE_IMAGE.DSF
For those who
have access to the SYS$BASE_IMAGE.DSF file, there may be another
complication with accessing symbols from the symbol vector. The problem
is that the module SYSTEM_ROUTINES contains the placeholder values for
each symbol in the symbol vector. So, if SYSTEM_ROUTINES is the
currently set module (which is the case if you are sitting at the
INI$BRK breakpoint) then the debugger will have the placeholder value
of the symbol as well as the value in the symbol vector. You can see
what values are loaded with the SHOW SYMBOL/ADDRESS command. The symbol
vector version should be marked with (global); the local one is not.
To set a breakpoint at the correct code address for a routine when
in this state, use the SHOW SYMBOL/ADDRESS command on the routine
symbol name. If the global and local values for the code address are
the same, then the image with the routine has not yet been loaded. If
not, set a breakpoint at the code address for the global symbol.
9.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 SCD. 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, the host system needs 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 boot flags 0, 8004,
so it stops at an initial breakpoint, and the devices DKB200,ESA0.
| Example 9-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 9-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, the target system's default password is the null string, 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 DBG> 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 9-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 9-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 9-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 9-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:
- Load the symbols for the SYSTEM_DEBUG image with the DEBUG SET
IMAGE command.
- Use the SET MODULE command to obtain the symbols for the module.
- Set the language to be C and set a breakpoint at the routine
test_c_code.
The language must be set because C is case sensitive
and test_c_code needs to be specified in lowercase. The language is
normally set to the language of the main image, in this example
SYS$BASE_IMAGE.EXE. Currently that is not C.
| Example 9-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
|
Now that the breakpoint is set, you can proceed and activate the
breakpoint. When that occurs, the debugger tries to open the source
code for that location in the same place as where the module was
compiled. Because that is not the same place as on your system, you
need to tell the debugger where to find the source code. This is done
with the debugger's SET SOURCE command, which takes a search list as a
parameter so you can make it point to many places.
| Example 9-6 Finding the Source Code |
DBG> set source/latest sys$examples,sys$library
DBG> go
break at routine C_TEST_ROUTINES\test_c_code
166: x = xdt$fregsav[0];
|
Now that the debugger has access to the source, you can put the
debugger into screen mode to see exactly where you are and the code
surrounding it.
| Example 9-7 Using the Set Mode Screen
Command |
DBG> Set Mode Screen; Set Step Nosource
- SRC: module C_TEST_ROUTINES -scroll-source------------------------------------
151: xdt$fregsav[5] = in64;
152: xdt$fregsav[6] = in32;
153: if (xdt$fregsav[9] > 0)
154: *pVar = (*pVar + xdt$fregsav[17])%xdt$fregsav[9];
155: else
156: *pVar = (*pVar + xdt$fregsav[17]);
157: xdt$fregsav[7] = test_c_code3(10);
158: xdt$fregsav[3] = test;
159: return xdt$fregsav[23];
160: }
161: void test_c_code(void)
162: {
163: int x,y;
164: int64 x64,y64;
165:
-> 166: x = xdt$fregsav[0];
167: y = xdt$fregsav[1];
168: x64 = xdt$fregsav[2];
169: y64 = xdt$fregsav[3];
170: xdt$fregsav[14] = test_c_code2(x64+y64,x+y,x64+x,&y64);
171: test_c_code4();
172: return;
173: }
- OUT -output-------------------------------------------------------------------
- PROMPT -error-program-prompt--------------------------------------------------
DBG>
|
|
