|
PIN_CALLBACK | TRACE_AddInstrumentFunction (TRACE_INSTRUMENT_CALLBACK fun, VOID *val) |
|
VOID | TRACE_AddSmcDetectedFunction (SMC_CALLBACK fun, VOID *val) |
|
VOID | TRACE_InsertCall (TRACE trace, IPOINT action, AFUNPTR funptr,...) |
|
VOID | TRACE_InsertIfCall (TRACE trace, IPOINT action, AFUNPTR funptr,...) |
|
VOID | TRACE_InsertThenCall (TRACE trace, IPOINT action, AFUNPTR funptr,...) |
|
BBL | TRACE_BblHead (TRACE trace) |
|
BBL | TRACE_BblTail (TRACE trace) |
|
ADDRINT | TRACE_Address (TRACE trace) |
|
USIZE | TRACE_Size (TRACE trace) |
|
RTN | TRACE_Rtn (TRACE trace) |
|
BOOL | TRACE_HasFallThrough (TRACE trace) |
|
UINT32 | TRACE_NumBbl (TRACE trace) |
|
UINT32 | TRACE_NumIns (TRACE trace) |
|
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:
◆ SMC_CALLBACK
typedef VOID(* 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] | traceStartAddress | The start address of the trace in which SMC is detected |
[in] | traceEndAddress | The end address of the trace in which SMC is detected |
[in] | v | The tool's call-back value |
◆ TRACE
typedef TRACE_CLASS* TRACE |
◆ TRACE_INSTRUMENT_CALLBACK
typedef VOID(* TRACE_INSTRUMENT_CALLBACK) (TRACE trace, VOID *v) |
Call back function used to instrument traces
◆ TRACE_AddInstrumentFunction()
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 |
- 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 TRACE_Address |
( |
TRACE |
trace | ) |
|
- Returns
- Application address of a trace
- Availability:
- Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All
◆ TRACE_AddSmcDetectedFunction()
VOID 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
-
fun | The call back function that is to be called |
val | Value 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 TRACE_BblHead |
( |
TRACE |
trace | ) |
|
- Returns
- first bbl of trace
- Availability:
- Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All
◆ TRACE_BblTail()
BBL TRACE_BblTail |
( |
TRACE |
trace | ) |
|
- Returns
- last bbl of trace
- Availability:
- Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All
◆ TRACE_HasFallThrough()
BOOL TRACE_HasFallThrough |
( |
TRACE |
trace | ) |
|
Tells if the last instructon in the trace has a fall-through path.
- Parameters
-
- 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 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
◆ TRACE_InsertIfCall()
VOID 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
◆ TRACE_InsertThenCall()
VOID 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
◆ TRACE_NumBbl()
UINT32 TRACE_NumBbl |
( |
TRACE |
trace | ) |
|
- Returns
- Number of BBLs in trace
- Availability:
- Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All
◆ TRACE_NumIns()
UINT32 TRACE_NumIns |
( |
TRACE |
trace | ) |
|
- Returns
- Number of instructions in trace
- Availability:
- Mode: JIT
O/S: Linux, Windows & macOS*
CPU: All
◆ TRACE_Rtn()
RTN 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 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