atom_application_instrumentation(5)				File Formats Manual			       atom_application_instrumentation(5)

NAME

       atom_application_instrumentation,  AddCallProto,  AddCallProgram,  AddCallObj,  AddCallProc,  AddCallBlock, AddCallInst, ReplaceProcedure -
       Allows an Atom tool's instrumentation routine to add, within an application program, calls to analysis routines

SYNOPSIS

       #include <cmplrs/atom.inst.h>

       void AddCallProto(
	       const char * ); void AddCallProgram(
	       PlaceType,
	       const char *, ...  ); void AddCallObj(
	       Obj *,
	       PlaceType,
	       const char *, ...  ); void AddCallProc(
	       Proc *,
	       PlaceType,
	       const char *, ...  ); void AddCallBlock(
	       Block *,
	       PlaceType,
	       const char *, ...  ); void AddCallInst(
	       Inst *,
	       PlaceType,
	       const char *, ...  ); void ReplaceProcedure(
	       Proc *,
	       const char * );

DESCRIPTION

       The Atom application instrumentation routines allow you to add arbitrary procedure  calls  before  and  after  objects,	procedures,  basic
       blocks, and instructions.  You can also add procedure calls before and after the application program executes.

       You can use these routines only from an Atom tool's instrumentation file.  See atom(1) for a description of Atom.

   AddCallProto Routine
       You  must  use the AddCallProto routine to specify the prototype of each procedure call to be added to the program. In other words, an Add-
       CallProto call must define the procedural interface for each call to an analysis procedure to be added to the program by  subsequent  calls
       to AddCallProgram, AddCallObj, AddCallProc, AddCallBlock, and AddCallInst.

       The  format of the prototype is similar to a C language function definition.  The name of the analysis procedure is followed by a parenthe-
       sized list of arguments.

       There are four basic argument types: Constants Computed values (VALUE) Register values  (REGV  and  FREGV)  Address  translation  structure
       (*XLATE)

       Constant  types include char, int, long, char *, char[], int[], and long[]. Often, arrays are used to communicate static information, espe-
       cially large data structures, to analysis procedures.  Three special keywords exist to facilitate the passing of  array	and  string  argu-
       ments:  Indicates  that	the  analysis  routine	cannot modify or write to the passed array or string. Atom allocates the memory for such a
       string or array in the instrumented program's read-only memory.	Using const can thus greatly reduce the memory usage of instrumented  pro-
       grams  that  have  multiple  images  active simultaneously.  Indicates that Atom does not need to make a copy of the data for the string or
       array during instrumentation.  If your instrumentation code passes a stable buffer to AddCallObj, AddCallProc,  AddCallBlock,  or  AddCall-
       Inst,  it  must not modify or free the buffer until after WriteObj is called for the object containing the given Obj, Proc, Block, or Inst.
       If you pass a stable buffer to AddCallProgram, you must never modify or free the buffer.

	      Strings returned by the following routines can be considered stable for the duration of  the  instrumentation  process:  GetObjName,
	      GetObjOutName,  GetAnalName,  GetObjInstArray,  ProcName, ProcFileName, and GetInstProcCalled.  Indicates that Atom does not need to
	      make a copy of the data for the string or array during instrumentation and that it will deallocate the buffer (by calling free) when
	      it  is done with it. Instrumentation code should never modify or free such a buffer after it has been passed to AddCallObj, AddCall-
	      Proc, AddCallBlock, AddCallInst, or AddCallProgram.

       You can use the const keyword with either stable or free. The stable and free keywords are mutually exclusive.

       The VALUE argument type defines an argument with a 64-bit value that Atom must compute before passing it to the analysis procedure.   There
       are two arguments of the VALUE argument type, as listed in the following table.	For such arguments, specify VALUE in the AddCallProto call
       and the argument's symbolic name in the call to AddCallObj, AddCallProc, AddCallBlock, AddCallInst, or AddCallProgram.

       ---------------------------------------------------------------------
       Type    Argument       Description
       ---------------------------------------------------------------------
       VALUE   EffAddrValue   Effective  load-time address  of	a  load  or
			      store  instruction.  This  is  the sum of the
			      64-bit address contained in the base register
			      and  the	signed	16-bit displacement.  (Note
			      that, for a shared library, the  run-time  PC
			      differs  from  the  compile-time	PC.)   This
			      argument is  valid  only	on  load  or  store
			      instructions  instrumented  by an AddCallInst
			      call with InstBefore  specified.	 Otherwise,
			      Atom reports an error.
       VALUE   BrCondValue    Outcome  of a conditional branch instruction.
			      Returns a zero (0) if  the  branch  condition
			      will  evaluate  to  false or a 64-bit nonzero
			      value if it  will  evaluate  to  true.   This
			      argument	is valid only on conditional branch
			      instructions instrumented by  an	AddCallInst
			      call  with  InstBefore specified.  Otherwise,
			      Atom reports an error.
       ---------------------------------------------------------------------

       The REGV and FREGV argument types define an argument representing the contents of a register.  FREGV is used for floating-point	registers;
       REGV  is  used for all other registers. There are several arguments of the REGV and FREGV argument types, as listed in the following table.
       For such arguments, specify REGV or FREGV in the AddCallProto call and the argument's symbolic name in the call to AddCallObj, AddCallProc,
       AddCallBlock, AddCallInst, or AddCallProgram.

       --------------------------------------------------------------------
       Type    Argument      Description
       --------------------------------------------------------------------
       REGV    REG_n	     Integer register n, where n is a value from 0
			     to 31.
       REGV    REG_RA	     Return address register.
       REGV    REG_GP	     Global pointer.
       REGV    REG_SP	     Stack pointer.
       REGV    REG_ZERO      Integer register 31.
       REGV    REG_CC	     Processor cycle counter.
       REGV    REG_PC	     Pure compile-time (that is,  noninstrumented)
			     program counter at the instrumentation point.
			     (Note that, for a shared  library,  the  run-
			     time PC differs from the compile-time PC.)
       REGV    REG_IPC	     Instrumented  program counter at run-time	If
			     the call is from a shared library,  the  run-
			     time PC is passed.
       REGV    REG_ARG_n     Integer  argument	register  n,  where n is a
			     value from 1 to 6.
       REGV    REG_RETVAL    Integer function return value.
       REGV    FREG_n	     Floating-point register n, where n is a value
			     from 0 to 31.
       FREGV   FREG_ZERO     Floating-point register 31.
       FREGV   FREG_ARG_n    Floating-point  argument  register n, where n
			     is a value from 1 to 6.
       FREGV   FREG_RETVAL   Floating-point function return value.
       --------------------------------------------------------------------

       Note that the special REGV-type value REG_NOTUSED is also defined as a return value from GetInstRegEnum.  You cannot pass it as an argument
       to AddCallObj, AddCallProc, AddCallBlock, AddCallInst, or AddCallProgram.

									  Note

       When  you  use  AddCallObj,  you will sometimes find that the analysis routine for each added call requires a slightly different prototype.
       This usually occurs when you pass an array argument and the number of elements in the array depends on the contents of  the  object.   Nor-
       mally,  it is illegal to reprototype an analysis routine, but Atom makes an exception for array parameters.  If the only difference between
       the new prototype and the old prototype is the length of an array parameter, Atom allows you to use AddCallProto to reprototype the  analy-
       sis routine.  Subsequent calls to that analysis routine will use the new array length.

   AddCallProgram Routine
       Use the AddCallProgram routine in an InstrumentInit or InstrumentAll routine to add a call to an analysis procedure before a program starts
       execution or after it completes execution.  Typically such an analysis procedure does something that applies to the whole program, such	as
       opening	an  output file or parsing command line options.  Supply a PlaceType value of ProgramBefore or ProgramAfter as the instrumentation
       point, followed by the name of the analysis procedure and a list of its arguments.  Since ProgramAfter actions are executed after the  pro-
       gram is complete, library routines requiring system services should not be used in ProgramAfter analysis routines.

       Because the Instrument routine is called for each object in a program, avoid calling AddCallProgram from the Instrument routine.

       If  the program forks and ProgramBefore is specified, Atom calls the analysis procedure only once - before the parent process starts execu-
       tion.  If ProgramAfter is specified, Atom calls the analysis procedure after each child process completes execution and	after  the  parent
       process completes execution.

   AddCallObj Routine
       Use  the AddCallObj routine in an instrumentation routine to add a call to an analysis procedure before an object starts execution or after
       it completes execution.	Typically such an analysis procedure does something that applies to the single object, such as	initializing  some
       data for its procedures.  Supply a PlaceType value of ObjBefore or ObjAfter as the instrumentation point, followed by the name of the anal-
       ysis procedure and a list of its arguments.

       Instrumentation code added at the beginning of an object is executed immediately after the object is loaded into memory (before any  proce-
       dures  in  that	object	are  executed).   Instrumentation code added at the end of an object is executed immediately before that object is
       unloaded from memory (after all procedures from that object have finished execution).

									  Note

       An InstrumentAll routine must call the BuildObj routine before calling AddCallObj, AddCallBlock, AddCallProc, or AddCallInst to add  analy-
       sis  routine  calls, and before traversing the procedures in the object.  BuildObj builds the internal data structures Atom uses to manipu-
       late the object.  After the Atom tool traverses and instruments the object, the InstrumentAll routine must call	the  WriteObj  routine	to
       write out the instrumented version of the object.  See the atom_object_management(5) reference page for additional information.

   AddCallProc Routine
       Use  the  AddCallProc  routine  in an instrumentation routine to add a call to an analysis procedure before a procedure starts execution or
       after it completes execution. Supply a PlaceType value of ProcBefore or ProcAfter as the instrumentation point, followed by the name of the
       analysis  procedure and a list of its arguments.  The following factors determine when the analysis procedures are called: If the procedure
       has multiple entry points and ProcBefore is specified, Atom calls the analysis procedure at each entry point.  If the procedure has  multi-
       ple  exit  points  and  ProcAfter  is specified, Atom calls the analysis procedure each time it issues a return.  If the procedure contains
       interprocedural branches or interprocedural jumps, the call to the analysis procedure will occur before the branch or jump.  Compilers  can
       optimize  return  statements  or non-returning function calls to interprocedural branches. To avoid this, recompile with -O0 or -no_inline.
       If the procedure does not issue a return (for example, it calls exit or longjmp), Atom does not call the analysis procedure.

   AddCallBlock Routine
       Use the AddCallBlock routine in an instrumentation routine to add a call to an analysis procedure before a basic block starts execution	or
       after  it  completes execution. Supply a PlaceType value of BlockBefore or BlockAfter as the instrumentation point, followed by the name of
       the analysis procedure and a list of its arguments.

       If the basic block ends with an unconditional branch or jump and BlockAfter is specified, Atom calls the analysis procedure after the basic
       block completes execution.  However, if the basic block ends with a jump to a subroutine that does not return (for instance, the subroutine
       calls exit or longjmp), Atom does not call the analysis procedure.

   AddCallInst Routine
       Use the AddCallInst routine in an instrumentation routine to add a call to an analysis procedure before a  given  instruction  executes	or
       after  it  executes. Supply a PlaceType value of InstBefore or InstAfter as the instrumentation point, followed by the name of the analysis
       procedure and a list of its arguments.

       If the instruction is an unconditional branch or jump and InstAfter is specified, Atom calls the analysis procedure after  the  instruction
       executes.   However, if the instruction is a jump to a subroutine that does not return (for example, the subroutine calls exit or longjmp),
       Atom does not call the analysis procedure.

       An implied scope hierarchy exists in the ordering of calls to analysis procedures before and after the execution of programs, objects, pro-
       cedures,  basic blocks, and instructions. By enforcing a scope hierarchy, Atom guarantees, for instance, that a procedure added at Program-
       Before executes before procedures added in lower scopes.  Procedures added at ProgramAfter execute after all application instructions  have
       executed.

   ReplaceProcedure Routine
       Use  the  ReplaceProcedure  routine  to	replace a procedure call in the instrumented program.  For instance, Atom's Third Degree tool uses
       ReplaceProcedure to replace all calls to dynamic memory allocation routines with special-purpose procedures. It defines the special  proce-
       dure 3rd_malloc as having the same arguments and return value as the original malloc.

									  NOTE

       Occasionally,  a  compiler optimization may create a procedure that is too complex for Atom to replace with the ReplaceProcedure() routine.
       If this occurs, an error will be reported, and instrumentation will abort: atom: Error: Unable to replace procedure with call  to  'my_mal-
       loc'.
	     Procedure does not adhere to calling standard.  atom: Error: Instrumentation aborted due to errors.

       To work around this problem, add -Wca, O0 to the atom command line.

EXAMPLES

       The  following example accumulates wall-clock and per-process time for a procedure.  The instrumentation routine defines the prototypes for
       calls to analysis procedures and identifies the intrumentation points at which those calls take place:

	  AddCallProto("Start(REGV)");
	  AddCallProto("Stop(REGV)");
	  .
	  .
	  .
	  AddCallProc(p,ProcBefore,"Start",REG_CC);
	  AddCallProc(p,ProcAfter,"Stop",REG_CC);
	  .
	  .
	  .

       The analysis routine is complicated by the format of the cycle counter. The low-order 32 bits contain a	free  running  cycle  count.   The
       high-order  32  bits  of  the counter are an offset that, when added to the low-order 32 bits, produces a cycle count for this process. The
       low-order 32 bits can be used directly to determine wall clock times:

	  long total;
	  long process;
	  int ccStart;
	  int ccStartProcess;

	  void Start(unsigned long cc) {
	    ccStart = cc;
	    ccStartProcess = ((cc << 32) + cc) >> 32;
	  }
	  void Stop(unsigned long cc) {
	    int ccEnd = cc;
	    int ccEndProcess = ((cc << 32) + cc) >> 32;
	    total += (unsigned) (ccEnd - ccStart);
	    process += (unsigned) (ccEndProcess - ccStartProcess);
	  }

RETURN VALUES

       These routines have no return values.

FILES

       Header file containing external definitions of Atom routines

SEE ALSO

       Commands: atom(1)

       AtomTools: hiprof(5), pixie(5), third(5)

       Functions:    atom_application_navigation(5),	atom_application_query(5),    atom_application_resolvers(5),	 atom_description_file(5),
       atom_object_management(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5), Thread(5)

       Programmer's Guide

													       atom_application_instrumentation(5)