atom_instrumentation_routines(5)				File Formats Manual				  atom_instrumentation_routines(5)

NAME

       atom_instrumentation_routines, Instrument, InstrumentAll, InstrumentInit, 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 instrumenta-
       tion 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) {
		  ProcRes     pres;

		  ResolveNamedProc("malloc", &pres);
		  if (pres.proc != NULL) {
		       AddCallProc(pres.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 rou-
	      tine. 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 Instru-
	      mentFini routine.  Atom calls the InstrumentAll routine once for the entire application program, thus allowing a tool's instrumenta-
	      tion  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 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 travers-
	      ing  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	Instrumen-
       tInit  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)

       Atom Tools: 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), Thread(5)

       Programmer's Guide

														  atom_instrumentation_routines(5)