- Main Page
- Modules
- Classes

- Search for |

# 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

Note:
  The pin client lock is obtained during the call of this API.

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 | ) |

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

Parameters:

  `[in]` | trace | The trace.

Returns:
  TRUE if the last instruction in the trace has a fall-through path.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

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

| Insert one or more analysis calls in a trace.

Parameters:

  `[in]` | trace | The trace to instrument.
  `[in]` | action | Specifies 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]` | funptr | The 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

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]` | trace | The trace to instrument.
  `[in]` | action | Specifies when the analysis call executes. See the documentation in TRACE_InsertCall().
  `[in]` | funptr | The 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

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]` | trace | The trace to instrument.
  `[in]` | action | Specifies when the analysis call executes. See the documentation in TRACE_InsertCall().
  `[in]` | funptr | The 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

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