Xlate(5)
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
*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
translation 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
speci-
Integer indicating the position of an instruction in the
fied 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 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
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 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
ProgramBefore 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
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 compiletime
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
RELATED INFORMATION
Commands: atom(1)
Atom Tools: 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