AddXlateEntry man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

Xlate(5)							      Xlate(5)

NAME
       Xlate, CreateXlate, AddXlateAddress, AddXlateEntry, XlateInstTextStart,
       XlateInstTextSize, XlateLoadShift, XlateAddr - Atom  routines  used  to
       determine the instrumented PC for selected instructions

SYNOPSIS
       The  following  interfaces  are defined for use by Atom instrumentation
       routines: #include <cmplrs/atom.inst.h>

       Xlate *CreateXlate(
	       Obj *obj,
	       unsigned size ); void AddXlateAddress(
	       Xlate *pxlt,
	       Inst *inst ); void AddXlateEntry(
	       Xlate *pxlt,
	       Entry *entry );

       The following interfaces are defined for use by Atom analysis routines:
       #include <cmplrs/atom.anal.h>

       unsigned long XlateNum(
	       XLATE *pxlt ); unsigned long XlateInstTextStart(
	       XLATE *pxlt ); unsigned long XlateInstTextSize(
	       XLATE *pxlt ); long XlateLoadShift(
	       XLATE *pxlt ); unsigned long XlateAddr(
	       XLATE *pxlt,
	       unsigned idx );

PARAMETERS
       Pointer	to  an	object	within	the  application.  Size of the address
       translation buffer (XLATE) to be created. Specify the size in terms  of
       the  number  of	instructions  to be added to the buffer. If you do not
       know the number of instructions to be added,  pass  the	special	 value
       XLATE_NOSIZE.   Location	 to  which CreateXlate returns a pointer to an
       address translation buffer (XLATE)  or,	for  AddXlateAddress  and  the
       analysis	 routine  functions, a pointer to an existing address transla‐
       tion  buffer.   Pointer	to  an	instruction  within  the  application.
       Pointer	to  an	entry  within the application.	Integer indicating the
       position of an instruction in the specified address translation	buffer
       for which XlateAddr returns an instrumented run-time address.

DESCRIPTION
       Atom's  Xlate  routines	allow you to determine the instrumented PC for
       selected instructions. You can use these functions  to  build  a	 table
       that  translates an instruction's PC in the instrumented application to
       its PC in the uninstrumented application.

       An Atom tool performs this translation by means of an address  transla‐
       tion buffer (XLATE) created at instrumentation time and passed to anal‐
       ysis code at run time. You can use this buffer at analysis time to  get
       the instrumented address for a selected set of instructions.

       An  Atom tool's instrumentation routine creates the address translation
       buffer by calling the CreateXlate routine. It fills the address	trans‐
       lation buffer by calling the AddXlateAddress or AddXlateEntry routines.
       An address translation buffer can only hold instructions from a	single
       object,	the  object identified by the obj parameter to the CreateXlate
       call.

       The AddXlateAddress routine adds the instruction indicated by the  inst
       parameter  to  an  existing address translation buffer. For an analysis
       routine to be able to translate its address at run time, you  must  add
       an  instruction	to  an	address	 translation buffer at instrumentation
       time. If the translation buffer was created with a fixed size and  this
       instruction  exceeds  that size, the AddXlateAddress routine reports an
       error. You must add instructions to the buffer  before  you  write  the
       associated  object. Only instructions from a single object may be added
       to a buffer.

       The AddXlateEntry routine adds the entry point indicated by  the	 entry
       parameter  to  an  existing address translation buffer. For an analysis
       routine to be able to translate its address at run time, you  must  add
       an  entry  point	 to  an	 address translation buffer at instrumentation
       time. If the translation buffer was created with a fixed size and  this
       entry  exceeds  that  size, the AddXlateEntry routine reports an error.
       You must add entries to the buffer  before  you	write  the  associated
       object. Only entries from a single object may be added to a buffer.

       An  Atom tool's instrumentation passes an address translation buffer to
       an analysis routine by using a parameter of type XLATE *, as  indicated
       in the analysis routine's prototype definition in an AddCallProto call.
       For example:

	   #include <cmplrs/atom.inst.h>
	   void InstrumentInit(int iargc, char **iargv)
	   {
	       /*
		* Add the prototype for an analysis routine that accepts an
		* Xlate argument.
		*/
	       AddCallProto("mycall(XLATE *)");
	   }
	   Instrument(int iargc, char **iargv, Obj *obj)
	   {
	       Xlate *	       pxlate;
	       Proc *	       p;
	       /*
		* Create a new Xlate.
		*/
	       pxlate = CreateXlate(obj, XLATE_NOSIZE);

	       /*
		* Add the starting address of each procedure to the Xlate.
		*/
	       for (p = GetFirstObjProc(obj);  p;  p = GetNextProc(p)) {
		   AddXlateAddress(pxlate, GetFirstInst(GetFirstBlock(p)));
	       }
	       /*
		* Pass the Xlate to the analysis routines.
		*/
	       AddCallObj(obj, ObjBefore, "mycall", pxlate);
	   }

					Note

       It is illegal to pass an address translation  buffer  created  for  one
       object  as  a parameter to a call from another object. For this reason,
       it is normally inappropriate to pass  address  translation  buffers  as
       parameters  to  analysis routines inserted at a PlaceType of ProgramBe‐
       fore and ProgramAfter.

       When the instrumentation routine specifies a formal parameter  type  of
       REGV (that is, register value) in an analysis routine's prototype defi‐
       nition, it can pass an instrumented version of a	 PC  to	 the  analysis
       routine	by  using  the REG_IPC type. See atom_application_instrumenta‐
       tion(5) for further details.

       An Atom tool's analysis routine uses the following interfaces to access
       an  address  translation buffer that is passed to it: The XlateNum rou‐
       tine returns the number of addresses in the specified address  transla‐
       tion  buffer.   The  XlateInstTextStart	routine	 returns  the starting
       address of the text segment for the instrumented	 object	 corresponding
       to the specified address translation buffer. The XlateInstTextSize rou‐
       tine returns the size of the text segment.  The XlateLoadShift  routine
       returns	the  difference	 between  the run-time addresses in the object
       corresponding to the specified address translation buffer and the  com‐
       pile-time  addresses.   The  XlateAddr routine returns the instrumented
       run-time address for the instruction in the specified position  of  the
       specified  address  translation	buffer. Note that the run-time address
       for an instruction in a shared library is not necessarily the  same  as
       its compile-time address.

       The  following example shows how an analysis routine retrieves informa‐
       tion from an address translation buffer:

	   #include <cmplrs/atom.anal.h>

	   void mycall(XLATE *pxlate)
	   {
	       unsigned	       n;
	       unsigned	       i;
	       /*
		* Get the number of addresses in the Xlate.
		*/
	       n = XlateNum(pxlate);
	       /*
		* Print the instrumented address for the start of each	proce‐
       dure.
		*/
	       printf("Instrumented procedure starting addresses\n");
	       for (i = 0;  i < n;  i++)
		   printf("0x%lx0, XlateAddr(pxlate, i));
	   }

RETURN VALUES
       These routines return the values described in the preceding section.

FILES
       Header file containing external definitions of Atom routines

SEE ALSO
       Commands: atom(1)

       Functions:  atom_application_instrumentation(5), atom_application_navi‐
       gation(5),   atom_application_query(5),	  atom_application_symbols(5),
       atom_description_file(5),	     atom_instrumentation_routines(5),
       atom_object_management(5), AnalHeapBase(5), Thread(5)

       Programmer's Guide

								      Xlate(5)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net