atom_instrumentation_routines(5)atom_instrumentation_routines(5)NAME
atom_instrumentation_routines, Instrument, InstrumentAll, Instrumen‐
tInit, InstrumentFini - Atom tool instrumentation routines
SYNOPSIS
#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 );
DESCRIPTION
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 instru‐
mentation 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, GetNex‐
tObj, and GetPrevObj). Because Atom automatically writes each object
before passing the next to the Instrument routine, the Instrument rou‐
tine should never call the BuildObj, WriteObj, or ReleaseObj routines.
If an Instrument routine calls the ResolveTargetProc or Resolve‐
NamedProc 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 con‐
struct 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 Instru‐
mentInit routine to perform tasks required before Atom calls
Instrument for the first object (such as defining analysis rou‐
tine 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 Get‐
NextObj GetPrevObj Calls to GetObjInfo that do not specify an
ObjInfoType of ObjNumberProcs, ObjNumberBlocks, or ObjNumberIn‐
sts GetObjName GetObjOutName GetAnalName GetObjInstArray GetOb‐
jInstCount GetProgInfo
Additionally, an InstrumentInit routine can call AddCallProgram.
Normally a tool does not use any Atom routines in an Instru‐
mentFini routine. Atom calls the InstrumentAll routine once for
the entire application program, thus allowing a tool's instru‐
mentation code itself to determine how to traverse the applica‐
tion's objects. With this method, you do not specify Instrumen‐
tInit 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 program-level 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 pro‐
gram: If an analysis routine applies to something contained within a
single object, use AddCallObj. An example of this is an analysis rou‐
tine that initializes some data for a procedure. If an analysis rou‐
tine applies to the entire program, call AddCallProgram from an Instru‐
mentInit 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.
RETURN VALUES
These routines return values as described in the preceding section.
FILES
Header file containing external definitions of Atom routines
SEE ALSO
Commands: atom(1)
Functions: atom_application_instrumentation(5), atom_application_navi‐
gation(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)