Generic modification API
[INS: Instruction Object]


Functions

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly (INS ins, MEMORY_TYPE mtype, REG newBase)
VOID LEVEL_PINCLIENT::INS_RewriteMemoryOperand (INS ins, UINT32 memopIdx, REG newBase)
VOID LEVEL_PINCLIENT::INS_InsertIndirectJump (INS ins, IPOINT ipoint, REG reg)
VOID LEVEL_PINCLIENT::INS_InsertDirectJump (INS ins, IPOINT ipoint, ADDRINT tgt)
VOID LEVEL_PINCLIENT::INS_Delete (INS ins)

Detailed Description

Use these functions to modify instructions. They work for all instruction sets. For experts only!

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

Function Documentation

VOID LEVEL_PINCLIENT::INS_Delete (  INS  ins  ) 
 

Delete the instruction

Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::INS_InsertDirectJump (  INS  ins,
IPOINT  ipoint,
ADDRINT  tgt
) 
 

Insert a direct jump instruction relative to the given instruction When used with INS_Delete it can be used to emulate control transfer instructions.

Parameters:
[in] ins input instruction
[in] ipoint location relative to ins (only IPOINT_BEFORE and IPOINT_AFTER are supported)
[in] tgt absolute address of the target
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

VOID LEVEL_PINCLIENT::INS_InsertIndirectJump (  INS  ins,
IPOINT  ipoint,
REG  reg
) 
 

Insert an indirect jump instruction relative to the given instruction. When used with INS_Delete it can be used to emulate control transfer instructions.

Parameters:
[in] ins input instruction
[in] ipoint location relative to ins (only IPOINT_BEFORE and IPOINT_AFTER are supported)
[in] reg register holding the target
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly (  INS  ins,
MEMORY_TYPE  mtype,
REG  newBase
) 
 

Change this memory access instruction to reference the virtual memory location contained in the given register.

On IA-32 and Intel64, the modified operand uses only base register addressing with the new base register newBase. Any index, scale, or offset fields from that operand in the original instruction are removed. In addition, if the original instruction's operand uses a segment override, the instruction is changed to use the default segment.

A memory operand can't be rewritten when:

  • the operand is implicit, but string operations are allowed
  • write operand has the same base register as read
  • some implicit stack operations (associated w/call,ret)

Parameters:
[in] ins input instruction
[in] mtype controls which operand to rewrite (read, write or second read operand)
[in] newBase register used as the new memory base address
DEPRECATED: this function is now deprecated. See INS_RewriteMemoryOperand for a more general function with fewer limitations which should be used instead.

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

VOID LEVEL_PINCLIENT::INS_RewriteMemoryOperand (  INS  ins,
UINT32  memopIdx,
REG  newBase
) 
 

Change this memory access instruction to reference the virtual memory location contained in the given register.

Parameters:
[in] ins input instruction
[in] memopIdx controls which memory operand to rewrite (0,1,...)
[in] newBase register containing the base address of the new operand which will normally be a scratch register allocated via PIN_ClaimToolRegister()
On IA-32 and Intel64, the modified operand uses only base register addressing with the new base register newBase. Any index, scale, or offset fields from that operand in the original instruction are removed. In addition, if the original instruction's operand uses a segment override, the instruction is changed to use the default segment.

This function can be used to rewrite memory operands even when they are implicit (for instance call, ret, push, pop), though in this case the instruction may ultimately be replaced by a sequence of instructions which achieve the same effect. (This is transparent to instrumentation, which continues to see the original instruction).

The only instruction which cannot be rewritten is enter with a second operand > 0

Note that the address in newBase is always the lowest address which will be accessed by this operand. This is consistent with the way in which Pin returns addresses in IARG_*_EA, but means that if the operand is modified by the instruction before the memory access occurs (for instance a push instruction), the value in newBase will not be the value in the stack pointer, but the address of the memory which is accessed by the instruction.

This can also be confusing for xlat; where the value of newBase is the address from which data is loaded, not the address of the base of the translation table. (Again, this is consistent with the IARG_*_EA which Pin will report for an xlat operation).

The canonical instrumentation code for memory address rewriting now looks something like this 

 // Map the originalEa to a translated address. 
 static ADDRINT ProcessAddress(ADDRINT originalEa, ADDRINT size, UINT32 access);
 ...
    for (UINT32 op = 0; op<INS_MemoryOperandCount(ins); op++)
    {
        UINT32 access = (INS_MemoryOperandIsRead(ins,op)    ? 1 : 0) |
                        (INS_MemoryOperandIsWritten(ins,op) ? 2 : 0);

        INS_InsertCall(ins, IPOINT_BEFORE,
                       AFUNPTR(ProcessAddress),
                       IARG_MEMORYOP_EA,   op,
                       IARG_MEMORYOP_SIZE, op,
                       IARG_UINT32,        access,
                       IARG_RETURN_REGS,   REG_INST_G0+i, 
                       IARG_END);

        INS_RewriteMemoryOperand(ins, i, REG(REG_INST_G0+i));
    }
There is no need to handle any instructions specially.

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

Generated on Tue Dec 15 03:24:17 2009 for Pin by  doxygen 1.4.6