Context manipulation API


Typedefs
typedef CONTEXT	CONTEXT
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_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.

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. This function can be called from an analysis routine or a replacement routine, but not from a callback.

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 Tue Dec 15 03:24:18 2009 for Pin by

1.4.6

Context manipulation API

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation