Document revision date: 19 July 1999

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. 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]

you would define DBGHK$IMAGE_PATH as follows.

$ 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.

• 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 the system code debugger.
• Commands that affect memory, such as DEPOSIT and EXAMINE. These commands are equivalent to the XDELTA /,!,[,",' commands.

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.

• It is not possible to 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.
• It is not possible to 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 SDA is invoked from SCD with an immediate command, and that command produces a full screen of output, SDA outputs the message "Press RETURN for more." followed by the "SDA>" prompt before continuing. At this prompt, if another SDA command is entered, SDA does not automatically return to SCD upon completion. To do this, an EXIT command must be entered.

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:

• 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.

There are three possible network errors:

• NETRETRY
  Displayed if the system code debugger connection is lost.
• SENDRETRY
  Indicates a message send failure.
• NETFAIL
  Caused by the two previous messages.

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.

7.11 Access to Symbols in OpenVMS Executive Images

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

• 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 the user cannot access (set breakpoints, etc.) any of the cross-image routines or data cells. The only symbols the user has access to are the ones defined by the current image.
  If the debugger only has access 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 which image it is defined in, you can just do a SET IMAGE, SET MODULE/ALL, and then a SET BREAK.
  There is a debugger workaround for this problem. The debugger and the system code debugger 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 VMS 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, it 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 the user does a SET IMAGE to a base image before all the symbol entries are corrected, it will get 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 the user is looking at stale data. One solution to this is to make sure to do a SET IMAGE 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 re-loads the information from the symbol vector. So, to get around this problem you could SET IMAGE to an image other than SYS$BASE_IMAGE and then use CANCEL MODULE SHARE$SYS$BASE_IMAGE and SET MODULE SHARE$SYS$BASE_IMAGE to do the same thing. The only other solution is to always connect to the target system once all images are loaded which define the real data for values in the symbol vectors. You could also enter the following commands, and you would get the latest values from in 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.

7.12 Sample System Code Debugging Session

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:

1. Load the symbols for the SYSTEM_DEBUG image with the DEBUG SET IMAGE command.
2. Use the SET MODULE command to get the symbols for the module.
3. 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 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

	privacy and legal statement
6549PRO_027.HTML