[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

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:

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:

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:

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 
      


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? 
      


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

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.


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_022.HTML