 |
Index for
Section 5 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
atom_application_query(5)
NAME
atom_application_query, GetProgInfo, GetObjInfo, GetObjName, GetObjOutName,
GetAnalName, GetObjInstArray, GetObjInstCount, GetErrantShlibName,
GetErrantShlibErr, GetProcInfo, ProcName, ProcFileName, ProcPC, ProcGP,
GetEntryInfo, EntryName, EntryPC, 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 <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 * );
const char *GetErrantShlibName(
int );
ShlibErrType GetErrantShlibErr(
int );
long GetProcInfo(
Proc *,
ProcInfoType );
const char *ProcName(
Proc * );
const char *ProcFileName(
Proc * );
long ProcPC(
Proc * );
long ProcGP(
Proc * );
long GetEntryInfo(
Entry *,
EntryInfoType );
const char *EntryName(
Entry * );
long EntryPC(
Entry * );
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.
ProgNumErrantShlibs
Returns the number of shared libraries that were
ignored due to processing problems.
______________________________________________________________________
Each object of a program is a self-contained program with the following
sections: text, uninitialized data, and initialized data. The text section
contains instructions. Initialized data includes data that must be
initialized to nonzero values, and uninitialized 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
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.
ObjNumberEntries
Returns the number of entries (main and
alternate) 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. 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.
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
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 nonshared.
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 file name 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.
GetErrantShlibName and GetErrantShlibErr Routines
Sometimes shared libraries cannot be instrumented and are ignored by Atom.
The names of these libraries are kept in a two-dimensional array in Atom.
The input parameter of GetErrantShlibName and GetErrantShlibErr is the
index of the array. The upper bound of the array can be found by using
GetProgInfo(ProgNumErrantShlibs). Use GetErrantShlibName to obtain the name
of the shared library that was unable to be processed. Use
GetErrantShlibErr to discover why the library was ignored. The following
ShlibErrType values indicate these problems:
______________________________________________________________
ShlibErrType Description
______________________________________________________________
SHLIB_NOTOPEN
Unable to open shared library;
ignored.
SHLIB_NOTFOUND
Unable to find shared library;
ignored.
SHLIB_STRIPPED Shared library is stripped; ignored.
SHLIB_CMRLC_VERSION
Relocation version number is
incorrect; ignored.
SHLIB_RELOC_NONE
Shared library has no relocation
records; ignored.
SHLIB_BADMAGIC
Shared library has unknown COFF
magic number; ignored.
SHLIB_NO_FINI_EXIT
Shared library must either define
_exit() or have .fini section;
ignored.
SHLIB_NO_INIT
Shared library must have .init
section, ignored.
SHLIB_NZMAGIC_AFTER_TIF
Shared library must not have section
immediately after .text/.init/.fini;
ignored.
SHLIB_VERSION
Unable to find matching version of
shared library; ignored.
______________________________________________________________
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.
ProcNumberEntries
Returns the number of entries (main and
alternate) in the procedure.
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 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
determine 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,
SYMRES_EXPORT_WEAK, SYMRES_EXTERN,
SYMRES_STATIC, and SYMRES_NONE.
ProcExceptionFrame
Returns a nonzero value if the procedure
includes a hardware exception context.
ProcHasAltEntries
Returns a nonzero value if the procedure has an
alternate entry.
ProcEntryLengthOffset
Returns the unsigned offset in longwords from
the entry address to the first instruction in
the procedure code segment following the
procedure prologue.
ProcSpSetOffset
Returns the unsigned offset in longwords from
the entry address of the procedure to the
instruction in the procedure prologue that
modifies the stack pointer.
________________________________________________________________________
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 and ProcGP Routines
Use the ProcPC routine to obtain the compile-time program counter (PC) of
the first instruction in the procedure.
Use the ProcGP routine to obtain the compile-time global pointer (GP) value
for the procedure. An appropriate GP value will be returned for any
procedure, even those that do not use the GP register ($gp).
GetEntryInfo Routine
Use the GetEntryInfo routine to obtain information about the specified
Entry. The following EntryInfoType values return the indicated information:
______________________________________________________________________
EntryInfoType Description
______________________________________________________________________
EntryIsRedundant
Returns a boolean value indicating whether this
entry point is redundant. All but one entry point
at the same address is a redundant entry point.
______________________________________________________________________
EntryName Routine
Use the EntryName routine to obtain the name of the specified Entry.
EntryPC Routine
Use the EntryPC routine to obtain the compile-time program counter (PC) of
the first instruction following the main or alternate entry point.
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
instruction
ClassFdivd
Floating-point double precision divide
instruction
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
procedure 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
allocated. 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.The input value is the address of the
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 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.
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)
Functions: atom_application_instrumentation(5),
atom_application_navigation(5), atom_application_symbols(5),
atom_description_file(5), atom_instrumentation_routines(5),
atom_object_management(5), AnalHeapBase(5), Thread(5), Xlate(5)
Programmer's Guide
|
Index for
Section 5 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|