Optimization API

Enumerations
enum	PROBE_TYPE {   PROBE_INVALID,   PROBE_REDIRECT,   PROBE_SINGLE_THREAD,   PROBE_MULTI_THREAD,   PROBE_FUNCTION_WRAPPER }
Functions
BOOL	LEVEL_PINCLIENT::INS_IsPinXfer (INS ins)
BOOL	LEVEL_PINCLIENT::INS_IsNativeXfer (INS ins)
VOID	LEVEL_PINCLIENT::INS_SetNativeXfer (INS ins)
VOID	LEVEL_PINCLIENT::TRACE_ExitsXferToNative (TRACE trace)
VOID	LEVEL_PINCLIENT::INS_SetPinXfer (INS ins)
BOOL	LEVEL_PINCLIENT::INS_IsNativeCall (INS ins)
BOOL	LEVEL_PINCLIENT::INS_IsXlateCall (INS ins)
VOID	LEVEL_PINCLIENT::INS_SetXlateCall (INS ins)
VOID	LEVEL_PINCLIENT::INS_SetNativeCall (INS ins)
VOID	LEVEL_PINCLIENT::INS_RedirectControlFlowToAddress (INS ins, ADDRINT target_addr)
VOID *	LEVEL_PINCLIENT::PIN_NewProbedThreadContext ()
AFUNPTR	LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed (RTN orgRtn, AFUNPTR replacementFunptr,...)
AFUNPTR	LEVEL_PINCLIENT::RTN_InsertProbe (RTN rtn, AFUNPTR probe)
VOID	LEVEL_PINCLIENT::PROTO_Free (PROTO proto)

---

Detailed Description

This API allows the user to modify the program for optimization

---

Enumeration Type Documentation

enum PROBE_TYPE

Controls the type of probe Enumerator: PROBE_INVALID  Invalid. PROBE_REDIRECT  Redirects control flow only. Does not need spill pointer. PROBE_SINGLE_THREAD  Spill pointer is set from static spill area. PROBE_MULTI_THREAD  Spill pointer is set by application before probe. PROBE_FUNCTION_WRAPPER  Wraps a function, spill area allocated on stack and spill pointer initialized.

---

Function Documentation

BOOL LEVEL_PINCLIENT::INS_IsNativeCall (  INS  ins  )

Returns: TRUE if a call instruction is marked to be executed natively.

BOOL LEVEL_PINCLIENT::INS_IsNativeXfer (  INS  ins  )

Returns: TRUE if a control flow instruction has been setup to transfer control back to the native code on the taken path. This is the default mechanism.

BOOL LEVEL_PINCLIENT::INS_IsPinXfer (  INS  ins  )

Returns: TRUE if a control flow instruction has been setup to transfer control to trace generator upon the taken path.

BOOL LEVEL_PINCLIENT::INS_IsXlateCall (  INS  ins  )

Returns: TRUE if a call instruction is marked to be traslated to a push and a jump to the target to ensure transparency to the application as to where the call originated from.

VOID LEVEL_PINCLIENT::INS_RedirectControlFlowToAddress (  INS  ins, ADDRINT  target_addr )

Patch a given branch or call instruction to the given target address. Parameters: ins  The branch or call instruction to patch with the new target address dst_addr  The destination address to encode as the new target for the branch/call

VOID LEVEL_PINCLIENT::INS_SetNativeCall (  INS  ins  )

A call instruction is not translated into a PUSH and a JUMP. This implies that the application might realize that the call is being made from the trace in the code cache and thus any code that depends on the return address at the target site is no longer valid and thus results in program corruption. Doing this implies any instruction following the call in the trace is executed.

VOID LEVEL_PINCLIENT::INS_SetNativeXfer (  INS  ins  )

Set a control flow instruction to transfer control back to the native code on the taken path. This is the default mechanism.

VOID LEVEL_PINCLIENT::INS_SetPinXfer (  INS  ins  )

Set a control flow instruction to transfer control back to the trace generator upon the taken path.

VOID LEVEL_PINCLIENT::INS_SetXlateCall (  INS  ins  )

A call instruction is translated into a return address PUSH and a JMP to ensure that the application does not realize that the call occured in the code cache if it looked at the return address on the stack since we put the original application return address on the stack. This implies that when a return is executed at the call target the control returns to the original application. Any fallthrough instructions in the trace are not executed. Also see INS_SetNativeCall for otherwise.

VOID* LEVEL_PINCLIENT::PIN_NewProbedThreadContext (   )

Returns: a handle to a thread context to be used for a probed thread

VOID LEVEL_PINCLIENT::PROTO_Free (  PROTO  proto  )

Free the specified function prototype. Parameters: proto  A pointer to a function prototype.

AFUNPTR LEVEL_PINCLIENT::RTN_InsertProbe (  RTN  rtn, AFUNPTR  probe )

Install a probe at the entry point of a routine Parameters: rtn  routine to be probed probe  routine to call at the probe point Returns: function pointer that to be called to execute the original unprobed routine

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed (  RTN  orgRtn, AFUNPTR  replacementFunptr,   ... )

Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes. The replacement function is not instrumented. Replacement functions typically need to call the replaced routines. However, calls to RTN_Funptr(orgRtn) will be redirected to replacementFunptr. Replacement functions must instead call the returned function pointer, which is a copy of the entry point that is not redirected. The replacement function signature does not have to be the same as the replaced function. The replacement function arguments must be passed to the replacement function using the Pin IARG_TYPEs, in the same way as RTN_InsertCall(). A prototype of the routine in the application must also be passed in as an argument. See PROTO_Allocate for more information. Parameters: orgRtn  the application routine to be replaced. replacementFunptr  the replacement function ...  Pin IARG_TYPEs. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END. Returns: a function pointer to the relocated application function entry point. This allows the replacement routine to execute the replaced routine. PIN_StartProgramProbed() must be used when using this API. "-probe" must be used on the command line.

VOID LEVEL_PINCLIENT::TRACE_ExitsXferToNative (  TRACE  trace  )

All exits from this trace go back to original code

---