unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



Xlate(5)							     Xlate(5)



NAME

  Xlate, CreateXlate, AddXlateAddress, XlateInstTextStart, XlateInstTextSize,
  XlateLoadShift, XlateAddr - Atom routines used to determine the instru-
  mented PC for	selected instructions

SYNOPSIS

  The following	interfaces are defined for use by Atom instrumentation rou-
  tines:

  #include <&lt;cmplrs/atom.inst.h>&gt;


  Xlate	*CreateXlate(
	  Obj *obj,
	  unsigned size	);

  void AddXlateAddress(
	  Xlate	*pxlt,
	  Inst *inst );

  The following	interfaces are defined for use by Atom analysis	routines:

  #include <&lt;cmplrs/atom.anal.h>&gt;


  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

  obj Pointer to an object within the application.

  size
      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.

  pxlt
      Location to which	CreateXlate returns a pointer to an address transla-
      tion buffer (XLATE) or, for AddXlateAddress and the analysis routine
      functions, a pointer to an existing address translation buffer.

  inst
      Pointer to an instruction	within the application.

  idx 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	translation
  buffer (XLATE) created at instrumentation time and passed to analysis	code
  at run time.	You can	use this buffer	at analysis time to get	the instru-
  mented address for a selected	set of instructions.

  An Atom tool's instrumentation routine creates and fills the address trans-
  lation buffer	by calling the CreateXlate and AddXlateAddress routines,
  respectively.	 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 rou-
  tine 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.

  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	exam-
  ple:

	   #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 definition, it
  can pass an instrumented version of a	PC to the analysis routine by using
  the REG_IPC type. See	atom_application_instrumentation(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 routine returns the	number of addresses in the specified
       address translation buffer.

    +  The XlateInstTextStart routine returns the starting address of the
       text segment for	the instrumented object	corresponding to the speci-
       fied address translation	buffer.	 The XlateInstTextSize routine
       returns the size	of the text segment.

    +  The XlateLoadShift routine returns the difference between the run-time
       addresses in the	object corresponding to	to the specified address
       translation buffer and the compile-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	information
  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 procedure.
		*/
	       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

  /usr/include/cmplrs/atom.inst.h
      Header file containing external definitions of Atom routines

SEE ALSO

  Commands: atom(1)

  AtomTools: hiprof(5),	pixie(5), third(5)

  Functions: atom_application_instrumentation(5),
  atom_application_navigation(5), atom_application_resolvers(5),
  atom_application_query(5), atom_description_file(5),
  atom_object_management(5), atom_instrumentation_routines(5), AnalHeap-
  Base(5), Thread(5)

  Programmer's Guide