Generic inspection API
[INS: Instruction Object]

Typedefs
typedef UINT32	LEVEL_CORE::INS_PROP
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_IPF_LINUX,   LEVEL_CORE::SYSCALL_STANDARD_IA32_MAC,   LEVEL_CORE::SYSCALL_STANDARD_IA32E_BSD,   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_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_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)
BOOL	LEVEL_CORE::INS_IsDirectBranchOrCall (INS ins)
PIN_DEPRECATED_API BOOL	LEVEL_CORE::INS_IsRewritableMemOpBase (INS ins, MEMORY_TYPE mtype, REG &base)
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)
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 UINT32 LEVEL_CORE::INS_PROP

Generic INS_PROP

---

Enumeration Type Documentation

enum LEVEL_CORE::MEMORY_TYPE

Returns: true if this instruction has a memory op that can be rewritten Exclude memory accesses with ip or sp base, or absolute Exclude a write if has the same base register as a read

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_IPF_LINUX  Linux system call in IA-64 architecture. SYSCALL_STANDARD_IA32_MAC  MacOS system call in IA-32 architecture. SYSCALL_STANDARD_IA32E_BSD  FreeBSD system call on 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

CATEGORY LEVEL_CORE::INS_Category (  const INS  ins  )

Returns: Instruction category, Use CATEGORY_StringShort to make it a string

ADDRINT LEVEL_PINCLIENT::INS_DirectBranchOrCallTargetAddress (  INS  ins  )

Returns: For direct branches or calls, the target address

string LEVEL_CORE::INS_Disassemble (  INS  ins  )

Disassembly type listing 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  )

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: Used to indicate no instruction 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  )

x

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_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_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_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_IsRewritableMemOpBase (  INS  ins, MEMORY_TYPE  mtype, REG &  base )

Returns: true if this instruction has a memory op that can be rewritten. Exclude anything with implicit memory operations, but allow the string ops. Exclude a write if has the same base register as a read because we'll rewrite it when we do the read. Exclude some implicit stack operations (associated w/call,ret) as they cannot be rewritten. DEPRECATED you should replace the use of this function with INS_RewriteMemoryOperand, which has almost no limitations on the instructions which can be rewritten.

BOOL LEVEL_CORE::INS_IsStackRead (  const INS  ins  )

Returns: true if ins is a read from the stack

BOOL LEVEL_CORE::INS_IsStackWrite (  const INS  ins  )

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 (0, 1 or 2). 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 )

Is the nth memory operand read?

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

Is the nth memory operand written?

UINT32 LEVEL_CORE::INS_MemoryOperandSize (  INS  ins, UINT32  memOpIdx )

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

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

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

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. For the IA-64 architecture, it does not make sense to add the size to the address to get the next instruction so use this primitive for all architectures. Returns: Address of instruction that follows this one

OPCODE LEVEL_CORE::INS_Opcode (  INS  ins  )

Returns: Opcode of instruction, Use INS_Mnemonic if you want a string

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  ins, UINT32  n )

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  ins, UINT32  n )

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: True if x is not INS_Invalid() 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

---

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.

---