Typedefs
typedef TRACE_CLASS *	TRACE

typedef VOID(*	SMC_CALLBACK) (ADDRINT traceStartAddress, ADDRINT traceEndAddress, VOID *v)

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

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

Detailed Description

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(* 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

Container for a trace

◆ TRACE_INSTRUMENT_CALLBACK

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

Call back function used to instrument traces

Function Documentation

◆ TRACE_AddInstrumentFunction()

PIN_CALLBACK 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

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

[in] trace The 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 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

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SMC_CALLBACK

◆ TRACE

◆ TRACE_INSTRUMENT_CALLBACK

Function Documentation

◆ TRACE_AddInstrumentFunction()

◆ TRACE_Address()

◆ TRACE_AddSmcDetectedFunction()

◆ TRACE_BblHead()

◆ TRACE_BblTail()

◆ TRACE_HasFallThrough()

◆ TRACE_InsertCall()

◆ TRACE_InsertIfCall()

◆ TRACE_InsertThenCall()

◆ TRACE_NumBbl()

◆ TRACE_NumIns()

◆ TRACE_Rtn()

◆ TRACE_Size()