- Main Page
- Modules
- Classes

- Search for |

# Context manipulation API

## Classes

union | PIN_REGISTER

## Typedefs

typedef CONTEXT | CONTEXT

## Enumerations

enum | PROCESSOR_STATE { PROCESSOR_STATE_X87, PROCESSOR_STATE_XMM, PROCESSOR_STATE_YMM, PROCESSOR_STATE_ZMM
}

## Functions

BOOL | LEVEL_PINCLIENT::PIN_SupportsProcessorState (PROCESSOR_STATE state)
BOOL | LEVEL_PINCLIENT::PIN_ContextContainsState (CONTEXT *ctxt, PROCESSOR_STATE state)
VOID | LEVEL_PINCLIENT::PIN_SetContextRegval (CONTEXT *ctxt, REG reg, const UINT8 *val)
VOID | LEVEL_PINCLIENT::PIN_GetContextRegval (const CONTEXT *ctxt, REG reg, UINT8 *val)
VOID | LEVEL_PINCLIENT::PIN_SetContextReg (CONTEXT *ctxt, REG reg, ADDRINT val)
ADDRINT | LEVEL_PINCLIENT::PIN_GetContextReg (const CONTEXT *ctxt, REG reg)
VOID | LEVEL_PINCLIENT::PIN_SetContextFPState (CONTEXT *ctxt, const FPSTATE *fpstate)
VOID | LEVEL_PINCLIENT::PIN_GetContextFPState (const CONTEXT *ctxt, FPSTATE *fpstate)
VOID | LEVEL_PINCLIENT::PIN_SaveContext (const CONTEXT *ctxtFrom, CONTEXT *ctxtTo)
VOID | LEVEL_PINCLIENT::PIN_ExecuteAt (const CONTEXT *ctxt)

## 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 IARG_CONTEXT argument to the instrumentation routine. At this time, the tool can read the individual register values or save the entire context using the PIN_GetContextReg, PIN_GetContextRegval, and PIN_SaveContext functions. 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 register state.

## Typedef Documentation

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.

## Enumeration Type Documentation

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
  PROCESSOR_STATE_YMM | are the ymm registers supported
  PROCESSOR_STATE_ZMM | are the zmm registers supported

## Function Documentation

BOOL LEVEL_PINCLIENT::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

VOID LEVEL_PINCLIENT::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.

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

VOID LEVEL_PINCLIENT::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

ADDRINT LEVEL_PINCLIENT::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

VOID LEVEL_PINCLIENT::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.
  It is recommended to use a PIN_REGISTER object as the buffer (and pass a pointer to it). This will ensure that the buffer is large enough for any architectural register.

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

VOID LEVEL_PINCLIENT::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

VOID LEVEL_PINCLIENT::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

VOID LEVEL_PINCLIENT::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

VOID LEVEL_PINCLIENT::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.
  It is recommended to use a PIN_REGISTER object as the buffer (and pass a pointer to it). This will ensure that the buffer is large enough for any architectural register.

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

BOOL LEVEL_PINCLIENT::PIN_SupportsProcessorState | ( | PROCESSOR_STATE | state | ) |

| Query if Pin 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