Classes
struct	XSAVE_HEADER

struct	FPSTATE

struct	CONTEXT

Typedefs
typedef UTIL::FXSAVE_IA32	FXSAVE

typedef UTIL::FXSAVE_INTEL64_DEFAULT	FXSAVE

typedef struct CONTEXT	CONTEXT

Enumerations
enum	PROCESSOR_STATE { PROCESSOR_STATE_X87, PROCESSOR_STATE_XMM, PROCESSOR_STATE_YMM, PROCESSOR_STATE_ZMM, PROCESSOR_STATE_TMM }

Functions
BOOL	PIN_SupportsProcessorState (PROCESSOR_STATE state)

BOOL	PIN_ContextContainsState (CONTEXT *ctxt, PROCESSOR_STATE state)

VOID	PIN_SetContextRegval (CONTEXT ctxt, REG reg, const UINT8 val)

VOID	PIN_GetContextRegval (const CONTEXT ctxt, REG reg, UINT8 val)

VOID	PIN_SetContextReg (CONTEXT *ctxt, REG reg, ADDRINT val)

ADDRINT	PIN_GetContextReg (const CONTEXT *ctxt, REG reg)

VOID	PIN_SetContextFPState (CONTEXT ctxt, const FPSTATE fpstate)

VOID	PIN_GetContextFPState (const CONTEXT ctxt, FPSTATE fpstate)

REGSET	PIN_GetFullContextRegsSet ()

VOID	PIN_SaveContext (const CONTEXT ctxtFrom, CONTEXT ctxtTo)

VOID	PIN_ExecuteAt (const CONTEXT *ctxt)

int	PIN_GetInitialContextForUnwind (const CONTEXT ctxt, void cursor)

int	PIN_Backtrace (const CONTEXT ctxt, void *buffer, int size)

Variables
const size_t	VSTATE_PADDING = 128

const size_t	FPSTATE_SIZE = sizeof(FPSTATE)

const size_t	FPSTATE_ALIGNMENT = 64

const size_t	VSTATE_PADDING = 128

const size_t	FPSTATE_SIZE = sizeof(FPSTATE)

const size_t	FPSTATE_ALIGNMENT = 64

const ADDRINT	NUM_PHYSICAL_REGS = REG_PHYSICAL_INTEGER_END - REG_PHYSICAL_INTEGER_BASE + 1

const ADDRINT	NUM_SCRATCH_REGS = REG_INST_SCRATCH_LAST - REG_INST_SCRATCH_BASE + 1

const ADDRINT	NUM_SPECIAL_REGS = 2 + NUM_SCRATCH_REGS

const ADDRINT	NUM_CONTEXT_INT_REGS = NUM_PHYSICAL_REGS + NUM_SPECIAL_REGS

const ADDRINT	NUM_CONTEXT_REGS = REG_LAST_CONTEXT_REG + 1

const ADDRINT	TILE_SIZE_BYTES = 1024

const ADDRINT	TILECFG_SIZE_BYTES = 64

const ADDRINT	NUM_TILE_REGS = REG_TMM_LAST - REG_TMM_FIRST + 1

const ADDRINT	NUM_TILE_AND_CFG_REGS = NUM_TILE_REGS + 1

const ADDRINT	TILE_STATE_SIZE = (NUM_TILE_REGS) * TILE_SIZE_BYTES

const ADDRINT	ARCH_STATE_SIZE

const ADDRINT	DEFAULT_CONTEXT_IMPL = 0

Detailed Description

This API allows the user to read and modify the architectural register state of the processor, as seen in the application that runs under Pin.

Usually, the tool receives context in the instrumentation callback like THREAD_START_CALLBACK, CONTEXT_CHANGE_CALLBACK, or when it specifies explicitly to pass CONTEXT to the instrumentation routine via IARG_CONTEXT, IARG_CONST_CONTEXT or IARG_PARTIAL_CONTEXT. At this time, the tool can read the individual register value via PIN_GetContextReg and @PIN_GetContextRegval, or save the entire context using the PIN_SaveContext. The PIN_ExecuteAt function can be called from an analysis routine to change the control flow of the thread and start execution from the specified context. The PIN_SetContextReg and PIN_SetContextRegval functions can be used from callbacks to change the thread's given register state. In case where IARG_PARTIAL_CONTEXT was used the behaviour of the threads can be changed by changing registers values without using the PIN_ExecuteAt.

Typedef Documentation

◆ CONTEXT

typedef struct CONTEXT CONTEXT

Architectural state of the processor.
The tool should not read or modify data members of this structure directly, but must treat the structure as logically opaque and use the Context manipulation API functions to manage it.

◆ FXSAVE [1/2]

typedef UTIL::FXSAVE_IA32 FXSAVE

Contains declarations of types related to the fp state on ia-32

The memory layout written by FXSAVE and read by FXRSTOR. It is the legacy part of the FP state

◆ FXSAVE [2/2]

typedef UTIL::FXSAVE_INTEL64_DEFAULT FXSAVE

Contains declarations of types related to the fp state on Intel64

The memory layout written by FXSAVE and read by FXRSTOR. It is the legacy part of the FP state

Enumeration Type Documentation

◆ PROCESSOR_STATE

enum PROCESSOR_STATE

enums for queries on the supported state: PIN_SupportsProcessorState and PIN_ContextContainsState

Enumerator
PROCESSOR_STATE_X87	is the X87 (fp stack) supported
PROCESSOR_STATE_XMM	are the xmm registers supported (AVX)
PROCESSOR_STATE_YMM	are the ymm registers supported (AVX2)
PROCESSOR_STATE_ZMM	are the zmm registers supported (AVX512)
PROCESSOR_STATE_TMM	are the tmm registers supported (AMX)

Function Documentation

◆ PIN_Backtrace()

int PIN_Backtrace	(	const CONTEXT *	ctxt,
		void **	buffer,
		int	size
	)

This function is the equivalent Pin version of backtrace(): While backtrace() generates a backtrace for the Pin (and Pin tool) call stack, PIN_Backtrace() generates a backtrace for the application that Pin is instrumenting.

Parameters

[in]	ctxt	context of the application - the backtrace will be generated based upon it.
[out]	buffer	Points to an array on which the backtrace will be stored.
[in]	size	specifies the maximum number of addresses that can be stored in buffer.

Returns: the number of addresses returned in buffer, which is not greater than size.

Availability:: Mode: All
O/S: Linux & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ContextContainsState()

BOOL PIN_ContextContainsState	(	CONTEXT *	ctxt,
		PROCESSOR_STATE	state
	)

Query if the specified CONTEXT contains the specified PROCESSOR_STATE.

Parameters

[in]	ctxt	context to be examined
[in]	state	the PROCESSOR_STATE being queried

Returns: TRUE if the PROCESSOR_STATE specified by state is contained in the ctxt

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ExecuteAt()

VOID PIN_ExecuteAt ( const CONTEXT * ctxt )

A tool can call this API to abandon the current analysis function and resume execution of the calling thread at a new application register state. Note that this API does not return back to the caller's analysis function.

This API can be called from an analysis function or a replacement routine, but not from a callback.

When this API is called from an analysis function or replacement function, and if they execute the current routine or instruction being analyzed, then execution will resume at the instrumented routine or instruction and the analysis function will be called again. It is the pintool's responsibility to avoid going into an infinite loop of calls to the analysis function.

Parameters

[in] ctxt New application register state for the calling thread.

Returns: This API never returns.

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

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetContextFPState()

VOID PIN_GetContextFPState	(	const CONTEXT *	ctxt,
		FPSTATE *	fpstate
	)

Get the floating point state of the specified context.

Parameters

[in]	ctxt	context whose floating point state is retrieved
[in]	fpstate	pointer to the buffer that receives floating point state of the context. the FPSTATE type is exposed by Pin.

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetContextReg()

ADDRINT PIN_GetContextReg	(	const CONTEXT *	ctxt,
		REG	reg
	)

Get the value of the integer register or fp status/control register in the specified context. Note that fp registers such as fp-stack regs, xmm regs, ymm regs (when running with Intel(R) AVX support), can only be read using PIN_GetContextRegval.

Parameters

[in]	ctxt	context whose register value is requested
[in]	reg	register whose value is requested. This could be an integer register or a floating point register with integer values, like FP status/control register.

Returns: value of the register in the specified context

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetContextRegval()

VOID PIN_GetContextRegval	(	const CONTEXT *	ctxt,
		REG	reg,
		UINT8 *	val
	)

Get the value of the requested register from the context. This function is applicable for all context registers (integer, fp etc).

Parameters

[in]	ctxt	context whose register value is requested
[in]	reg	register whose value is requested
[out]	val	an empty buffer which will hold the register value, see note below

Note: It is the user's responsibility to allocate and free the val buffer. The buffer size should be at least as wide as the register. The register size can be obtained using REG_Size.; Trying to read a tile register (REG_TMM0-REG_TMM7) when AMX is not active (PIN_IsAmxActive()) or when tile is not valid (rows and bytes per row are both zeroes) leaves the specified val buffer unmodified.

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetFullContextRegsSet()

REGSET PIN_GetFullContextRegsSet ( )

Get full REGSET.
When using IARG_PARTIAL_CONTEXT such a regset for both in and out REGSET will provide access to all registers including the ability to update them. Such a usage will provide better performance than using IARG_CONTEXT combined with PIN_ExecuteAt().

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetInitialContextForUnwind()

int PIN_GetInitialContextForUnwind	(	const CONTEXT *	ctxt,
		void *	cursor
	)

libbacktrace equivalent implementation

This function is the equivalent Pin version of unw_getcontext(): While unw_getcontext() generates a context for libunwind based on the native context, PIN_GetInitialContextForUnwind() generates a context for libunwind based on Pin CONTEXT.

Parameters

[in]	ctxt	Pin context to convert to libunwind's context
[out]	cursor	Points to valid object of type unw_cursor_t which was initialized using unw_init_local().

Returns: UNW_ESUCCESS in case of success.

Availability:: Mode: All
O/S: Linux & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SaveContext()

VOID PIN_SaveContext	(	const CONTEXT *	ctxtFrom,
		CONTEXT *	ctxtTo
	)

Copy the CONTEXT structure.
CONTEXT structures supplied by Pin to the instrumentation callbacks are not "byte-copyable". The tool should use this function to copy the context provided by Pin and must not attempt to move it as raw memory bytes.

Parameters

[in]	ctxtFrom	CONTEXT structure to copy from
[out]	ctxtTo	CONTEXT structure to copy into

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetContextFPState()

VOID PIN_SetContextFPState	(	CONTEXT *	ctxt,
		const FPSTATE *	fpstate
	)

Set the given floating point state in the specified context.

Parameters

[in,out]	ctxt	context whose floating point state is to be set
[in]	fpstate	new floating point state of the context. the FPSTATE type is exposed by Pin.

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetContextReg()

VOID PIN_SetContextReg	(	CONTEXT *	ctxt,
		REG	reg,
		ADDRINT	val
	)

Set the given value for the integer register or fp status/control register in the specified context. Note that fp registers such as fp-stack regs, xmm regs, ymm regs (when running with Intel(R) AVX support), can only be set using PIN_SetContextRegval.

Parameters

[in,out]	ctxt	context whose register value is to be set
[in]	reg	register whose value is to be set. This could be an integer register or a floating point register with integer values, like FP status/control register.
[in]	val	new value of the register

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetContextRegval()

VOID PIN_SetContextRegval	(	CONTEXT *	ctxt,
		REG	reg,
		const UINT8 *	val
	)

Set the given value for the requested register in the context. This function is applicable for all context registers (integer, fp etc.). When this function is used from within a callback, e.g. THREAD_START_CALLBACK, the new context will take effect when the application continues. If this function is called from within an analysis routine, in order for the new context to take effect when the application continues one must do one of the following: Either use IARG_PARTIAL_CONTEXT and specify the registers which should be modified in the "out" REGSET. Or, use the IARG_CONTEXT and call PIN_ExecuteAt (don't forget to set REG_INST_PTR appropriately).

Parameters

[in,out]	ctxt	context whose register value is to be set
[in]	reg	register whose value is to be set
[in]	val	buffer holding the new value of the register, see note below

Note: It is the user's responsibility to allocate and free the val buffer. The buffer size should be at least as wide as the register. The register size can be obtained using REG_Size.; Trying to set a value inside a tile register (REG_TMM0-REG_TMM7) when AMX is not active (PIN_IsAmxActive()) or when tile is not valid (rows and bytes per row are both zeroes) leaves the specified CONTEXT unmodified.; Setting tile config meta data register (REG_TILECONFIG) inside CONTEXT initialize all tile registers to zero inside context. This mimics CPU behavior.

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SupportsProcessorState()

BOOL PIN_SupportsProcessorState ( PROCESSOR_STATE state )

Query if Pin (and CPU) supports the specified PROCESSOR_STATE.

Parameters

[in] state the PROCESSOR_STATE being queried

Returns: TRUE if the PROCESSOR_STATE specified by state is supported by Pin

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

Variable Documentation

◆ ARCH_STATE_SIZE

const ADDRINT ARCH_STATE_SIZE

Initial value:

=
    (NUM_PHYSICAL_REGS + NUM_SPECIAL_REGS) * sizeof(ADDRINT) + (FPSTATE_SIZE 
                                                                             
                                                                + FPSTATE_ALIGNMENT
 
                                                                + TILE_STATE_SIZE + TILECFG_SIZE_BYTES + NUM_TILE_AND_CFG_REGS
 
                                                                )

Size of the CONTEXT's architectural state in bytes

◆ DEFAULT_CONTEXT_IMPL

const ADDRINT DEFAULT_CONTEXT_IMPL = 0

A constant that designates default (canonical) CONTEXT implementation.

◆ FPSTATE_ALIGNMENT [1/2]

const size_t FPSTATE_ALIGNMENT = 64

This is the alignment that the structure used to save the FPSTATE The alignment required by xsave is 64, the alignment required by fxsave is 16 - so we use the larger

◆ FPSTATE_ALIGNMENT [2/2]

const size_t FPSTATE_ALIGNMENT = 64

This is the alignment that the structure used to save the FPSTATE The alignment required by xsave is 64, the alignment required by fxsave is 16 - so we use the larger

◆ FPSTATE_SIZE [1/2]

const size_t FPSTATE_SIZE = sizeof(FPSTATE)

Size of Pin's (full) FP state structure. It is larger than the size of the structure used by the fxsave instruction (see FXSAVE). It may be larger than the size of the structure used by the xsave instruction, depending on the features enabled in the xstate_bv field in the extended header.

◆ FPSTATE_SIZE [2/2]

const size_t FPSTATE_SIZE = sizeof(FPSTATE)

Size of Pin's (full) FP state structure. It is larger than the size of the structure used by the fxsave instruction (see FXSAVE). It may be larger than the size of the structure used by the xsave instruction, depending on the features enabled in the xstate_bv field in the extended header.

◆ NUM_CONTEXT_INT_REGS

const ADDRINT NUM_CONTEXT_INT_REGS = NUM_PHYSICAL_REGS + NUM_SPECIAL_REGS

Total number of integer registers in CONTEXT

◆ NUM_CONTEXT_REGS

const ADDRINT NUM_CONTEXT_REGS = REG_LAST_CONTEXT_REG + 1

Total number of registers in CONTEXT (app registers + tool registers + special)

◆ NUM_SPECIAL_REGS

const ADDRINT NUM_SPECIAL_REGS = 2 + NUM_SCRATCH_REGS

REG_SEG_FS_BASE and REG_SEG_GS_BASE are represented as special IA-32/Intel(R) 64 architecture registers

◆ NUM_TILE_AND_CFG_REGS

const ADDRINT NUM_TILE_AND_CFG_REGS = NUM_TILE_REGS + 1

Number of tile register + tile configuration "register"

◆ NUM_TILE_REGS

const ADDRINT NUM_TILE_REGS = REG_TMM_LAST - REG_TMM_FIRST + 1

Number of tile register (AMX)

◆ TILE_SIZE_BYTES

const ADDRINT TILE_SIZE_BYTES = 1024

Tile size in bytes

◆ TILE_STATE_SIZE

const ADDRINT TILE_STATE_SIZE = (NUM_TILE_REGS) * TILE_SIZE_BYTES

Size of Tile state buffer inside CONTEXT in bytes.

◆ TILECFG_SIZE_BYTES

const ADDRINT TILECFG_SIZE_BYTES = 64

Tile configuration virtual register size in bytes (this is not a real CPU register)

◆ VSTATE_PADDING [1/2]

const size_t VSTATE_PADDING = 128

Size of the reserved bytes between the XSTATE and the VSTATE parts of the FP state area, as defined by the xsave layout in the SDM.

◆ VSTATE_PADDING [2/2]

const size_t VSTATE_PADDING = 128

Size of the reserved bytes between the XSTATE and the VSTATE parts of the FP state area, as defined by the xsave layout in the SDM.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ CONTEXT

◆ FXSAVE [1/2]

◆ FXSAVE [2/2]

Enumeration Type Documentation

◆ PROCESSOR_STATE

Function Documentation

◆ PIN_Backtrace()

◆ PIN_ContextContainsState()

◆ PIN_ExecuteAt()

◆ PIN_GetContextFPState()

◆ PIN_GetContextReg()

◆ PIN_GetContextRegval()

◆ PIN_GetFullContextRegsSet()

◆ PIN_GetInitialContextForUnwind()

◆ PIN_SaveContext()

◆ PIN_SetContextFPState()

◆ PIN_SetContextReg()

◆ PIN_SetContextRegval()

◆ PIN_SupportsProcessorState()

Variable Documentation

◆ ARCH_STATE_SIZE

◆ DEFAULT_CONTEXT_IMPL

◆ FPSTATE_ALIGNMENT [1/2]

◆ FPSTATE_ALIGNMENT [2/2]

◆ FPSTATE_SIZE [1/2]

◆ FPSTATE_SIZE [2/2]

◆ NUM_CONTEXT_INT_REGS

◆ NUM_CONTEXT_REGS

◆ NUM_SPECIAL_REGS

◆ NUM_TILE_AND_CFG_REGS

◆ NUM_TILE_REGS

◆ TILE_SIZE_BYTES

◆ TILE_STATE_SIZE

◆ TILECFG_SIZE_BYTES

◆ VSTATE_PADDING [1/2]

◆ VSTATE_PADDING [2/2]