Generic inspection API
[INS: Instruction Object]

Typedefs
typedef PREDICATE_IA32	LEVEL_BASE::PREDICATE
Enumerations
enum	LEVEL_CORE::MEMORY_TYPE {   MEMORY_TYPE_READ,   MEMORY_TYPE_WRITE,   MEMORY_TYPE_READ2 }
enum	LEVEL_CORE::SYSCALL_STANDARD {   LEVEL_CORE::SYSCALL_STANDARD_INVALID,   LEVEL_CORE::SYSCALL_STANDARD_IA32_LINUX,   LEVEL_CORE::SYSCALL_STANDARD_IA32E_LINUX,   LEVEL_CORE::SYSCALL_STANDARD_IA32_MAC,   LEVEL_CORE::SYSCALL_STANDARD_IA32E_MAC,   LEVEL_CORE::SYSCALL_STANDARD_IA32_WINDOWS_FAST,   LEVEL_CORE::SYSCALL_STANDARD_IA32E_WINDOWS_FAST,   LEVEL_CORE::SYSCALL_STANDARD_IA32_WINDOWS_ALT,   LEVEL_CORE::SYSCALL_STANDARD_WOW64,   LEVEL_CORE::SYSCALL_STANDARD_WINDOWS_INT }
Functions
INT32	LEVEL_CORE::INS_Category (const INS ins)
INT32	LEVEL_CORE::INS_Extension (const INS ins)
USIZE	LEVEL_CORE::INS_MemoryOperandSize (INS ins, UINT32 memoryOp)
USIZE	LEVEL_CORE::INS_MemoryWriteSize (INS ins)
PREDICATE	LEVEL_CORE::INS_GetPredicate (INS ins)
USIZE	LEVEL_CORE::INS_MemoryReadSize (INS ins)
BOOL	LEVEL_CORE::INS_IsMemoryRead (INS ins)
BOOL	LEVEL_CORE::INS_IsMemoryWrite (INS ins)
BOOL	LEVEL_CORE::INS_HasMemoryRead2 (INS ins)
BOOL	LEVEL_CORE::INS_HasFallThrough (INS ins)
BOOL	LEVEL_CORE::INS_IsLea (INS ins)
BOOL	LEVEL_CORE::INS_IsNop (INS ins)
string	LEVEL_CORE::OPCODE_StringShort (UINT32 opcode)
string	LEVEL_CORE::INS_Mnemonic (INS ins)
BOOL	LEVEL_CORE::INS_IsBranch (INS ins)
BOOL	LEVEL_CORE::INS_IsDirectBranch (INS ins)
BOOL	LEVEL_CORE::INS_IsDirectCall (INS ins)
BOOL	LEVEL_CORE::INS_IsDirectBranchOrCall (INS ins)
BOOL	LEVEL_CORE::INS_IsBranchOrCall (INS ins)
BOOL	LEVEL_CORE::INS_Stutters (INS ins)
BOOL	LEVEL_CORE::INS_IsCall (INS ins)
BOOL	LEVEL_CORE::INS_IsProcedureCall (INS ins)
BOOL	LEVEL_CORE::INS_IsRet (INS ins)
BOOL	LEVEL_CORE::INS_IsSysret (INS ins)
BOOL	LEVEL_CORE::INS_IsPrefetch (INS ins)
BOOL	LEVEL_CORE::INS_IsAtomicUpdate (const INS ins)
BOOL	LEVEL_CORE::INS_IsIndirectBranchOrCall (INS ins)
REG	LEVEL_CORE::INS_RegR (INS x, UINT32 k)
REG	LEVEL_CORE::INS_RegW (INS x, UINT32 k)
OPCODE	LEVEL_CORE::INS_Opcode (INS ins)
string	LEVEL_CORE::CATEGORY_StringShort (UINT32 num)
string	LEVEL_CORE::EXTENSION_StringShort (UINT32 num)
UINT32	LEVEL_CORE::INS_MaxNumRRegs (INS x)
UINT32	LEVEL_CORE::INS_MaxNumWRegs (INS x)
BOOL	LEVEL_CORE::INS_RegRContain (const INS ins, const REG reg)
BOOL	LEVEL_CORE::INS_RegWContain (const INS ins, const REG reg)
BOOL	LEVEL_CORE::INS_IsStackRead (const INS ins)
BOOL	LEVEL_CORE::INS_IsStackWrite (const INS ins)
BOOL	LEVEL_CORE::INS_IsIpRelRead (const INS ins)
BOOL	LEVEL_CORE::INS_IsIpRelWrite (const INS ins)
BOOL	LEVEL_CORE::INS_IsPredicated (INS ins)
BOOL	LEVEL_CORE::INS_IsOriginal (INS ins)
string	LEVEL_CORE::INS_Disassemble (INS ins)
	XED (x86 encoder decoder) low-level support routines.This supports the other core_ia32 files and is the lowest level interface to XED encoding/decoding.*/namespace LEVEL_CORE
UINT32	LEVEL_CORE::INS_MemoryOperandCount (INS ins)
BOOL	LEVEL_CORE::INS_OperandIsAddressGenerator (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_MemoryOperandIsRead (INS ins, UINT32 memopIdx)
BOOL	LEVEL_CORE::INS_MemoryOperandIsWritten (INS ins, UINT32 memopIdx)
BOOL	LEVEL_CORE::INS_IsSyscall (INS ins)
SYSCALL_STANDARD	LEVEL_CORE::INS_SyscallStd (INS ins)
RTN	LEVEL_PINCLIENT::INS_Rtn (INS x)
INS	LEVEL_PINCLIENT::INS_Next (INS x)
INS	LEVEL_PINCLIENT::INS_Prev (INS x)
INS	LEVEL_PINCLIENT::INS_Invalid ()
BOOL	LEVEL_PINCLIENT::INS_Valid (INS x)
ADDRINT	LEVEL_PINCLIENT::INS_Address (INS ins)
USIZE	LEVEL_PINCLIENT::INS_Size (INS ins)
ADDRINT	LEVEL_PINCLIENT::INS_DirectBranchOrCallTargetAddress (INS ins)
ADDRINT	LEVEL_PINCLIENT::INS_NextAddress (INS ins)
Variables
GLOBALCONST PIN_DEPRECATED_API UINT32	LEVEL_CORE::VARIABLE_MEMORY_REFERENCE_SIZE = ~0U

---

Detailed Description

Use these functions to examine an instruction. They work for all instruction sets.

Availability:

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

---

Typedef Documentation

typedef PREDICATE_IA32 LEVEL_BASE::PREDICATE

Predication type in instructions, see PREDICATE_IA32.

---

Enumeration Type Documentation

enum LEVEL_CORE::MEMORY_TYPE

Memory type of argument

enum LEVEL_CORE::SYSCALL_STANDARD

Calling standard of the system call instruction. Enumerator: SYSCALL_STANDARD_INVALID  Invalid value; the instruction is not a system call. SYSCALL_STANDARD_IA32_LINUX  Linux system call on IA-32 architecture. SYSCALL_STANDARD_IA32E_LINUX  Linux system call on Intel(R) 64 architecture. SYSCALL_STANDARD_IA32_MAC  MacOS system call in IA-32 architecture. SYSCALL_STANDARD_IA32E_MAC  MacOS system call in Intel(R) 64 architecture. SYSCALL_STANDARD_IA32_WINDOWS_FAST  "Fast" (SYSENTER) Windows system call in IA-32 architecture SYSCALL_STANDARD_IA32E_WINDOWS_FAST  "Fast" (SYSCALL) Windows system call in Intel(R) 64 architecture SYSCALL_STANDARD_IA32_WINDOWS_ALT  Alternative (INT2E) Windows system call in IA-32 architecture. SYSCALL_STANDARD_WOW64  System call in WOW64 (32 bit process in 64-bit Windows). SYSCALL_STANDARD_WINDOWS_INT  Software interruption (INT n) in Windows.

---

Function Documentation

string LEVEL_CORE::CATEGORY_StringShort (  UINT32  num  )

Returns: String form of category

string LEVEL_CORE::EXTENSION_StringShort (  UINT32  num  )

Returns: String form of ISA extension

ADDRINT LEVEL_PINCLIENT::INS_Address (  INS  ins  )

Returns: Address of instruction Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

INT32 LEVEL_CORE::INS_Category (  const INS  ins  )

The category of an instruction is a higher level semantic description of an instruction than its opcode (INS_Opcode). So, for instance, you can test for a conditional branch by using INS_Category(ins) == XED_CATEGORY_COND_BR, whereas using INS_Opcode(ins) would require that you enumerate all twenty conditional branch opcodes. A category can be converted into a string by using CATEGORY_StringShort. Returns: Instruction category

ADDRINT LEVEL_PINCLIENT::INS_DirectBranchOrCallTargetAddress (  INS  ins  )

Returns: For direct branches or calls, the target address

string LEVEL_CORE::INS_Disassemble (  INS  ins  )

Returns: std::string disassembly of instruction

INT32 LEVEL_CORE::INS_Extension (  const INS  ins  )

Returns: Instruction extension, Use EXTENSION_StringShort to make it a string

PREDICATE LEVEL_CORE::INS_GetPredicate (  INS  ins  )

Returns: predicate for instruction (see PREDICATE) CMOVcc and FMOVcc instructions are treated as predicated. Rep string ops are treated as predicated.

BOOL LEVEL_CORE::INS_HasFallThrough (  INS  ins  )

If INS_HasFallThrough(INS) is TRUE, then the instruction may execute the "natural" next instruction (i.e. the one which starts immediately after this one), if it is FALSE, then the instruction following the one tested will not (normally) be executed next. So HasFallThrough is TRUE for instructions which don't change the control flow (most instructions), or for conditional branches (which might change the control flow, but might not), and FALSE for unconditional branches and calls (where the next instruction to be executed is always explicitly specified). Note that an unconditional branch or call to the next instruction still doesn't have a fall-through, since a fall through is the implicitly following instruction, and an unconditional branch never uses that. Returns: TRUE if the instruction type has a fallthrough path based on the opcode

BOOL LEVEL_CORE::INS_HasMemoryRead2 (  INS  ins  )

Returns: true if this instruction has 2 memory read operands

INS LEVEL_PINCLIENT::INS_Invalid (   )

Returns: Invalid instruction used in iterators INS_Prev and INS_Next Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

BOOL LEVEL_CORE::INS_IsAtomicUpdate (  const INS  ins  )

Returns: true if this instruction may do an atomic update of memory. On IA-32 architectures, this is xchg, or any instruction with the lock prefix set.

BOOL LEVEL_CORE::INS_IsBranch (  INS  ins  )

Returns: true if the ins is a branch instruction.

BOOL LEVEL_CORE::INS_IsBranchOrCall (  INS  ins  )

Returns: true if ins is a Branch or Call instruction, includes both direct and indirect instruction types

BOOL LEVEL_CORE::INS_IsCall (  INS  ins  )

Returns: true if ins is a Call instruction

BOOL LEVEL_CORE::INS_IsDirectBranch (  INS  ins  )

These are supposed to be near relative branches. Returns: true if the target address is an offset from the instruction pointer or is an immediate.

BOOL LEVEL_CORE::INS_IsDirectBranchOrCall (  INS  ins  )

These are supposed to be near relative branches. Returns: true if the target address is an offset from the instruction pointer or is an immediate.

BOOL LEVEL_CORE::INS_IsDirectCall (  INS  ins  )

These are supposed to be near relative branches. Returns: true if the target address is an offset from the instruction pointer or is an immediate.

BOOL LEVEL_CORE::INS_IsIndirectBranchOrCall (  INS  ins  )

Returns: true if the branch target comes from a register or memory

BOOL LEVEL_CORE::INS_IsIpRelRead (  const INS  ins  )

Is an IP-relative read

BOOL LEVEL_CORE::INS_IsIpRelWrite (  const INS  ins  )

Is an IP-relative write

BOOL LEVEL_CORE::INS_IsLea (  INS  ins  )

Returns: TRUE if the instruction is Lea.

BOOL LEVEL_CORE::INS_IsMemoryRead (  INS  ins  )

Returns: true if this instruction reads memory (Note that on some OSes instructions which read relative to gs or fs are treated as if they do not access memory...)

BOOL LEVEL_CORE::INS_IsMemoryWrite (  INS  ins  )

Returns: true if this instruction writes memory

BOOL LEVEL_CORE::INS_IsNop (  INS  ins  )

Returns: TRUE if the instruction is a nop.

BOOL LEVEL_CORE::INS_IsOriginal (  INS  ins  )

Returns: true if this is an original instruction

BOOL LEVEL_CORE::INS_IsPredicated (  INS  ins  )

We treat these instructions as predicated conditional move (CMOVcc) floating conditional move (FCMOVcc) rep string ops (since they don't execute if GCX==0)

BOOL LEVEL_CORE::INS_IsPrefetch (  INS  ins  )

Returns: true if this instruction is a prefetch

BOOL LEVEL_CORE::INS_IsProcedureCall (  INS  ins  )

Returns: true if ins is a procedure call. This filters out call instructions that are (ab)used for other purposes

BOOL LEVEL_CORE::INS_IsRet (  INS  ins  )

Returns: true if ins is a Return instruction

BOOL LEVEL_CORE::INS_IsStackRead (  const INS  ins  )

Access to the stack simply means that the instruction accesses memory relative to the stack pointer (ESP or RSP), or the frame pointer (EBP or RBP). In code compiled without a frame pointer (where EBP/RBP is used as a general register), this may give a misleading result. Returns: TRUE if ins is a read from the stack

BOOL LEVEL_CORE::INS_IsStackWrite (  const INS  ins  )

Detection of stack accesses is done in the same way as for INS_IsStackRead, so the same caveats apply here too. Returns: TRUE if ins is a write to the stack

BOOL LEVEL_CORE::INS_IsSyscall (  INS  ins  )

Returns: true if the instruction is a system call

BOOL LEVEL_CORE::INS_IsSysret (  INS  ins  )

Returns: true if ins is a System Return instruction

UINT32 LEVEL_CORE::INS_MaxNumRRegs (  INS  x  )

Returns: Maximum number of read operands

UINT32 LEVEL_CORE::INS_MaxNumWRegs (  INS  x  )

Returns: Maximum number of write operands

UINT32 LEVEL_CORE::INS_MemoryOperandCount (  INS  ins  )

Returns: the number of memory operands. On OSes where Pin is not virtualising the segment registers, accesses with segment register overrides (e.g. gs:4) are ignored. (This is in line with Pin's behavior elsewhere).

BOOL LEVEL_CORE::INS_MemoryOperandIsRead (  INS  ins, UINT32  memopIdx )

Returns: TRUE if memory operand memopIdx is read

BOOL LEVEL_CORE::INS_MemoryOperandIsWritten (  INS  ins, UINT32  memopIdx )

Returns: TRUE if memory operand memopIdx is written

USIZE LEVEL_CORE::INS_MemoryOperandSize (  INS  ins, UINT32  memoryOp )

Parameters: [in]  ins  the instruction. [in]  memoryOp  the memory operand index whose size is required. Returns: the size of the requested memory operand in bytes (for REPped instructions this is the size accessed in each iteration of the implicit loop).

USIZE LEVEL_CORE::INS_MemoryReadSize (  INS  ins  )

Returns: the size of the memory read in bytes (for REP prefixed instructions this is the size of the operand read on each iteration of the REP, so 1,2,4 or 8).

USIZE LEVEL_CORE::INS_MemoryWriteSize (  INS  ins  )

Returns: the size of the memory write in bytes (for REP prefixed instructions this is the size of the operand written on each iteration of the REP, so 1,2,4 or 8).

string LEVEL_CORE::INS_Mnemonic (  INS  ins  )

Only use this function if you really want a printable version of the instruction's opcode. If you are trying to test what the opcode of an instruction is, use INS_Opcode and compare it with one of the XED_ICLASS values, or use one of the INS_Is... calls such as INS_IsMov, rather than using this function and comparing a string. Generating and comparing strings is much slower than comparing small integer values! Returns: String form of mnemonic

INS LEVEL_PINCLIENT::INS_Next (  INS  x  )

Returns: Instruction that follows x, or INS_Invalid() if x is the last in the rtn or trace Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

ADDRINT LEVEL_PINCLIENT::INS_NextAddress (  INS  ins  )

Get the address of the next instruction. Returns: Address of instruction that follows this one

OPCODE LEVEL_CORE::INS_Opcode (  INS  ins  )

On ia-32 and Intel64 the opcodes are constants of the form XED_ICLASS_name. The full list of valid opcodes can be found in the idata.txt file in the XED distribution (which is distributed as part of the Pin kit), and the enum definitions are in the file "xed-iclass-enum.h". Use INS_Mnemonic if you want a string. Returns: Opcode of instruction

BOOL LEVEL_CORE::INS_OperandIsAddressGenerator (  INS  ins, UINT32  n )

Returns: true if this operand generates an address, but the address does not access memory (e.g. load effective address instruction)

INS LEVEL_PINCLIENT::INS_Prev (  INS  x  )

Returns: Instruction that precedes x, or INS_Invalid() if x is the first in the rtn or trace Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

REG LEVEL_CORE::INS_RegR (  INS  x, UINT32  k )

Returns: kth read register of instruction x, including implicit reads (e.g. stack pointer is read by push on IA-32 architectures)

BOOL LEVEL_CORE::INS_RegRContain (  const INS  ins, const REG  reg )

Returns: true if ins uses reg as a read operand

REG LEVEL_CORE::INS_RegW (  INS  x, UINT32  k )

Returns: kth write register of instruction x, including implicit writes (e.g. stack pointer is written by push on IA-32 architectures)

BOOL LEVEL_CORE::INS_RegWContain (  const INS  ins, const REG  reg )

Returns: true if ins uses reg as a write operand

RTN LEVEL_PINCLIENT::INS_Rtn (  INS  x  )

Returns: Routine that contains this instruction Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

USIZE LEVEL_PINCLIENT::INS_Size (  INS  ins  )

Returns: Size of instruction in bytes

BOOL LEVEL_CORE::INS_Stutters (  INS  ins  )

Returns: true if ins "stutters", so re-executes even though it is not a branch or call. REP prefixed string ops do this.

SYSCALL_STANDARD LEVEL_CORE::INS_SyscallStd (  INS  ins  )

Check to see if the given instruction is a system call and return corresponding calling standard. Returns: calling standard of the system call instruction or SYSCALL_STANDARD_INVALID if the instruction is not a system call.

BOOL LEVEL_PINCLIENT::INS_Valid (  INS  x  )

Returns: Invalid instruction used in iterators INS_Prev and INS_Next Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

string LEVEL_CORE::OPCODE_StringShort (  UINT32  opcode  )

Returns: String with the opcode of the instruction

XED (  x86 encoder  decoder  )

The stripe data structure for XED decoded instructions. The stripe data structure for caching information about encoded XED instructions. Determines if Intel(R) MPX instructions are enabled: 0 - the instructions decode as NOPs 1 - the instructions decode as Intel MPX instructions The stripe data structure for XED decoded instructions. The stripe data structure for XED encoded instructions. Returns: Returns original size of instruction in bytes Sets original size of instruction in bytes Returns: This provides the pointer to the decoded xed instruction. This provides the pointer to the decoded xed instruction operand values. mark that the instruction encoding in the cache is not valid Returns: This provides the pointer to the decoded xed instruction. Global version of INS_DirtyG(). Used for accessing the dirty bits from another file. Global version of INS_DirtyG(). Used for accessing the dirty bits from another file. Make the INS_EncodeSizeSet available for external use Global version of INS_EncodeSize(). Used for accessing the encode size from another file. Make the INS_EncodeBuffer available for external use Sets the ith read register. This function uses INS_get_pos_r on the same register, make sure to set it (using INS_set_pos_r) before calling this function. Sets the ith written register. This function uses INS_get_pos_w on the same register, make sure to set it (using INS_set_pos_w) before calling this function. Returns: Returns the ith read register Returns the ith written register x Returns: Returns role of ith written register Returns xed operand position of ith read register Returns xed operand position of ith written register If read is TRUE, returns the role of the ith read register, otherwise the ith written register If read is TRUE, returns the operand position of the ith read register, otherwise the ith written register If read is TRUE, gets the ith read register, otherwise the ith written register If read is TRUE, sets the ith read register, otherwise the ith written register Returns: Returns the number of registers read by this instruction Returns the number of registers written by this instruction Sets the number of registers read by this instruction Sets the number of registers written by this instruction x decode with XED! Then update the stripe Returns: a string for the encode request Reencode modified (previously-decoded) instruction with XED. Then decode with XED. Then update the stripe. Encode a new instruction with XED. Then decode with XED. Then update the stripe. encode a NOP with XED! decode with XED! Then update the stripe Returns: the PIN register name for a given XED register name nothing This function allows writing to the xed log from other source files. Returns: nothing Convert a XED xed_reg_enum_t register to a Pin REG type. Returns: a valid pin register, but never an invalid one. Asserts if there is no exact map. a valid pin register, but never an invalid one a valid pin register or REG_INVALID(). x x Returns: nothing Take the reg/role/pos arrays from the stripe and pack them back in to XED decoded instruction. Return the physical flags (DF, OF, SF, ZF, AF, PF, CF) that are written according to the xed decode info. Specify whether to return only the flags that are definitely (must) written Parameters: [in]  xedd  The xed decode info [in]  onlyDefinite  Specify TRUE if only the flags that are definitely written should be returned Returns: the FLAGS written according to the xed decode info, and the onlyDefinite specification Return the physical flags (DF, OF, SF, ZF, AF, PF, CF) that are read according to the xed decode info. Parameters: [in]  xedd  The xed decode info Returns: the FLAGS read according to the xed decode info nothing Fill in the reg/role/pos arrays in the stripe using information from the XED decoded instruction. Replace xedreg with pinreg in the flat regs Returns: foo Nothing cmov with equivalent test as jmp the condition tested by an instruction (should only be used on instructions which do test a condition). Nothing The encoded length in bytes, or 0 on invalid encodings. size of instruction Convert the specified XED error code into the corresponding EXCEPTION_CODE value. Note: the XED_ERROR_BUFFER_TOO_SHORT error is converted into EXCEPTCODE_ACCESS_FAULT. Decode an instruction and initialize the specified INS object. Parameters: [out]  ins  the instruction object to be initialized [in]  out]  address on input: address of the instruction to be decoded on output: address of the instruction immediately following the decoded one [in]  size  maximum size of the instruction to be decoded [out]  excCode  If return value is INSDECODE_EXCEPTION and excCode is not NULL, it receives an exception code telling why the instruction could not be decoded. Returns: An INSDECODE value telling whether an instruction was decoded.

---

Variable Documentation

GLOBALCONST PIN_DEPRECATED_API UINT32 LEVEL_CORE::VARIABLE_MEMORY_REFERENCE_SIZE = ~0U

DEPRECATED VARIABLE_MEMORY_REFERENCE_SIZE is no longer generated by Pin, so all code which used to test for it can (and should ) now be removed, since the definition of this symbol will disappear in a future Pin release. Pin now treats REP prefixed string ops as implicit loops, with the IPOINT_BEFORE and IPOINT_AFTER instrumentation called once for each iteration. That allows the IARG_MEMORY*_SIZE of the instruction to be that of the un-repped instruction (1,2,4 or 8 bytes), which can be determined at instrumentation time as with any other instruction. In most cases this significantly simplifies tools, which no longer have to special case unbounded memory accesses. To handle the case of zero iteration REP prefixed instructions (which used to dynamically generate a zero memory size, but which will now generate the statically determined size), REP prefixed instructions are treated as predicated, so you can use INS_InsertPredicatedCall, or IARG_EXECUTING to determine whether the instruction actually executes. Note that this is the same behavior as for CMOVcc instructions which can also have conditional memory accesses, but have never generated a zero memory size operand.

---