 |
HP OpenVMS System Analysis Tools Manual
SDA$INSTRUCTION_DECODE
Translates one machine instruction into the assembler string equivalent.
Format
int sda$instruction_decode (void *istream_ptr, char *buffer, uint32
buflen,__optional_params);
Arguments
istream_ptr
| OpenVMS usage |
address |
| type |
longword (unsigned) |
| access |
read/write |
| mechanism |
by reference |
Address of the pointer that points to a copy of the i-stream in a local
buffer.
buffer
| OpenVMS usage |
char_string |
| type |
character string |
| access |
write only |
| mechanism |
by reference |
Address of a string buffer into which to store the output assembler
string.
buflen
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
Maximum size of the string buffer.
template_buffer
| OpenVMS usage |
char_string |
| type |
character string |
| access |
write only |
| mechanism |
by reference |
(Integrity servers only.) Address of a string buffer into which to
store the template string.
template_buflen
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
(Integrity servers only.) Maximum size of the template buffer.
Description
Translates a machine instruction into the assembler string equivalent.
Alpha instructions are always 4 bytes long; Integrity server
instructions are always in bundles that are 16 bytes long. The
instruction stream must first be read into local memory and then the
address of a pointer to the local copy of the instruction stream is
passed to the routine. For every successful translated instruction, the
pointer is automatically updated to point to the next instruction on
Alpha or slot on Integrity servers.
The output assembler string and optionally the template string is
zero-terminated and in case of a failure a null string is returned.
The template_buffer and template_buflen arguments only apply to
Integrity servers and are optional.
Condition Values Returned
|
SS$_NORMAL
|
Successful completion.
|
|
SS$_BADPARAM
|
Any of the following failures:
|
|
|
Output buffer too small
Invalid register
Invalid opcode class/format
Could not translate instruction
|
Examples
1. Alpha
int status;
VOID_PQ va = (VOID_PQ)0xFFFFFFFF80102030;
uint32 instruction;
uint32 *istream = &instruction;
char buffer[64];
...
sda$reqmem (va, &instruction, 4);
status = sda$instruction_decode (&istream, buffer, sizeof (buffer));
if ( !$VMS_STATUS_SUCCESS (status) )
sda$print ( "SDA$INSTRUCTION_DECODE failed, status = !XL", status);
else
sda$print ( "VA: !AZ", buffer );)
|
This example on an Alpha system reads the instruction at dump location
VA and decodes it, putting the result into BUFFER, and displays the
instruction. Pointer ISTREAM is incremented (to the next longword).
2. Integrity servers
int status;
VOID_PQ va = (VOID_PQ)0xFFFFFFFF80102030;
uint64 instruction [2];
uint64 *istream = &instruction;
char buffer [64];
char template [16];
sda$reqmem (va, &instruction, 16);
status = sda$instruction_decode ( &istream, buffer, sizeof (buffer),
template, sizeof (template) );
if ( !$VMS_STATUS_SUCCESS (status) )
sda$print ( "SDA$INSTRUCTION_DECODE failed, status = !XL", status);
else
{
sda$print ( " { !AZ", template );
sda$print ( "VA: !AZ", buffer );
while (((int)istream & 7) != 0)// local buffer only has to be quadword aligned
{
status = sda$instruction_decode ( &istream, buffer, sizeof (buffer) );
if ( !$VMS_STATUS_SUCCESS (status) )
{
sda$print ( "SDA$INSTRUCTION_DECODE failed, status = !XL", status);
break;
}
else
sda$print ( " !AZ", buffer );
}
sda$print ( " }" );
}
|
This example for Integrity servers reads the instruction bundle at dump
location VA and decodes it, displaying each of the instructions in the
bundle. Pointer ISTREAM is incremented (to the next octaword bundle).
SDA$NEW_PAGE
Begins a new page of output.
Format
void sda$new_page ();
Arguments
None.
Description
This routine causes a new page to be written and outputs the page
heading (established with SDA$FORMAT_HEADING) and the current
subheading (established with SDA$SET_HEADING_ROUTINE).
Condition Values Returned
Example
This call outputs a page break and displays the current page heading
and subheading (if any).
SDA$PARSE_COMMAND
Parses and executes an SDA command line.
Format
void sda$parse_command (char *cmd_line, __optional_params);
Arguments
cmd_line
| OpenVMS usage |
char_string |
| type |
character string |
| access |
read only |
| mechanism |
by reference |
Address of a valid SDA command line (zero-terminated).
options
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
The options argument has the following values:
| Value |
Meaning |
|
SDA_OPT$K_PARSE_DONT_SAVE
|
Indicates "do not save this command." This is the default.
|
|
SDA_OPT$K_PARSE_SAVE
|
Indicates "save this command." That is, it can be recalled with KP0 or
REPEAT.
|
Description
Not every SDA command has a callable extension interface. For example,
to redirect SDA's output, you would pass the command string "SET OUTPUT
MBX.LIS" to this parse command routine. Abbreviations are allowed.
Condition Values Returned
Example
|
sda$parse_command ("SHOW ADDRESS 80102030");
|
This call produces the following output:
|
FFFFFFFF.80102030 is an S0/S1 address
Mapped by Level-3 PTE at: FFFFFFFD.FFE00408
Mapped by Level-2 PTE at: FFFFFFFD.FF7FF800
Mapped by Level-1 PTE at: FFFFFFFD.FF7FDFF8
Mapped by Selfmap PTE at: FFFFFFFD.FF7FDFF0
Also mapped in SPT window at: FFFFFFFF.FFDF0408
|
The "SHOW ADDRESS" command is not recorded as the most recent command
for use with the KP0 key or the REPEAT command.
SDA$PRINT
Formats and prints a single line.
Format
int sda$print (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 FAO 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. This is normally output to the
terminal, unless you used the SDA commands SET OUTPUT or SET LOG to
redirect or copy the output to a file.
Condition Values Returned
|
SDA$_SUCCESS
|
Indicates a successful completion.
|
|
SDA$_CNFLTARGS
|
Indicates more than twenty FAO parameters given.
|
|
Other
|
Returns from the $PUT issued by SDA$PRINT (the error is also signaled).
If the $FAOL_64 call issued by SDA$PRINT fails, the control string is
output.
|
Example
|
char buffer[32];
...
sda$get_block_name (0x6F, 0x20,
buffer,
sizeof (buffer));
sda$print ("Block type: !AZ", buffer);
|
This example outputs the following line:
SDA$READ_SYMFILE
Reads symbols from a given file.
Format
int sda$read_symfile (char *filespec, uint32 options,
__optional_params);
Arguments
filespec
| OpenVMS usage |
char_string |
| type |
character string |
| access |
read only |
| mechanism |
by reference |
Address of file or directory specification from which to read the
symbols (zero-terminated ASCII string).
options
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
Indicates type of symbol file and flags, as shown in the following:
| Flags |
Effect |
|
SDA_OPT$M_READ_FORCE
|
read/force <file>
|
|
SDA_OPT$M_READ_IMAGE
|
read/image <file>
|
|
SDA_OPT$M_READ_SYMVA
|
read/symva <file>
|
|
SDA_OPT$M_READ_RELO
|
read/relo <file>
|
|
SDA_OPT$M_READ_EXEC
|
read/exec [<dir>]
|
|
SDA_OPT$M_READ_NOLOG
|
/nolog, suppress count of symbols read
|
|
SDA_OPT$M_READ_FILESPEC
|
<file> or <dir> given
|
|
SDA_OPT$M_READ_NOSIGNAL
|
return status, without signaling errors
|
relocate_base
| OpenVMS usage |
address |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
Base address for symbols (nonsliced symbols).
symvect_va
| OpenVMS usage |
address |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
The symbol vector address (symbols are offsets into the symbol vector).
symvect_size
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
Size of symbol vector.
loaded_img_info
| OpenVMS usage |
address |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
The address of $LDRIMG data structure with execlet information.
Description
This command reads symbols from a given file to add symbol definitions
to the working symbol table by reading GST entries. The file is usually
a symbol file (.STB) or an image (.EXE). If SDA_OPT$M_READ_EXEC is
specified in the options, then the filespec is treated as a directory
specification, where symbol files and/or image files for all execlets
may be found (as with READ/EXECUTIVE). If no directory specification is
given, the logical name SDA$READ_DIR is used.
Note that when SDA reads symbol files and finds routine names, the
symbol name that matches the routine name is set to the address of the
procedure or function descriptor. A second symbol name, the routine
name with "_C" appended, is set to the start of the routine's prologue.
Condition Values Returned
|
SDA$_SUCCESS
|
Successful completion.
|
|
SDA$_CNFLTARGS
|
No filename given and SDA_OPT$M_READ_EXEC not set.
|
Other errors are signaled and/or returned, exactly as though the
equivalent SDA READ command had been used. Use HELP/MESSAGE for
explanations.
Example
|
sda$read_symfile ("SDA$READ_DIR:SYSDEF", SDA_OPT$M_READ_NOLOG);
|
The symbols in SYSDEF.STB are added to SDA's internal symbol table, and
the number of symbols found is not output to the terminal.
SDA$REQMEM
Reads dump or system memory and signals an error if inaccessible.
Format
int sda$reqmem (VOID_PQ start, void *dest, int length,
__optional_params);
Arguments
start
| OpenVMS usage |
address |
| type |
quadword (unsigned) |
| access |
read only |
| mechanism |
by value |
Starting virtual address in dump or system.
dest
| OpenVMS usage |
address |
| type |
varies |
| access |
write only |
| mechanism |
by reference |
Return buffer address.
length
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
Length of transfer.
physical
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by value |
0: <start> is a virtual address. This is the default.
1: <start> is a physical address.
Description
This routine transfers an area from the memory in the dump file or the
running system to the caller's return buffer. It performs the necessary
address translation to locate the data in the dump file. SDA$REQMEM
signals an error and aborts the current command if the data is
inaccessible.
Related Routines
SDA$GETMEM and SDA$TRYMEM
Condition Values Returned
|
SDA$_SUCCESS
|
Successful completion.
|
Any failure is signaled as an error and the current command aborts.
Example
|
VOID_PQ address;
uint32 instruction;
...
sda$symbol_value ("EXE_STD$ALLOCATE_C", (uint64 *)&address);
sda$reqmem (address, &instruction, 4);
|
This example reads the first instruction of the routine
EXE_STD$ALLOCATE into the location INSTRUCTION.
|
