Xlate(5)							File Formats Manual							  Xlate(5)

NAME

       Xlate, CreateXlate, AddXlateAddress, 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 );

       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 translation buffer.  Pointer to an instruction within the application.  Inte-
       ger 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 instrumented address for a selected set of instructions.

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

       An  Atom  tool's instrumentation passes an address translation buffer to an analysis routine by using a parameter of type XLATE *, as indi-
       cated 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
       definition,  it can pass an instrumented version of a PC to the analysis routine by using the REG_IPC type. See atom_application_instrumen-
       tation(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 specified 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
");
	       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)

       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), AnalHeapBase(5)

       Programmer's Guide

																	  Xlate(5)