|
|
atom_instrumentation_routines(5)
Contents
|
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
appl_prog parameter to the atom(1) command, and either of
the following is true: The tool is named in an argument to
the -tool flag of an atom command. By default, Atom looks
for named 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.
If an Instrument routine calls the ResolveTargetProc
or ResolveNamedProc routine for a procedure
name that exists in another object, the routine
sets the proc field in the ProcRes structure to
NULL. If the tool uses ResolveNamedProc to add
special instrumentation code to a specific procedure,
it can use a construct like the following:
Instrument(int iargc, char **iargv, Obj *obj) {
Proc *proc;
proc = FindProc(obj,"malloc");
if (proc != NULL) {
AddCallProc(proc, ProcBefore, "foo");
<Add special instrumentation code>
} }
Because malloc exists in only one of the objects,
this construct adds the special instrumentation
code to malloc exactly once - when its object is
instrumented.
When using the Instrument interface, you can define
an InstrumentInit routine to perform tasks required
before Atom calls Instrument for the first object
(such as defining analysis routine prototypes,
adding program level instrumentation calls, and
performing global initializations). Atom passes the
arguments specified in the -toolargs flag to the
atom command to the InstrumentInit routine. You can
also define an InstrumentFini routine to perform
tasks required after Atom calls Instrument for the
last object (such as global cleanup). Atom passes
no parameters to the InstrumentFini routine.
Atom restricts an InstrumentInit or InstrumentFini
routine to using only a subset of the Atom routines.
In general terms, either routine is allowed
to add prototypes, add program level analysis
calls, traverse objects, and perform some queries
about objects. Neither can traverse the procedures
in any object.
Specifically, InstrumentInit and InstrumentFini can
call only the following routines: AddCallProto GetFirstObj
GetLastObj GetNextObj GetPrevObj Calls to
GetObjInfo that do not specify an ObjInfoType of
ObjNumberProcs, ObjNumberBlocks, or ObjNumberInsts
GetObjName GetObjOutName GetAnalName GetObjInstArray
GetObjInstCount GetProgInfo
Additionally, an InstrumentInit routine can call
AddCallProgram. Normally a tool does not use any
Atom routines in an InstrumentFini routine. Atom
calls the InstrumentAll routine once for the entire
application program, thus allowing a tool's instrumentation
code itself to determine how to traverse
the application's objects. With this method, you do
not specify InstrumentInit or InstrumentFini routines.
The InstrumentAll routine does everything.
Because of this, an InstrumentAll routine must call
the Atom object navigation routines itself and use
the BuildObj, WriteObj, or ReleaseObj routine to
manage the application's objects.
A typical InstrumentAll routine might contain the
following code:
unsigned InstrumentAll(int iargc, char **iargv) {
Obj * obj;
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);
}
return(0); }
The InstrumentAll routine first adds the prototypes
for the analysis routine and then adds the programlevel
analysis calls. Next, it traverses the
objects in the program, calling BuildObj to build
the internal Atom data structures for each object
before traversing that object's procedures or
adding analysis calls to the object. Afterwards,
it calls WriteObj to write out the instrumented
version of the given object and deallocate the
internal data structures that BuildObj created.
Note that, because BuildObj may return an error
code, the InstrumentAll routine propagates this
error return back to Atom by returning 1. An
InstrumentAll routine must return zero (0) to Atom
if the tool completes successfully, or 1 if it
encounters an error. Atom terminates with an error
code if the routine returns 1.
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)
Functions: atom_application_instrumentation(5),
atom_application_navigation(5), atom_application_query(5),
atom_application_symbols(5), atom_description_file(5),
atom_object_management(5), AnalHeapBase(5), Thread(5),
Xlate(5)
Programmer's Guide
atom_instrumentation_routines(5)
[ Back ] |
