- Main Page
- Modules
- Classes

- Search for |

# 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

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

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

ADDRINT LEVEL_PINCLIENT::TRACE_Version | ( | TRACE | trace | ) |

| Returns the version for this trace. See BBL_SetTargetVersion

Availability:
  Mode: JIT
  O/S: All
  CPU: All