Content-type: text/html
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
#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 *
);
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.
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.
Use the GetProgInfo routine to obtain the number of objects in a program. The only accepted ProgInfo value is ProgNumberObjects.
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.
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 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 instructions 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.
|
ObjModifyHint |
Returns a Boolean value indicating whether
the user requested that the object be instrumented or not. A user indicates
which objects are or are not to be instrumented by specifying the
-all,
-incobj, or
-excobj
flags on
the
atom
command line. The
ObjModifyHint
type returns the value
OBJ_READONLY
if the user did not
ask for the object to be instrumented or
OBJ_WRITEABLE
if the user asked for the object to be instrumented. Certain tools can use
this hint to decide whether to exclude particular objects from instrumentation.
Although an Atom tool can disregard these flag settings and instrument objects
as it sees fit, it typically honors the user's requests.
|
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.
|
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.
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.
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
procedure.
|
ProcNumberInsts |
Returns the number of instructions in the
procedure.
|
ProcID |
Returns a unique numeric identifier for the
procedure. This identifier is unique across all shared libraries and can thus
be used to create per-procedure data structures.
|
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 determine if the procedure is a potential target of an indirect
procedure call.
|
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.
|
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.
Use the
ProcPC
routine to obtain the compile-time
program counter (PC) of the first instruction in the procedure.
Use the GetBlockInfo routine to obtain information about the pecified 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.
|
Use the
BlockPC
routine to obtain the compile-time
program counter (PC) of the first instruction in the basic block.
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.
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 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 instruction
|
ClassFdivd |
Floating-point double precision divide instruction
|
ClassNull |
call pal
instruction,
hw_x
instruction, etc
|
ClassMem | Miscellaneous instructions which access memory |
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 |
InstTypeCondBr |
Integer or floating-point conditional branch
instruction
|
InstTypeUncondBr |
Integer or floating-point unconditional branch
instruction, but not a subroutine call
|
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 procedure entry point and zero (0) if it is not.
|
Use the
InstPC
routine to obtain the compile-time
program counter (PC) of the instruction.
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.
Use the
GetInstBinary
routine to obtain a 32-bit
binary representation of the assembly language instruction.
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.
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 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.
These routines return the values described in the preceding section.
Header file containing external definitions of Atom routines
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