Pin
Enumerations | Functions | Variables
Inspection API for IA-32 and Intel(R) 64 instructions

Enumerations

enum  PREDICATE {
  PREDICATE_ALWAYS_TRUE,
  PREDICATE_INVALID,
  PREDICATE_BELOW,
  PREDICATE_BELOW_OR_EQUAL,
  PREDICATE_LESS,
  PREDICATE_LESS_OR_EQUAL,
  PREDICATE_NOT_BELOW,
  PREDICATE_NOT_BELOW_OR_EQUAL,
  PREDICATE_NOT_LESS,
  PREDICATE_NOT_LESS_OR_EQUAL,
  PREDICATE_NOT_OVERFLOW,
  PREDICATE_NOT_PARITY,
  PREDICATE_NOT_SIGN,
  PREDICATE_NOT_ZERO,
  PREDICATE_OVERFLOW,
  PREDICATE_PARITY,
  PREDICATE_SIGN,
  PREDICATE_ZERO,
  PREDICATE_CX_NON_ZERO,
  PREDICATE_ECX_NON_ZERO,
  PREDICATE_RCX_NON_ZERO,
  PREDICATE_SAVED_GCX_NON_ZERO,
  PREDICATE_LAST
}
 
enum  MEMORY_TYPE {
  MEMORY_TYPE_READ,
  MEMORY_TYPE_WRITE,
  MEMORY_TYPE_READ2
}
 
enum  SYSCALL_STANDARD {
  SYSCALL_STANDARD_INVALID,
  SYSCALL_STANDARD_IA32_LINUX,
  SYSCALL_STANDARD_IA32_LINUX_SYSENTER,
  SYSCALL_STANDARD_IA32E_LINUX,
  SYSCALL_STANDARD_IA32E_LINUX_VSYSCALL,
  SYSCALL_STANDARD_IA32_MAC,
  SYSCALL_STANDARD_IA32E_MAC,
  SYSCALL_STANDARD_IA32_WINDOWS_FAST,
  SYSCALL_STANDARD_IA32E_WINDOWS_FAST,
  SYSCALL_STANDARD_IA32_WINDOWS_ALT,
  SYSCALL_STANDARD_WOW64,
  SYSCALL_STANDARD_WINDOWS_INT
}
 

Functions

BOOL INS_HasRealRep (INS ins)
 
BOOL INS_IsStandardMemop (INS ins)
 
BOOL INS_IsCacheLineFlush (INS ins)
 
INT32 INS_Category (const INS ins)
 
INT32 INS_Extension (const INS ins)
 
UINT32 INS_EffectiveAddressWidth (INS ins)
 
USIZE INS_MemoryOperandSize (INS ins, UINT32 memoryOp)
 
USIZE INS_MemoryOperandElementSize (INS ins, UINT32 memoryOp)
 
PIN_DEPRECATED_API USIZE INS_MemoryWriteSize (INS ins)
 
PIN_DEPRECATED_API USIZE INS_MemoryReadSize (INS ins)
 
PREDICATE INS_GetPredicate (INS ins)
 
BOOL INS_IsMemoryRead (INS ins)
 
BOOL INS_IsMemoryWrite (INS ins)
 
BOOL INS_HasMemoryRead2 (INS ins)
 
BOOL INS_HasFallThrough (INS ins)
 
BOOL INS_IsSysenter (INS ins)
 
BOOL INS_IsXbegin (INS ins)
 
BOOL INS_IsXend (INS ins)
 
BOOL INS_IsLea (INS ins)
 
BOOL INS_IsNop (INS ins)
 
std::string OPCODE_StringShort (UINT32 opcode)
 
std::string INS_Mnemonic (INS ins)
 
BOOL INS_IsBranch (INS ins)
 
BOOL INS_IsDirectBranch (INS ins)
 
BOOL INS_IsDirectCall (INS ins)
 
PIN_DEPRECATED_API BOOL INS_IsDirectBranchOrCall (INS ins)
 
BOOL INS_IsDirectControlFlow (INS ins)
 
BOOL INS_IsHalt (INS ins)
 
PIN_DEPRECATED_API BOOL INS_IsBranchOrCall (INS ins)
 
BOOL INS_Stutters (INS ins)
 
BOOL INS_IsPcMaterialization (INS ins)
 
BOOL INS_IsCall (INS ins)
 
BOOL INS_IsControlFlow (INS ins)
 
BOOL INS_IsFarCall (INS ins)
 
BOOL INS_IsFarJump (INS ins)
 
BOOL INS_IsDirectFarJump (INS ins)
 
BOOL INS_IsValidForIpointAfter (INS ins)
 
BOOL INS_IsValidForIpointTakenBranch (INS ins)
 
BOOL INS_IsVgather (INS ins)
 
BOOL INS_IsVscatter (INS ins)
 
BOOL INS_HasMemoryVector (INS ins)
 
BOOL INS_HasScatteredMemoryAccess (INS ins)
 
BOOL INS_IsAmx (INS ins)
 
VOID INS_GetFarPointer (INS ins, UINT16 &segment_selector, UINT32 &displacement)
 
BOOL INS_IsProcedureCall (INS ins)
 
BOOL INS_IsInterrupt (INS ins)
 
BOOL INS_IsRet (INS ins)
 
BOOL INS_IsSysret (INS ins)
 
BOOL INS_IsFarRet (INS ins)
 
BOOL INS_IsPrefetch (INS ins)
 
BOOL INS_IsSub (const INS ins)
 
BOOL INS_IsMov (const INS ins)
 
BOOL INS_IsMovFullRegRegSame (const INS ins)
 
BOOL INS_IsAtomicUpdate (const INS ins)
 
BOOL INS_IsRDTSC (const INS ins)
 
BOOL INS_IsMaskMov (const INS ins)
 
REG INS_RepCountRegister (INS ins)
 
PIN_DEPRECATED_API BOOL INS_IsIndirectBranchOrCall (INS ins)
 
BOOL INS_IsIndirectControlFlow (INS ins)
 
REG INS_SegmentRegPrefix (INS ins)
 
BOOL INS_HasExplicitMemoryReference (INS ins)
 
VOID PIN_SetSyntaxIntel ()
 
VOID PIN_SetSyntaxATT ()
 
VOID PIN_SetSyntaxXED ()
 
REG INS_RegR (INS x, UINT32 k)
 
REG INS_RegW (INS x, UINT32 k)
 
OPCODE INS_Opcode (INS ins)
 
std::string CATEGORY_StringShort (UINT32 num)
 
std::string EXTENSION_StringShort (UINT32 num)
 
BOOL INS_SegPrefixIsMemoryRead (INS ins)
 
BOOL INS_SegPrefixIsMemoryWrite (INS ins)
 
BOOL INS_AddressSizePrefix (INS ins)
 
BOOL INS_BranchNotTakenPrefix (INS ins)
 
BOOL INS_BranchTakenPrefix (INS ins)
 
BOOL INS_LockPrefix (INS ins)
 
BOOL INS_OperandSizePrefix (INS ins)
 
BOOL INS_RepPrefix (INS ins)
 
BOOL INS_RepnePrefix (INS ins)
 
BOOL INS_SegmentPrefix (INS ins)
 
BOOL INS_IsXchg (INS ins)
 
BOOL INS_IsStringop (INS ins)
 
BOOL INS_IsIRet (INS ins)
 
UINT32 INS_MaxNumRRegs (INS x)
 
UINT32 INS_MaxNumWRegs (INS x)
 
BOOL INS_RegRContain (const INS ins, const REG reg)
 
BOOL INS_RegWContain (const INS ins, const REG reg)
 
BOOL INS_FullRegRContain (const INS ins, const REG reg)
 
BOOL INS_FullRegWContain (const INS ins, const REG reg)
 
BOOL INS_IsStackRead (const INS ins)
 
BOOL INS_IsStackWrite (const INS ins)
 
BOOL INS_IsIpRelRead (const INS ins)
 
BOOL INS_IsIpRelWrite (const INS ins)
 
BOOL INS_IsPredicated (INS ins)
 
BOOL INS_IsOriginal (INS ins)
 
std::string INS_Disassemble (INS ins)
 
ADDRDELTA INS_MemoryDisplacement (INS ins)
 
REG INS_MemoryBaseReg (INS ins)
 
REG INS_MemoryIndexReg (INS ins)
 
UINT32 INS_MemoryScale (INS ins)
 
BOOL INS_ChangeReg (const INS ins, const REG old_reg, const REG new_reg, const BOOL as_read)
 
xed_decoded_inst_t * INS_XedDec (INS ins)
 
REG INS_XedExactMapToPinReg (xed_reg_enum_t xed_reg)
 
PIN_DEPRECATED_API REG INS_XedExactMapToPinReg (unsigned int r)
 
xed_reg_enum_t INS_XedExactMapFromPinReg (REG pin_reg)
 
UINT32 INS_OperandCount (INS ins)
 
UINT32 INS_OperandNameId (INS ins, UINT32 n)
 
BOOL INS_OperandIsMemory (INS ins, UINT32 n)
 
REG INS_OperandMemoryBaseReg (INS ins, UINT32 n)
 
REG INS_OperandMemoryIndexReg (INS ins, UINT32 n)
 
REG INS_OperandMemorySegmentReg (INS ins, UINT32 n)
 
UINT32 INS_OperandMemoryScale (INS ins, UINT32 n)
 
ADDRDELTA INS_OperandMemoryDisplacement (INS ins, UINT32 n)
 
BOOL INS_OperandIsFixedMemop (INS ins, UINT32 n)
 
VOID GetNumberAndSizeOfMemAccesses (INS ins, int *numAccesses, int *accessSize, int *indexSize)
 
UINT32 INS_MemoryOperandCount (INS ins)
 
UINT32 INS_MemoryOperandElementCount (INS ins, UINT32 memoryOp)
 
BOOL INS_OperandIsAddressGenerator (INS ins, UINT32 n)
 
BOOL INS_OperandIsBranchDisplacement (INS ins, UINT32 n)
 
BOOL INS_MemoryOperandIsRead (INS ins, UINT32 memopIdx)
 
BOOL INS_MemoryOperandIsWritten (INS ins, UINT32 memopIdx)
 
UINT32 INS_MemoryOperandIndexToOperandIndex (INS ins, UINT32 memopIdx)
 
BOOL INS_OperandIsReg (INS ins, UINT32 n)
 
BOOL INS_OperandIsSegmentReg (INS ins, UINT32 n)
 
REG INS_OperandReg (INS ins, UINT32 n)
 
BOOL INS_OperandIsImmediate (INS ins, UINT32 n)
 
UINT64 INS_OperandImmediate (INS ins, UINT32 n)
 
BOOL INS_OperandIsImplicit (INS ins, UINT32 n)
 
BOOL INS_RegIsImplicit (INS ins, REG reg)
 
UINT32 INS_OperandWidth (INS ins, UINT32 n)
 
BOOL INS_OperandRead (INS ins, UINT32 n)
 
BOOL INS_OperandWritten (INS ins, UINT32 n)
 
BOOL INS_OperandReadOnly (INS ins, UINT32 n)
 
BOOL INS_OperandWrittenOnly (INS ins, UINT32 n)
 
BOOL INS_OperandReadAndWritten (INS ins, UINT32 n)
 
BOOL INS_IsSyscall (INS ins)
 
SYSCALL_STANDARD INS_SyscallStd (INS ins)
 
RTN INS_Rtn (INS x)
 
INS INS_Next (INS x)
 
INS INS_Prev (INS x)
 
INS INS_Invalid ()
 
BOOL INS_Valid (INS x)
 
ADDRINT INS_Address (INS ins)
 
USIZE INS_Size (INS ins)
 
PIN_DEPRECATED_API ADDRINT INS_DirectBranchOrCallTargetAddress (INS ins)
 
ADDRINT INS_DirectControlFlowTargetAddress (INS ins)
 
ADDRINT INS_NextAddress (INS ins)
 
BOOL INS_IsAddedForFunctionReplacement (INS ins)
 

Variables

const UINT32 VSYSCALL_NR = 0xABCDDCBA
 

Detailed Description

Functions to examine IA-32 and Intel(R) 64 instructions.

Availability:
Mode: JIT & Probe
O/S: Linux & Windows
CPU: IA-32 and Intel(R) 64 architectures

Enumeration Type Documentation

◆ MEMORY_TYPE

Memory type of argument

◆ PREDICATE

enum PREDICATE

Predicate abstraction for IA-32 and Intel(R) 64 instructions.

This file contains basic abstractions for IA32

Enumerator
PREDICATE_ALWAYS_TRUE 

Default predication on IA-32 and Intel(R) 64 architectures.

PREDICATE_BELOW 

Below (CF==1)

PREDICATE_BELOW_OR_EQUAL 

Below or Equal (CF==1 or ZF==1)

PREDICATE_LESS 

Less (SF!=OF)

PREDICATE_LESS_OR_EQUAL 

Less or Equal (ZF==1 or SF!=OF)

PREDICATE_NOT_BELOW 

Not Below (CF==0)

PREDICATE_NOT_BELOW_OR_EQUAL 

Above (CF==0 and ZF==0)

PREDICATE_NOT_LESS 

Greater or Equal (SF==OF)

PREDICATE_NOT_LESS_OR_EQUAL 

Greater (ZF==0 and SF==OF)

PREDICATE_NOT_OVERFLOW 

Not Overflow (OF==0)

PREDICATE_NOT_PARITY 

Not Parity (PF==0)

PREDICATE_NOT_SIGN 

Not Sign (SF==0)

PREDICATE_NOT_ZERO 

Not Zero (ZF==0)

PREDICATE_OVERFLOW 

Overflow (OF==1)

PREDICATE_PARITY 

Parity (PF==1)

PREDICATE_SIGN 

Sign (SF==1)

PREDICATE_ZERO 

Zero (ZF==1)

PREDICATE_CX_NON_ZERO 

CX != 0.

PREDICATE_ECX_NON_ZERO 

ECX != 0.

PREDICATE_RCX_NON_ZERO 

RCX != 0.

PREDICATE_SAVED_GCX_NON_ZERO 

(Internal) Use the saved value of one of the previous three tests

◆ 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_IA32_LINUX_SYSENTER 

Linux system call via 'sysenter' on IA-32 architecture.

SYSCALL_STANDARD_IA32E_LINUX 

Linux system call on Intel(R) 64 architecture.

SYSCALL_STANDARD_IA32E_LINUX_VSYSCALL 

Linux virtual 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

◆ CATEGORY_StringShort()

std::string CATEGORY_StringShort ( UINT32  num)
Returns
String form of category

◆ EXTENSION_StringShort()

std::string EXTENSION_StringShort ( UINT32  num)
Returns
String form of ISA extension

◆ INS_Address()

ADDRINT INS_Address ( INS  ins)
Returns
Address of instruction
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ INS_AddressSizePrefix()

BOOL INS_AddressSizePrefix ( INS  ins)
Returns
true if the instruction has an address size prefix.

◆ INS_BranchNotTakenPrefix()

BOOL INS_BranchNotTakenPrefix ( INS  ins)
Returns
true if the instruction has an branch not taken hint prefix

◆ INS_BranchTakenPrefix()

BOOL INS_BranchTakenPrefix ( INS  ins)
Returns
true if the instruction has an branch taken hint prefix

◆ INS_Category()

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

The full mapping of opcodes to categories can be found in the idata.txt file in the Intel(R) X86 Encoder Decoder distribution (which is distributed as part of the Pin kit). The category enumeration can be found in the file "xed-category-enum.h".

A category can be converted into a string by using CATEGORY_StringShort.

Returns
Instruction category

◆ INS_ChangeReg()

BOOL INS_ChangeReg ( const INS  ins,
const REG  old_reg,
const REG  new_reg,
const BOOL  as_read 
)

Change all occurrences of old_reg to new_reg in the r/w sets of the ins. Return TRUE if at least one occurrence changed.

◆ INS_DirectBranchOrCallTargetAddress()

PIN_DEPRECATED_API ADDRINT INS_DirectBranchOrCallTargetAddress ( INS  ins)
Returns
For direct branches or calls, the target address
Note
DEPRECATED: see INS_DirectControlFlowTargetAddress() instead.

◆ INS_DirectControlFlowTargetAddress()

ADDRINT INS_DirectControlFlowTargetAddress ( INS  ins)
Returns
the target address for direct control-flow instructions. must verify that INS_IsDirectControlFlow() is true before using this function. Refer to INS_IsControlFlow() for more details on control-flow instructions.

◆ INS_Disassemble()

std::string INS_Disassemble ( INS  ins)
Returns
std::string disassembly of instruction

◆ INS_EffectiveAddressWidth()

UINT32 INS_EffectiveAddressWidth ( INS  ins)
Returns
the width of the effective address in bits

◆ INS_Extension()

INT32 INS_Extension ( const INS  ins)
Returns
Instruction extension, Use EXTENSION_StringShort to make it a string

◆ INS_FullRegRContain()

BOOL INS_FullRegRContain ( const INS  ins,
const REG  reg 
)
Returns
true if ins uses reg as a read operand

◆ INS_FullRegWContain()

BOOL INS_FullRegWContain ( const INS  ins,
const REG  reg 
)
Returns
true if ins uses reg as a write operand

◆ INS_GetFarPointer()

VOID INS_GetFarPointer ( INS  ins,
UINT16 &  segment_selector,
UINT32 &  displacement 
)
Returns
the segment selector and displacement from a direct far jump.

◆ INS_GetPredicate()

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

◆ INS_HasExplicitMemoryReference()

BOOL INS_HasExplicitMemoryReference ( INS  ins)

Test if this instruction has an explict memory operand. We include the memory operand in lea.

Returns
TRUE if the instruction is has an explicit memory operand

◆ INS_HasFallThrough()

BOOL 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
Note
for system calls function returns false.

◆ INS_HasMemoryRead2()

BOOL INS_HasMemoryRead2 ( INS  ins)
Returns
true if this instruction has 2 memory read operands

◆ INS_HasMemoryVector()

BOOL INS_HasMemoryVector ( INS  ins)
Returns
TRUE iff the ins has a memory vector, i.e. the memory is accessed using a base address and an index vector with a scale.

◆ INS_HasRealRep()

BOOL INS_HasRealRep ( INS  ins)

this file contains functions visible in level_core it uses primitives from level_core_with_ia32_ins but does not leak out any IA32 stuff!

Returns
whether the instruction has a real REP/REPZ/REPNZ prefix (i.e. one which is not just part of the opcode encoding but does cause the instruction to repeat).

◆ INS_HasScatteredMemoryAccess()

BOOL INS_HasScatteredMemoryAccess ( INS  ins)
Returns
TRUE iff the ins has scattered memory access. Scattered memory access means that the instruction does not access the memory as a single sequential block, but rather is scattered into multiple memory blocks. For exmaple, with the vscatter/vgather instructions, the index vector register is broken down to multiple index values that are used together with the base address, scale and displacement to access multiple blocks.

◆ INS_Invalid()

INS INS_Invalid ( )
Returns
Invalid instruction used in iterators INS_Prev and INS_Next
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ INS_IsAddedForFunctionReplacement()

BOOL INS_IsAddedForFunctionReplacement ( INS  ins)

Return TRUE if ins is not an original instruction in the application, but is an instruction added by Pin for doing function replacement. Pin allows you to even instrument these non-original instructions in JIT mode.

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

◆ INS_IsAmx()

BOOL INS_IsAmx ( INS  ins)

Return TRUE iff the ins is an AMX instruction

◆ INS_IsAtomicUpdate()

BOOL INS_IsAtomicUpdate ( const INS  ins)
Returns
true if this instruction performs an atomic update of memory.
Note
An XCHG instruction accessing memory is atomic with or without a LOCK prefix.

◆ INS_IsBranch()

BOOL INS_IsBranch ( INS  ins)
Returns
true if ins is a branch instruction. A branch can be conditional or unconditional.
Note
In some cases branch instructions are actually system calls. In case ins is in practice a system call, the function returns false. For example, JMP_FAR in Windows IA-32 can be a system call under certain conditions.

◆ INS_IsBranchOrCall()

PIN_DEPRECATED_API BOOL INS_IsBranchOrCall ( INS  ins)
Returns
TRUE if ins is a Branch or Call instruction, includes both direct and indirect instruction types.
Note
DEPRECATED: Use INS_IsValidForIpointTakenBranch() instead to check if you can use IPOINT_TAKEN_BRANCH. Or use INS_IsControlFlow() to check if instruction is a control flow.

◆ INS_IsCacheLineFlush()

BOOL INS_IsCacheLineFlush ( INS  ins)
Returns
TRUE if instruction causes cache line flush

◆ INS_IsCall()

BOOL INS_IsCall ( INS  ins)
Returns
true if ins is a Call instruction. Note: In case ins is in practice a system call, the function returns false.

◆ INS_IsControlFlow()

BOOL INS_IsControlFlow ( INS  ins)
Returns
true if ins is a Control Flow instruction.
Note
In general, any Branch, Call or Ret is a control flow instruction. However, we exclude any instruction which in practice is a system call (e.g. FAR_JMP in Windows with IA32 is sometimes a syscall).
In addition, note that it returns true for Xbegin and Xend instructions. Use this function to verify that an instruction is valid for instrumentation with IARG_BRANCH_TARGET_ADDR.

◆ INS_IsDirectBranch()

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

◆ INS_IsDirectBranchOrCall()

PIN_DEPRECATED_API BOOL 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.
Note
DEPRECATED: see INS_IsDirectControlFlow() instead.

◆ INS_IsDirectCall()

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

◆ INS_IsDirectControlFlow()

BOOL INS_IsDirectControlFlow ( INS  ins)
Returns
TRUE if ins is a control-flow instruction, and its target address is an offset from the instruction pointer or is an immediate.

◆ INS_IsDirectFarJump()

BOOL INS_IsDirectFarJump ( INS  ins)
Returns
true if the target address is a direct far jump

◆ INS_IsFarCall()

BOOL INS_IsFarCall ( INS  ins)
Returns
true if ins is a Far Call instruction

◆ INS_IsFarJump()

BOOL INS_IsFarJump ( INS  ins)
Returns
true if ins is a Far Jump instruction

◆ INS_IsFarRet()

BOOL INS_IsFarRet ( INS  ins)
Returns
true if ins is a far ret instruction

◆ INS_IsHalt()

BOOL INS_IsHalt ( INS  ins)
Returns
true if the ins is a halt or reserved undefined (UD2) instruction.

◆ INS_IsIndirectBranchOrCall()

PIN_DEPRECATED_API BOOL INS_IsIndirectBranchOrCall ( INS  ins)
Returns
true if the branch target comes from a register or memory. result is valid only if INS_IsControlFlow() is true.
Note
DEPRECATED: see INS_IsIndirectControlFlow() instead.

◆ INS_IsIndirectControlFlow()

BOOL INS_IsIndirectControlFlow ( INS  ins)
Returns
true if ins is a control-flow instruction, and its target address is provided through memory or through a register.

◆ INS_IsInterrupt()

BOOL INS_IsInterrupt ( INS  ins)

Return TRUE if the INS is an interrupt category instruction

◆ INS_IsIpRelRead()

BOOL INS_IsIpRelRead ( const INS  ins)

Is an IP-relative read

◆ INS_IsIpRelWrite()

BOOL INS_IsIpRelWrite ( const INS  ins)

Is an IP-relative write

◆ INS_IsIRet()

BOOL INS_IsIRet ( INS  ins)

Returns true iff the given ins is an iret instruction.

Note
See also INS_IsRet.
Returns
true if the instruction is an iret.

◆ INS_IsLea()

BOOL INS_IsLea ( INS  ins)
Returns
TRUE if the instruction is Lea.

◆ INS_IsMaskMov()

BOOL INS_IsMaskMov ( const INS  ins)
Returns
true if this instruction is a maskmovq or maskmovdqu.

◆ INS_IsMemoryRead()

BOOL INS_IsMemoryRead ( INS  ins)
Returns
true if this instruction reads memory
Note
Segment prefix operands (i.e. gs:0x14 ) are memory operands.

◆ INS_IsMemoryWrite()

BOOL INS_IsMemoryWrite ( INS  ins)
Returns
true if this instruction writes memory
Note
Segment prefix operands (i.e. gs:0x14 ) are memory operands.

◆ INS_IsMov()

BOOL INS_IsMov ( const INS  ins)

returns true if this instruction is a move.

◆ INS_IsMovFullRegRegSame()

BOOL INS_IsMovFullRegRegSame ( const INS  ins)

returns true if this instruction is a mov reg1, reg1. And reg1 is a full reg

◆ INS_IsNop()

BOOL INS_IsNop ( INS  ins)
Returns
TRUE if the instruction is a nop.

◆ INS_IsOriginal()

BOOL INS_IsOriginal ( INS  ins)
Returns
true if this is an original instruction

◆ INS_IsPcMaterialization()

BOOL INS_IsPcMaterialization ( INS  ins)
Returns
true if this is a call to the next instruction, which is an idiom for materializing the instruction pointer

◆ INS_IsPredicated()

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

◆ INS_IsPrefetch()

BOOL INS_IsPrefetch ( INS  ins)
Returns
true if this instruction is a prefetch

◆ INS_IsProcedureCall()

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

◆ INS_IsRDTSC()

BOOL INS_IsRDTSC ( const INS  ins)
Returns
true if this instruction is an rdtsc or rdtscp.

◆ INS_IsRet()

BOOL INS_IsRet ( INS  ins)

Returns true if the given ins is a ret instruction.

Note
This function will return true for iret instructions as well.
See also INS_IsIRet.
Returns
true if the instruction is ret or iret.

◆ INS_IsStackRead()

BOOL 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

◆ INS_IsStackWrite()

BOOL 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

◆ INS_IsStandardMemop()

BOOL INS_IsStandardMemop ( INS  ins)
Returns
false if this instruction has a memory operand which has unconventional meaning (e.g. vectorized memory reference of the GATHER/SCATTER instructions or some of the XSAVE instructions).

◆ INS_IsStringop()

BOOL INS_IsStringop ( INS  ins)
Returns
true if the instruction is a string op (can be REP prefixed).

◆ INS_IsSub()

BOOL INS_IsSub ( const INS  ins)

returns true if this instruction is a subtract.

◆ INS_IsSyscall()

BOOL INS_IsSyscall ( INS  ins)

Syscall information for Unix/x86 systems

Returns
true if the instruction is a system call

◆ INS_IsSysenter()

BOOL INS_IsSysenter ( INS  ins)
Returns
true if the instruction is a SysEnter

◆ INS_IsSysret()

BOOL INS_IsSysret ( INS  ins)
Returns
true if ins is a System Return instruction

◆ INS_IsValidForIpointAfter()

BOOL INS_IsValidForIpointAfter ( INS  ins)
Returns
TRUE if ins can be instrumented at location IPOINT_AFTER.

◆ INS_IsValidForIpointTakenBranch()

BOOL INS_IsValidForIpointTakenBranch ( INS  ins)
Returns
TRUE if ins can be instrumented at location IPOINT_TAKEN_BRANCH.

◆ INS_IsVgather()

BOOL INS_IsVgather ( INS  ins)
Returns
TRUE iff the ins is a VGATHER* instruction

◆ INS_IsVscatter()

BOOL INS_IsVscatter ( INS  ins)
Returns
TRUE iff the ins is a VSCATTER* instruction

◆ INS_IsXbegin()

BOOL INS_IsXbegin ( INS  ins)
Returns
true if the instruction is a Xbegin

◆ INS_IsXchg()

BOOL INS_IsXchg ( INS  ins)
Returns
true if the instruction is an "xchg"

◆ INS_IsXend()

BOOL INS_IsXend ( INS  ins)
Returns
true if the instruction is a Xend

◆ INS_LockPrefix()

BOOL INS_LockPrefix ( INS  ins)
Returns
true if the instruction has a lock prefix.

◆ INS_MaxNumRRegs()

UINT32 INS_MaxNumRRegs ( INS  x)

ELF specific stuff related to INS

Returns
Maximum number of read operands

◆ INS_MaxNumWRegs()

UINT32 INS_MaxNumWRegs ( INS  x)
Returns
Maximum number of write operands

◆ INS_MemoryBaseReg()

REG INS_MemoryBaseReg ( INS  ins)
Returns
The base register used in the instruction's memory operand, or REG_INVALID() if there is no base register.

◆ INS_MemoryDisplacement()

ADDRDELTA INS_MemoryDisplacement ( INS  ins)
Returns
The memory displacement of an instrucation with memory operand.
Note
: the displacement is a signed number.

◆ INS_MemoryIndexReg()

REG INS_MemoryIndexReg ( INS  ins)
Returns
The index register used in the instruction's memory operand, or REG_INVALID() if there is no index register.

◆ INS_MemoryOperandCount()

UINT32 INS_MemoryOperandCount ( INS  ins)
Returns
the number of memory operands. Please note INS_MemoryOperandElementCount for reading the number of elements per memory operand.
Note
Segment prefix operands (i.e. gs:0x14 ) are memory operands.

◆ INS_MemoryOperandElementCount()

UINT32 INS_MemoryOperandElementCount ( INS  ins,
UINT32  memoryOp 
)
Returns
the number of elements in the requested memory operand. For instructions where the memory operands has not elemenets, returns 1.

◆ INS_MemoryOperandElementSize()

USIZE INS_MemoryOperandElementSize ( INS  ins,
UINT32  memoryOp 
)
Parameters
[in]insthe instruction.
[in]memoryOpthe memory operand index whose element size is required.
Returns
the size of the requested memory operand element in bytes. For scalar instructions, this function will return the same as INS_MemoryOperandSize. For vector instructions, this function will return the size of a single element.

◆ INS_MemoryOperandIndexToOperandIndex()

UINT32 INS_MemoryOperandIndexToOperandIndex ( INS  ins,
UINT32  memopIdx 
)

Convert a memory operand index into a simple operand index.

Parameters
[in]insThe instruction.
[in]memopIdxMemory operand's index in the range [0, n-1], where n is from INS_MemoryOperandCount().
Returns
operand index

◆ INS_MemoryOperandIsRead()

BOOL INS_MemoryOperandIsRead ( INS  ins,
UINT32  memopIdx 
)
Returns
TRUE if memory operand memopIdx is read

◆ INS_MemoryOperandIsWritten()

BOOL INS_MemoryOperandIsWritten ( INS  ins,
UINT32  memopIdx 
)
Returns
TRUE if memory operand memopIdx is written

◆ INS_MemoryOperandSize()

USIZE INS_MemoryOperandSize ( INS  ins,
UINT32  memoryOp 
)
Parameters
[in]insthe instruction.
[in]memoryOpthe 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). The operand of instructions with scattered memory access (like vscatter/vgather) does not have a size, and this function should not be called for these functions. Use INS_HasScatteredMemoryAccess before calling this function.

◆ INS_MemoryReadSize()

PIN_DEPRECATED_API USIZE 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).
Note
DEPRECATED: see INS_MemoryOperandSize() instead.

◆ INS_MemoryScale()

UINT32 INS_MemoryScale ( INS  ins)
Returns
The scale factor (1,2,4,8) by which the index register in the instruction's memory operand is multiplied.

◆ INS_MemoryWriteSize()

PIN_DEPRECATED_API USIZE 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).
Note
DEPRECATED: see INS_MemoryOperandSize() instead.

◆ INS_Mnemonic()

std::string 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_Next()

INS 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

◆ INS_NextAddress()

ADDRINT INS_NextAddress ( INS  ins)

Get the address of the next instruction.

Returns
Address of instruction that follows this one

◆ INS_Opcode()

OPCODE 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 Intel(R) X86 Encoder Decoder 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

◆ INS_OperandCount()

UINT32 INS_OperandCount ( INS  ins)

ia32 specific stuff related to OPERAND

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]insThe instruction.
Returns
The number of operands for the instruction.

◆ INS_OperandImmediate()

UINT64 INS_OperandImmediate ( INS  ins,
UINT32  n 
)

Although return type is UINT64, on 32-bit systems only the lower 32 bits are utilized. To see how to retrieve immediate values with correct width and sign information, see example in test tool PinTools/SimpleExamples/oper-imm.cpp.

Returns
immediate value for operand

◆ INS_OperandIsAddressGenerator()

BOOL 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_OperandIsBranchDisplacement()

BOOL INS_OperandIsBranchDisplacement ( INS  ins,
UINT32  n 
)
Returns
true if this operand is a displacement (e.g. branch offset)

◆ INS_OperandIsFixedMemop()

BOOL 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

◆ INS_OperandIsImmediate()

BOOL INS_OperandIsImmediate ( INS  ins,
UINT32  n 
)
Returns
true if this operand is an immediate

◆ INS_OperandIsImplicit()

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

◆ INS_OperandIsMemory()

BOOL INS_OperandIsMemory ( INS  ins,
UINT32  n 
)
Returns
true if this operand is a memory reference

Note: this does not include LEA operands.

◆ INS_OperandIsReg()

BOOL INS_OperandIsReg ( INS  ins,
UINT32  n 
)
Returns
true if this operand is a register

◆ INS_OperandIsSegmentReg()

BOOL INS_OperandIsSegmentReg ( INS  ins,
UINT32  n 
)
Returns
true if this operand is a segment register

◆ INS_OperandMemoryBaseReg()

REG INS_OperandMemoryBaseReg ( INS  ins,
UINT32  n 
)
Returns
register used as base register in memory operand, or REG_INVALID() Effective address = Displacement + BaseReg + IndexReg * Scale

◆ INS_OperandMemoryDisplacement()

ADDRDELTA INS_OperandMemoryDisplacement ( INS  ins,
UINT32  n 
)
Returns
The memory displacement of an instrucation with memory operand.
Note
the displacement is a signed number. Effective address = Displacement + BaseReg + IndexReg * Scale

◆ INS_OperandMemoryIndexReg()

REG INS_OperandMemoryIndexReg ( INS  ins,
UINT32  n 
)
Returns
register used as index register in memory operand, or REG_INVALID() Effective address = Displacement + BaseReg + IndexReg * Scale

◆ INS_OperandMemoryScale()

UINT32 INS_OperandMemoryScale ( INS  ins,
UINT32  n 
)
Returns
scale used for addressing in memory operand. Effective address = Displacement + BaseReg + IndexReg * Scale

◆ INS_OperandMemorySegmentReg()

REG INS_OperandMemorySegmentReg ( INS  ins,
UINT32  n 
)
Returns
register used as segment register in memory operand, or REG_INVALID()

◆ INS_OperandRead()

BOOL INS_OperandRead ( INS  ins,
UINT32  n 
)

Tells if an instruction operand is a source; it may also be a destination.

Parameters
[in]insThe instruction.
[in]nOperand's index in the range [0, n-1], where n is from INS_OperandCount().
Returns
TRUE if the operand is a source.

◆ INS_OperandReadAndWritten()

BOOL INS_OperandReadAndWritten ( INS  ins,
UINT32  n 
)

Tells if an instruction operand is both a source and a destination.

Parameters
[in]insThe instruction.
[in]nOperand's index in the range [0, n-1], where n is from INS_OperandCount().
Returns
TRUE if the operand is both a source and a destination.

◆ INS_OperandReadOnly()

BOOL INS_OperandReadOnly ( INS  ins,
UINT32  n 
)

Tells if an instruction operand is just a source (and not a destination).

Parameters
[in]insThe instruction.
[in]nOperand's index in the range [0, n-1], where n is from INS_OperandCount().
Returns
TRUE if the operand is just a source.

◆ INS_OperandReg()

REG INS_OperandReg ( INS  ins,
UINT32  n 
)
Returns
register name for this operand, may return REG_INVALID()

◆ INS_OperandSizePrefix()

BOOL INS_OperandSizePrefix ( INS  ins)
Returns
true if the instruction has an operand size prefix.

◆ INS_OperandWidth()

UINT32 INS_OperandWidth ( INS  ins,
UINT32  n 
)
Returns
operand width in bits.

◆ INS_OperandWritten()

BOOL INS_OperandWritten ( INS  ins,
UINT32  n 
)

Tells if an instruction operand is a destination; it may also be a source.

Parameters
[in]insThe instruction.
[in]nOperand's index in the range [0, n-1], where n is from INS_OperandCount().
Returns
TRUE if the operand is a destination.

◆ INS_OperandWrittenOnly()

BOOL INS_OperandWrittenOnly ( INS  ins,
UINT32  n 
)

Tells if an instruction operand is just a destination (and not a source).

Parameters
[in]insThe instruction.
[in]nOperand's index in the range [0, n-1], where n is from INS_OperandCount().
Returns
TRUE if the operand is just a destination.

◆ INS_Prev()

INS 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

◆ INS_RegIsImplicit()

BOOL INS_RegIsImplicit ( INS  ins,
REG  reg 
)

Assumes that reg is a PIN register

Returns
true if the ins has

◆ INS_RegR()

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

◆ INS_RegRContain()

BOOL INS_RegRContain ( const INS  ins,
const REG  reg 
)
Returns
true if ins uses reg as a read operand

◆ INS_RegW()

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

◆ INS_RegWContain()

BOOL INS_RegWContain ( const INS  ins,
const REG  reg 
)
Returns
true if ins uses reg as a write operand

◆ INS_RepCountRegister()

REG INS_RepCountRegister ( INS  ins)
Returns
register used as the repeat counter by this REP prefixed instruction, or REG_INVALID() if the instruction does not have a real REP prefix.

◆ INS_RepnePrefix()

BOOL INS_RepnePrefix ( INS  ins)
Returns
true if the instruction has an REPNE (0xF2) prefix.

◆ INS_RepPrefix()

BOOL INS_RepPrefix ( INS  ins)
Returns
true if the instruction has an REP (0xF3) prefix.

◆ INS_Rtn()

RTN INS_Rtn ( INS  x)
Returns
Routine that contains this instruction
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ INS_SegmentPrefix()

BOOL INS_SegmentPrefix ( INS  ins)
Returns
true if the instruction has a segment prefix; Call INS_SegmentRegPrefix() to get the actual prefix register name.

◆ INS_SegmentRegPrefix()

REG INS_SegmentRegPrefix ( INS  ins)
Returns
Segment overide prefix used by INS

◆ INS_SegPrefixIsMemoryRead()

BOOL INS_SegPrefixIsMemoryRead ( INS  ins)
Returns
true if this Seg prefixed instruction reads memory

◆ INS_SegPrefixIsMemoryWrite()

BOOL INS_SegPrefixIsMemoryWrite ( INS  ins)
Returns
true if this Seg prefixed instruction writes to memory

◆ INS_Size()

USIZE INS_Size ( INS  ins)
Returns
Size of instruction in bytes

◆ INS_Stutters()

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

◆ INS_SyscallStd()

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

◆ INS_Valid()

BOOL 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

◆ INS_XedDec()

xed_decoded_inst_t* INS_XedDec ( INS  ins)

Intel(R) X86 Encoder Decoder low-level support routines.

This supports the other core_ia32 files and is the lowest level interface to Intel(R) XED encoding/decoding.

Returns
This provides the pointer to the decoded Intel(R) X86 Encoder Decoder instruction.

◆ INS_XedExactMapFromPinReg()

xed_reg_enum_t INS_XedExactMapFromPinReg ( REG  pin_reg)

Convert Pin REG type (application register) to an Intel(R) X86 Encoder Decoder xed_reg_enum_t register.

Returns
xed reg mapping to pin reg. if no map returns XED_REG_INVALID

◆ INS_XedExactMapToPinReg() [1/2]

REG INS_XedExactMapToPinReg ( xed_reg_enum_t  xed_reg)

Convert a Intel(R) X86 Encoder Decoder 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.

◆ INS_XedExactMapToPinReg() [2/2]

PIN_DEPRECATED_API REG INS_XedExactMapToPinReg ( unsigned int  r)

Convert a Intel(R) X86 Encoder Decoder 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.
Note
DEPRECATED: Use INS_XedExactMapToPinReg(xed_reg_enum_t xed_reg) instead

◆ OPCODE_StringShort()

std::string OPCODE_StringShort ( UINT32  opcode)
Returns
String with the opcode of the instruction

◆ PIN_SetSyntaxATT()

VOID PIN_SetSyntaxATT ( )

Sets the disassembly syntax to ATT SYSV format. (Destination on the right)

◆ PIN_SetSyntaxIntel()

VOID PIN_SetSyntaxIntel ( )

Sets the disassembly syntax to Intel format. (Destination on the left)

◆ PIN_SetSyntaxXED()

VOID PIN_SetSyntaxXED ( )

Sets the disassembly syntax to Intel(R) X86 Encoder Decoder detailed format which lists all resources read and written.

Variable Documentation

◆ VSYSCALL_NR

const UINT32 VSYSCALL_NR = 0xABCDDCBA

This file contains INS primitives

system call number for function called from vsyscall