 |
OpenVMS Alpha System Analysis Tools Manual
8.4 Debugging an Extension
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>
|
8.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, 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:
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_CPU
|
SDA$GET_BLOCK_NAME
|
SDA$SET_HEADING_ROUTINE
|
SDA$GET_BUGCHECK_MSG
|
SDA$SET_LINE_COUNT
|
SDA$GET_CURRENT_CPU
|
SDA$SET_PROCESS
|
SDA$GET_CURRENT_PCB
|
SDA$SKIP_LINES
|
SDA$GET_DEVICE_NAME
|
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. 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.
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
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 Routine
SDA$DEALLOCATE
Condition Values Returned
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
Example
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 Routine
SDA$ALLOCATE
Condition Values Returned
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
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?
|
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
Example
This call ensures that there are five lines left on the current page,
and it outputs a page break if there are 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 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
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.
|