HP OpenVMS Systems Documentation

OpenVMS Alpha System Analysis Tools Manual

Formats and types a single line to SYS$OUTPUT.

Format

int sda$type (char *ctrstr, __optional_params);

Arguments

ctrstr

OpenVMS usage	char_string
type	character-coded text string
access	read only
mechanism	by reference

Address of a zero-terminated control string.

prmlst

OpenVMS usage	varying_arg
type	quadword (signed or unsigned)
access	read only
mechanism	by value

Optional FAO parameters. All arguments after the control string are copied into a quadword parameter list, as used by $FAOL_64.

Description

Formats and prints a single line to the terminal. This is unaffected by the use of the SDA commands SET OUTPUT or SET LOG.

Condition Values Returned

SDA$_SUCCESS	Indicates a successful completion.
SDA$_CNFLTARGS	Indicates more than twenty FAO parameters given.
Other	Returns from the $PUT issued by SDA$TYPE (the error is also signaled). If the $FAOL_64 call issued by SDA$TYPE fails, the control string is output.

Example

int status;
...
status = sda$type ("Invoking SHOW SUMMARY to output file...");
      

This example displays the message "Invoking SHOW SUMMARY to output file..." to the terminal.

Validates queue structures.

Format

void sda$validate_queue (VOID_PQ queue_header, __optional_params);

Arguments

queue_header

OpenVMS usage	address
type	quadword (unsigned)
access	read only
mechanism	by value

Address from which to start search.

options

OpenVMS usage	mask_longword
type	longword (unsigned)
access	read only
mechanism	by value

The following table shows the flags that indicate the type of queue:

Description

You can use this routine to validate the integrity of doubly-linked, singly-linked or self-relative queues either with longword or quadword links. If you specify the option SDA_OPT$M_QUEUE_LISTQUEUE, the queue elements are displayed for debugging. Otherwise a one-line summary indicates how many elements were found and whether the queue is intact.

Condition Values Returned

None

If an error occurs, it is signaled by SDA$VALIDATE_QUEUE.

Example

int64 temp;
int64 *queue;
...
sda$symbol_value ("EXE$GL_NONPAGED", &temp);
temp += 4;
sda$reqmem ((VOID_PQ)temp, &queue, 4);
sda$validate_queue (queue, SDA_OPT$M_QUEUE_SINGLINK);
      

This sequence validates the nonpaged pool free list, and outputs a message of the form:

        Queue is zero-terminated, total of 204 elements in the queue
      

• Building a system image to be debugged
• Setting up the target system for connections
• Setting up the host system
• Starting SCD
• Troubleshooting connections and network failures
• Looking at a sample SCD session
• Analyzing memory as recorded in a system dump
• Looking at a sample SDD session

This chapter describes the OpenVMS Alpha System Code Debugger (SCD) and how it can be used to debug nonpageable system code and device drivers running at any interrupt priority level (IPL).

You can use SCD to perform the following tasks:

• Control the system software's execution----stop at points of interest, resume execution, intercept fatal exceptions, and so on
• Trace the execution path of the system software
• Monitor exception conditions
• Examine and modify the values of variables
• Test the effect of modifications, in some cases, without having to edit the source code, recompile, and relink

The use of SCD requires two systems:

• The host system, probably also the system where the image to be debugged has been built
• The target system, usually a standalone test system, where the image being debugged is executed

SCD is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code. SCD can also display the source code where the software is executing, and allow you to step by source line.

SCD recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your code or driver is written in more than one language, you can change the debugging context from one language to another during a debugging session.

To use SCD, you must do the following:

• Build a system image or device driver to be debugged.
• Set up the target kernel on a standalone system.
  The target kernel is the part of SCD that resides on the system that is being debugged. It is integrated with XDELTA and is part of the SYSTEM_DEBUG execlet.
• Set up the host system environment, which is integrated with the OpenVMS Debugger.

The following sections cover these tasks in more detail, describe the available user-interface options, summarize applicable OpenVMS Debugger commands, and provide a sample SCD session.

9.1 User-Interface Options

SCD has the following user-interface options:

• A DECwindows Motif interface for workstations
  When using this interface, you interact with SCD by using a mouse and pointer to choose items from menus, click on buttons, select names in windows, and so on.
  Note that you can also use OpenVMS Debugger commands with the DECwindows Motif interface.
• A character cell interface for terminals and workstations
  When using this interface, you interact with SCD by entering commands at a prompt. The sections in this chapter describe how to use the system code debugger with the character cell interface.

For more information about using the OpenVMS DECwindows Motif interface and OpenVMS Debugger commands with SCD, see the OpenVMS Debugger Manual.

9.2 Building a System Image to Be Debugged

1. Compile the sources you want to debug, and be sure to use the /DEBUG and /NOOPT qualifiers.

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

2. Link your image using the /DSF (debug symbol file) qualifier. Do not use the /DEBUG qualifier, which is for debugging user programs. The /DSF qualifier takes an optional filename argument similar to the /EXE qualifier. For more information, see the OpenVMS Linker Utility Manual. If you specify a name in the /EXE qualifier, you will need to specify the same name for the /DSF qualifier. For example, you would use the following command:

   $ LINK/EXE=EXE$:MY_EXECLET/DSF=EXE$:MY_EXECLET OPTIONS_FILE/OPT

   
   The .DSF and .EXE file names must be the same. Only the extensions will be different, that is .DSF and .EXE.
   The contents of the .EXE file should be exactly the same as if you had linked without the /DSF qualifier. The .DSF file will contain the image header and all the debug symbol tables for .EXE file. It is not an executable file, and cannot be run or loaded.
3. Put the .EXE file on your target system.
4. Put the .DSF file on your host system, because when you use SCD to debug code in your image, it will try to look for a .DSF file first and then look for an .EXE file. The .DSF file is better because it has symbols in it. Section 9.4 describes how to tell SCD where to find your .DSF and .EXE files.

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.

Boot Command

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.

• 8000
  This is the SCD boot flag. It enables operation of the target kernel. If this SCD boot flag is not set, not only will it be impossible to use SCD to debug the system, but the additional XDELTA commands related to the target kernel will generate an XDELTA error message. If this boot flag is set, SYSTEM_DEBUG is loaded, and SCD is enabled.
• 0004
  This is the initial breakpoint boot flag. It controls whether the system calls INI$BRK at the beginning and end of EXEC_INIT. Notice that if SCD is the default debugger, the first breakpoint is not as early as it is for XDELTA. It is delayed until immediately after the PFN database is set up.
• 0002
  This is the XDELTA boot flag, which controls whether XDELTA is loaded. It behaves slightly differently when the SCD boot flag is also set.
  If the SCD boot flag is clear, this flag simply determines if XDELTA is loaded. If the SCD boot flag is set, this flag determines whether XDELTA or the system code debugger is the default debugger. If the XDELTA flag is set, XDELTA will be the default debugger. In this state, the initial system breakpoints and any calls to INI$BRK trigger XDELTA, and you must enter an XDELTA command to start using SCD. If the XDELTA boot flag is clear, the initial breakpoints and calls to INI$BRK go to SCD. You cannot use XDELTA if the XDELTA boot flag is clear.

Boot Command Example

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

SCD Configuration File

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

XDELTA Commands

When the system is booted with both the XDELTA boot flag and the SCD boot flag, the following two additional XDELTA commands are enabled:

• n,\xxxx;R ContRol SCD connection
  You can use this command to do the following:
  • Change the password which the SCD host must present
  • Disconnect the current session from SCD
  • Give control to SCD by simulating a call to INI$BRK
  • Any combination of these
  
  Optional string argument xxxx specifies the password that the system code debugger must present for its connection to be accepted. If this argument is left out, the required password is unchanged. The initial password is taken from the first line of the SYS$SYSTEM:DBGTK$CONFIG.SYS file. The new password does not remain in effect across a boot of the target system.

  
  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

  
  Currently, the default action is the same action as +1.
  If SCD is already connected, the ;R command transfers control to SCD, and optionally changes the password that must be presented the next time a system code debugger tries to make a connection. This new password does not last across a boot of the target system.
• n;K Change inibrK behavior
  If optional argument n is 1, future calls to INI$BRK will result in a breakpoint being taken by SCD. If the argument is 0, or no argument is specified, future calls to INI$BRK will result in a breakpoint being taken by XDELTA.

SYSTEM Parameters

• DBGTK_SCRATCH
  Bits 0 through 7 specify how many pages of memory are allocated for SCD. This memory is allocated only if system code debugging is enabled with the SCD boot flag (described earlier in this section). Usually, the default value of 1 is adequate; however, if SCD displays an error message, increase this value.
  Bits 8 through 31 are reserved by Compaq.
• SCSNODE
  Identifies the target kernel node name for SCD. See Section 9.3.1 for more information.

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.

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

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