Exception API


Typedefs
typedef EXCEPTION_INFO	EXCEPTION_INFO
Enumerations
enum	EXCEPTION_CLASS { EXCEPTCLASS_NONE, EXCEPTCLASS_ACCESS_FAULT, EXCEPTCLASS_INVALID_INS, EXCEPTCLASS_INT_ERROR, EXCEPTCLASS_FP_ERROR, EXCEPTCLASS_DEBUG, EXCEPTCLASS_OS_SPECIFIC }
enum	EXCEPTION_CODE { EXCEPTCODE_NONE, EXCEPTCODE_ACCESS_FAULT, EXCEPTCODE_ACCESS_INVALID_ADDRESS, EXCEPTCODE_ACCESS_INVALID_PAGE, EXCEPTCODE_ACCESS_DENIED, EXCEPTCODE_ACCESS_MISALIGNED, EXCEPTCODE_ACCESS_GUARD_PAGE, EXCEPTCODE_ACCESS_STACK_OVERFLOW, EXCEPTCODE_ILLEGAL_INS, EXCEPTCODE_ILLEGAL_INS_OPCODE, EXCEPTCODE_ILLEGAL_INS_OPERAND, EXCEPTCODE_ILLEGAL_INS_ADDRMODE, EXCEPTCODE_ILLEGAL_INS_TRAP, EXCEPTCODE_ILLEGAL_INS_COPROCESSOR, EXCEPTCODE_PRIVILEGED_INS, EXCEPTCODE_PRIVILEGED_INS_OPCODE, EXCEPTCODE_PRIVILEGED_INS_REGISTER, EXCEPTCODE_INT_DIVIDE_BY_ZERO, EXCEPTCODE_INT_OVERFLOW_TRAP, EXCEPTCODE_INT_BOUNDS_EXCEEDED, EXCEPTCODE_FP_DIVIDE_BY_ZERO, EXCEPTCODE_FP_OVERFLOW, EXCEPTCODE_FP_UNDERFLOW, EXCEPTCODE_FP_INEXACT_RESULT, EXCEPTCODE_FP_INVALID_OPERATION, EXCEPTCODE_FP_DENORMAL_OPERAND, EXCEPTCODE_FP_STACK_ERROR, EXCEPTCODE_DBG_BREAKPOINT_TRAP, EXCEPTCODE_DBG_SINGLE_STEP_TRAP, EXCEPTCODE_OS_SPECIFIC }
enum	FAULTY_ACCESS_TYPE { FAULTY_ACCESS_TYPE_UNKNOWN, FAULTY_ACCESS_READ, FAULTY_ACCESS_WRITE, FAULTY_ACCESS_EXECUTE }
Functions
VOID	PIN_InitExceptionInfo (EXCEPTION_INFO *pExceptInfo, EXCEPTION_CODE exceptCode, ADDRINT exceptAddress)
VOID	PIN_InitAccessFaultInfo (EXCEPTION_INFO *pExceptInfo, EXCEPTION_CODE exceptCode, ADDRINT exceptAddress, ADDRINT accessAddress, FAULTY_ACCESS_TYPE accessType=FAULTY_ACCESS_TYPE_UNKNOWN)
VOID	PIN_InitSysExceptionInfo (EXCEPTION_INFO pExceptInfo, UINT32 sysExceptCode, ADDRINT exceptAddress, UINT32 numArgs=0, const ADDRINT pArgs=0)
EXCEPTION_CODE	PIN_GetExceptionCode (const EXCEPTION_INFO *pExceptInfo)
EXCEPTION_CLASS	PIN_GetExceptionClass (EXCEPTION_CODE exceptCode)
ADDRINT	PIN_GetExceptionAddress (const EXCEPTION_INFO *pExceptInfo)
VOID	PIN_SetExceptionAddress (EXCEPTION_INFO *pExceptInfo, ADDRINT exceptAddress)
FAULTY_ACCESS_TYPE	PIN_GetFaultyAccessType (const EXCEPTION_INFO *pExceptInfo)
BOOL	PIN_GetFaultyAccessAddress (const EXCEPTION_INFO pExceptInfo, ADDRINT pAccessAddress)
UINT32	PIN_GetSysExceptionCode (const EXCEPTION_INFO *pExceptInfo)
UINT32	PIN_CountSysExceptionArguments (const EXCEPTION_INFO *pExceptInfo)
ADDRINT	PIN_GetSysExceptionArgument (const EXCEPTION_INFO *pExceptInfo, UINT32 argNum)
string	PIN_ExceptionToString (const EXCEPTION_INFO *pExceptInfo)
VOID	LEVEL_PINCLIENT::PIN_RaiseException (const CONTEXT ctxt, const EXCEPTION_INFO pExceptInfo)
Variables
GLOBALCONST UINT32	MAX_SYS_EXCEPTION_ARGS = 5

Detailed Description

This API allows the user to raise exceptions on behalf of the application and also analyze information associated with exceptions.

Typedef Documentation

typedef struct EXCEPTION_INFO EXCEPTION_INFO

Structure that describes an exception.
The tool should not read or modify data members of this structure directly, but must treat the structure as logically opaque and use the Exception API functions to manage it.

Enumeration Type Documentation

enum EXCEPTION_CLASS

Identifiers of exception classes. Exception class indicates the type of information (set of attributes) that accompanies exceptions of this class.
Enumerator:

EXCEPTCLASS_NONE Reserved. Neither exception belongs to this class.

EXCEPTCLASS_ACCESS_FAULT Memory access fault.

EXCEPTCLASS_INVALID_INS Invalid instruction.

EXCEPTCLASS_INT_ERROR Erroneous integer operation.

EXCEPTCLASS_FP_ERROR Erroneous floating point operation.

EXCEPTCLASS_DEBUG Debugging trap.

EXCEPTCLASS_OS_SPECIFIC OS-specific exception.

enum EXCEPTION_CODE

Identifiers of exception codes. Exception code specifies the cause of an exception and also indicates the class of that exception (EXCEPTION_CLASS).
Enumerator:

EXCEPTCODE_NONE Reserved. Neither exception has this code.

EXCEPTCODE_ACCESS_FAULT General memory access fault. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_INVALID_ADDRESS Virtual address is not mapped. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_INVALID_PAGE Unavailable physical address. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_DENIED Access is not permitted (protection violation). Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_MISALIGNED Misaligned access. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_GUARD_PAGE Guard page access. This exception can be reported only on systems that support guard pages, e.g. Windows. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ACCESS_STACK_OVERFLOW Thread stack overflowed. On some systems this exception is reported as a general memory access fault. Belongs to EXCEPTCLASS_ACCESS_FAULT.

EXCEPTCODE_ILLEGAL_INS Illegal instruction. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_ILLEGAL_INS_OPCODE Illegal opcode. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_ILLEGAL_INS_OPERAND Illegal operand. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_ILLEGAL_INS_ADDRMODE Illegal addressing mode. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_ILLEGAL_INS_TRAP Illegal trap. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_ILLEGAL_INS_COPROCESSOR Coprocessor error. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_PRIVILEGED_INS Privileged instruction. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_PRIVILEGED_INS_OPCODE Privileged opcode. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_PRIVILEGED_INS_REGISTER Privileged register. Belongs to EXCEPTCLASS_INVALID_INS.

EXCEPTCODE_INT_DIVIDE_BY_ZERO Integer divide by zero. Belongs to EXCEPTCLASS_INT_ERROR.

EXCEPTCODE_INT_OVERFLOW_TRAP Integer overflow trap. Belongs to EXCEPTCLASS_INT_ERROR.

EXCEPTCODE_INT_BOUNDS_EXCEEDED Array index is out of bounds ("#BR" exception in IA-32 and Intel(R) 64 architectures). Belongs to EXCEPTCLASS_INT_ERROR.

EXCEPTCODE_FP_DIVIDE_BY_ZERO Floating point divide by zero. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_OVERFLOW Floating point overflow. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_UNDERFLOW Floating point underflow. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_INEXACT_RESULT Floating point inexact result. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_INVALID_OPERATION Invalid floating point operation. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_DENORMAL_OPERAND Denormal floating point operand. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_FP_STACK_ERROR Floating point stack overflowed or underflowed. Belongs to EXCEPTCLASS_FP_ERROR.

EXCEPTCODE_DBG_BREAKPOINT_TRAP Breakpoint trap. Belongs to EXCEPTCLASS_DEBUG.

EXCEPTCODE_DBG_SINGLE_STEP_TRAP Trace trap. Belongs to EXCEPTCLASS_DEBUG.

EXCEPTCODE_OS_SPECIFIC OS-specific exception. Belongs to EXCEPTCLASS_OS_SPECIFIC.

enum FAULTY_ACCESS_TYPE

Types of faulty memory accesses that may cause an EXCEPTCLASS_ACCESS_FAULT exception
Enumerator:

FAULTY_ACCESS_TYPE_UNKNOWN Unknown access violation.

FAULTY_ACCESS_READ Read access.

FAULTY_ACCESS_WRITE Write access.

FAULTY_ACCESS_EXECUTE Execute access.

Function Documentation

UINT32 PIN_CountSysExceptionArguments ( const EXCEPTION_INFO * pExceptInfo )

Retrieve the number of the system exception's arguments from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

Returns:
The number of arguments associated with the system exception

Precondition:
The specified exception information should describe an EXCEPTCODE_OS_SPECIFIC exception.

Availability:
Mode: All
O/S: All
CPU: All

string PIN_ExceptionToString ( const EXCEPTION_INFO * pExceptInfo )

Get a string representation of the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be stringized

Returns:
The string representation of this structure.

Availability:
Mode: All
O/S: All
CPU: All

ADDRINT PIN_GetExceptionAddress ( const EXCEPTION_INFO * pExceptInfo )

Retrieve the address of the instruction that caused the specified exception.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

Returns:
The address of the instruction that caused the exception

Availability:
Mode: All
O/S: All
CPU: All

EXCEPTION_CLASS PIN_GetExceptionClass ( EXCEPTION_CODE exceptCode )

Given an exception code, return the corresponding exception class.
Parameters:

[in] exceptCode exception code

Returns:
The class of the exception

Availability:
Mode: All
O/S: All
CPU: All

EXCEPTION_CODE PIN_GetExceptionCode ( const EXCEPTION_INFO * pExceptInfo )

Retrieve the exception code from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

Returns:
The code of the exception

Availability:
Mode: All
O/S: All
CPU: All

BOOL PIN_GetFaultyAccessAddress ( const EXCEPTION_INFO * pExceptInfo,

ADDRINT * pAccessAddress

)

Retrieve the address of the faulty memory access from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

[out] pAccessAddress pointer to variable that receives the address of the faulty memory access, if known. If this pointer is NULL, the function only checks if the requested address is known but does not return its value.

Returns:
TRUE, if the address of the faulty memory access is known

Precondition:
The specified exception information should describe an EXCEPTCLASS_ACCESS_FAULT exception.

Availability:
Mode: All
O/S: All
CPU: All

FAULTY_ACCESS_TYPE PIN_GetFaultyAccessType ( const EXCEPTION_INFO * pExceptInfo )

Retrieve the type of the faulty memory access from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

Returns:
The type of the faulty memory access that caused the exception

Precondition:
The specified exception information should describe an EXCEPTCLASS_ACCESS_FAULT exception.

Availability:
Mode: All
O/S: All
CPU: All

ADDRINT PIN_GetSysExceptionArgument ( const EXCEPTION_INFO * pExceptInfo,

UINT32 argNum

)

Retrieve the specified system exception's argument from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

[in] argNum ordinal number of the argument to be retrieved, starting from zero. The value of this parameter should not exceed the value returned by the PIN_CountSysExceptionArguments function.

Returns:
The value of the specified system exception's argument

Precondition:
The specified exception information should describe an EXCEPTCODE_OS_SPECIFIC exception.

Availability:
Mode: All
O/S: All
CPU: All

UINT32 PIN_GetSysExceptionCode ( const EXCEPTION_INFO * pExceptInfo )

Retrieve the system exception code from the specified EXCEPTION_INFO structure.
Parameters:

[in] pExceptInfo pointer to the exception information structure to be queried

Returns:
The system exception code

Precondition:
The specified exception information should describe an EXCEPTCODE_OS_SPECIFIC exception.

Availability:
Mode: All
O/S: All
CPU: All

VOID PIN_InitAccessFaultInfo ( EXCEPTION_INFO * pExceptInfo,

EXCEPTION_CODE exceptCode,

ADDRINT exceptAddress,

ADDRINT accessAddress,

FAULTY_ACCESS_TYPE accessType = FAULTY_ACCESS_TYPE_UNKNOWN

)

Initialize the specified EXCEPTION_INFO structure with the given attributes of an EXCEPTCLASS_ACCESS_FAULT exception.

Parameters:

[out] pExceptInfo pointer to the exception information structure to be initialized

[in] exceptCode exception code that specifies an EXCEPTCLASS_ACCESS_FAULT exception

[in] exceptAddress address of the instruction that caused the exception

[in] accessAddress address of the faulty memory access

[in] accessType type of the faulty memory access

Availability:
Mode: All
O/S: All
CPU: All

VOID PIN_InitExceptionInfo ( EXCEPTION_INFO * pExceptInfo,

EXCEPTION_CODE exceptCode,

ADDRINT exceptAddress

)

Initialize the specified EXCEPTION_INFO structure with the given generic exception's attributes. Set "unknown" state for all exception-specific attributes.

Note:
This function is useful when the specified exception code does not require any additional exception information or such information is not available. The function can not be used to initialize EXCEPTCODE_OS_SPECIFIC exception information.
Use exception-specific initialization functions if an additional exception information is available/required.

Parameters:

[out] pExceptInfo pointer to the exception information structure to be initialized

[in] exceptCode exception code. It could specify any exception other than EXCEPTCODE_OS_SPECIFIC

[in] exceptAddress address of the instruction that caused the exception

Availability:
Mode: All
O/S: All
CPU: All

VOID PIN_InitSysExceptionInfo ( EXCEPTION_INFO * pExceptInfo,

UINT32 sysExceptCode,

ADDRINT exceptAddress,

UINT32 numArgs = 0,

const ADDRINT * pArgs = 0

)

Initialize the specified EXCEPTION_INFO structure with the given attributes of an EXCEPTCODE_OS_SPECIFIC exception.

Parameters:

[out] pExceptInfo pointer to the exception information structure to be initialized

[in] sysExceptCode the system exception code

[in] exceptAddress address of the instruction that caused the exception

[in] numArgs number of arguments associated with the system exception. This is the number of elements in the <pArgs> array; it should not exceed the MAX_SYS_EXCEPTION_ARGS value.

[in] pArgs pointer to an array of arguments associated with the system exception or NULL if the number of arguments is zero

Availability:
Mode: All
O/S: Windows
CPU: All

VOID LEVEL_PINCLIENT::PIN_RaiseException ( const CONTEXT * ctxt,

const EXCEPTION_INFO * pExceptInfo

)

Raise an exception with the specified exception information. The exception will be delivered to the application in the calling thread.
This function can be called from an analysis routine or a replacement routine, but not from an instrumentation callback.
Parameters:

[in] ctxt register state to be reported as the application's context at the exception point

[in] pExceptInfo pointer to the EXCEPTION_INFO structure that describes the exception. The exception information should be properly initialized.

Returns:
The function never returns

Precondition:
All locks must be released before calling to this function.

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

VOID PIN_SetExceptionAddress ( EXCEPTION_INFO * pExceptInfo,

ADDRINT exceptAddress

)

Set the address of the instruction that caused the specified exception.
Parameters:

[in,out] pExceptInfo pointer to the exception information structure that receives the new exception address

[in] exceptAddress address of the instruction that caused the exception

Variable Documentation

GLOBALCONST UINT32 MAX_SYS_EXCEPTION_ARGS = 5

Maximum number of arguments that can be associated with an EXCEPTCODE_OS_SPECIFIC exception.

Generated on Thu Jun 18 03:16:17 2009 for Pin by

1.4.6

Exception API

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation