Index Index for
Section 5
Index Alphabetical
listing for A
Bottom of page Bottom of
page		 

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

  void Instrument(int iargc, char **iargv, Obj *obj);
      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.

  unsigned InstrumentAll(int iargc, char **iargv);
      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 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 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.


RETURN VALUES

  These routines return values as described in the preceding section.


FILES

  /usr/include/cmplrs/atom.inst.h
      Header file containing external definitions of Atom routines


SEE ALSO

  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

Index Index for
Section 5
Index Alphabetical
listing for A
Top of page Top of
page