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)