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
BBL	LEVEL_PINCLIENT::TRACE_AddInlineReturnEdg (TRACE trace)
BBL	LEVEL_PINCLIENT::TRACE_AddInlineCallEdg (TRACE trace)
BBL	LEVEL_PINCLIENT::TRACE_AddBranchEdg (TRACE trace)
BBL	LEVEL_PINCLIENT::TRACE_AddFallthroughEdg (TRACE trace)
VOID	LEVEL_PINCLIENT::TRACE_StraightenControlFlow (TRACE trace)
ADDRINT	LEVEL_PINCLIENT::TRACE_GenerateCode (TRACE trace)
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)
USIZE	LEVEL_PINCLIENT::TRACE_OriginalSize (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 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

BBL LEVEL_PINCLIENT::TRACE_AddBranchEdg (  TRACE  trace  )

If the last instruction of the trace is a direct branch then add the target path bbl as the fallthrough path into the trace. TRACE_StraightenControlFlow must be invoked prior to compiling the trace to ensure that the branches are invereted. Parameters: trace  Trace to add the new basic block to Returns: bbl A handle to the newly added basic block

BBL LEVEL_PINCLIENT::TRACE_AddFallthroughEdg (  TRACE  trace  )

Add the fallthrough path bbl of the current last instruction in the trace to the end of the trace. Parameters: trace  Trace to add the new basic block to Returns: bbl A handle to the newly added basic block

BBL LEVEL_PINCLIENT::TRACE_AddInlineCallEdg (  TRACE  trace  )

If the last instruction of the trace is a direct call then inline the call target into the trace. Parameters: trace  Trace to add the new basic block to Returns: bbl A handle to the newly added basic block

BBL LEVEL_PINCLIENT::TRACE_AddInlineReturnEdg (  TRACE  trace  )

Inline the return path of a call that has been previously inlined in this trace using TRACE_AddInlineCallEdg. This requires that the tail instruction of the trace is a return instruction. Parameters: trace  Trace to add the new basic block to Returns: bbl A handle to the newly added basic block

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

ADDRINT LEVEL_PINCLIENT::TRACE_Address (  TRACE  trace  )

Returns: Application address of a trace

BBL LEVEL_PINCLIENT::TRACE_BblHead (  TRACE  trace  )

Returns: first bbl of trace

BBL LEVEL_PINCLIENT::TRACE_BblTail (  TRACE  trace  )

Returns: last bbl of trace

ADDRINT LEVEL_PINCLIENT::TRACE_GenerateCode (  TRACE  trace  )

Compile and put trace in the code cache. Returns: Address where the trace has been placed

BOOL LEVEL_PINCLIENT::TRACE_HasFallThrough (  TRACE  trace  )

Returns: True if the trace has a fall-through else returns false

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

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

Insert call relative to a trace and pass the result to the immediate following "then" analysis call. 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

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

Insert call relative to a trace, which will be invoked only if the immediate preceeding "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

UINT32 LEVEL_PINCLIENT::TRACE_NumBbl (  TRACE  trace  )

Returns: Number of BBL's in trace

UINT32 LEVEL_PINCLIENT::TRACE_NumIns (  TRACE  trace  )

Returns: Number of instructions in trace

BOOL LEVEL_PINCLIENT::TRACE_Original (  TRACE  trace  )

Returns: Whether the TRACE data structure has been instrumented or optimized since it was created

USIZE LEVEL_PINCLIENT::TRACE_OriginalSize (  TRACE  trace  )

Returns: Application code size of a trace

RTN LEVEL_PINCLIENT::TRACE_Rtn (  TRACE  trace  )

Returns: RTN that contains first instruction of trace

USIZE LEVEL_PINCLIENT::TRACE_Size (  TRACE  trace  )

Returns: Application code size of a trace

VOID LEVEL_PINCLIENT::TRACE_StraightenControlFlow (  TRACE  trace  )

Build the control flow for the trace just generated; allows the traversing of the instructions inserted into the trace. This must be called prior to looking at a trace that has applied TRACE_AddInlineCallEdg or TRACE_AddInlineReturnEdg functions for the adding of basic blocks to the trace. Upon invoking this function, the trace's control flow is fixed up to look as it would in the memory afer compilation.

---