[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Alpha System Analysis Tools Manual


Previous Contents Index


SDA$TYPE

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 Successful completion.
SDA$_CNFLTARGS Indicates more than twenty FAO parameters given.
Other Returned from the $PUT issued by SDA$TYPE (the error is also signaled). If the $FAOL_64 call issued by SDA$TYPE fails, a blank line is output.

Status returns one of the above.


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.


SDA$VALIDATE_QUEUE

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 show the flags that indicate the type of queue:
Flag Meaning
None Defaults to double-linked longword queue
SDA_OPT$M_QUEUE_BACKLINK Validates the integrity of a double-linked queue using the back links instead of the forward links
SDA_OPT$M_QUEUE_LISTQUEUE Displays queue elements for debugging
SDA_OPT$M_QUEUE_QUADLINK Sets a quadword queue
SDA_OPT$M_QUEUE_SELF Sets a self-relative queue
SDA_OPT$M_QUEUE_SINGLINK Sets a single-linked queue

Description

This routine can be used to validate the integrity of double-linked, single-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 purposes. Otherwise a one-line summary will indicate 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 
      


Part 2
OpenVMS Alpha System Code Debugger & System Dump Debugger

Part II describes the System Code Debugger and the System Dump Debugger. It presents how to use the System Code Debugger and System Dump Debugger tools by doing the following:


Chapter 7
The OpenVMS Alpha System Code Debugger

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

The system code debugger can be used to perform the following tasks:

The use of the system code debugger requires two systems:

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

The system code debugger 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 the system code debugger, you must do the following:

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

7.1 User-Interface Options

The system code debugger has the following user-interface options:

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

7.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. The system code debugger 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 the system code debugger to debug code in your image, it will try to look for a .DSF file first and then look for a .EXE file. The .DSF file is better because it has symbols in it. Section 7.4 describes how to tell the system code debugger where to find your .DSF and .EXE files.

7.3 Setting Up the Target System for Connections

The target kernel is controlled by flags and devices specified when the system is booted, XDELTA commands, a configuration file, and several sysgen 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 the system code debugger, you must specify an Ethernet device with the boot command on the target system. This device will be used by the target system 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 to boot from. For example, the following command will boot a DEC 3000 Model 400 from the dkb100 disk, and the system code debugger 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.

Boot Command Example

The following command boots a DEC 3000 Model 400 from the dka0 disk, enables the system code debugger, 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

System Code Debugger Configuration File

The system code debugger 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. 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 cannot run the system code debugger.

XDELTA Commands

When the system is booted with the system code debugger boot flag, the following two additional XDELTA commands are enabled:

SYSGEN Parameters

7.3.1 Making Connections Between the Target Kernel and the System Code Debugger

It is always the system code debugger that initiates a connection to the target kernel. When the system code debugger 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). The system code debugger gets the node name from the SCSNODE SYSGEN parameter.

The target kernel can accept a connection from the system code debugger anytime 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 system code debugger in two cases: when it has no existing connection to a system code debugger 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 from XDELTA.

7.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 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 system code debugger and to switch INI$BRK behavior such that the system code debugger 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 command 1;K (switch INI$BRK to the system code debugger) and ;R (start using the system code debugger). Then, from the system code debugger, you set a breakpoint at location "B". If the system executes the breakpoint at A, XDELTA will report a breakpoint, and the remote debugger will see nothing (though you could switch the system code debugger by issuing the XDELTA ;R command). If the system executes the breakpoint at B, the system code debugger will get control and report a breakpoint (you cannot switch to XDELTA).

Notice that if you examine location A with the system code debugger, 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 the system code debugger 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 the system code debugger.

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 system code debugger flag. When you see that the error has happened, 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 the system code debugger.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
6549PRO_026.HTML