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

◆ SMC_CALLBACK

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

◆ TRACE

typedef TRACE_CLASS* LEVEL_PINCLIENT::TRACE

Container for a trace

◆ TRACE_INSTRUMENT_CALLBACK

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

Call back function used to instrument traces

Function Documentation

◆ TRACE_AddInstrumentFunction()

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 & macOS*
CPU: All

◆ TRACE_Address()

ADDRINT LEVEL_PINCLIENT::TRACE_Address ( TRACE  trace)
Returns
Application address of a trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_AddSmcDetectedFunction()

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 & macOS*
CPU: All

◆ TRACE_BblHead()

BBL LEVEL_PINCLIENT::TRACE_BblHead ( TRACE  trace)
Returns
first bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_BblTail()

BBL LEVEL_PINCLIENT::TRACE_BblTail ( TRACE  trace)
Returns
last bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_HasFallThrough()

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. see INS_HasFallThrough for more details.
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_InsertCall()

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 & macOS*
CPU: All

◆ TRACE_InsertIfCall()

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 & macOS*
CPU: All

◆ TRACE_InsertThenCall()

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 & macOS*
CPU: All

◆ TRACE_NumBbl()

UINT32 LEVEL_PINCLIENT::TRACE_NumBbl ( TRACE  trace)
Returns
Number of BBLs in trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_NumIns()

UINT32 LEVEL_PINCLIENT::TRACE_NumIns ( TRACE  trace)
Returns
Number of instructions in trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_Rtn()

RTN LEVEL_PINCLIENT::TRACE_Rtn ( TRACE  trace)
Returns
RTN that contains first instruction of trace
Availability:
Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All

◆ TRACE_Size()

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 & macOS*
CPU: All