Pin
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Typedefs | Enumerations | Functions | Variables
Generic inspection API

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)
 
BOOL LEVEL_CORE::INS_HasExplicitMemoryReference (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_decoded_inst_t * LEVEL_CORE::INS_XedDec (INS ins)
 
REG LEVEL_CORE::INS_XedExactMapToPinReg (unsigned int r)
 
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

Enumeration Type Documentation

Memory type of argument

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.

The full mapping of opcodes to categories can be found in the idata.txt file in the XED 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
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_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
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]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).
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
xed_decoded_inst_t* LEVEL_CORE::INS_XedDec ( INS  ins)
Returns
This provides the pointer to the decoded xed instruction.
REG LEVEL_CORE::INS_XedExactMapToPinReg ( unsigned int  r)

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