atom_application_query(5) File Formats Manual 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, GetInst-
Binary, GetInstRegEnum, GetInstRegUsage - Allows an Atom-tool instrumentation routine to obtain information about the parts of an applica-
tion program
SYNOPSIS
#include <cmplrs/atom.inst.h>
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, unitialized, and data sections. The text section contains instructions.
Initialized 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 informa-
tion:
----------------------------------------------------------------------
ObjInfoType Description
----------------------------------------------------------------------
ObjTextStartAddress Returns the starting compile-time address
of the object's text segment.
When instrumenting a nonshared executable
or the main executable of call-shared
programs, the compile-time address is
identical to the run-time address. For
shared libraries, the compiler 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 instruc-
tions returned is not usually equal to
the value returned by ObjTextSize divided
by the instruction size (4 bytes). The
compiler aligns procedures on 16-byte
boundaries by padding them on both sides
with NOP instructions. 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 application
program. It is in the range zero to Get-
ProgInfo(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 instru-
mented, but Atom had to instrument the
library to support options such as -fork
or -pthread, then the value OBJ_AUTOMATIC
will be returned. Otherwise, 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. Certain tools can use this
hint to decide whether to exclude partic-
ular 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 infor-
mation:
-----------------------------------------------------------------------
ProcInfoType Description
-----------------------------------------------------------------------
ProcFrameSize Returns the size of the fixed portion of the pro-
cedure'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 reg-
ister 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 vari-
ables 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 proce-
dure.
ProcNumberInsts Returns the number of instructions in the proce-
dure.
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
unavailable.
ProcLineHigh Returns the highest source line in the procedure,
or zero (0) if source line information is
unavailable. This value and the value returned
by ProcLineLow are useful for determining 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 contains
an interprocedural branch or interprocedural
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, SYM-
RES_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 program.
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
information:
------------------------------------------------------------------------
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 assembly
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 proce-
dure entry point and zero (0) if it is not.
InstIPJmp Returns a nonzero value if the instruction is an inter-
procedural jump.
InstIPBr Returns a nonzero value if the instruction is an inter-
procedural 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 han-
dling 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 allocated. NON_CONTEXT_STACK
-- This instruction does not reside in the routine's
context, but stack space has been allocated. CON-
TEXT_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 proce-
dure's frame.
InstStackPtrValid Returns a non-zero value if the register that is being
used as the stack pointer is pointing to the proce-
dure'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 instruction 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 proces-
sors, this results in a one cycle pipeline stall (also known as a load/use conflict). The LoadUseConflict procedure in the following exam-
ple uses the GetInstRegUsage 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 perform 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 destination of the LDQ instruction and the source for the ADDQ instruction.
RETURN VALUES
These routines return the values described in the preceding section.
FILES
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
atom_application_query(5)