Content-type: text/html Man page of Xlate

Xlate

Section: File Formats (5)
Index Return to Main Contents
 

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

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


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:43:12 GMT, October 02, 2010