|
|
atom_application_query(5)
Contents
|
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
#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 * );
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 callshared
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 callshared,
sharable (.so), or nonshared.
Valid return values are OBJ_CALL_SHARED,
OBJ_SHARABLE, and OBJ_NON_SHARED.
---------------------------------------------------------------------
GetObjName and GetObjOutName Routines [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 section; ignored.
SHLIB_NO_INIT Shared library must have section,
ignored.
SHLIB_NZMAGIC_AFTER_TIF Shared library must not have section
immediately after
SHLIB_VERSION Unable to find matching version of
shared library; ignored.
---------------------------------------------------------------
GetProcInfo Routine [Toc] [Back]
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 floatingpoint
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
Use the EntryName routine to obtain the name of the specified
Entry.
EntryPC Routine [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
Use the BlockPC routine to obtain the compile-time program
counter (PC) of the first instruction in the basic block.
IsBranchTarget Routine [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
Use the InstPC routine to obtain the compile-time program
counter (PC) of the instruction.
InstLineNo Routine [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 floatingpoint
instruction.
GetInstRegUsage Routine [Toc] [Back]
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)
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
atom_application_query(5)
[ Back ] |
