TRACE: Single entrance, multiple exit sequence of instructions


Typedefs

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

Functions

VOID LEVEL_PINCLIENT::TRACE_AddInstrumentFunction (TRACE_INSTRUMENT_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)
BOOL LEVEL_PINCLIENT::TRACE_Original (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)
USIZE LEVEL_PINCLIENT::TRACE_StubSize (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 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

VOID LEVEL_PINCLIENT::TRACE_AddInstrumentFunction TRACE_INSTRUMENT_CALLBACK  fun,
VOID *  val
 

Add a function used to instrument at trace granularity

Parameters:
fun Instrumentation function for traces
val passed as the second argument to the instrumentation function
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

ADDRINT LEVEL_PINCLIENT::TRACE_Address TRACE  trace  ) 
 

Returns:
Application address of a trace
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

BBL LEVEL_PINCLIENT::TRACE_BblHead TRACE  trace  ) 
 

Returns:
first bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

BBL LEVEL_PINCLIENT::TRACE_BblTail TRACE  trace  ) 
 

Returns:
last bbl of trace
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

BOOL LEVEL_PINCLIENT::TRACE_HasFallThrough TRACE  trace  ) 
 

Returns:
True if the trace has a fall-through else returns false
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::TRACE_InsertCall TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ...
 

Insert call relative to a trace.

Parameters:
trace Trace to instrument
action Specifies before, after, etc.
IPOINT_BEFORE is always valid for all instructions.
IPOINT_AFTER is valid only when a fall-through exists (e.g. Calls and unconditional branches will fail).
IPOINT_ANYWHERE will put the instrumentation at a place inside the trace for best performance
IPOINT_TAKEN_BRANCH is invalid for non-branches.
funptr Analysis function to call
... Arguments to pass to funptr
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::TRACE_InsertIfCall TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ...
 

Insert a call to funptr relative to a trace. If funptr returns a non-zero ADDRINT, then the immediately following "then" analysis call is executed.

Parameters:
trace Trace to instrument
action Specifies before, after, etc.
IPOINT_BEFORE is always valid for all instructions.
IPOINT_AFTER is valid only when a fall-through exists (e.g. Calls and unconditional branches will fail).
IPOINT_ANYWHERE will put the instrumentation at a place inside the trace for best performance
IPOINT_TAKEN_BRANCH is invalid for non-branches.
funptr Analysis function to call. Its return type must be ADDRINT
... Arguments to pass to funptr
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::TRACE_InsertThenCall TRACE  trace,
IPOINT  action,
AFUNPTR  funptr,
  ...
 

Insert a call to funptr relative to a trace. The function is called only if the immediately preceding "if" analysis call returns a non-zero value.

Parameters:
trace Trace to instrument
action Specifies before, after, etc.
IPOINT_BEFORE is always valid for all instructions.
IPOINT_AFTER is valid only when a fall-through exists (e.g. Calls and unconditional branches will fail).
IPOINT_TAKEN_BRANCH is invalid for non-branches.
funptr Analysis function to call
... Arguments to pass to funptr
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

UINT32 LEVEL_PINCLIENT::TRACE_NumBbl TRACE  trace  ) 
 

Returns:
Number of BBLs in trace
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

UINT32 LEVEL_PINCLIENT::TRACE_NumIns TRACE  trace  ) 
 

Returns:
Number of instructions in trace
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

BOOL LEVEL_PINCLIENT::TRACE_Original TRACE  trace  ) 
 

Returns:
Whether the TRACE data structure has been instrumented or optimized since it was created
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

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

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

USIZE LEVEL_PINCLIENT::TRACE_StubSize TRACE  trace  ) 
 

Returns:
Number of bytes in the exit stubs
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All


Generated on Thu May 15 03:23:39 2008 for Pin by  doxygen 1.4.6