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_application_query(5)			    atom_application_query(5)



NAME

  atom_application_query, GetProgInfo, GetObjInfo, GetObjName, GetObjOutName,
  GetAnalName, GetObjInstArray,	GetObjInstCount, GetProcInfo, ProcName,
  ProcFileName,	ProcPC,	GetBlockInfo, BlockPC, IsBranchTarget, GetInstClass,
  IsInstType, GetInstInfo, InstPC, InstLineNo, GetInstBinary, GetInstRegEnum,
  GetInstRegUsage - Allows an Atom-tool	instrumentation	routine	to obtain
  information about the	parts of an application	program

SYNOPSIS

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


  const	char *GetAnalName(
	  void );

  long GetProgInfo(
	  ProgInfoType );

  long GetObjInfo(
	  Obj *,
	  ObjInfoType );

  const	char *GetObjName(
	  Obj *	);

  const	char *GetObjOutName(
	  Obj *	);

  const	unsigned int *GetObjInstArray(
	  Obj *	);

  long GetObjInstCount(
	  Obj *	);

  long GetProcInfo(
	  Proc *,
	  ProcInfoType );

  const	char *ProcName(
	  Proc * );

  const	char *ProcFileName(
	  Proc * );

  long ProcPC(
	  Proc * );

  long GetBlockInfo(
	  Block	*,
	  BlockInfoType	);

  long BlockPC(
	  Block	* );

  unsigned IsBranchTarget(
	  Block	* );

  IClassType GetInstClass(
	  Inst * );

  int IsInstType(
	  Inst *,
	  ITypeType );

  int GetInstInfo(
	  Inst *,
	  InstInfoType );

  long InstPC(
	  Inst * );

  long InstLineNo(
	  Inst * );

  int GetInstBinary(
	  long );

  RegvType GetInstRegEnum(
	  Inst *,
	  InstInfoType );

  void GetInstRegUsage(
	  Inst *,
	  InstRegUsageVec * );

DESCRIPTION

  Atom's application query routines allow an instrumentation routine to
  obtain information about the parts of	an application program.

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

  GetAnalName Routine


  Use the GetAnalName routine to obtain	the name of the	analysis file, as
  passed to the	atom command.  This routine is useful for tools	that have a
  single instrumentation file and multiple analysis files.

  GetProgInfo Routine


  Use the GetProgInfo routine to obtain	the number of objects in a program.

  _____________________________________________________________________
  ProgInfo	       Description
  _____________________________________________________________________
  ProgNumberObjects

		       Returns the number of objects associated	with an
		       application.
  ProgNumInstObjects

		       Returns the number of objects that the user
		       requested instrumentation upon.
  _____________________________________________________________________

  Each object of a program is a	self-contained program with text, unitial-
  ized,	and data sections.  The	text section contains instructions.  Initial-
  ized data includes data that must be initialized to nonzero values;
  unitialized data is filled with zeroes when the corresponding	pages are
  mapped into the user's address space.





  GetObjInfo Routine


  Use the GetObjInfo routine to	obtain information about the specified Obj.
  The following	ObjInfoType values return the indicated	information:

  ____________________________________________________________________
  ObjInfoType		      Description
  ____________________________________________________________________
  ObjTextStartAddress

			      Returns the starting compile-time
			      address of the object's text segment.

			      When instrumenting a nonshared execut-
			      able or the main executable of call-
			      shared programs, the compile-time
			      address is identical to the run-time
			      address.	For shared libraries, the com-
			      piler may	place an object	at a different
			      address than its compile-time address.
  ObjTextSize

			      Returns the size in bytes	of the
			      object's text segment.
  ObjInitDataStartAddress

			      Returns the starting address of the
			      object's data segment.
  ObjInitDataSize

			      Returns the size in bytes	of the
			      object's data segment.
  ObjUninitDataStartAddress

			      Returns the starting address of the
			      object's bss segment.
  ObjUninitDataSize

			      Returns the size in bytes	of the
			      object's bss segment.
  ObjNumberProcs

			      Returns the number of procedures in the
			      object.
  ObjNumberBlocks

			      Returns the number of basic blocks in
			      the object.
  ObjNumberInsts

			      Returns the number of instructions in
			      the object.  Note	that the number	of
			      instructions returned is not usually
			      equal to the value returned by
			      ObjTextSize divided by the instruction
			      size (4 bytes). The compiler aligns pro-
			      cedures on 16-byte boundaries by padding
			      them on both sides with NOP instruc-
			      tions.  Because these instructions are
			      never executed, they are not included in
			      the count	returned by ObjNumberInsts.
  ObjID

			      Returns a	unique numeric identifier for
			      the object.  This	identifier is unique
			      to this object within the	entire appli-
			      cation program. It is in the range zero
			      to GetProgInfo(ProgNumberObjects).










  ObjModifyHint

			      The ObjModifyHint	type returns the value
			      OBJ_WRITABLE if the user asked for the
			      object to	be instrumented. If the	user
			      did not request that a library be
			      instrumented, but	Atom had to instrument
			      the library to support options such as
			      -fork or -pthread, then the value
			      OBJ_AUTOMATIC will be returned. Other-
			      wise, the	value OBJ_READONLY will	be
			      returned.	A user indicates which objects
			      are or are not to	be instrumented	by
			      specifying the -all, -incobj, or -excobj
			      options on the atom command line.	Cer-
			      tain tools can use this hint to decide
			      whether to exclude particular objects
			      from instrumentation.


















































  ObjSymResolution

			      Indicates	if a shared library was	linked
			      symbolically or not. Valid return	values
			      are OBJ_SYMBOLIC and OBJ_STANDARD.



  ObjShared

			      Indicates	if an object was linked	call-
			      shared, sharable (.so), or non-shared.
			      Valid return values are OBJ_CALL_SHARED,
			      OBJ_SHARABLE, and	OBJ_NON_SHARED.
  ____________________________________________________________________

  GetObjName and GetObjOutName Routines


  Use the GetObjName routine to	obtain the original filename of	the specified
  object.

  Use the GetObjOutName	routine	to obtain the name of the instrumented
  object.

  GetObjInstArray and GetObjInstCount Routines


  Use the GetObjInstArray routine to obtain an array consisting	of the 32-bit
  instructions included	in the specified Obj.

  Use GetObjInstCount to obtain	the number of instructions in the array.

  GetProcInfo Routine


  Use the GetProcInfo routine to obtain	information about the specified	Proc.
  The following	ProcInfoType values return the indicated information:

  _____________________________________________________________________
  ProcInfoType	       Description
  _____________________________________________________________________
  ProcFrameSize

		       Returns the size	of the fixed portion of	the
		       procedure's stack frame.
  ProcIRegMask

		       Returns the procedure's saved integer register
		       mask.
  ProcIRegOffset

		       Returns the offset to the procedure's integer
		       register	save area in the stack frame.
  ProcFRegMask

		       Returns the procedure's saved floating-point
		       register	mask.
  ProcFRegOffset

		       Returns the offset to the procedure's floating-
		       point register save area	in the stack frame.
  ProcgpPrologue

		       Returns the size	in bytes of the	global pointer
		       (GP) prologue.
  ProcgpUsed

		       Returns a nonzero value if the procedure	uses
		       the GP register ($gp) and zero (0) if it	does
		       not.
  ProcLocalOffset

		       Returns the offset to the procedure's local
		       variables from the virtual frame	pointer.
  ProcFrameReg

		       Returns the number of the register that is being
		       used as the procedure's frame pointer.
  ProcPcReg

		       Returns the number of the register that contains
		       the procedure's return address.
  ProcNumberBlocks

		       Returns the number of basic blocks in the pro-
		       cedure.
  ProcNumberInsts

		       Returns the number of instructions in the pro-
		       cedure.



  ProcID

		       Returns a unique	numeric	identifier for the pro-
		       cedure. This identifier is unique within	the
		       object.



  ProcLineLow

		       Returns the lowest source line in the procedure,
		       or zero (0) if source line information is una-
		       vailable.
  ProcLineHigh

		       Returns the highest source line in the pro-
		       cedure, or zero (0) if source line information
		       is unavailable.	This value and the value
		       returned	by ProcLineLow are useful for determin-
		       ing when	the compiler has performed inline
		       operations that have changed the	line number of
		       an instruction to a value that is not in	the
		       range of	the current procedure.
  ProcAddrTaken

		       Returns a nonzero value if the program has taken
		       the procedure's address and zero	(0) if it has
		       not.  An	Atom tool can use this value to	deter-
		       mine if the procedure is	a potential target of
		       an indirect procedure call.
  ProcIpBrJmp

		       Returns a nonzero value if the procedure	con-
		       tains an	interprocedural	branch or interpro-
		       cedural jump.
  ProcIsRegFrame

		       Returns a nonzero value if the procedure	has a
		       register	frame.
  ProcSymRes

		       Indicates how a procedure name is resolved.
		       Valid return values are SYMRES_EXPORT,
		       SYMRES_EXPORT_WEAK, SYMRES_EXTERN,
		       SYMRES_STATIC, and SYMRES_NONE.
  ProcExceptionFrame

		       Returns a non-zero value	if the procedure
		       includes	a hardware exception context.
  _____________________________________________________________________

  ProcName and ProcFileName Routines


  Use the ProcName routine to obtain the name of the specified Proc.

  Use the ProcFileName routine to obtain the name of the source	file that
  contains the specified Proc. If local	symbols	are not	present, the value
  NULL is returned. Use	to ProcFileName	and InstLineNo routines	to identify
  the file name	and line number	of any instruction in the application pro-
  gram.

  ProcPC Routine


  Use the ProcPC routine to obtain the compile-time program counter (PC) of
  the first instruction	in the procedure.

  GetBlockInfo Routine


  Use the GetBlockInfo routine to obtain information about the specified
  Block.  The following	BlockInfoType values return the	indicated informa-
  tion:








  ______________________________________________________________________
  BlockInfoType	     Description
  ______________________________________________________________________
  BlockNumberInsts

		     Returns the number	of instructions	in the basic
		     block.

  BlockID

		     Returns a unique numeric identifier for the basic
		     block.  This identifier is	unique to this basic
		     block within its containing object.
  ______________________________________________________________________

  BlockPC Routine


  Use the BlockPC routine to obtain the	compile-time program counter (PC) of
  the first instruction	in the basic block.

  IsBranchTarget Routine


  Use the IsBranchTarget routine to determine if the specified Block is	the
  target of a branch instruction, such as br, bsr, a conditional integer
  branch, or a conditional floating-point branch.  IsBranchTarget returns a
  nonzero value	if the basic block is the target of a branch and zero (0) if
  it is	not. A tool that builds	a call flow graph would	find this information
  useful.

  GetInstClass Routine


  Use the GetInstClass routine to obtain the class of the specified Inst.
  Each instruction can belong to only one class. Class information could be
  used to instrument a specific	kind of	instruction. The following IClassType
  values may be	returned:

  ___________________________________________________________________
  IClassType	     Description
  ___________________________________________________________________
  ClassLoad	     Integer load instruction
  ClassFload	     Floating-point load instruction
  ClassStore	     Integer store data	instruction
  ClassFstore	     Floating-point store data instruction
  ClassIbranch	     Integer branch instruction
  ClassFbranch	     Floating-point branch instruction
  ClassSubroutine    Integer subroutine	call or	return instruction
  ClassIarithmetic   Integer arithmetic	instruction
  ClassImultiplyl    Integer longword multiply instruction
  ClassImultiplyq    Integer quadword multiply instruction
  ClassIlogical	     Logical function instruction
  ClassIshift	     Shift function instruction
  ClassIcondmove     Conditional move instruction
  ClassIcompare	     Integer compare instruction
  ClassFpop	     Other floating-point operations
  ClassFdivs

		     Floating-point single precision divide instruc-
		     tion
  ClassFdivd

		     Floating-point double precision divide instruc-
		     tion
  ClassNull

		     call pal instruction, hw_x	instruction,  etc
  ClassMem	     Miscellaneous instructions	which access memory
  ___________________________________________________________________







  IsInstType Routine


  Use the IsInstType routine to	determine if the specified Inst	is an
  instruction of the specified type. You can specify any of the	following
  ITypeType values.  IsInstType	returns	a nonzero value	if the instruction is
  of the specified type	and zero (0) if	it is not. Note	that any instruction
  can be of more than one ITypeType.

  _____________________________________________________________________
  ITypeType	     Description
  _____________________________________________________________________
  InstTypeLoad	     Integer or	floating-point load instruction
  InstTypeStore	     Integer or	floating-point store instruction
  InstTypeMem	     Any instruction that accesses memory
  InstTypeJump	     Jump, jump	to subroutine, or return instruction
  InstTypeFP	     Any floating-point	instruction
  InstTypeInt	     Any integer or nonfloating-point instruction
  InstTypeDiv	     Single or double precision	divide instruction
  InstTypeMul	     Integer or	floating-point multiply	instruction
  InstTypeAdd	     Integer or	floating-point add instruction
  InstTypeSub	     Integer or	floating-point subtract	instruction
  InstTypeNop	     Any type of NOP instruction
  InstTypeRet	     Return instruction
  InstTypeCondBr

		     Integer or	floating-point conditional branch
		     instruction
  InstTypeUncondBr

		     Integer or	floating-point unconditional branch
		     instruction, but not a subroutine call
  _____________________________________________________________________

  GetInstInfo Routine


  Use the GetInstInfo routine to parse an entire 32-bit	instruction and
  obtain all or	a portion of that instruction.	You can	specify	any of the
  following InstInfoType values:

  _________________________________________________________________________
  InstInfoType	      Description
  _________________________________________________________________________
  InstMemDisp

		      Returns the 16-bit memory-format displacement field,
		      sign-extended to 32 bits (even if	the instruction
		      does not reference memory).
  InstBrDisp

		      Returns the sign-extended, branch-format displacement
		      field.
  InstRA

		      Returns register field A.	 Supply	InstA to a call	to
		      GetInstRegEnum to	determine whether the instruction
		      is an integer or floating-point instruction.
  InstRB

		      Returns register field B.	 Supply	InstB to a call	to
		      GetInstRegEnum to	determine whether the instruction
		      is an integer or floating-point instruction.
  InstRC

		      Returns register field C.	 Supply	InstC to a call	to
		      GetInstRegEnum to	determine whether the instruction
		      is an integer or floating-point instruction.
  InstOpcode	      Returns the instruction's	opcode.
  InstBinary

		      Returns a	32-bit binary representation of	the assem-
		      bly language instruction.
  InstAddrTaken

		      Returns a	nonzero	value if the instruction's address
		      is taken and zero	(0) if it is not.
  InstEntryPoint

		      Returns a	nonzero	value if the instruction is a pro-
		      cedure entry point and zero (0) if it is not.
  InstIPJmp

		      Returns a	nonzero	value if the instruction is an
		      interprocedural jump.


  InstIPBr

		      Returns a	nonzero	value if the instruction is an
		      interprocedural branch.




  InstContext

		      Describes	the procedure's	context	at the specified
		      instruction. It returns one of the following values:
		      IN_CONTEXT -- This instruction resides in	the
		      routine's	context. This means that this instruction
		      stands in	the part of the	routine	that is	current	for
		      exception	handling purposes. Stack space has been
		      allocated, and registers were saved on the stack.
		      NON_CONTEXT -- This instruction does not reside in
		      the routine's context. No	stack space has	been allo-
		      cated.  NON_CONTEXT_STACK	-- This	instruction does
		      not reside in the	routine's context, but stack space
		      has been allocated.  CONTEXT_UNKNOWN -- This context
		      information is unavailable or invalid.
  InstFramePtrValid

		      Returns a	non-zero value if the register that is
		      being used as the	frame pointer is pointing to the
		      procedure's frame.
  InstStackPtrValid

		      Returns a	non-zero value if the register that is
		      being used as the	stack pointer is pointing to the
		      procedure's frame.
  InstRaRegValid

		      Returns a	non-zero value if the register that is
		      being used to save the return address contains the
		      return address.  (This is	used for procedures without
		      stack frames.)
  _________________________________________________________________________

  InstPC Routine


  Use the InstPC routine to obtain the compile-time program counter (PC) of
  the instruction.

  InstLineNo Routine


  Use the InstLineNo routine to	obtain the specified instruction's source
  line number.	Often, an Atom tool's instrumentation routine uses this
  information with the information returned by a call to the ProcFileName
  routine to obtain the	corresponding line in the source file.	A value	of 0
  (zero) is returned if	local symbol table information is not present.

  GetInstBinary	Routine


  Use the GetInstBinary	routine	to obtain a 32-bit binary representation of
  the assembly language	instruction.

  GetInstRegEnum Routine


  Use the GetInstRegEnum routine to obtain the register	type from an instruc-
  tion field (IInstInfoType). (See the description of AddCallProto in the
  atom_application_instrumentation(5) reference	page for a list	of register
  types.)  If the specified register is	not defined for	this instruction,
  GetInstRegEnum returns REG_NOTUSED.

  For example, if you supply an	argument of InstRA to GetInstRegEnum and the
  RA field of the instruction contains a 5, GetInstRegEnum returns REG_5 if
  the instruction is an	integer	instruction and	FREG_5 if it is	a floating-
  point	instruction.


  GetInstRegUsage Routine


  The GetInstRegUsage routine returns a	structure containing two vectors.
  The first vector is a	bitmask	with bits set for each register	read by	the
  instruction, and the second vector is	a bitmask with bits set	for each
  register stored by the instruction. Each vector is composed of two 64-bit
  integers:  the low 32	bits correspond	to the integer registers, the next 32
  bits correspond to the floating-point	registers, and the next	two bits
  refer	to the program counter (PC) and	the cycle counter, respectively.

  The format of	the InstRegUsageVec structure is as follows:

       typedef struct inst_reg_usage{
	  unsigned long	ureg_bitvec[2];
	  unsigned long	dreg_bitvec[2];
       } InstRegUsageVec;

  Consider the following example:

       InstRegUsageVec usageVec;
       Inst *inst = GetLastInst(GetFirstBlock(GetFirstProc()));
       GetInstRegUsage(inst,&usageVec);

  This small code fragment sets	inst to	point to the last instruction in the
  first	basic block in the first procedure. Assume the first instruction was

       ADDQ r0,r2,r7

  This instruction adds	of the contents	of register 0 to the contents of
  register 2 and places	the result in register 7. The value returned in
  usageVec.ureg_bitvec[0] is 0x5 because register 0 and	register 2 are both
  used.	 The value of usageVec.dreg_bitvec[0] is set to	0x40, indicating that
  register 7 is	set by the add instruction.

  One use of this primitive would be to	determine if the register loaded in
  one cycle is used in the next	cycle. In most pipelined processors, this
  results in a one cycle pipeline stall	(also known as a load/use conflict).
  The LoadUseConflict procedure	in the following example uses the GetInstRe-
  gUsage routine to detect such	conflicts:

	  1  int LoadUseConflict(Inst *instA,Inst *instB) {
	  2    int confict;
	  3    InstRegUsageVec vecA,vecB;
	  4    GetInstRegUsage(instA,&vecA);
	  5    GetInstRegUsage(instB,&vecB);
	  6    conflict	= (vecA.dreg_bitvec[0] & vecB.ureg_bitvec[0]) ||
	  7		   vecA.dreg_bitvec[1] & vecB.ureg_bitvec[1]);
	  8    return(IsInstType(instA,InstTypeLoad) &&	conflict);
	  9  }

  The arguments	are two	instructions, A	and B.	Line 3,	4, and 5 define	and
  set the bit usage bit	vectors	for the	two instructions. Lines	6 and 7	per-
  form a logical-AND operation on the destination vector of instruction	A
  with the usage vector	of instruction B. Line 8 returns TRUE if instruction
  A is a load instruction and a	load/use conflict was detected.	 In this
  example, LoadUseConflict would return	TRUE because register 1	is the desti-
  nation of the	LDQ instruction	and the	source for the ADDQ instruction.








RETURN VALUES

  These	routines return	the values 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)

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

  Functions: atom_application_instrumentation(5),
  atom_application_navigation(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