Context manipulation API


Functions

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 VOID *fpstate)
VOID LEVEL_PINCLIENT::PIN_GetContextFPState (const CONTEXT *ctxt, VOID *fpstate)
VOID LEVEL_PINCLIENT::PIN_SaveContext (const CONTEXT *ctxtFrom, CONTEXT *ctxtTo)
VOID LEVEL_PINCLIENT::PIN_ExecuteAt (const CONTEXT *ctxt)
VOID LEVEL_PINCLIENT::PIN_SetSyscallArgument (CONTEXT *ctxt, SYSCALL_STANDARD std, UINT32 argNum, ADDRINT val)
ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallArgument (const CONTEXT *ctxt, SYSCALL_STANDARD std, UINT32 argNum)
VOID LEVEL_PINCLIENT::PIN_SetSyscallNumber (CONTEXT *ctxt, SYSCALL_STANDARD std, ADDRINT val)
ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallNumber (const CONTEXT *ctxt, SYSCALL_STANDARD std)
ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallReturn (const CONTEXT *ctxt, SYSCALL_STANDARD std)
ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallErrno (const CONTEXT *ctxt, SYSCALL_STANDARD std)

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_SetContextReg and PIN_SetContextFPState functions can be used to modify the context. The PIN_ExecuteAt function allows to change the control flow of the program (thread) and start execution from the specified context.

Function Documentation

VOID LEVEL_PINCLIENT::PIN_ExecuteAt const CONTEXT ctxt  ) 
 

Set the new context for the current application's thread and run the thread starting from this context.

Parameters:
[in] ctxt new context for the current application's thread
Returns:
the function 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,
VOID *  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 size of the buffer must be at least FPSTATE_SIZE bytes. The returned state has fxsave format in IA-32 and Intel(R) 64 architectures.
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 in the specified context.

Parameters:
[in] ctxt context whose register value is requested
[in] reg register whose value is requested
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

ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallArgument const CONTEXT ctxt,
SYSCALL_STANDARD  std,
UINT32  argNum
 

Get the value of the argument of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context and the current memory content represent the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior and even may cause crash on systems in which system call arguments are located in memory.

Parameters:
[in] ctxt context before the system call execution
[in] std system calling standard
[in] argNum ordinal number of the argument whose value is requested. Ordinal numbers start from zero for the first argument
Returns:
value of the argument
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallErrno const CONTEXT ctxt,
SYSCALL_STANDARD  std
 

Get the error code of the system call which is just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters:
[in] ctxt context after the system call execution
[in] std system calling standard
Returns:
error code, if the system call failed;
zero, if the system call succeeded
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallNumber const CONTEXT ctxt,
SYSCALL_STANDARD  std
 

Get the number (ID) of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters:
[in] ctxt context before the system call execution
[in] std system calling standard
Returns:
system call number
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

ADDRINT LEVEL_PINCLIENT::PIN_GetSyscallReturn const CONTEXT ctxt,
SYSCALL_STANDARD  std
 

Get the return value of the system call which is just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters:
[in] ctxt context after the system call execution
[in] std system calling standard
Returns:
return value of the system call.
On Linux and MacOS the function returns -1 if the system call failed
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 VOID *  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. It must have fxsave format in IA-32 and Intel(R) 64 architectures.
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 in the specified context.

Parameters:
[in,out] ctxt context whose register value is to be set
[in] reg register whose value is to be set
[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_SetSyscallArgument CONTEXT ctxt,
SYSCALL_STANDARD  std,
UINT32  argNum,
ADDRINT  val
 

Set the given value for the argument of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context and the current memory content represent the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior and even may cause crash on systems in which system call arguments are located in memory.

Parameters:
[in,out] ctxt context before the system call execution
[in] std system calling standard
[in] argNum ordinal number of the argument whose value is to be set. Ordinal numbers start from zero for the first argument
[in] val new value of the argument
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

VOID LEVEL_PINCLIENT::PIN_SetSyscallNumber CONTEXT ctxt,
SYSCALL_STANDARD  std,
ADDRINT  val
 

Set the number (ID) of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters:
[in] ctxt context before the system call execution
[in] std system calling standard
[in] val new system call number
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures


Generated on Thu May 15 03:23:40 2008 for Pin by  doxygen 1.4.6