unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



atom_instrumentation_routines(5)	     atom_instrumentation_routines(5)



NAME

  atom_instrumentation_routines, Instrument, InstrumentAll, InstrumentInit,
  InstrumentFini - Atom	tool instrumentation routines

SYNOPSIS

  #include <&lt;cmplrs/atom.inst.h>&gt;


  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 pro-
  gram 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 direc-
       tories.

    +  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 ver-
  sion 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 rou-
      tines (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 Buil-
      dObj, WriteObj, or ReleaseObj routines.

      If an Instrument routine calls the ResolveTargetProc or Resol-
      veNamedProc 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 pro-
      gram level instrumentation calls,	and performing global initializa-
      tions). 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	fol-
      lowing routines:

	+  AddCallProto

	+  GetFirstObj

	+  GetLastObj

	+  GetNextObj

	+  GetPrevObj

	+  Calls to GetObjInfo that do not specify an ObjInfoType of ObjNum-
	   berProcs, 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 deter-
      mine 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 Instrumen-
      tAll 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.  After-
      wards, 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 argu-
  ments	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 AddCallPro-
       gram 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)

  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