Content-type: text/html Man page of atom_application_query

atom_application_query

Section: File Formats (5)
Index Return to Main Contents
 

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 <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. 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.
 

GetObjInfo Routine

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


ObjInfoTypeDescription

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.


 

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:


ProcInfoTypeDescription

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.


 

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 pecified Block. The following BlockInfoType values return the indicated information:


BlockInfoTypeDescription

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:


IClassTypeDescription

ClassLoadInteger load instruction
ClassFloadFloating-point load instruction
ClassStoreInteger store data instruction
ClassFstoreFloating-point store data instruction
ClassIbranchInteger branch instruction
ClassFbranchFloating-point branch instruction
ClassSubroutineInteger subroutine call instruction
ClassIarithmeticInteger arithmetic instruction
ClassImultiplylInteger longword multiply instruction
ClassImultiplyqInteger quadword multiply instruction
ClassIlogicalLogical function instruction
ClassIshiftShift function instruction
ClassIcondmoveConditional move instruction
ClassIcompareInteger compare instruction
ClassFpopOther 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
ClassMemMiscellaneous 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.


ITypeTypeDescription

InstTypeLoadInteger or floating-point load instruction
InstTypeStoreInteger or floating-point store instruction
InstTypeMemAny instruction that accesses memory
InstTypeJumpJump, jump to subroutine, or return instruction
InstTypeFPAny floating-point instruction
InstTypeIntAny integer or nonfloating-point instruction
InstTypeDivSingle or double precision divide instruction
InstTypeMulInteger or floating-point multiply instruction
InstTypeAddInteger or floating-point add instruction
InstTypeSubInteger 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


 

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:


InstInfoTypeDescription

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.
InstOpcodeReturns 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.


 

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 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

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


 

Index

NAME
SYNOPSIS
DESCRIPTION
GetAnalName Routine
GetProgInfo Routine
GetObjInfo Routine
GetObjName and GetObjOutName Routines
GetObjInstArray and GetObjInstCount Routines
GetProcInfo Routine
ProcName and ProcFileName Routines
ProcPC Routine
GetBlockInfo Routine
BlockPC Routine
IsBranchTarget Routine
GetInstClass Routine
IsInstType Routine
GetInstInfo Routine
InstPC Routine
InstLineNo Routine
GetInstBinary Routine
GetInstRegEnum Routine
GetInstRegUsage Routine
RETURN VALUES
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:43:09 GMT, October 02, 2010