Content-type: text/html
atom instrumentation_routines, Instrument, InstrumentAll, InstrumentInit, InstrumentFini - Atom tool instrumentation routines
#include <cmplrs/atom.inst.h>
void Instrument(
int iargc,
char **iargv,
Obj *obj
);
void InstrumentInit(
int iargc,
char **iargv
);
void InstrumentFini(
void
);
unsigned InstrumentAll(
int iargc,
char **iargv
);
Atom invokes a tool's instrumentation routine on a given application program when that program is specified as the application_program parameter to the atom command, and either of the following is true: The tool is a prepackaged tool specified as an argument to the -tool flag of an atom command. By default, Atom looks for prepackaged tools in the /usr/lib/cmplrs/atom/tools and /usr/lib/cmplrs/atom/examples directories. The file containing the instrumentation routine is specified as the instrum_file parameter of an atom command.
The instrumentation routine contains the code that traverses the objects, procedures, basic blocks, and instructions to locate instrumentation points; adds calls to analysis procedures; and builds the instrumented version of an application.
An instrumentation routine can employ one of the following interfaces based on the needs of the tool: Atom calls the Instrument routine for each eligible object in the application program. As a result, an Instrument routine should not call AddCallProgram and does not need to use the object navigation routines (GetFirstObj, GetLastObj, GetNextObj, and GetPrevObj). Because Atom automatically writes each object before passing the next to the Instrument routine, the Instrument routine should never call the BuildObj, WriteObj, or ReleaseObj routines.
ResolveNamedProc("malloc", &pres);
if (pres.proc != NULL) {
AddCallProc(pres.proc, ProcBefore, "foo");
<Add special instrumentation code>
}
}
AddCallProto("Startup()");
AddCallProto("Finish()");
AddCallProto("foo(int, REGV)");
AddCallProgram(ProgramBefore, "Startup");
AddCallProgram(ProgramAfter, "Finish");
for (obj = GetFirstObj(); obj; obj = GetNextObj(obj))
{
if (BuildObj(obj))
return(1);
/* instrument obj */
WriteObj(obj);
}
}
Regardless of the instrumentation routine interface, Atom passes the arguments specified in the -toolargs flag to the routine. In the case of the Instrument interface, Atom also passes a pointer to the current object.
An Atom tool should use one of the following methods of specifying analysis
routines to instrument an entire object or application program:
If an analysis routine applies to something contained within
a single object, use
AddCallObj. An example of this is
an analysis routine that initializes some data for a procedure.
If an analysis routine applies to the entire program, call
AddCallProgram
from an
InstrumentInit
routine
(when using the
Instrument
interface) or from the
InstrumentAll
routine. An example of this is an analysis routine
that opens an output file or parses command line options.
These routines return values as described in the preceding section.
Header file containing external definitions of Atom routines
Commands: atom(1)
AtomTools: hiprof(5), pixie(5), third(5)
Functions: atom_application_instrumentation(5), atom_application_query(5), atom_application_navigation(5), atom_description_file(5), atom_application_resolvers(5), atom_object_management(5), AnalHeapBase(5), Xlate(5)
Programmer's Guide