k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


HDepending on the specified arguments and bits, the following operations are performed by this callback:



HThe following table gives an overview about all arguments and lists the Hcorresponding SDA commands. Note that the OPT$M_ prefix is omitted from the bit names in the table. # & % %                                                   
Bit Name SDA command image type reloc symvec_xxx
 EXEC_READ  READ/EXECUTIVE ¹  -  -
 IMAGE_READ²  READ/IMAGE  system,shar.  -  -
 FORCE_READ²  READ/FORCE [/RELOC]  system,shar. opt  -
²  READ/SYMVA [/RELOC]  shareable opt req
²  READ/RELOC [/SYMVA]] system req opt
 -  READ [/RELOC]  non-activated opt  -
 -  READ [/RELOC]  symbol table opt  -



F¹Optional name of the directory wherein all system images reside.
²Alpha only



ENote that the OPT$M_EXEC_READ, OPT$M_IMAGE_READ and OPT$M_FORCE_READ <bits are mutually exclusive, only one of them can be set in options. 


!

READING EXECUTIVE IMAGES



HBy setting the leavevmode hbox OPT $M _EXEC _READ bit Hin the options argument, you tell SDA to read all symbols from Gall currently loaded executive (system) images. A list of these images Hcan be displayed with SDA's SHOW EXECUTIVE command. If Fyou do not supply a directory name with the filnam argument, ?the target directory defaults to SYS$LOADABLE_IMAGES (VAX) and HSDA$READ_DIR (Alpha). Note that SDA$READ_DIR is a search list currently .pointing to SYS$LOADABLE_IMAGES and SYS$SHARE.

GUse this bit if you want to set global entry points into system images Fto their absolute addresses within these images, instead to the entry Gpoints in the S0 pointer page. Note that on VAX, this bit is available in VMS V7 only.

7When reading the executive images, the reloc, Gsymvec_va, symvec_siz, and ldrimg arguments =are meaningless. In addition, you must not set other bits in Boptions, except OPT$M_NOLOG_READ and OPT$M_NOSIGNAL_READ (Alpha V7 only).


<

PROCESSING LOADED AND ACTIVATED IMAGES (ALPHA ONLY)



GOn Alpha, shareable images and some system images (or their associated Esymbol tables) contain universal symbol definitions in the following data structures:



EWhen reading GST and symbol vector from an image file, all addresses Htherein are relative to the image's base address. In contrast, Fwhen the image is activated (or, in the case of system images, loaded Cat system initialization), the symbol vector contains absolute Baddresses. Therefore, when examining the symbol vector of an Gactivated shareable image, you must decide whether you want to process Ethe memory-version of the symbol vector, or you want to read it from the image file.

HBy specifying the OPT$M_IMAGE_READ bit in options and the name @of an activated shareable image, SDA locates the data structure Arepresenting the activated image and, using the in-memory symbol Avector, creates all symbols with their actual absolute addresses.

EIn order to process an image in this way, it must be either a system Dimage, loaded as part of the VMS executive (you can check this with GSHOW EXECUTVE, or it must be activated by the current Gprocess (must appear in the current process' activated image list; you Acan display this list with SHOW PROCESS/IMAGES).

GIf you do not set the OPT$M_IMAGE_READ bit, but specify the name of an Bactivated or loaded image, you must supply additional information:



HSpecifying symnam_va and symnam_siz explicitly allows Cyou to process symbols from an activated shareable image using the Fsymbol vector (and relocation information) from a different shareable Fimage. This is, however, useful only if two different versions of the %same activated shareable image exist.

:Note that you cannot process sliced images in this way. A :sliced image consists of different parts (called Bexeclets) and is loaded in a non-contiguous manner. Each Fexeclet is loaded at a different virtual address and may have its own Hsymbol vector. For sliced images, you must always set OPT$M_IMAGE_READ, >telling SDA to obtain execlet-related information from memory.

HWhenever you specify the name of an activated image, SDA expects either Gthe OPT$M_IMAGE_READ to be set or additional information supplied with ?the reloc, symnam_va and symnam_siz Darguments. However, if you want to read symbol information from the Aimage file, set the OPT$M_FORCE_READ bit in the options Cargument. This causes SDA to bypass all information in memory, the Gimage is processed like any other, non-activated image. Note, however, Bthat in this case, all symbols are set to their relative Faddresses within the image; they do not point to the actual locations in memory.

;When setting the OPT$M_IMAGE_READ bit, the reloc, Fsymvec_va and symvec_siz arguments are meaningless. EIn addition, you must not set other bits in options, except E(on Alpha V7 only) OPT$M_NOLOG_READ and/or OPT$M_NOSIGNAL_READ. Note Hthat setting OPT$M_IMAGE_READ and specifying the name of an image which @is not either loaded or activated, results in an error.

EWhen setting the OPT$M_FORCE_READ bit, you may specify an additional 8relocation offset with the reloc argument; the Esymvec_va and symvec_siz arguments are meaningless Chere since this information is taken from the image file or symbol table file.

HIf you do not specify OPT$M_IMAGE_READ or OPT$M_FORCE_READ, but specify Ethe name of either a loaded or activated image, an error is returned.


:

PROCESSING NON-ACTIVATED IMAGES AND SYMBOL TABLES



GIf you specify the name of a symbol table file or of an image which is Cnot activated by the current process or found in the loaded system ?image list, symbols are defined using the information from the Cspecified file. On VAX, this is the only way to read symbol tables.

GDepending on the image type, SDA reads the symbols either from the GST E(global symbol table) or from the symbol vector, or from both (Alpha Gonly). Remember, if you have not supplied a file type, SDA looks first Dfor a symbol table (.STB) file, before it looks for an image (.EXE) file.

FYou can use the reloc argument to specify a relocation value G(an offset which is added to all relative symbols). This may be useful Hif you want to address symbols from a given offset (e.g., the image was Dmapped at a non-zero base address). Note that a relocation does not #affect absolute symbols (literals).

<When reading images in this way, the symvec_va and Esymvec_siz arguments are meaningless. In addition, you must ;not set bits in options except (on Alpha V7 only) ,OPT$M_NOLOG_READ and/or OPT$M_NOSIGNAL_READ.


(

FURTHER OPTIONS (ALPHA V7 ONLY)



?On Alpha V7 only, you may set the following additional bits in options:


5

THE LDRIMG ARGUMENT (ALPHA V7 ONLY)



BLoaded system images are represented in memory by an LDRIMG image Fblock. This data structure contains the image name, its virtual start Fand end address, the date and time when the image was linked, as well Athe address of its symbol vector (if any). For sliced images, it ?contains information about the image's execlets as well. SDA's DSHOW EXECUTIVE command interprets and displays the contents of LDRIMG blocks.

HWhen you set the OPT$M_IMAGE_READ bit, SDA uses the image name given in Hthe filnam argument to locate the appropriate LDRIMG block and 5takes the information found therein to build symbols.

FWith the ldrimg argument, you can specify the address of the Bimage's LDRIMG block directly. All information is taken from this Fblock; the reloc, symvec_va and symvec_siz Darguments are not used. In addition, you must not set other bits in Foptions, except OPT$M_NOLOG_READ and/or OPT$M_NOSIGNAL_READ. FNevertheless, you must specify the image name in the filnam argument.





Note

ESDA compares the link time of the image specified in filnam >with the link time stored in the LDRIMG block and signals the :SDA$_LINKTIMEMISM warning condition if they do not match. 


.

Condition values returned

jSee Table B-3 for the numeric values of all error codes.                                       
 SS$_NORMAL 4 The READ operation was performed successfully.
 SDA$_IMAGENF (Alpha only) @ "Image is not in activated image lists". You have set the L OPT$M_IMAGE_READ bit, but the image wasn't found in the loaded system I image or activated shareable image list. To read symbols from this , image, clear the OPT$M_IMAGE_READ bit.
' SDA$_LINKTIMEMISM (Alpha V7 only) L "Image link times do not match". You have supplied an IMGLDR block in theL imgldr argument whose link time does not match the link time  of the image specified inL filnam. This may or may not be an error condition, depending  on what you want to do.
 SDA$_NOFILENAME J "Image in EXEC list has no valid file name". The LDRIMG contains no 1 (valid) image file name; see SDA$_NOLDRIMG.
 SDA$_NOLDRIMG M "No loaded image list found". There were no loaded system images. This I can never happen on the running system; however, it may occur when * analyzing an incomplete system dump.
 SDA$_NOREADLDRIMG J "Unable to access loaded image block". A LDRIMG image block was not ) accessible. See previous condition.
 SDA$_OPENIN M "Error opening specified image or symbol table file". An error occured 4 while trying to open the file specified in theL filnam argument. In most cases, you have supplied an invalid 0 filename or specified a non-existent file.
$ SDA$_RD_IMAGE_ERR (Alpha only) L "Image is sliced or has a symbol vector". You have specified the name L of an activated shareable image; either an image with a symbol vector C or a sliced image. Sliced images cannot be processed without N OPT$M_IMAGE_READ; if the image has a symbol vector, you must set either M OPT$M_IMAGE_READ or OPT$M_FORCE_READ, or you must supply symbol vector  information with symvec_va and symvec_siz.
% SDA$_RD_SYSIMG_ERR (Alpha only) L "Error reading loaded system image." You have specified the name of a G loaded system image, but have not set either OPT$M_IMAGE_READ or K OPT$M_FORCE_READ; or you have specified not enough information in the reloc, symvec_va and$ symvec_siz arguments.
 $CONNECT and SYS$GET.



Example


%/* Read symbols from symbol table */  8$DESCRIPTOR(sysdef,"SYS$SYSTEM:SYSDEF");      /* VAX */  <SDA$EXTEND_READ_SYMFILE(&sysdef,0);           /* VAX */  :$DESCRIPTOR(sysdef,"SYSDEF");                 /* Alpha */  >SDA$EXTEND_READ_SYMFILE(&sysdef,0,0,0,0,1);   /* Alpha */  1/* Read all executive images (READ/EXECUTIVE) */  #define OPT$M_EXEC_READ 0x10  ESDA$EXTEND_READ_SYMFILE(0,0,OPT$M_EXEC_READ);       /* VAX V7 only*/  @SDA$EXTEND_READ_SYMFILE(0,0,0,0,OPT$M_EXEC_READ,1); /* Alpha */  


FThe above example shows some ways to use SDA$EXTEND_READ_SYMFILE. The =first example reads the contents of the system symbol table, CSYSDEF.STB. This table contains definition for various system data |structures; if you want to format these structures with SDA$EXTEND_FORMAT, Gyou must first read in this table. Note that on VAX, you must supply a Gdirectory as well; on Alpha, the logical SDA$READ_DIR is translated to locate symbol tables.

EThe second example is similar to READ/EXECUTIVE, it >reads the symbol tables of all currently loaded system images.

EIn both examples, on Alpha, the suppr argument is set to 1, Hcausing SDA to suppress the display of its READSYM message (on VAX, you cannot suppress this message).


3

SDA$EXTEND_REQMEM



Copies data from memory.



Format

6

SDA$EXTEND_REQMEM inadr, [retadr, len] (VAX)

:

SDA$EXTEND_REQMEM inadr, [retadr, len], [phyflg]

(Alpha V6)>

SDA$EXTEND_REQMEM64 inadr64, [retadr, len], [phyflg]

(Alpha V7)



RETURNS

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


.All conditions are signaled as errors as well.




ARGUMENTS

!

inadr (VAX and Alpha V6)


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

FLongword holding the 32-bit virtual base address of the data you want Hto copy from memory. This argument is used with SDA$EXTEND_REQMEM only; 2on Alpha, inadr must be longword-aligned.

inadr64 (Alpha V7)


                
 VMS usage: address
type:  quadword (unsigned)
access:  read only
 mechanism:  by value

FQuadword holding the 64-bit virtual base address of the data you want Dto copy from memory. This argument is used with SDA$EXTEND_REQMEM64 5only; the specified address must be longword-aligned.

retadr


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

GReturn address wherein the data should be written. The retadr Fargument is a longword holding the base address of a buffer receiving Bthe copied data. This must be a 32-bit address in either P0 or P1 Fspace. The argument is optional; if you do not supply it, an internal +buffer is used to retrieve the copied data.

DIf you specify this argument, you must also supply the len argument.

EWhen programming in MACRO-32 or BLISS, you can obtain the first four :bytes of the copied data in processor register R1 as well.

len


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

DNumber of bytes to copy. This argument must be specified unless the Bretadr argument was omitted as well. The lowest value of Blen is 4, in other words, the smallest unit to copy is a longword (on VAX and Alpha).

phyflg (Alpha only)


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

APhysical address indicator. If you set phyflg to 1, the Gaddress given in inadr/inadr64 is treated as physical address.



DESCRIPTION

AThis callback is a jacket to SDA's general-purpose memory access wroutine SDA$EXTEND_TRYMEM. The only difference between them is their }behaviour in case of error: while SDA$EXTEND_TRYMEM returns the error code Honly, this callback also signals it as error condition. Unless you have Gdeclared a condition handler, this causes SDA to interrupt the code of Gyour extension, displaying the appropriate error message and return to Hits main loop, printing its SDA> prompt. Use this callback when data Ainaccessibility at the given address will prevent your code from ;continuing. You will not receive control in case of errors.

GOn Alpha V7, the input address (inadr64 argument) is a 64-bit Eaddress, allowing you to access every virtual address in P0, P1, P2, AS0/S1 and S2 space. To indicate this, the routine was renamed to 9SDA$EXTEND_REQMEM64; the 32-bit version 8SDA$EXTEND_REQMEM is not available on Alpha V7.

qFor more information, see the description of SDA$EXTEND_TRYMEM.


.

Condition values returned

                                                
 SDA$_SUCCESS Memory copied successfully
 SDA$_INVLDADR  Invalid virtual address
 SDA$_INVRANGE % Invalid address range specified
 SDA$_MEMNOTACC F Memory locations not accessible in override mode (Alpha V7 only)
 SDA$_MEMNOTSVD - Specified memory not saved in dump file
 SDA$_NOREAD ' Could not access specified memory
 SDA$_NOTINPHYS ) Virtual data not in physical memory
 SDA$_NOTVALID ( Information not in physical memory
 SDA$_OUTSIDPT = Virtual address range exceeds process page table bounds
 SDA$_PFNNOTMPD 2 PFN from PTE not mapped by memory descriptor
 SDA$_REGNOTVALID # Register reference is invalid
 SDA$_UNALIGNED . Unaligned address specified (Alpha only)


DFor a detailed description of these condition codes, please see the sCondition values returned section of SDA$EXTEND_TRYMEM. tTable B-3 contains the numeric values for all error codes; if you Cwant to use the names listed here, you must define the appropriate literals yourself.




Example


int pcbadr, retval;  )SDA$EXTEND_REQMEM(pcbadr,&retval,4);  /* is equivalent to */  int status;  Wif (!((status = SDA$EXTEND_TRYMEM(pcbadr,&retval,4)) & 1)) lib$signal(status);  


sThis example shows the relationship between SDA$EXTEND_GETMEM and ASDA$EXTEND_REQMEM. If you want to terminate immediately when the Erequested memory is not available, you should use SDA$EXTEND_REQMEM. zOtherwise, use SDA$EXTEND_GETMEM if you want to display an error message ~and want to continue, or use SDA$EXTEND_TRYMEM if you want to continue, but !do not want to display a message.


8

SDA$EXTEND_SET_ADDRESS



"Establishes a new current address.



Format

'

SDA$EXTEND_SET_ADDRESS curadr

+

SDA$EXTEND_SET_ADDRESS64 curadr64

 (Alpha V7 only)



RETURNS



0This callback does not return a condition value.




ARGUMENTS



curadr


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

DA longword holding the new 32-bit current address. This argument is &used with SDA$EXTEND_SET_ADDRESS only.!

curadr64 (Alpha V7 only)


                
 VMS usage: address
type:  quadword (unsigned)
access:  read only
 mechanism:  by value

DA quadword holding the new 64-bit current address. This argument is (used with SDA$EXTEND_SET_ADDRESS64 only.



DESCRIPTION

GThis callback establishes or changes the current address. The Bcurrent address is also set by the last EXAMINE, GFORMATor VALIDATE command; it may be Bspecified with the dot (.) character in any command accepting SDA Bexpressions. You may change the current address in your code to a Eparticular value, allowing the user to reference this value later in other commands.

BThere is also a way to compute standard SDA expressions with this ¸callback in conjunction with SDA$EXTEND_GET_ADDRESS and SDA$EXTEND_PARSECOMMAND. See <Section 3.4.

AOn Alpha V7, this callback exists in a version supporting 64-bit Daddresses as well. If you want to work in a 64-bit environment, you Ashould use SDA$EXTEND_SET_ADDRESS64. Note that on Alpha V7, both Dcallbacks, SDA$EXTEND_SET_ADDRESS and SDA$EXTEND_SET_ADDRESS64, are available.





Note

FSince the current address may change between calls of your extension, Fyou should re-establish it always if you want to provide it for later Ereferences. Do not assume that it remains unchanged between 3calls of your extension.


/

Condition values returned

2



Example


int curadr;    .   .   . SDA$EXTEND_SET_ADDRESS(curadr);  


FThis code establishes a new current address, possibly from a previous memory fetch.


8

SDA$EXTEND_SET_HEADING



Establishes a new header text.



Format

'

SDA$EXTEND_SET_HEADING hdrstr




RETURNS



0This callback does not return a condition value.




ARGUMENTS



hdrstr


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

HThe new header string. The hdrstr argument is the address of a >character string descriptor pointing to the new header string.



DESCRIPTION

EThis callback stores a new header string for further use. The header @string is displayed on the top of every new page (when you call cSDA$EXTEND_NEW_PAGE or SDA inserts a page break).




9Previous- | Next6 | Contents