Context manipulation API


Typedefs

typedef CONTEXT CONTEXT

Enumerations

enum  PROCESSOR_STATE {
  PROCESSOR_STATE_X87,
  PROCESSOR_STATE_XMM,
  PROCESSOR_STATE_YMM
}

Functions

BOOL LEVEL_PINCLIENT::PIN_SupportsProcessorState (PROCESSOR_STATE state)
BOOL LEVEL_PINCLIENT::PIN_ContextContainsState (CONTEXT *ctxt, PROCESSOR_STATE state)
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_GetContextFPState 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_SetContextFPState 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


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.
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 AVX support), can only read thru the FPSTATE * parameter of the PIN_GetContextFPState function

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_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 AVX support), can only set thru the FPSTATE * parameter of the PIN_SetContextFPState function

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

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


Generated on Tue Nov 22 12:28:41 2011 for Pin by  doxygen 1.4.6