Pin
Typedefs | Functions
TRACE: Single entrance, multiple exit sequence of instructions

Typedefs

typedef TRACE_CLASS * LEVEL_PINCLIENT::TRACE
typedef VOID(* LEVEL_PINCLIENT::SMC_CALLBACK )(ADDRINT traceStartAddress, ADDRINT traceEndAddress, VOID *v)
typedef VOID(* LEVEL_PINCLIENT::TRACE_INSTRUMENT_CALLBACK )(TRACE trace, VOID *v)

Functions

PIN_CALLBACK LEVEL_PINCLIENT::TRACE_AddInstrumentFunction (TRACE_INSTRUMENT_CALLBACK fun, VOID *val)
VOID LEVEL_PINCLIENT::TRACE_AddSmcDetectedFunction (SMC_CALLBACK fun, VOID *val)
VOID LEVEL_PINCLIENT::TRACE_InsertCall (TRACE trace, IPOINT action, AFUNPTR funptr,...)
VOID LEVEL_PINCLIENT::TRACE_InsertIfCall (TRACE trace, IPOINT action, AFUNPTR funptr,...)
VOID LEVEL_PINCLIENT::TRACE_InsertThenCall (TRACE trace, IPOINT action, AFUNPTR funptr,...)
BBL LEVEL_PINCLIENT::TRACE_BblHead (TRACE trace)
BBL LEVEL_PINCLIENT::TRACE_BblTail (TRACE trace)
ADDRINT LEVEL_PINCLIENT::TRACE_Address (TRACE trace)
USIZE LEVEL_PINCLIENT::TRACE_Size (TRACE trace)
RTN LEVEL_PINCLIENT::TRACE_Rtn (TRACE trace)
BOOL LEVEL_PINCLIENT::TRACE_HasFallThrough (TRACE trace)
UINT32 LEVEL_PINCLIENT::TRACE_NumBbl (TRACE trace)
UINT32 LEVEL_PINCLIENT::TRACE_NumIns (TRACE trace)

Detailed Description

Sequence of instructions that is always entered at the top and may have multiple exits. If Pin detects a jump to an instruction in the middle of a trace, it will create a new trace beginning at the target. See Instrumentation Granularity.

Iteration idioms:

  // Forward pass over all bbls in a trace
  for( BBL bbl = TRACE_BblHead(trace); BBL_Valid(bbl); bbl = BBL_Next(bbl) )

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::SMC_CALLBACK)(ADDRINT traceStartAddress, ADDRINT traceEndAddress, VOID *v)

Call back function when SMC is detected. This function can be registered via TRACE_AddSmcDetectedFunction. The callback delivers the start and end addresses of the TRACE containing the SMC. Using this function can potentially cause Pin to use unlimited memory due to SMC tracking.

Parameters:
[in]traceStartAddressThe start address of the trace in which SMC is detected
[in]traceEndAddressThe end address of the trace in which SMC is detected
[in]vThe tool's call-back value
typedef TRACE_CLASS* LEVEL_PINCLIENT::TRACE

Container for a trace

typedef VOID(* LEVEL_PINCLIENT::TRACE_INSTRUMENT_CALLBACK)(TRACE trace, VOID *v)

Call back function used to instrument traces


Function Documentation

PIN_CALLBACK LEVEL_PINCLIENT::TRACE_AddInstrumentFunction ( TRACE_INSTRUMENT_CALLBACK  fun,
VOID *  val 
)

Add a function used to instrument at trace granularity

Parameters:
funInstrumentation function for traces
valpassed as the second argument to the instrumentation function
Returns:
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note:
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
ADDRINT LEVEL_PINCLIENT::TRACE_Address ( TRACE  trace)
Returns:
Application address of a trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
VOID LEVEL_PINCLIENT::TRACE_AddSmcDetectedFunction ( SMC_CALLBACK  fun,
VOID *  val 
)

Register a call back to be called when Pin detects a self modification of code in the application. See SMC_CALLBACK for usage details.

Parameters:
funThe call back function that is to be called
valValue to be passed to fun when it is called
Note:
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
BBL LEVEL_PINCLIENT::TRACE_BblHead ( TRACE  trace)
Returns:
first bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
BBL LEVEL_PINCLIENT::TRACE_BblTail ( TRACE  trace)
Returns:
last bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
BOOL LEVEL_PINCLIENT::TRACE_HasFallThrough ( TRACE  trace)

Tells if the last instructon in the trace has a fall-through path.

Parameters:
[in]traceThe trace.
Returns:
TRUE if the last instruction in the trace has a fall-through path.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
VOID LEVEL_PINCLIENT::TRACE_InsertCall ( TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ... 
)

Insert one or more analysis calls in a trace.

Parameters:
[in]traceThe trace to instrument.
[in]actionSpecifies when the analysis call executes:
  • IPOINT_BEFORE inserts the call before the first instruction in the trace.
  • IPOINT_AFTER inserts the call after the last instruction in the trace. This call will only execute if execution falls-through (i.e. does not branch). You may only use IPOINT_AFTER if the last instruction in the trace has a fall-through path, which you can find out by using TRACE_HasFallThrough().
  • IPOINT_ANYWHERE is like IPOINT_BEFORE, but may put the call on a different instruction for better performance.
  • IPOINT_TAKEN_BRANCH inserts a call after each branch in the trace. The call only executes if the trace exits with a taken branch.
[in]funptrThe analysis function to call.
[in]...IARG_TYPE. Arguments to pass to funptr.
Note:
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
VOID LEVEL_PINCLIENT::TRACE_InsertIfCall ( TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ... 
)

Insert one or more analysis calls in a trace. If funptr returns a non-zero ADDRINT, then the immediately following "then" analysis call is executed. Note that if CALL_ORDER is used, Both "if" and "then" analysis calls must have the same order.

Parameters:
[in]traceThe trace to instrument.
[in]actionSpecifies when the analysis call executes. See the documentation in TRACE_InsertCall().
[in]funptrThe analysis function to call. Its return type must be ADDRINT.
[in]...IARG_TYPE. Arguments to pass to funptr.
Note:
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
VOID LEVEL_PINCLIENT::TRACE_InsertThenCall ( TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ... 
)

Insert one or more analysis calls in a trace. The functions are called only if the immediately preceding "if" analysis call returns a non-zero value. Note that if CALL_ORDER is used, Both "if" and "then" analysis calls must have the same order.

Parameters:
[in]traceThe trace to instrument.
[in]actionSpecifies when the analysis call executes. See the documentation in TRACE_InsertCall().
[in]funptrThe analysis function to call.
[in]...IARG_TYPE. Arguments to pass to funptr.
Note:
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
UINT32 LEVEL_PINCLIENT::TRACE_NumBbl ( TRACE  trace)
Returns:
Number of BBLs in trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
UINT32 LEVEL_PINCLIENT::TRACE_NumIns ( TRACE  trace)
Returns:
Number of instructions in trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
RTN LEVEL_PINCLIENT::TRACE_Rtn ( TRACE  trace)
Returns:
RTN that contains first instruction of trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
USIZE LEVEL_PINCLIENT::TRACE_Size ( TRACE  trace)

Traces represent contiguous segments of the original code. This function returns the original source footprint of the given trace (not the corresponding post-instrumentation footprint in the code cache).

Returns:
Original application code size of a trace
Availability:
Mode: JIT
O/S: Linux, Windows & OS X*
CPU: All
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator