Instrument man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

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)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net