Classes
struct	PIN_MEM_ACCESS_INFO

struct	PIN_MULTI_MEM_ACCESS_INFO

class	IMULTI_ELEMENT_OPERAND

union	PIN_MEM_TRANS_FLAGS

class	ISCATTERED_MEMORY_REWRITE

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_UINT64, 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_MULTI_ELEMENT_OPERAND, IARG_REWRITE_SCATTERED_MEMOP, 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_IARGLIST, IARG_FAST_ANALYSIS_CALL, IARG_MEMORYOP_EA, IARG_MEMORYOP_SIZE, IARG_MEMORYOP_MASKED_ON, IARG_TSC, IARG_FILE_NAME, IARG_LINE_NO, IARG_LAST }

enum	PIN_MEMOP_ENUM { PIN_MEMOP_LOAD, PIN_MEMOP_STORE }

enum	PIN_OP_ELEMENT_ACCESS { PIN_OP_ELEMENT_ACCESS_READ, PIN_OP_ELEMENT_ACCESS_WRITE, PIN_OP_ELEMENT_ACCESS_READWRITE }

Functions
VOID	IARGLIST_AddArguments (IARGLIST args,...)

IARGLIST	IARGLIST_Alloc ()

VOID	IARGLIST_Free (IARGLIST args)

Variables
const int	MAX_MULTI_MEMOPS = 16

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, IARG_REG_REFERENCE, IARG_CONST_CONTEXT and IARG_PARTIAL_CONTEXT is not supported in Probe mode.

Inlining Considerations

The IARG_CONTEXT, IARG_CONST_CONTEXT and IARG_PARTIAL_CONTEXT IARG_TYPE cannot be inlined. Using these CONTEXT IARG_TYPE will prevent the analysis routine from being inlined.

Macro Definition Documentation

◆ PIN_FAST_ANALYSIS_CALL

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

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

◆ IARGLIST

typedef IARGLIST_CLASS* IARGLIST

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

Enumeration Type Documentation

◆ CALL_ORDER

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.

◆ IARG_TYPE

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_UINT64	Type: UINT64. Constant (additional UINT64 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 registers. Value of a register (additional register arg required) REG: Register Object Basically, this cannot be used to retrieve the value of registers whose size is larger than ADDRINT (e.g. x87 FPU/XMM/YMM/ZMM/opmask) or registers which are not architectural (REG_PIN_*), but there are some exceptions to this rule.
IARG_REG_REFERENCE	Type: UINT8*. Pointer to buffer holding the content of the requested register. buffer size is the size of the requested register. Register is specified in additional argument. Register is updated back to the relevant application register (Meaning if you change values in the mentioned pointer they will be propagated to the relevant application register). If you're not interested in modifying the register value, but only read its value use IARG_REG_CONST_REFERENCE instead. Not supported in Probe mode or with the Buffering APIs. Note additional REG arg required!!! PIN_REGISTER is now deprecated. If the requested register is a tile register and AMX is in init state (i.e., not active) - a NULL pointer will be passed to the analysis routine as the reference argument.
IARG_REG_CONST_REFERENCE	Type: UINT8*. Pointer to buffer holding the content of the requested register. buffer size is the size of the requested register. Register is specified in additional argument. Registers are not updated back to the relevant application register (Meaning if you change values in the mentioned pointer they will not be propagated to the relevant application register). If you're interested in modifying the register value, use IARG_REG_REFERENCE instead. Not supported with the Buffering APIs. Note additional REG arg required!!! PIN_REGISTER is now deprecated. If the requested register is a tile register and AMX is in init state (i.e., not active) - a NULL pointer will be passed to the analysis routine as the reference argument.
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. This IARG is applicable for all instructions for which INS_hasKnownMemorySize returns TRUE. For other instructions e.g. vgather/vscatter see IARG_MULTI_ELEMENT_OPERAND. For the varying memory size read instruction, XRSTOR, the size is based on the XSAVE area header. If the header indicates compact mode it will provide the compact size. Otherwise it will provide the standard size. The minimum size for the XRSTOR instruction (not including FXRSTOR) is 576 (i.e the XSAVE area size up to and including the header).
IARG_MEMORYWRITE_SIZE	Type: UINT32. Size in bytes of memory write. This IARG is applicable for all instructions for which INS_hasKnownMemorySize returns TRUE. For other instructions e.g. vgather/vscatter see IARG_MULTI_ELEMENT_OPERAND. For varying size memory write instructions, the supported instructions are the XSAVE family of instructions. For XSAVE, the size of the XSAVE area used is based on user request and supported features in the machine. This will provide the exact size used. For XSAVEOPT, the size is calculated the same as if XSAVE was used. This may provide in some cases an upper bound to the actual used memory. For XSAVEC, in IPOINT_BEFORE the size is calculated based on user request only. This may provide in some cases an upper bound to the actual size. If used in IPOINT_AFTER it will provide the exact compact size as defined in the XSAVE area header. The minimum size for the XSAVE family write instructions (not including FXSAVE) is 576 (i.e the XSAVE area size up to and including the header).
IARG_MEMORYREAD_PTR	Actual address of the memory access; same as IARG_MEMORYREAD_EA, unless the memory address is translated by MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by INS_RewriteMemoryOperand
IARG_MEMORYREAD2_PTR	Actual address of the memory access; same as IARG_MEMORYREAD2_EA, unless the memory address is translated by MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by INS_RewriteMemoryOperand
IARG_MEMORYWRITE_PTR	Actual address of the memory access. Same as IARG_MEMORYWRITE_EA, unless the memory address is translated by MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by INS_RewriteMemoryOperand
IARG_MEMORYOP_PTR	Actual address of the memory access. Same as IARG_MEMORYOP_EA, unless the memory address is translated by MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by INS_RewriteMemoryOperand. When using INS_RewriteMemoryOperand the value is valid only with IPOINT_AFTER.
IARG_MULTI_MEMORYACCESS_EA	Type: PIN_MULTI_MEM_ACCESS_INFO* the addresses read by the various vgather* instructions, Also available for regular memory instructions
IARG_MULTI_ELEMENT_OPERAND	Type: IMULTI_ELEMENT_OPERAND * . Information about a multi element operand (implemented for IPOINT_BEFORE). The operand index is required as the next argument.
IARG_REWRITE_SCATTERED_MEMOP	Type: ISCATTERED_MEMORY_REWRITE * . Interface that allows rewriting elemenets addresses for instructions with scattered memory access (implemented for IPOINT_BEFORE). Only valid for instructions where INS_IsValidForIarg for this IARG returns TRUE.
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. Argument is invalid for XBEGIN and XEND instructions.
IARG_BRANCH_TARGET_ADDR	Type: ADDRINT. Target address of branch instruction. In case of INS instrumentation, valid when INS_IsControlFlow() is true. However, this argument is invalid if the instruction is XBEGIN or XEND. In Linux, for the case of branching into the vsyscall area (in kernel 5.3 or above), the target address that will be received in the analysis routine would be that of the vsyscall area. Note that this address is not readable (e.g. via PIN_SafeCopy() and PIN_FetchCode())
IARG_FALLTHROUGH_ADDR	Type: ADDRINT. Fall through address of the instrumented object. In case of INS instrumentation, valid only if INS_HasFallThrough() is true.
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. Note In case count register is 0 when calling analysis routine, the value of IARG_FIRST_REP_ITERATION is 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 PROTO API.
IARG_THREAD_ID	Type: THREADID. Application thread id.
IARG_CONTEXT	Type: Context manipulation API *. 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 manipulation API. 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 manipulation API . Like IARG_CONTEXT, but tool receives a read-only Context manipulation API. PIN_SetContextReg, PIN_SetContextRegval 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 manipulation API* and only read from it should use IARG_CONST_CONTEXT. Tools that need a Context manipulation API* and only occasionally write into it should also use IARG_CONST_CONTEXT. One example of a tool that needs a Context manipulation API * and only occasionally writes into it, would be an emulator that would need to write into the Context manipulation API * only when an exception occurs, and then raise an exception with the Context manipulation API . PIN_SaveContext can be used by the tool to get a writable copy of the Context manipulation API . IARG_CONST_CONTEXT is available only in Jit mode.
IARG_PARTIAL_CONTEXT	Type: Context manipulation API . Additional two REGSET arguments are needed 'inSet' and 'outSet'. Like IARG_CONTEXT, but tool needs to define also which registers set it needs to read (inSet) and which registers set it may write (outSet). PIN_SetContextReg, PIN_SetContextRegval and PIN_SetContextFPState will work only on registers that are in the outSet. These functions will change the actual application registers so there is no need to perform PIN_ExecuteAt as need to be done with IARG_CONTEXT. PIN_GetContextReg, PIN_GetContextRegval and PIN_GetContextFPState will return unexpected values for registers not defined in the 'inSet'. The overhead of IARG_PARTIAL_CONTEXT may lower than that of IARG_CONTEXT as there is no need to perform PIN_ExecuteAt to update registers. Tools that know which application registers are needed to be read should use IARG_PARTIAL_CONTEXT instead of IARG_CONST_CONTEXT. Thus may reduce the overhead as not fully updated context for read need to be provided. Tools that know which application registers are needed to be written other than REG_INST_PTR should use IARG_PARTIAL_CONTEXT instead of combination of IARG_CONTEXT and the use of PIN_ExecuteAt for registers update. If REG_INST_PTR needs to be updated PIN_ExecuteAt still needs to be used. Any updates to a register from the outSet of an IARG_PARTIAL_CONTEXT will be propagated to the application upon return from the analysis routine. Tools that want to update Context manipulation API registers without affecting application registers should use IARG_CONTEXT. IARG_PARTIAL_CONTEXT is available only in Jit 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 XMM 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_*) functions defined under REG: Register Object 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_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_MEMORYOP_EA	Type: ADDRINT. Effective address of a memory op (memory op index is next arg); only valid at IPOINT_BEFORE.
IARG_MEMORYOP_SIZE	Type: UINT32. Size of a memory op (memory op index is next arg)
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.

◆ IPOINT

enum IPOINT

Determines where the analysis call is inserted relative to the instrumented object. Instrumented object can be: INS, BBL, TRACE, RTN. This is used in instrumentation functions, for example see TRACE_InsertCall().

Enumerator
IPOINT_BEFORE	Insert a call before the first instruction of the instrumented object. Always valid.
IPOINT_AFTER	Insert a call on the fall-through path of the last instruction of the instrumented object (if such fall-through exists). In case of a routine (RTN), instruments all return paths. Always valid. In case of an instruction (INS), valid only if INS_IsValidForIpointAfter() is true. In case of a BBL, valid only if BBL_HasFallThrough() is true. In case of a TRACE, valid only if TRACE_HasFallThrough() is true.
IPOINT_ANYWHERE	Insert a call anywhere inside the instrumented object. Valid on all instrumentation functions except INS_InsertIfCall(), INS_InsertThenCall().
IPOINT_TAKEN_BRANCH	Insert a call on the taken edge of control-flow instructions of the instrumented object. In case of an instruction, Valid only if INS_IsValidForIpointTakenBranch() is true.

◆ PIN_MEMOP_ENUM

enum PIN_MEMOP_ENUM

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

◆ PIN_OP_ELEMENT_ACCESS

enum PIN_OP_ELEMENT_ACCESS

Element Access type used in IMULTI_ELEMENT_OPERAND

Function Documentation

◆ IARGLIST_AddArguments()

VOID IARGLIST_AddArguments	(	IARGLIST	args,
			...
	)

Add an argument to an IARGLIST.

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

◆ IARGLIST_Alloc()

IARGLIST 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

◆ IARGLIST_Free()

VOID 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

Classes

Macros

Typedefs

Enumerations

Functions

Variables