/*! * Type: ADDRINT. The address of the instrumented instruction. This value does not change at IPOINT_AFTER. * This is simply shorthand for <tt>IARG_ADDRINT, INS_Address(ins)</tt>. */ IARG_INST_PTR,
/*! * Type: ADDRINT for integer registers. Value of a register (additional register arg required) @ref REG * 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_VALUE,
/*! * Type: @ref 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!!! * @note 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_REFERENCE,
/*! * Type: @ref 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!!! * @note 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,
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 /*! * Type: UINT32. Size in bytes of memory read. * This IARG is applicable for all instructions for which @ref INS_hasKnownMemorySize returns TRUE. * For other instructions e.g. vgather/vscatter see @ref 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_MEMORYREAD_SIZE, /*! * Type: UINT32. Size in bytes of memory write. * This IARG is applicable for all instructions for which @ref INS_hasKnownMemorySize returns TRUE. * For other instructions e.g. vgather/vscatter see @ref 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_MEMORYWRITE_SIZE,
// IARG_MEMORY*_PTR argument represents actual address of the memory access, even if the operand is rewritten // or a memory translation callback is registered /*! * Actual address of the memory access; same as @ref IARG_MEMORYREAD_EA, unless the memory address is translated * by @ref MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by @ref INS_RewriteMemoryOperand */ IARG_MEMORYREAD_PTR, /*! * Actual address of the memory access; same as @ref IARG_MEMORYREAD2_EA, unless the memory address is translated * by @ref MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by @ref INS_RewriteMemoryOperand */ IARG_MEMORYREAD2_PTR, /*! * Actual address of the memory access. Same as @ref IARG_MEMORYWRITE_EA, unless the memory address is translated * by @ref MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by @ref INS_RewriteMemoryOperand */ IARG_MEMORYWRITE_PTR, /*! * Actual address of the memory access. Same as @ref IARG_MEMORYOP_EA, unless the memory address is translated * by @ref MEMORY_ADDR_TRANS_CALLBACK, or the memory operand is rewritten by @ref INS_RewriteMemoryOperand. \n * When using @ref INS_RewriteMemoryOperand the value is valid only with IPOINT_AFTER. */ IARG_MEMORYOP_PTR,
/*! * Type: PIN_MULTI_MEM_ACCESS_INFO* the addresses read by the various vgather* instructions, * Also available for regular memory instructions */ IARG_MULTI_MEMORYACCESS_EA, /*! * Type: @ref IMULTI_ELEMENT_OPERAND * . Information about a multi element operand (implemented for IPOINT_BEFORE). * The operand index is required as the next argument. */ IARG_MULTI_ELEMENT_OPERAND,
/*! * Type: @ref ISCATTERED_MEMORY_REWRITE * . Interface that allows rewriting elemenets addresses for instructions * with scattered memory access (implemented for IPOINT_BEFORE). * Only valid for instructions where @ref INS_IsValidForIarg for this IARG returns TRUE. */ IARG_REWRITE_SCATTERED_MEMOP,
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. /*! Type: ADDRINT. Target address of branch instruction.\n * In case of INS instrumentation, valid when @ref INS_IsControlFlow() is true.\n * 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_BRANCH_TARGET_ADDR, /*! Type: ADDRINT. Fall through address of the instrumented object.\n * In case of INS instrumentation, valid only if @ref INS_HasFallThrough() is true. */ IARG_FALLTHROUGH_ADDR,
IARG_EXECUTING, ///< Type: BOOL. False if the instruction will not be executed because of predication, otherwise true.
/*! Type: BOOL. True if INS_HasRealRep(ins) and this the first iteration of the REP sequence, otherwise false.\n * @note In case count register is 0 when calling analysis routine, the value of IARG_FIRST_REP_ITERATION is false. */ IARG_FIRST_REP_ITERATION, IARG_PREDICATE, ///< Reserved. Do not use
// These are internal only 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
// Syscall stuff 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).
// function arguments /*! * Type: "ADDRINT *". Pointer to integer argument n. Valid only at the call site. (First argument number is 0.) */ IARG_FUNCARG_CALLSITE_REFERENCE, /*! * Type: ADDRINT. Integer argument n. Valid only at the call site. (First argument number is 0.) */ IARG_FUNCARG_CALLSITE_VALUE, /*! * Type: "ADDRINT *". Pointer to integer argument n. Valid only at the entry point of a routine. (First argument number is 0.) */ IARG_FUNCARG_ENTRYPOINT_REFERENCE, /*! * Type: ADDRINT. Integer argument n. Valid only at the entry point of a routine. (First argument number is 0.) */ IARG_FUNCARG_ENTRYPOINT_VALUE, 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 @ref PROTO
/*! * Type: @ref CONTEXT *. Handle to access a context (architectural state). When passed at * @ref IPOINT_AFTER or @ref IPOINT_TAKEN_BRANCH, PC points to the next instruction. Upon return from * the analysis routine, Pin ignores any changes you've made to the @ref CONTEXT. If you want * to change register values, use @ref IARG_REG_REFERENCE, @ref IARG_RETURN_REGS, or @ref PIN_ExecuteAt. * See @ref PROBE_IARGS for probe mode restrictions. Not supported with the Buffering APIs. */ IARG_CONTEXT, /*! * Type: @ref CONTEXT *. * Like @ref IARG_CONTEXT, but tool receives a read-only @ref CONTEXT*. * @ref PIN_SetContextReg, @ref PIN_SetContextRegval and @ref PIN_SetContextFPState will not work with * @ref IARG_CONST_CONTEXT. * The overhead of @ref IARG_CONST_CONTEXT is considerably lower than that of @ref IARG_CONTEXT. * Tools that need a @ref CONTEXT* and only read from it should use @ref IARG_CONST_CONTEXT. * Tools that need a @ref CONTEXT* and only occasionally write into it should also use @ref IARG_CONST_CONTEXT (by * using PIN_SaveContext() - see below). * One example of a tool that needs a @ref CONTEXT * and only occasionally writes into it, would be an * emulator that would need to write into the @ref CONTEXT * only when an exception occurs, and then * raise an exception with the @ref CONTEXT *. * @ref PIN_SaveContext can be used by the tool to get a writable copy of the @ref CONTEXT *. * @ref IARG_CONST_CONTEXT is available only in Jit mode. */ IARG_CONST_CONTEXT, /*! * Type: @ref CONTEXT *. Additional two @ref REGSET * arguments are needed 'inSet' and 'outSet'. * Like @ref IARG_CONTEXT, but tool needs to define also which registers set it needs to read (inSet) * and which registers set it may write (outSet). * @ref PIN_SetContextReg, @ref PIN_SetContextRegval and @ref 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 @ref PIN_ExecuteAt as need to be done with @ref IARG_CONTEXT. * @ref PIN_GetContextReg, @ref PIN_GetContextRegval and @ref PIN_GetContextFPState will return unexpected values * for registers not defined in the 'inSet'. * The overhead of @ref IARG_PARTIAL_CONTEXT may lower than that of @ref IARG_CONTEXT as there is no need to perform * @ref PIN_ExecuteAt to update registers. * Tools that know which application registers are needed to be read should use @ref IARG_PARTIAL_CONTEXT instead of * @ref 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 @ref REG_INST_PTR should use * @ref IARG_PARTIAL_CONTEXT instead of combination of @ref IARG_CONTEXT and the use of @ref PIN_ExecuteAt * for registers update. * If @ref REG_INST_PTR needs to be updated @ref PIN_ExecuteAt still needs to be used. * Any updates to a register from the outSet of an @ref IARG_PARTIAL_CONTEXT will be propagated to the application upon * return from the analysis routine. Tools that want to update @ref CONTEXT registers without affecting application * registers should use @ref IARG_CONTEXT. * @ref IARG_PARTIAL_CONTEXT is available only in Jit mode. */ IARG_PARTIAL_CONTEXT,
/*! * Type: @ref 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 @ref 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 @ref IARG_PRESERVE * @ref IARG_PRESERVE must be followed by a @ref REGSET* that points to the @ref REGSET containing the registers preserved. * See the @ref REGSET_AddAll "(REGSET_*)" functions defined under @ref REG for @ref REGSET construction and manipulation. */ IARG_PRESERVE,
/*! Type: BOOL. * Used to mark analysis routine that is expected to be inlined. * If the analysis ruotine is not inlinable and -assert_check_inline has been passed then Pin will assert. */ IARG_CHECK_INLINE,
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 @ref 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 @ref PIN_FAST_ANALYSIS_CALL
/*! * Type: @ref REGSET *. * The only supported register for now is REG_MXCSR. In case it is not included into the register set * then an error is issued. * . Upon entry to the analysis routine, the MXCSR physical register value is loaded with the application value. * . Upon termination of the routine the physical MXCSR register including the changes are visible by * the application. * . As a side effect, the analysis routine will never be inlined. * @ref IARG_EXPOSE must be followed by a @ref REGSET* that points to the @ref REGSET containing the registers * exposed, REG_MXCSR must be included and be the only one. */ IARG_EXPOSE,
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.
