Trace version APIs

Functions
VOID	LEVEL_PINCLIENT::BBL_SetTargetVersion (BBL bbl, ADDRINT version)
ADDRINT	LEVEL_PINCLIENT::TRACE_Version (TRACE trace)
VOID	LEVEL_PINCLIENT::INS_InsertVersionCase (INS ins, REG reg, INT32 case_value, ADDRINT version,...)

Detailed Description

APIs to implement multiple types of instrumentation on traces and switch between them. Trace versioning allows the same code to be instrumented multiple times. For example, a trace can have both heavyweight and lightweight instrumentation and Pin can switch between the two while the application is running. See tests in the tools/InstrumentationOrderAndVersion directory for examples that use the versioning API's.

Versions are user-defined integer values. By default, all traces have a version value of 0. Tool writers insert instrumentation that switch the application between different versions values. A trace with version value N only transfers control to successor traces with version value N.

There are 2 ways to switch between versions. By calling BBL_SetTargetVersion on a BBL, all successor BBL's (taken and not taken path) will have the new version. BBL_SetTargetVersion can only be called once for a BBL, but it can be applied to every BBL in a trace, allowing all the exits to have different versions.

In addition to BBL_SetTargetVersion, it is possible to insert a dynamic test to jump to a different version based on the value of a Pin virtual register with INS_InsertVersionCase

Instrumentation functions can query which version is being used with TRACE_Version.

There are some situations where Pin will reset the version value to 0, even if executing a non 0 trace. This may occur after a system call, exception or other unusual control flow. Versioning is intended to enable lightweight instrumentation. We suggest you structure the tool so a non-zero version value is used for lightweight instrumentation and 0 is for heavyweight, but always safe to use instrumentation.

Function Documentation

BBL_SetTargetVersion()

VOID LEVEL_PINCLIENT::BBL_SetTargetVersion	(	BBL	bbl,
		ADDRINT	version
	)

Set the versioning for traces that can be reached from this basic block. Overrides the versioning from previous basic blocks. It is an error to set the versioning for the same basic block more than once.

Parameters

[in]	bbl	BBL to mark for versioning
[in]	version	make BBL have this version

Availability:

Mode: JIT
O/S: All
CPU: All

INS_InsertVersionCase()

VOID LEVEL_PINCLIENT::INS_InsertVersionCase	(	INS	ins,
		REG	reg,
		INT32	case_value,
		ADDRINT	version,
			...
	)

Insert a dynamic test to switch between versions before ins. If the value in reg matches case_value, then continue execution at ins with version version. Switching to a new version will cause execution to continue at a new trace starting with ins. This API can be called multiple times for the same instruction, creating a switch/case construct to select the version.

Parameters

[in]	ins	Insert case test before this instruction
[in]	reg	Virtual register used to select case.
[in]	case_value	Go to new version if reg contains case_value
[in]	version	New version to use
[in]	...	List of additional arguments (see IARG_TYPE), terminated with IARG_END. Currently, only IARG_CALL_ORDER is supported. For more information, see CALL_ORDER.

Availability:

Mode: JIT
O/S: All
CPU: IA-32 and Intel(R) 64 architectures

TRACE_Version()

ADDRINT LEVEL_PINCLIENT::TRACE_Version

(

TRACE

trace

)

Returns the version for this trace. See BBL_SetTargetVersion

Availability:

Mode: JIT
O/S: All
CPU: All