Xlate, CreateXlate, AddXlateAddress, AddXlateEntry, XlateInstTextStart,
XlateInstTextSize, XlateLoadShift,
XlateAddr - Atom routines used to determine the instrumented
PC for selected instructions
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 );
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. 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.
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 the address
translation buffer by calling the CreateXlate routine. It
fills the address translation 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 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 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));
}
These routines return the values described in the preceding
section.
Header file containing external definitions of Atom routines
Commands: atom(1)
Functions: atom_application_instrumentation(5),
atom_application_navigation(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)
[ Back ] |
