OpenVMS Alpha System Analysis Tools Manual

Document revision date: 19 July 1999

OpenVMS Alpha System Analysis Tools Manual

Contents

Index

6.4 Debugging an Extension

In addition to the "after-the-fact" information provided by the condition handler, it is possible to 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, SDA extensions can be debugged, 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, etc., in the extension and then type GO
Invoke the extension, providing the necessary arguments

An example of the previous procedures 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>

6.5 Callable Routines Overview

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, etc. (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:

SDA$ADD_SYMBOL SDA$GETMEM

SDA$ALLOCATE SDA$INSTRUCTION_DECODE

SDA$DBG_IMAGE_INFO SDA$NEW_PAGE

SDA$DEALLOCATE SDA$PARSE_COMMAND

SDA$DISPLAY_HELP SDA$PRINT

SDA$ENSURE SDA$READ_SYMFILE

SDA$FORMAT SDA$REQMEM

SDA$FORMAT_HEADING SDA$SET_ADDRESS

SDA$GET_ADDRESS SDA$SET_HEADING_ROUTINE

SDA$GET_BLOCK_NAME SDA$SET_LINE_COUNT

SDA$GET_BUGCHECK_MSG SDA$SKIP_LINES

SDA$GET_CURRENT_PCB SDA$SYMBOL_VALUE

SDA$GET_HEADER SDA$SYMBOLIZE

SDA$GET_HW_NAME SDA$TRYMEM

SDA$GET_IMAGE_OFFSET SDA$TYPE

SDA$GET_INPUT SDA$VALIDATE_QUEUE

SDA$GET_LINE_COUNT

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. It should therefore be used directly when inaccessibility of the location being read is an expected situation, which the caller of SDA$TRYMEM will handle 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. It should, therefore, be used when inaccessibility of the location being read is unexpected, but 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. It should, therefore, be used when inaccessibility of the location being read is unexpected, and will prevent the command currently being executed from continuing. The caller of SDA$REQMEM will not resume if an error occurs.
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, etc., are being displayed directly, as 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.
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 */

specifying the address of interest in the dump, and

void *dest /* 32-bit pointer */

specifying the address in local storage to which the dump contents are to be copied.

6.6 Callable Routines Specifics

The following section describes the SDA extension callable routines.

SDA$ADD_SYMBOL

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.

SDA$ALLOCATE

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 Command

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.

SDA$DBG_IMAGE_INFO

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

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

SDA$DEALLOCATE

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 Command

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.

SDA$DISPLAY_HELP

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 Search memory for a given value You can obtain help on any of the following topics by typing HELP <name>: ATTACH Execute_Command Operation SET CPU_Context EXIT Process_Context SHOW COPY Expressions READ SPAWN DEFINE FORMAT REPEAT Symbols EVALUATE HELP SEARCH VALIDATE EXAMINE Initialization Topic?

 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 
                 Search memory for a given value 
 
    You can obtain help on any of the following topics by typing HELP <name>: 
 
        ATTACH        Execute_Command    Operation          SET 
        CPU_Context   EXIT               Process_Context    SHOW 
        COPY          Expressions        READ               SPAWN 
        DEFINE        FORMAT             REPEAT             Symbols 
        EVALUATE      HELP               SEARCH             VALIDATE 
        EXAMINE       Initialization 
 
 
    Topic?

SDA$ENSURE

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 is not.

SDA$FORMAT

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 flags:

Flag Meaning

None Use structure type from the xxx$B_TYPE field of the structure. This is the default.

SDA_OPT$M_FORMAT_TYPE Use 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).

Flag	Meaning
None	Use structure type from the xxx$B_TYPE field of the structure. This is the default.
SDA_OPT$M_FORMAT_TYPE	Use 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.

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 byte of the structure. The second call formats the structure whose system address is held in the variable LOCAL_PHD, using PHD symbols.

Contents

Index

privacy and legal statement

6549PRO_022.HTML

SDA$ADD_SYMBOL	SDA$GETMEM
SDA$ALLOCATE	SDA$INSTRUCTION_DECODE
SDA$DBG_IMAGE_INFO	SDA$NEW_PAGE
SDA$DEALLOCATE	SDA$PARSE_COMMAND
SDA$DISPLAY_HELP	SDA$PRINT
SDA$ENSURE	SDA$READ_SYMFILE
SDA$FORMAT	SDA$REQMEM
SDA$FORMAT_HEADING	SDA$SET_ADDRESS
SDA$GET_ADDRESS	SDA$SET_HEADING_ROUTINE
SDA$GET_BLOCK_NAME	SDA$SET_LINE_COUNT
SDA$GET_BUGCHECK_MSG	SDA$SKIP_LINES
SDA$GET_CURRENT_PCB	SDA$SYMBOL_VALUE
SDA$GET_HEADER	SDA$SYMBOLIZE
SDA$GET_HW_NAME	SDA$TRYMEM
SDA$GET_IMAGE_OFFSET	SDA$TYPE
SDA$GET_INPUT	SDA$VALIDATE_QUEUE
SDA$GET_LINE_COUNT

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

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

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

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

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