HP OpenVMS Systems Documentation

OpenVMS Alpha System Analysis Tools Manual

In addition to the "after-the-fact" information provided by the condition handler, you can debug SDA extensions using the OpenVMS Debugger. A second copy of the SDA image, SDA_DEBUG.EXE, is provided in SYS$SYSTEM. By defining the logical name SDA to reference this image, you can debug SDA extensions as follows:

• Compile your extension /DEBUG/NOOPT and link it /DEBUG.
• Define logical names for SDA and the extension, and invoke SDA.
• Type GO at the initial DBG> prompt.
• Invoke the extension with no argument at the initial SDA> prompt.
• Return control to Debug at the next prompt (either from SDA or the extension).
• Use Debug commands to set breakpoints, and so on, in the extension and then type GO.
• Invoke the extension, providing the necessary arguments.

An example of the preceding steps is as follows:

        $ cc /debug /noopt mbx$sda + alpha$library:sys$lib_c /library
        $ link /debug /share -
                mbx$sda.obj, -
                alpha$library:vms$volatile_private_interfaces /library, -
                sys$input /option
        symbol_vector = (sda$extend=procedure)
        symbol_vector = (sda$extend_version=data)
        $ !
        $ define mbx$sda sys$disk:[]mbx$sda
        $ define sda sda_debug
        $ analyze /system
        ...
        DBG> go
        ...
        SDA> mbx
        MBX commands: 'MBX SUMMARY' and 'MBX <address>'
        SDA>
        ^C <CR>
        DBG> set image mbx$sda
        DBG> set language c
        DBG> set break /exception
        DBG> go
        SDA> mbx summary
        ...
        SDA> mbx <address>
        ...
        %DEBUG-I-DYNMODSET, setting module MBX$SDA
        %SYSTEM-E-INVARG, invalid argument
        ...
        DBG>

The user-written routine may call SDA routines to accomplish any of the following tasks:

• Read the contents of memory locations in the dump.
• Translate symbol names to values and vice-versa, define new symbols, and read symbol table files.
• Map an address to the activated image or executive image that contains that address.
• Output text to the terminal, with page breaks, page headings, and so on (and which is output to a file if the SDA commands SET OUTPUT or SET LOG have been used).
• Allocate and deallocate dynamic memory.
• Validate queues/lists.
• Format data structures.
• Issue any SDA command.

The full list of available routines is as follows:

The details of all these routines follow. But there are some points to be aware of in using them:

• There are three different routines available to read the contents of memory locations in the dump: SDA$TRYMEM, SDA$GETMEM, and SDA$REQMEM. They are used as follows:
  SDA$TRYMEM is called from both SDA$GETMEM and SDA$REQMEM as the lower-level routine that actually does the work. SDA$TRYMEM returns success/failure status in R0, but does not signal any errors. Use it directly when you expect that the location being read may be inaccessible. The caller of SDA$TRYMEM will handle this situation by checking the status returned by SDA$TRYMEM.
  SDA$GETMEM signals a warning when any error status is returned from SDA$TRYMEM. Signaling a warning will print out a warning message, but does not abort the SDA command in progress. You should use this routine when you expect the location to be read to be accessible. This routine does not prevent the command currently being executed from continuing. The caller of SDA$GETMEM must allow for this by checking the status returned by SDA$GETMEM.
  SDA$REQMEM signals an error when any error status is returned from SDA$TRYMEM. Signaling an error will print out an error message, abort the SDA command in progress and return to the "SDA>" prompt. You should use this routine when you expect the location to be read to be accessible. This routine will prevent the command currently being executed from continuing. The caller of SDA$REQMEM will not resume if an error occurs.
• You should use only the routines provided to output text. Do not use printf() or any other standard routine. If you do, the SDA commands SET OUTPUT and SET LOG will not produce the expected results. Do not include control characters in output (except tab); in particular, avoid <CR>, <LF>,<FF>, and the FAO directives that create them. Use the FAO directive !AF when contents of memory returned by SDA$TRYMEM, and so on, are being displayed directly, because embedded control characters will cause undesirable results. For example, displaying process names or resource names that contain particular control characters or escape sequences can lock up the terminal.
• You should use only the routines provided to allocate and deallocate dynamic memory. Do not use malloc() and free(). Where possible, allocate dynamic memory once, the first time the extension is activated, and deallocate it only if it needs to be replaced by a larger allocation. Because SDA commands can be interrupted by invoking another command at the "Press return for more" prompt, it is very easy to cause memory leaks.
• Some routines expect 32-bit pointers, and others expect 64-bit pointers. At first this not may appear to be logical, but in fact it is. All code and data used by SDA and any extensions must be in P0 or P1 space, as SDA does not need to (and does not) use P2 space for local data storage. However, addresses in the system dump (or running system, in the case of ANALYZE/SYSTEM) are 64-bit addresses, and SDA must provide access to all locations in the dump.

So, for example, the first two arguments to the routine SDA$TRYMEM are:

        VOID_PQ start   /* 64-bit pointer */

        void *dest      /* 32-bit pointer */

They specify the address of interest in the dump and the address in local storage to which the dump contents are to be copied.

8.6 Callable Routines Specifics

The following section describes the SDA extension callable routines.

Adds a symbol to SDA's local symbol table.

Format

void sda$add_symbol (char *symbol_name, uint64 symbol_value);

Arguments

symbol_name

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

Address of symbol name string (zero-terminated).

symbol_value

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

The symbol value.

Description

SDA maintains a list of symbols and the corresponding values. SDA$ADD_SYMBOL is used to insert additional symbols into this list, so that they can be used in expressions and during symbolization.

Condition Values Returned

None

Example

sda$add_symbol ("MBX", 0xFFFFFFFF80102030);
      

This call defines the symbol MBX to the hexadecimal value FFFFFFFF80102030.

Allocates dynamic memory.

Format

void sda$allocate (uint32 size, void **ptr_block);

Arguments

size

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

Size of block to allocate (in bytes).

ptr_block

OpenVMS usage	address
type	longword (unsigned)
access	write only
mechanism	by reference

Address of longword to receive address of block.

Description

The requested memory is allocated and the address returned. Note that this is the only supported mechanism for allocation of dynamic memory.

Related Routine

SDA$DEALLOCATE

Condition Values Returned

None

If no memory is available, the error is signaled and the SDA session aborted.

Example

PCB *local_pcb;
...
sda$allocate (PCB$C_LENGTH, (void *)&local_pcb);
      

This call allocates a block of heap storage for a copy of a PCB, and stores its address in the pointer LOCAL_PCB.

Displays a list of activated images together with their virtual address ranges for debugging purposes.

Format

void sda$dbg_image_info ();

Arguments

None.

Description

A list of the images currently activated, with their start and end addresses, is displayed. This is provided as a debugging aid for SDA extensions.

Condition Values Returned

None

Example

sda$dbg_image_info ();
      

SDA outputs the list of images in the following format:

Current VMS Version:   "X6DX-FT1"

     Process Activated Images:

        Start VA  End VA    Image Name
        00010000  000301FF  SDA
        00032000  00177FFF  SDA$SHARE
        7B508000  7B58BFFF  DECC$SHR
        7B2D8000  7B399FFF  DPML$SHR
        7B288000  7B2C9FFF  CMA$TIS_SHR
        7B698000  7B6D9FFF  LBRSHR
        0021A000  0025A3FF  SCRSHR
        00178000  002187FF  SMGSHR
        7B1E8000  7B239FFF  LIBRTL
        7B248000  7B279FFF  LIBOTS
        80C140D0  80C23120  SYS$BASE_IMAGE
        80C036B8  80C05288  SYS$PUBLIC_VECTORS
        002C6000  002D31FF  PRGDEVMSG
        002D4000  002DA9FF  SHRIMGMSG
        002DC000  002DFFFF  DECC$MSG
        00380000  003E03FF  MBX$SDA
      

Deallocates and frees dynamic memory.

Format

void sda$deallocate (void *ptr_block, uint32 size);

Arguments

ptr_block

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

Starting address of block to be freed.

size

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

Size of block to deallocate (in bytes).

Description

The specified memory is deallocated. Note that this is the only supported mechanism for deallocation of dynamic memory.

Related Routine

SDA$ALLOCATE

Condition Values Returned

None

If an error occurs, it is signaled and the SDA session aborted.

Example

PCB *local_pcb;
...
sda$deallocate ((void *)local_pcb, PCB$C_LENGTH;
      

This call deallocates the block of length PCB$C_LENGTH whose address is stored in the pointer LOCAL_PCB.

Displays online help.

Format

void sda$display_help (char *library_desc, char *topic_desc);

Arguments

library

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

Address of library filespec. Specify as zero-terminated ASCII string.

topic

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

Address of topic name. Specify as zero-terminated ASCII string.

Description

Help from the specified library is displayed on the given topic.

Condition Values Returned

None

Example

sda$display_help ("SYS$HELP:SDA", "HELP");
      

This call produces the following output at the terminal:

HELP


     The System Dump Analyzer (SDA) allows you to inspect the contents
     of memory as saved in the dump taken at crash time or as exists
     in a running system. You can use SDA interactively or in batch
     mode. You can send the output from SDA to a listing file. You can
     use SDA to perform the following operations:

                      Assign a value to a symbol
                      Examine memory of any process
                      Format instructions and blocks of data
                      Display device data structures
                      Display memory management data structures
                      Display a summary of all processes on the system
                      Display the SDA symbol table
                      Copy the system dump file
                      Send output to a file or device
                      Read global symbols from any object module
                      Send output to a file or device
                      Read global symbols from any object module
                      Search memory for a given value

     For help on performing these functions, use the HELP command and
     specify a topic.

     Format

       HELP  [topic-name]




  Additional information available:

  Parameter

HELP Subtopic?
      

Ensures sufficient space on the current output page.

Format

void sda$ensure (uint32 lines);

Argument

lines

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

Number of lines to fit on a page.

Description

This routine checks and makes sure that the number of lines specified fit on the current page; otherwise, it issues a page break.

Condition Values Returned

None

Example

sda$ensure (5);
      

This call ensures that there are five lines left on the current page, and it outputs a page break if there are not.

Displays the formatted contents of a data structure.

Format

void sda$format (VOID_PQ struct_addr, __optional_params);

Arguments

struct_addr

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

The address in the system dump of the data structure to be formatted.

options

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

The following provides more information on options:

Option	Meaning
None	Uses structure type from the xxx$B_TYPE and/or xxx$B_SUBTYPE field of the structure. This is the default.
SDA_OPT$M_FORMAT_TYPE	Uses the structure type given in struct_prefix.
SDA_OPT$M_FORMAT_PHYSICAL	Indicates that struct_addr is a physical address instead of a virtual address.

struct_prefix

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

Address of structure name string (zero-terminated).

Description

This routine displays the formatted content of a data structure that begins at the address specified. If no symbol prefix is passed, then SDA tries to find the symbols associated with the block type specified in the block-type byte of the data structure.

Condition Values Returned

None

Example

PCB *local_pcb;
PHD *local_phd;
...
sda$format (local_pcb);
sda$format (local_phd, SDA_OPT$M_FORMAT_TYPE, "PHD");
      

The first call formats the structure whose system address is held in the variable LOCAL_PCB, determining the type from the type and/or subtype byte of the structure. The second call formats the structure whose system address is held in the variable LOCAL_PHD, using PHD symbols.