k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


BThe symbolization routine is invoked with the following arguments:



@This routine is invoked for instructions with memory-operand or Hbranch-operand format only. Instructions with memory-operand format use 1a 16-bit signed displacement and are of the form:

  ins Ra,disp(Rb) 


<Instructions with branch-operand format use a 21-bit signed !displacement and are of the form:

  ins Ra,disp 


BThe branch-operand format is a special form of the memory-operand ;format where the program counter (PC) is used instead of a general-purpose ('Rb') register.





Note

HThe symbolization routine is not invoked for instructions with Hspecial memory-operand 'function' format (e.g. MB, FETCH, FETCH_M, EXCB %or TRAPB).



<The purpose of this routine is to replace the 16- or 21-bit Ddisplacement value (disp in the instructions above) with a ?meaningful symbol name. The routine is called for both formats F(memory-operand and branch-operand); to distinguish between them, SDA Hpasses the reserved register value 32 in case of branch-operand format, Fwhereas the register number from the instruction (in range 0...31) is !passed for memory-operand format.

HThe symbolization routine must append its output to the string Dwhose descriptor address is given in the third argument. The fourth Bargument contains the current string length before the routine is Ginvoked; the routine must update it with the resultant string 'length when the symbolization was done.

HIn case of successful symbolization, the routine must return a non-zero Evalue. Otherwise, SDA$EXTEND_LIB$INS_DECODE assumes that nothing was Eappended to the output string and displays the offset as hexadecimal value. 


.

Condition values returned

                    
 SS$_NORMAL # Normal successful completion.
 LIB$_NOINSTRAN (2) 6 Could not translate instruction (invalid opcode)
 LIB$_NOSPACE (4) ' Not enough space in output buffer
 LIB$_INVREG (6)  Invalid register
 LIB$_INVCLASS (8) $ Invalid opcode class or format


GNote that these LIB$ message codes are not declared in module A$LIBDEF; if you want to use it, you must declare the appropriate Aliterals yourself, using the integer values given in parentheses.




Example


"int decode_and_print(int address) {  char buffer[60];  ( int status, retlen, argvec[2], locadr;   $DESCRIPTOR(bufdsc,buffer);  E status = SDA$EXTEND_GETMEM(address,&locadr); /* Fetch memory */  * if (status != SS$_NORMAL) return status;  T status = SDA$EXTEND_LIB$INS_DECODE(&locadr,&bufdsc,&retlen,symbolize);  D if (status != SS$_NORMAL) return status;     /* Return on error */  N argvec[0] = address; argvec[1] = &bufdsc;    /* Setup argument vector */  ? SDA$EXTEND_PRINT("!XL: !AS",argvec);         /* Print line */   return SS$_NORMAL; }    .   .   .Lint symbolize(int offset, int reg, struct dsc$descriptor *out, int *outlen) {  symbuf[40], workbuf[8];   $DESCRIPTOR(symdsc,symbuf);  C SDA$EXTEND_SYMBOLIZE(offset,&symdsc);  /* Try to symbolize */  I if (!symdsc.dsc$w_length) return 0;    /* No success, let SDA decode */  A symbuf[symdsc.dsc$w_length] = 0;       /* Build ASCIZ string */  I if (reg != 32)                         /* Memory-format instruction? */  { I  sprintf(wkrbuf,"(R%d)",reg);          /* Yes, include register (Rb) */  D  strcat(symbuf,wrkbuf);                /* Append to symbol name */  } H symdsc.dsc$w_length = strlen(symbuf);  /* Set our descriptor length */  M str$append(out,&symdsc);               /* Append to given descriptor */  M *outlen = out->dsc$w_length;           /* Set resultant output length */  I return 1;                              /* OK, symbolization was done */ }  


GGiven an address as input, the routine decode_and_print tries 2to fetch the instruction at this address, invokes CSDA$EXTEND_LIB$INS_DECODE to decode it and finally displays a line >containing the given address and the decoded instruction with |SDA$EXTEND_PRINT. Remember that you should copy the memory containing the ?instruction yourself before invoking SDA$EXTEND_LIB$INS_DECODE.

BFor instructions with memory-operand and branch-operand format, a symbolization routine is provided. This routine uses SDA$EXTEND_SYMBOLIZE to Fconvert the displacement into a symbol name, supplies a register name F(for memory-operand instructions) and appends this information to the initial string.

CIf the symbolization fails for some reason, the routine returns 0, ;telling SDA to show the displacement in hexadecimal format.


5

SDA$EXTEND_NEW_PAGE



Inserts a new page.



Format



SDA$EXTEND_NEW_PAGE




RETURNS



0This callback does not return a condition value.




ARGUMENTS

None.



DESCRIPTION

@This callback inserts a new page into the current output stream.

FIn screen mode, the screen is erased, the cursor is set to the 'home' ‚position, and the subheader (if one was defined with SDA$EXTEND_SET_HEADING) is Ddisplayed. On Alpha only, if a heading routine was established with hSDA$EXTEND_SET_HEADING_ROUTINE, it is invoked as well.

AIn file mode (output was redirected to a file), a FF (form-feed) Hcharacter, followed by a header containing SDA's version, a time stamp, Dthe current (already incremented) page number and the subheader (if Eany) are written to the file. The heading routine is invoked as well.

lSee Section 3.2 for more information about SDA output modes.


/

Condition values returned

2



Example


SDA$EXTEND_NEW_PAGE();  


9A new page is displayed or inserted into the output file.


>

SDA$EXTEND_ON_CURRENT_SYSTEM



?Checks whether the current system or a system dump is analyzed.



Format

&

SDA$EXTEND_ON_CURRENT_SYSTEM




RETURNS

                
 VMS usage:  boolean value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


H1 if the analysis source is the current (running) system; 0 in the case of a system dump.




ARGUMENTS

None.



DESCRIPTION

DThis callback returns 1 if the current (running) system is analyzed E(ANALYZE/SYSTEM) or 0, if a system dump is analyzed C(ANALYZE/CRASH _DUMP). If your extension provides Ecommands or functions available for one source of analysis only, you ?can use this callback to find out in which environment you are.

EThis callback is available on Alpha only. A MACRO-32 replacement for LVAX is given in Section 3.1.




Example


$if (SDA$EXTEND_ON_CURRENT_SYSTEM()) {   lib$signal(SDA$_CMDNOTVLD); }  


CIn this example, a check is made whether the running system is the Bsource of analysis. If it is, an error ("command not valid on the Erunning system") is signaled. This causes SDA's condition handler to Gdisplay the above error message and to pass control back either to SDA lor to the caller of this routine (see SDA$EXTEND_HANDLER).


9

SDA$EXTEND_PARSECOMMAND



Parse and execute a SDA command.



Format

!

SDA$EXTEND_PARSE tpablk




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


GA return value, either from SDA's parser or from the executed command. $All conditions are signaled as well.




ARGUMENTS



tpablk


                
 VMS usage: address
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

GA longword holding the address of a TPA (table-driven parser) argument Fblock. This block consists of 9 longwords where the first 4 longwords Cmust be initialized; the remaining longwords should be set to zero.
7                -------------------------------------- 7TPA$L_COUNT     I Remaining # of longwords (8)       I 7                -------------------------------------- 7TPA$L_OPTIONS   I Parsing options (see below)        I 7                -------------------------------------- 7TPA$L_STRINGCNT I Length of supplied command string  I 7                -------------------------------------- 7TPA$L_STRINGPTR I Address of supplied command string I 7                -------------------------------------- 


CThe offsets and parsing options are defined in module $TPADEF. The following parsing options exist:  "                 
Name Value Meaning
 TPA$M_BLANKS  01 ( Process blanks and tabs explicitly
 TPA$M_ABBREV  02 Allow command abbreviation
 TPA$M_ABBRFM  04 , Allow first match command abbreviation


EA detailed description of these options and the table-driven command Fparser can be found in the RTL Library (LIB$) manual, in the 7description of the LIB$TPARSE/LIB$TABLE_PARSE routines.




DESCRIPTION

HNot all SDA commands provide a callable interface. Using this callback, *you can invoke every SDA command directly.

EThe callback provides a way to change SDA's current process sand/or current CPU context (see Section 3.3). By creating <the appropriate SET PROCESS or SET HCPU command strings and invoking this callback, you can easily ?access the per-process address space of any process or examine CPU-specific data of any CPU.

CAnother use of this callback (compute SDA expressions) is shown in <Section 3.4.


.

Condition values returned

           
 SDA$_NORMAL D Normal successful completion. Command was parsed and executed  successfully.
 SDA$_SYNTAX G Error parsing the supplied command string. You have specified an 0 unknown command or invalid command syntax.
% of the supplied command fails.



Example


struct _tpadef tpa; char cmdbuf[40]; int prc_index;    .   .   .-sprintf(cmdbuf,"SET PROC/IND=%X",prc_index);   memset(&tpa,0,sizeof(tpa));   tpa.tpa$l_count = TPA$K_COUNT0; "tpa.tpa$l_options = TPA$M_ABBREV; &tpa.tpa$l_stringcnt = strlen(cmdbuf); $tpa.tpa$l_stringptr = (int) cmdbuf;  :if (!(SDA$EXTEND_PARSECOMMAND(&tpa)) & 1) return;  


AIn this example, SDA's current process is change to the ?process whose index or PID is given in prc_index. The Gappropriate command string is built, the TPA structure initialized and >SDA$EXTEND_PARSECOMMAND is invoked to execute the SET FPROCESScommand. If the commands fails for some reason (e.g., Enon-existent index or PID was given), control is passed back to SDA. GThere is no need to do more; since the condition was signaled as well, ESDA's condition handler has already displayed the approbiate message.

?Note that the TPA$M_ABBREV bit was set in the parsing options; Hotherwise, we had to spell out the command entirely (SET PROCESS/INDEX).


2

SDA$EXTEND_PRINT



Prints a line of data.



Format

+

SDA$EXTEND_PRINT txtstr, [p1..pn]

 (VAX)+

SDA$EXTEND_PRINT txtstr, [prmlst]

 (Alpha)/

SDA$EXTEND_PRINT64 txtstr, [prmlst64]

 (Alpha V7 only)



RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


>Always SDA$_SUCCESS (0x00F48009). All conditions are signaled.




ARGUMENTS



txtstr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: 4 by descriptor - fixed-length string descriptor

GText to be displayed. The txtstr argument is the address of a Hcharacter string descriptor pointing to the text string. The string may 0contain FAO (Formatted ASCII Output) directives.

p1 to pn (VAX only)


                
 VMS usage:  varying_arg
type:  longword (signed)
access:  read only
 mechanism:  by value

EValues to be passed as FAO directive parameters. These arguments are Alongwords containing the parameters needed by the FAO directives Cspecified in the text string. Up to 17 parameters may be supplied; Gtheir number and contents depend on the used FAO directives. If you do @not use FAO directives in the text string, you can omit further arguments.

prmlst (Alpha only)


                
 VMS usage:  vector_longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

FList of FAO directive parameters. The prmlst argument is the >address of a longword vector wherein each longword contains a Hparameter. The vector must start on a longword boundary; the number and Gcontents of longwords depend on the used FAO directives. If you do not Buse FAO directives in the text string, you can omit this argument.

1This argument is used with SDA$EXTEND_PRINT only.!

prmlst64 (Alpha V7 only)


                
 VMS usage:  vector_quadword_unsigned
type:  quadword (unsigned)
access:  read only
 mechanism:  by reference

HList of FAO directive parameters. The prmlst64 argument is the >address of a quadword vector wherein each quadword contains a Hparameter. The vector must start on a quadword boundary; the number and Gcontents of quadwords depend on the used FAO directives. If you do not Buse FAO directives in the text string, you can omit this argument.

3This argument is used with SDA$EXTEND_PRINT64 only.




DESCRIPTION

HThis callback formats and displays a line of data on the current output >device; either on the screen or, if output was redirected via <SET OUTPUT, into the specified output file.

FThe callback provides a screen-oriented display. Therefore, it should Hbe used when a particular block of information should be presented on a Hsingle page or should be presented on multiple pages where the user may Dswitch to the next page on demand. Before the first line of data is }displayed, invoke SDA$EXTEND_NEW_PAGE to start the display on the top of a @new page. Subsequent lines are shown by invoking this callback. DWhenever the screen becomes full, output is suspended unit the user Gpresses the [RETURN] key in response to the SDA> prompt. @Most of SDA's SHOW commands behave in this way.

DText formatting occurs via FAO directives. The callback invokes the GSYS$FAO (VAX) or SYS$FAOL (Alpha) system service to format the string. GMost FAO directives require parameters, they are supplied as arguments ;(VAX) or passed in a vector of longwords/quadwords (Alpha).

EOn Alpha V7, this callback exists in a version using the SYS$FAOL_64 @system service as well. This service accepts 64-bit parameters, =allowing you to display 64-bit data with the appropriate FAO Hdirectives. Note that on Alpha V7, both callbacks, SDA$EXTEND_PRINT and !SDA$EXTEND_PRINT64 are available.

FSee the System Service Reference Manual for a description of Dthe SYS$FAO/SYS$FAOL/SYS$FAOL_64 system services, the available FAO (directives, and the required parameters.


/

Condition values returned

1
EReturns always SDA$_SUCCESS (0x00F48009). Conditions returned by RMS G(which is used for the write operations) are signaled and displayed on &the screen by SDA's condition handler.

FError conditions given by SYS$FAO/SYS$FAOL are not returned. FIf SYS$FAO/SYS$FAOL fails for some reason (you have specified invalid FFAO directives or insufficient directive arguments), a null string is displayed.




Example


9$DESCRIPTOR(txt_str,"Total of !UL !AZ sections found.");  char sectyp[] = "group-global";  int seccnt, prmlst[2];  ;SDA$EXTEND_PRINT(&txt_str,seccnt,sectyp);    /* VAX */  9prmlst[0] = seccnt;                          /* Alpha */ 9prmlst[1] = (int) sectyp;                    /* Alpha */  =SDA$EXTEND_PRINT(&txt_str,prmlst);           /* Alpha */  


FThis example shows the use of SDA$EXTEND_PRINT on VAX and Alpha. Some rother examples are given in Section 2.3.1 and in the description of žSDA$EXTEND_GET_BUGCHECK_MSG and SDA$EXTEND_LIB$INS_DECODE.


:

SDA$EXTEND_PRINT_COLUMNS



Displays rows of columns.



Format

F

SDA$EXTEND_PRINT_COLUMNS datbas, datsva, coll1, [...,coll10]




RETURNS



0This callback does not return a condition value.




ARGUMENTS



datbas


                
 VMS usage: address
type:  longword_unsigned
access:  read only
 mechanism:  by reference

GBase address of the data structure against which the offsets specified Fin the column table apply. The datbas argument is a longword holding this address.

datsva


                
 VMS usage: address
type:  longword_unsigned
access:  read only
 mechanism:  by value

BSystem virtual address of the data structure. The datsva Hargument is a longword containing the data structure's virtual address. EThis argument is used only when processing queue headers (see below).

coll<n>


                
 VMS usage: address
type:  longword_unsigned
access:  read only
 mechanism:  by reference

4Address(es) of one or more column list entries. The Hcoll<n> arguments are longwords holding the addresses of Hthe column entries. The format of these entries is described below. You Fmust pass at least one and may pass up to 10 entries. The columns are Hdisplayed from left to right (the coll1 argument describes the Gleftmost column). See section Column entries and line entries /for a detailled description of these arguments.



DESCRIPTION

EThis callback allows you to easily print information in columns. The Hcallback is table-driven; with column entries, you pass information how Gthe columns are formatted, give a description of each column entry and Aeither pass an offset value which is used in cojunction with the Ddatbas argument to obtain a value from a data structure or Epass the address of a user-written formatting routine and a value to Eformat by this routine. Once the column entries are defined, you may ?invoke this callback many times with different datbas Harguments to display multiple instances of the same data structure. For Aexample, you could define column entries containing PCB (process Hcontrol block) information and could invoke this callback with each PCB Eaddress taken from the SCH$GL_PCBVEC array (the vector array holding Call PCB addresses) from a loop. An example of this is shown in the Examples section.

AThe remaining description is divided into the following sections:



?SDA$EXTEND_PRINT_COLUMNS is mainly and best used from MACRO-32 Gprograms. There exist some macros to built the line entries and column Dentries in an easy way. Most language provide their own features to @format data and display columns; it is recommended to use these ?features instead of this callback. Note also that user-written Eformatting routines, if provided, are invoked as subroutines, not as Dprocedures; and since data to these routines is passed in processor @registers, direct access to these registers is required as well.

}The callback uses SDA$EXTEND_PRINT to print the formatted lines on screen. HThis results in the same prompt behaviour and may cause the callback to }pass control back to SDA and not return to your code. See SDA$EXTEND_PRINT for more information.

0Column entries and line entries

HInformation about columns is given in column entries. A column consists Hof one or more lines where each line is represented by its own line @entry. The column entry is an array of line entries; it is Gterminated by a longword of 0. To display multiple columns in a single Fdisplay, all column entries must have the same number of line entries.

FA line entry consists of a string describing its meaning, a formatted =value and a column separator. For example, type SHOW CPROCESS (while in SDA) and look at the line starting with H"PCB address". Here, "PCB address" is the description Fstring, followed by the formatted value (a hexadecimal longword), and Gfollowed by 4 blanks to separate this column from the next column. The Gstring starting with "JIB address" is already part of another line entry in the second column.

0A line entry may be described by this structure:

struct LINE_ENTRY { < char  *string;   /* Address of ASCIC description string */ K int   offset;    /* NEGATIVE offset to the value in the data structure */ A int   fao_cod;   /* FAO directive code to display this value */ 4 char  des_wid;   /* Width of description string */ . char  val_wid;   /* Width of value string */ 2 char  sep_wid;   /* Width of column separator */ / char  0;         /* Alignment byte, unused */ }; 


>'string' is a pointer to the counted-ASCII string holding the Hdescription text. 'offset' is the offset to the desired location in the Bdata structure whose base address is given in the datbas Aargument; it must specified as negative offset. D'fao_cod' is the code of the FAO directive which should be used for >formatting; see section FAO directive codes for more information.

EThe last three bytes determine the width for the description string, Gthe value string and the column separator. In most cases, these values Fare the same for all line entries in a column. The callback uses them Eto specify a width count in the FAO directives (which all start with G"!#"). The width of the entire column is the sum of these three bytes, rounded up to a multiple of 4.

GNote that 'sep_wid' should be set to 0 for the last (rightmost) column.

FThe above example shows the line entry using FAO directives to format Fdata. If you do not want to use FAO directives or want to format data Hin way not supported by FAO directives (e.g., floating point data), you Fmay provide your own formatting routine. This is the layout of a line 4entry to activate a user-written formatting routine:

struct LINE_ENTRY { < char  *string;   /* Address of ASCIC description string */ C void  *rtnadr;   /* Address of user-written formatting routine */ . int   value;     /* Value to be formatted */ 4 char  des_wid;   /* Width of description string */ . char  val_wid;   /* Width of value string */ 2 char  sep_wid;   /* Width of column separator */ / char  0;         /* Alignment byte, unused */ }; 


EThe only difference to the format above are the 'rtnadr' and 'value' Afields: 'rtnadr' holds the address of the formatting routine and E'value' is the value to be formatted. The formatting routine and its >input is described in the Formatting routine section.

BYou may combine both line entry formats in a single column entry. GWhether or not a user-written routine is invoked is determined only by Hthe sign of the 'offset'/'rtnadr' field in the line entry. If a routine Bis specified, this field must be positive (the P0 or P1 routine's Faddress), else it must contain the negative offset into the structure Gwhere the desired value is stored. For example, if you want to display Dthe PHD address taken from a PCB, you would specify -PCB$L_PHD. The Hcallback recognizes the negative value as offset, converts them back to Hpositive and perform its own formatting, according to the FAO directive "code given in the 'fao_cod' field.

GThere is no restriction how many line entries may build a column entry C(i.e., how many lines a column may consist of). You can even build )columns across screen or page boundaries.

$FAO directive codes

@SDA$EXTEND_PRINT_COLUMNS uses the SYSFAO system service and FAO D(formatted ASCII output) directives to format data. Only a 9subset of FAO directives is available with this callback.

HThe FAO directive code is an integer value describing the FAO directive Gwhich should be used to format the data (actually, it's an offset into lan internal table of FAO directives). The Table B-2 shows the %supported directives and their codes:

C   "                                                                                                 
Table B-2 FAO directive codes
Name Value Meaning
 0  AC 0 Counted ASCII string (passed by reference)
 1  AS ) ASCID string (passed by descriptor)
 2  OB  octal byte
 3  XB  hexadecimal byte
 4  ZB ( unsigned decimal byte, zero-filled
 5  UB  unsigned decimal byte
 6  SB  signed decimal byte
 7  OW  octal word
 8  XW  hexadecimal word
 9  ZW ( unsigned decimal word, zero-filled
 10  UW  unsigned decimal word
 11  SW  signed decimal word
 12  OL  octal longword
 13  XL  hexadecimal longword
 14  ZL , unsigned decimal longword, zero-filled
 15  UL  unsigned decimal longword
 16  SL  signed decimal longword
 17  Q2 1 absolute queue header (passed by reference)
 18 Q2S 6 self-relative queue header (passed by reference)
 




9Previous- | Next6 | Contents