Pin
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Classes | Macros | Typedefs | Enumerations | Functions | Variables
Instrumentation arguments

Classes

struct  PIN_MEM_ACCESS_INFO
 
struct  PIN_MULTI_MEM_ACCESS_INFO
 
union  PIN_MEM_TRANS_FLAGS
 

Macros

#define PIN_FAST_ANALYSIS_CALL
 

Typedefs

typedef IARGLIST_CLASS * IARGLIST
 

Enumerations

enum  IPOINT {
  IPOINT_INVALID,
  IPOINT_BEFORE,
  IPOINT_AFTER,
  IPOINT_ANYWHERE,
  IPOINT_TAKEN_BRANCH
}
 
enum  CALL_ORDER {
  CALL_ORDER_FIRST = 100,
  CALL_ORDER_DEFAULT = 200,
  CALL_ORDER_LAST = 300
}
 
enum  IARG_TYPE {
  IARG_INVALID,
  IARG_ADDRINT,
  IARG_PTR,
  IARG_BOOL,
  IARG_UINT32,
  IARG_INST_PTR,
  IARG_REG_VALUE,
  IARG_REG_REFERENCE,
  IARG_REG_CONST_REFERENCE,
  IARG_MEMORYREAD_EA,
  IARG_MEMORYREAD2_EA,
  IARG_MEMORYWRITE_EA,
  IARG_MEMORYREAD_SIZE,
  IARG_MEMORYWRITE_SIZE,
  IARG_MEMORYREAD_PTR,
  IARG_MEMORYREAD2_PTR,
  IARG_MEMORYWRITE_PTR,
  IARG_MEMORYOP_PTR,
  IARG_MULTI_MEMORYACCESS_EA,
  IARG_EXPLICIT_MEMORY_EA,
  IARG_BRANCH_TAKEN,
  IARG_BRANCH_TARGET_ADDR,
  IARG_FALLTHROUGH_ADDR,
  IARG_EXECUTING,
  IARG_FIRST_REP_ITERATION,
  IARG_PREDICATE,
  IARG_STACK_VALUE,
  IARG_STACK_REFERENCE,
  IARG_MEMORY_VALUE,
  IARG_MEMORY_REFERENCE,
  IARG_SYSCALL_NUMBER,
  IARG_SYSARG_REFERENCE,
  IARG_SYSARG_VALUE,
  IARG_SYSRET_VALUE,
  IARG_SYSRET_ERRNO,
  IARG_FUNCARG_CALLSITE_REFERENCE,
  IARG_FUNCARG_CALLSITE_VALUE,
  IARG_FUNCARG_ENTRYPOINT_REFERENCE,
  IARG_FUNCARG_ENTRYPOINT_VALUE,
  IARG_FUNCRET_EXITPOINT_REFERENCE,
  IARG_FUNCRET_EXITPOINT_VALUE,
  IARG_RETURN_IP,
  IARG_ORIG_FUNCPTR,
  IARG_PROTOTYPE,
  IARG_THREAD_ID,
  IARG_CONTEXT,
  IARG_CONST_CONTEXT,
  IARG_PARTIAL_CONTEXT,
  IARG_PRESERVE,
  IARG_RETURN_REGS,
  IARG_CALL_ORDER,
  IARG_REG_NAT_VALUE,
  IARG_REG_OUTPUT_FRAME_VALUE,
  IARG_REG_OUTPUT_FRAME_REFERENCE,
  IARG_IARGLIST,
  IARG_FAST_ANALYSIS_CALL,
  IARG_SYSCALL_ARG0,
  IARG_SYSCALL_ARGBASE = IARG_SYSCALL_ARG0,
  IARG_SYSCALL_ARG1,
  IARG_SYSCALL_ARG2,
  IARG_SYSCALL_ARG3,
  IARG_SYSCALL_ARG4,
  IARG_SYSCALL_ARG5,
  IARG_SYSCALL_ARGLAST = IARG_SYSCALL_ARG5,
  IARG_G_RESULT0,
  IARG_G_RETBASE = IARG_G_RESULT0,
  IARG_G_RESULTLAST = IARG_G_RESULT0,
  IARG_G_ARG0_CALLEE,
  IARG_G_ARGBASE_CALLEE = IARG_G_ARG0_CALLEE,
  IARG_G_ARG1_CALLEE,
  IARG_G_ARG2_CALLEE,
  IARG_G_ARG3_CALLEE,
  IARG_G_ARG4_CALLEE,
  IARG_G_ARG5_CALLEE,
  IARG_G_ARGLAST_CALLEE = IARG_G_ARG5_CALLEE,
  IARG_G_ARG0_CALLER,
  IARG_G_ARGBASE_CALLER = IARG_G_ARG0_CALLER,
  IARG_G_ARG1_CALLER,
  IARG_G_ARG2_CALLER,
  IARG_G_ARG3_CALLER,
  IARG_G_ARG4_CALLER,
  IARG_G_ARG5_CALLER,
  IARG_G_ARGLAST_CALLER = IARG_G_ARG5_CALLER,
  IARG_MEMORYOP_EA,
  IARG_MEMORYOP_MASKED_ON,
  IARG_TSC,
  IARG_FILE_NAME,
  IARG_LINE_NO,
  IARG_LAST
}
 
enum  PIN_MEMOP_ENUM {
  PIN_MEMOP_LOAD,
  PIN_MEMOP_STORE
}
 

Functions

VOID LEVEL_PINCLIENT::IARGLIST_AddArguments (IARGLIST args,...)
 
IARGLIST LEVEL_PINCLIENT::IARGLIST_Alloc ()
 
VOID LEVEL_PINCLIENT::IARGLIST_Free (IARGLIST args)
 

Variables

GLOBALCONST int MAX_MULTI_MEMOPS = 8
 

Detailed Description

See INS_InsertCall.

IARG_END

All argument lists must end with IARG_END. Please see the Examples for further information.

Probe Mode Considerations

When IARG_CONTEXT is used in probe mode,it is impossible to get certain register values correct. The values in these registers are meaningless when IARG_CONTEXT is used in probe mode:

REG_SEG_GS_BASE
REG_SEG_FS_BASE
REG_INST_G0 - REG_INST_G19
Using IARG_RETURN_REGS and IARG_REG_REFERENCE is not supported in Probe mode.

Inlining Considerations

The IARG_CONTEXT IARG_TYPE cannot be inlined. Using these IARG_CONTEXT will prevent the analysis routine from being inlined.

Macro Definition Documentation

#define PIN_FAST_ANALYSIS_CALL

Use a faster linkage for calls to analysis functions. Add PIN_FAST_ANALYSIS_CALL to the declaration between the return type and the function name. You must also add IARG_FAST_ANALYSIS_CALL to the InsertCall. For example:

VOID PIN_FAST_ANALYSIS_CALL docount(int j);

INS_InsertCall(ins, IPOINT_BEFORE, AFUNPTR(docount), IARG_FAST_ANALYSIS_CALL, IARG_UINT32, 3, IARG_END);

You will gain the most benefit from using PIN_FAST_ANALYSIS_CALL if

  • you are instrumenting a 32 bit process (the 64 bit calling conventions already pass arguments in registers)
  • your analysis routine is not inlined (if it is inlined there is no call to optimize)
  • your analysis routine is relatively small (if it is large the extra overhead imposed by the poor calling convention won't be significant anyway)

Typedef Documentation

typedef IARGLIST_CLASS* IARGLIST

List of IARG_TYPE elements. See IARGLIST_Alloc() for its use.

Enumeration Type Documentation

enum CALL_ORDER

Predefined values for IARG_CALL_ORDER. Controls the order of analysis call invocations when an instruction has multiple analysis calls. CALL_ORDER_DEFAULT is the default call order when IARG_CALL_ORDER is not specified. You can use integral values relative to the predefined values to have a fine-grained control over the instrumentation order (e.g., CALL_ORDER_DEFAULT + 5, CALL_ORDER_LAST - 10, etc).

Pin guarantees that multiple analysis calls with the same CALL_ORDER on the same instruction, added in the context of the same instrumentation callback (e.g,. INS_INSTRUMENT_CALLBACK), will be invoked according to their insertion order. For all other cases, the invocation order for analysis calls with the same CALL_ORDER on the same instruction depends on the implementation and may change without notice.

Enumerator
CALL_ORDER_FIRST 

Execute this call first. Value is 100.

CALL_ORDER_DEFAULT 

Default when IARG_CALL_ORDER is not specified. Value is 200.

CALL_ORDER_LAST 

Execute this call last. Value is 300.

enum IARG_TYPE

Determines the arguments that are passed to the analysis call. All argument lists must end with IARG_END.

Enumerator
IARG_ADDRINT 

Type: ADDRINT. Constant value (additional arg required)

IARG_PTR 

Type: "VOID *". Constant value (additional pointer arg required)

IARG_BOOL 

Type: BOOL. Constant (additional BOOL arg required)

IARG_UINT32 

Type: UINT32. Constant (additional integer arg required)

IARG_INST_PTR 

Type: ADDRINT. The address of the instrumented instruction. This value does not change at IPOINT_AFTER. This is simply shorthand for IARG_ADDRINT, INS_Address(ins).

IARG_REG_VALUE 

Type: ADDRINT for integer register. Value of a register (additional register arg required) REG: Register Object.

IARG_REG_REFERENCE 

Type: "@ref PIN_REGISTER *". Pointer to union holding register contents. Registers are updated. Not supported in Probe mode or with the Buffering APIs.

IARG_REG_CONST_REFERENCE 

Type: "@ref PIN_REGISTER *". Pointer to union holding register contents. Registers are not updated. Not supported with the Buffering APIs.

IARG_MEMORYREAD_EA 

Type: ADDRINT. Effective address of a memory read, only valid if INS_IsMemoryRead is true and at IPOINT_BEFORE.

IARG_MEMORYREAD2_EA 

Type: ADDRINT. Effective address of a 2nd memory read (e.g. 2nd operand in cmps on ia32), only valid at IPOINT_BEFORE.

IARG_MEMORYWRITE_EA 

Type: ADDRINT. Effective address of a memory write, only valid at IPOINT_BEFORE.

IARG_MEMORYREAD_SIZE 

Type: UINT32. Size in bytes of memory read.

IARG_MEMORYWRITE_SIZE 

Type: UINT32. Size in bytes of memory write.

IARG_MEMORYREAD_PTR 

Same as IARG_MEMORYREAD_EA, but allows registering a MEMORY_ADDR_TRANS_CALLBACK.

IARG_MEMORYREAD2_PTR 

Same as IARG_MEMORYREAD2_EA, but allows registering a MEMORY_ADDR_TRANS_CALLBACK.

IARG_MEMORYWRITE_PTR 

Same as IARG_MEMORYWRITE_EA, but allows registering a MEMORY_ADDR_TRANS_CALLBACK.

IARG_MEMORYOP_PTR 

Same as IARG_MEMORYOP_EA, but allows registering a MEMORY_ADDR_TRANS_CALLBACK.

IARG_MULTI_MEMORYACCESS_EA 

Type: PIN_MULTI_MEM_ACCESS_INFO* the addresses read by the various vgather* instructions.

IARG_EXPLICIT_MEMORY_EA 

Type: ADDRINT. Effective address of the explicit memory operand. Useful for instrumenting LEA instructions.

IARG_BRANCH_TAKEN 

Type: BOOL. Non zero if a branch is taken.

IARG_BRANCH_TARGET_ADDR 

Type: ADDRINT. Target address of this branch instruction, only valid if INS_IsBranchOrCall is true.

IARG_FALLTHROUGH_ADDR 

Type: ADDRINT. Fall through address of this instruction.

IARG_EXECUTING 

Type: BOOL. False if the instruction will not be executed because of predication, otherwise true.

IARG_FIRST_REP_ITERATION 

Type: BOOL. True if INS_HasRealRep(ins) and this the first iteration of the REP sequence, otherwise false.

IARG_PREDICATE 

Reserved. Do not use.

IARG_STACK_VALUE 

Reserved. Do not use.

IARG_STACK_REFERENCE 

Reserved. Do not use.

IARG_MEMORY_VALUE 

Reserved. IA32(e) only.

IARG_MEMORY_REFERENCE 

Reserved. IA32(e) only.

IARG_SYSCALL_NUMBER 

Type: ADDRINT. System call number. Valid for IPOINT_BEFORE at the system call instruction.

IARG_SYSARG_REFERENCE 

Type: "ADDRINT *". Pointer to system call argument n. Valid for IPOINT_BEFORE at the system call instruction. (First argument number is 0.)

IARG_SYSARG_VALUE 

Type: ADDRINT. System call argument n. Valid for IPOINT_BEFORE at the system call instruction. (First argument number is 0.)

IARG_SYSRET_VALUE 

Type: ADDRINT. System call return value. On Linux and MacOS the value is -1 if the system call failed. (IPOINT_AFTER only)

IARG_SYSRET_ERRNO 

Type: INT32. System call errno (IPOINT_AFTER_only).

IARG_FUNCARG_CALLSITE_REFERENCE 

Type: "ADDRINT *". Pointer to integer argument n. Valid only at the call site. (First argument number is 0.)

IARG_FUNCARG_CALLSITE_VALUE 

Type: ADDRINT. Integer argument n. Valid only at the call site. (First argument number is 0.)

IARG_FUNCARG_ENTRYPOINT_REFERENCE 

Type: "ADDRINT *". Pointer to integer argument n. Valid only at the entry point of a routine. (First argument number is 0.)

IARG_FUNCARG_ENTRYPOINT_VALUE 

Type: ADDRINT. Integer argument n. Valid only at the entry point of a routine. (First argument number is 0.)

IARG_FUNCRET_EXITPOINT_REFERENCE 

Type: "ADDRINT *". Pointer to function result. Valid only at return instruction.

IARG_FUNCRET_EXITPOINT_VALUE 

Type: ADDRINT. Function result. Valid only at return instruction.

IARG_RETURN_IP 

Type: ADDRINT. Return address for function call, valid only at the function entry point.

IARG_ORIG_FUNCPTR 

Type: AFUNPTR. Function pointer to the relocated entry of the original uninstrumented function.

IARG_PROTOTYPE 

Type: PROTO. The function prototype of the application function. See Prototypes.

IARG_THREAD_ID 

Type: THREADID. Application thread id.

IARG_CONTEXT 

Type: "CONTEXT *". Handle to access a context (architectural state). When passed at IPOINT_AFTER or IPOINT_TAKEN_BRANCH, PC points to the next instruction. Upon return from the analysis routine, Pin ignores any changes you've made to the CONTEXT. If you want to change register values, use IARG_REG_REFERENCE, IARG_RETURN_REGS, or PIN_ExecuteAt(). See Probe Mode Considerations for probe mode restrictions. Not supported with the Buffering APIs.

IARG_CONST_CONTEXT 

Type: "CONTEXT *". Like IARG_CONTEXT, but tool receives a read-only CONTEXT*. PIN_SetContextReg and PIN_SetContextFPState will not work with IARG_CONST_CONTEXT. The overhead of IARG_CONST_CONTEXT is considerably lower than that of IARG_CONTEXT. Tools that need a CONTEXT* and only read from it should use IARG_CONST_CONTEXT. Tools that need a CONTEXT* and only occasionally write into it should also use IARG_CONST_CONTEXT. One example of a tool that needs a CONTEXT* and only occasionally writes into it, would be an emulator that would need to write into the CONTEXT* only when an exception occurs, and then raise an exception with the CONTEXT*. PIN_SaveContext can be used by the tool to get a writable copy of the CONTEXT*. IARG_CONST_CONTEXT is available only in Jit mode, and is silently deprecated to IARG_CONTEXT in probe mode

IARG_PRESERVE 

Type: "REGSET *". Used to specify registers whose values will be the same upon return from the analysis routine. Should be used to specify caller-saved registers which are preserved by the analysis routine. When a non-inlinable analysis routine preserves caller-saved registers, Pin can avoid generating code to preserve these registers, across the analysis call, if they are specified in the IARG_PRESERVE. e.g. if a non-inlinable analysis routine preserves the values in the x87 registers, then Pin can avoid generating code to preserve these registers, across the analysis call, if REG_X87 is specified in the IARG_PRESERVE e.g. if a non-inlinable analysis routine preserves the values in XMM caller saved registers, then Pin can avoid generating code to preserve these registers, across the analysis call, if those preserved XXM registers are specified in the IARG_PRESERVE IARG_PRESERVE must be followed by a REGSET* that points to the REGSET containing the registers preserved. See the REGSET_* macros defined under REG (specific to the IA-32 and Intel(R) 64 architectures) for REGSET construction and manipulation.

IARG_RETURN_REGS 

Register to write analysis function return value (additional register arg required). Not supported in Probe mode.

IARG_CALL_ORDER 

Type: CALL_ORDER. Determine order of analysis calls. See CALL_ORDER.

IARG_REG_NAT_VALUE 

Type: BOOL. Nat value of register. Ipf only.

IARG_REG_OUTPUT_FRAME_VALUE 

Type: ADDRINT for integer registers. Like IARG_REG_VALUE, but use index into RSE output frame instead of register name. IA64 only.

IARG_REG_OUTPUT_FRAME_REFERENCE 

Type: "ADDRINT *". Like IARG_REG_REFERENCE, but use index into RSE output frame instead of register name. IA64 only.

IARG_IARGLIST 

Type: IARGLIST. List of IARGS which can be constructed one IARG at a time.

IARG_FAST_ANALYSIS_CALL 

No type: Use a fast linkage to call the analysis function. See PIN_FAST_ANALYSIS_CALL.

IARG_SYSCALL_ARG0 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_SYSCALL_ARG1 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_SYSCALL_ARG2 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_SYSCALL_ARG3 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_SYSCALL_ARG4 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_SYSCALL_ARG5 

DEPRECATED, see IARG_SYSARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_RESULT0 

DEPRECATED, see IARG_SYSRET_{VALUE,REFERENCE}.

IARG_G_ARG0_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG1_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG2_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG3_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG4_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG5_CALLEE 

DEPRECATED, see IARG_FUNCARG_CALLSITE_{VALUE,REFERENCE}.

IARG_G_ARG0_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_G_ARG1_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_G_ARG2_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_G_ARG3_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_G_ARG4_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_G_ARG5_CALLER 

DEPRECATED, see IARG_FUNCARG_ENTRYPOINT_{VALUE,REFERENCE}.

IARG_MEMORYOP_EA 

Type: ADDRINT. Effective address of a memory op (memory op index is next arg); only valid at IPOINT_BEFORE.

IARG_MEMORYOP_MASKED_ON 

Type: BOOL. TRUE if the this memory op (memory op index is next arg) is masked on; only valid at IPOINT_BEFORE.

IARG_TSC 

Type: UINT64. Time Stamp Counter value at the point of entering the analysis call.

IARG_FILE_NAME 

Reserved for internal use only.

IARG_LINE_NO 

Reserved for internal use only.

IARG_LAST 

Reserved for internal use only.

enum IPOINT

Determines where the analysis call is inserted relative to the instrumented object

Enumerator
IPOINT_BEFORE 

Insert a call before an instruction or routine.

IPOINT_AFTER 

Insert a call on the fall through path of an instruction or return path of a routine.

IPOINT_ANYWHERE 

Insert a call anywhere inside a trace or a bbl.

IPOINT_TAKEN_BRANCH 

Insert a call on the taken edge of branch, the side effects of the branch are visible.

used in the Type whose address is passed to analysis routine when IARG_MULTI_MEMORYACCESS_EA is requested

Function Documentation

VOID LEVEL_PINCLIENT::IARGLIST_AddArguments ( IARGLIST  args,
  ... 
)

Add an argument to an IARGLIST.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
IARGLIST LEVEL_PINCLIENT::IARGLIST_Alloc ( )

Allocate a container to hold instrumentation arguments. Pass to *_InsertCall by using IARG_LIST

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All
VOID LEVEL_PINCLIENT::IARGLIST_Free ( IARGLIST  args)

Free a container to hold instrumentation arguments. Pass to *_InsertCall by using IARG_LIST

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All