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_IA32_WINDOWS_FAST,   LEVEL_CORE::SYSCALL_STANDARD_IA32E_WINDOWS_FAST,   LEVEL_CORE::SYSCALL_STANDARD_IA32_WINDOWS_ALT,   LEVEL_CORE::SYSCALL_STANDARD_WINDOWS_INT }
Functions
INT32	LEVEL_CORE::INS_Category (const INS ins)
INT32	LEVEL_CORE::INS_Extension (const INS ins)
UINT32	LEVEL_CORE::INS_EffectiveAddressWidth (INS ins)
USIZE	LEVEL_CORE::INS_MemoryWriteSize (INS ins)
USIZE	LEVEL_CORE::INS_MemoryWriteSizeWithoutPrefix (INS ins)
USIZE	LEVEL_CORE::INS_MemoryReadSize (INS ins)
USIZE	LEVEL_CORE::INS_MemoryReadSizeWithoutPrefix (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_IsSysenter (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_IsPcMaterialization (INS ins)
BOOL	LEVEL_CORE::INS_IsCall (INS ins)
BOOL	LEVEL_CORE::INS_IsFarCall (INS ins)
BOOL	LEVEL_CORE::INS_IsFarJump (INS ins)
BOOL	LEVEL_CORE::INS_IsDirectFarJump (INS ins)
VOID	LEVEL_CORE::INS_GetFarPointer (INS ins, UINT16 &segment_selector, UINT32 &displacement)
BOOL	LEVEL_CORE::INS_IsProcedureCall (INS ins)
BOOL	LEVEL_CORE::INS_IsInterrupt (INS ins)
BOOL	LEVEL_CORE::INS_IsRet (INS ins)
BOOL	LEVEL_CORE::INS_IsFarRet (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)
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_FullRegRContain (const INS ins, const REG reg)
BOOL	LEVEL_CORE::INS_FullRegWContain (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)
PREDICATE	LEVEL_CORE::INS_GetPredicate (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_OperandCount (INS ins)
BOOL	LEVEL_CORE::INS_OperandIsMemory (INS ins, UINT32 n)
REG	LEVEL_CORE::INS_OperandMemoryBaseReg (INS ins, UINT32 n)
REG	LEVEL_CORE::INS_OperandMemoryIndexReg (INS ins, UINT32 n)
REG	LEVEL_CORE::INS_OperandMemorySegmentReg (INS ins, UINT32 n)
UINT32	LEVEL_CORE::INS_OperandMemoryScale (INS ins, UINT32 n)
INT64	LEVEL_CORE::INS_OperandMemoryDisplacement (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsFixedMemop (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsAddressGenerator (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsBranchDisplacement (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsReg (INS ins, UINT32 n)
REG	LEVEL_CORE::INS_OperandReg (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsImmediate (INS ins, UINT32 n)
UINT64	LEVEL_CORE::INS_OperandImmediate (INS ins, UINT32 n)
BOOL	LEVEL_CORE::INS_OperandIsImplicit (INS ins, UINT32 n)
UINT32	LEVEL_CORE::INS_OperandWidth (INS ins, UINT32 n)
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 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_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, WOW64) Windows system call. 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

UINT32 LEVEL_CORE::INS_EffectiveAddressWidth (  INS  ins  )

Returns: the width of the effective address in bits

INT32 LEVEL_CORE::INS_Extension (  const INS  ins  )

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

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

Returns: true if ins uses reg as a read operand

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

Returns: true if ins uses reg as a write operand

VOID LEVEL_CORE::INS_GetFarPointer (  INS  ins, UINT16 &  segment_selector, UINT32 &  displacement )

Returns: the segment selector and displacement from a direct far jump.

PREDICATE LEVEL_CORE::INS_GetPredicate (  INS  ins  )

Returns: predicate for instruction

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_IsDirectFarJump (  INS  ins  )

Returns: true if the target address is a direct far jump

BOOL LEVEL_CORE::INS_IsFarCall (  INS  ins  )

Returns: true if ins is a Far Call instruction

BOOL LEVEL_CORE::INS_IsFarJump (  INS  ins  )

Returns: true if ins is a Far Jump instruction

BOOL LEVEL_CORE::INS_IsFarRet (  INS  ins  )

Returns: true if ins is a far ret instruction

BOOL LEVEL_CORE::INS_IsIndirectBranchOrCall (  INS  ins  )

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

BOOL LEVEL_CORE::INS_IsInterrupt (  INS  ins  )

Return TRUE if the INS is an interrupt category instruction

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

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_IsPcMaterialization (  INS  ins  )

Returns: true if this is a call to the next instruction, which is an idiom for materializing the instruction pointer

BOOL LEVEL_CORE::INS_IsPredicated (  INS  ins  )

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.

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_IsSysenter (  INS  ins  )

Returns: true if the instruction is a SysEnter

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_MemoryReadSize (  INS  ins  )

Returns: the size of the memory read in bytes or VARIABLE_MEMORY_REFERENCE_SIZE if the size is determined at runtime (e.g. movs on IA-32 ISA)

USIZE LEVEL_CORE::INS_MemoryReadSizeWithoutPrefix (  INS  ins  )

Returns: Size of memory read in bytes, ignorning any repeat prefix

UINT32 LEVEL_CORE::INS_MemoryWriteSize (  INS  ins  )

Returns: the size of the memory write in bytes or VARIABLE_MEMORY_REFERENCE_SIZE if the size is determined at runtime (e.g. movs on IA-32 ISA)

USIZE LEVEL_CORE::INS_MemoryWriteSizeWithoutPrefix (  INS  ins  )

Returns: Size of memory written in bytes, ignorning any repeat prefix

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

UINT32 LEVEL_CORE::INS_OperandCount (  INS  ins  )

Tells the number of operands for the instruction. Several other APIs take an operand index as a parameter. Those APIs expect an index in the range [0, n-1], where n is the value returned by INS_OperandCount(). Parameters: [in]  ins  The instruction. Returns: The number of operands for the instruction.

UINT64 LEVEL_CORE::INS_OperandImmediate (  INS  ins, UINT32  n )

Returns: immediate value for operand

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)

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

Returns: true if this operand is a displacement (e.g. branch offset)

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

Returns: TRUE if memory operand uses predefined base register and this register can not be changed Example: movs ds:(esi), es:(edi) There are two fixed operands

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

Returns: true if this operand is an immediate

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

Returns: true if this operand is implied by the opcode (e.g. the stack write in a push instruction)

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

Returns: true if this operand is a memory reference Note: this does not include LEA operands.

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

Returns: true if this operand is a register

REG LEVEL_CORE::INS_OperandMemoryBaseReg (  INS  ins, UINT32  n )

Returns: register used as base register in memory operand, or REG_INVALID() Effective address = Displacement + BaseReg + IndexReg * Scale

INT64 LEVEL_CORE::INS_OperandMemoryDisplacement (  INS  ins, UINT32  n )

Returns: displacement used in memory operand. Effective address = Displacement + BaseReg + IndexReg * Scale

REG LEVEL_CORE::INS_OperandMemoryIndexReg (  INS  ins, UINT32  n )

Returns: register used as index register in memory operand, or REG_INVALID() Effective address = Displacement + BaseReg + IndexReg * Scale

UINT32 LEVEL_CORE::INS_OperandMemoryScale (  INS  ins, UINT32  n )

Returns: scale used for addressing in memory operand. Effective address = Displacement + BaseReg + IndexReg * Scale

REG LEVEL_CORE::INS_OperandMemorySegmentReg (  INS  ins, UINT32  n )

Returns: register used as segment register in memory operand, or REG_INVALID()

REG LEVEL_CORE::INS_OperandReg (  INS  ins, UINT32  n )

Returns: register name for this operand, may return REG_INVALID()

UINT32 LEVEL_CORE::INS_OperandWidth (  INS  ins, UINT32  n )

Returns: operand width in bits.

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

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 UINT32 LEVEL_CORE::VARIABLE_MEMORY_REFERENCE_SIZE = ~0U

Value returned by INS_MemoryReadSize or INS_MemoryWriteSize when the instruction reads/writes a variable size area of memory. (e.g. stos on x86). Use IARG_MEMORYREAD_SIZE/IARG_MEMORYWRITE_SIZE to determine the value

---