HP OpenVMS System Analysis Tools Manual
Previous Contents Index

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

None  

Example


sda$new_page ();

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

None  

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: 


Block type: VCC_CFCB

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.

Previous Next Contents Index