Pin Deprecated API

Defines
#define	PIN_DEPRECATED_WARNINGS   1
Typedefs
typedef VOID(*	LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK )(THREADID threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK )(THREADID threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_BEGIN_CALLBACK )(THREADID threadIndex, VOID *sp, int flags, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_END_CALLBACK )(THREADID threadIndex, INT32 code, VOID *v)
typedef BOOL(*	LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK )(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)
Functions
PIN_DEPRECATED_API BOOL	LEVEL_CORE::INS_IsRewritableMemOpBaseLimited (INS ins, MEMORY_TYPE mtype, REG &base)
PIN_DEPRECATED_API BOOL	LEVEL_CORE::INS_IsRewritableMemOpBase (INS ins, MEMORY_TYPE mtype, REG &base)
PIN_DEPRECATED_API BOOL	LEVEL_CORE::INS_IsDynamicRewritableMemOpBase (INS ins, MEMORY_TYPE mtype, REG &reg)
PIN_DEPRECATED_API ADDRINT	LEVEL_CORE::INS_MemoryOffset (INS ins)
PIN_DEPRECATED_API ADDRDELTA	LEVEL_CORE::INS_MemoryDisplacementSigned (INS ins)
PIN_DEPRECATED_API BOOL	LEVEL_CORE::INS_OperandReadAndWriten (INS ins, UINT32 n)
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction (SIGNAL_BEFORE_CALLBACK fun, VOID *val)
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::PIN_AddSignalAfterFunction (SIGNAL_AFTER_CALLBACK fun, VOID *val)
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (INT32 sig, SIGNAL_INTERCEPT_CALLBACK fun, VOID *val)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::PIN_AddThreadBeginFunction (THREAD_BEGIN_CALLBACK fun, VOID *val)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::PIN_AddThreadEndFunction (THREAD_END_CALLBACK fun, VOID *val)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::PIN_StartProbedProgram ()
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::RTN_IsSafeForProbe (RTN rtn)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine (RTN replacedRtn, AFUNPTR replacementFun)
PIN_DEPRECATED_API BBL	LEVEL_PINCLIENT::RTN_BblHead (RTN x)
PIN_DEPRECATED_API BBL	LEVEL_PINCLIENT::RTN_BblTail (RTN x)
PIN_DEPRECATED_API INT32	LEVEL_PINCLIENT::RTN_No (RTN x)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::PIN_RegisterItcAuxCallBackPushFun (AFUNPTR callBackPushFun)
PIN_DEPRECATED_API VOID	LEVEL_PINCLIENT::RTN_ComplexReplaceWithUninstrumentedRoutine (RTN replacedRtn, AFUNPTR replacementFun)
PIN_DEPRECATED_API ADDRINT	LEVEL_PINCLIENT::PIN_FindAlternateAppStack ()
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::ParseCommandLine (int xargc, CHAR **xargv)
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::INS_ChangeMemOpToBaseRegisterAddressMode (INS ins, MEMORY_TYPE mtype, REG newBase)
PIN_DEPRECATED_API BOOL	LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly (INS ins, MEMORY_TYPE mtype, REG newBase)
BOOL	LEVEL_PINCLIENT::PIN_SetThreadData (TLS_KEY key, const VOID *data)
VOID *	LEVEL_PINCLIENT::PIN_GetThreadData (TLS_KEY key)

---

Detailed Description

APIs from older versions of Pin that have been replaced by more powerful, or simpler, interfaces in the current version of Pin. The newer APIs should be used instead of these interfaces.

---

Define Documentation

#define PIN_DEPRECATED_WARNINGS   1

By default Pin will annotate deprecated parts of the API so that their use in tools will generate compiler warnings. If you want to suppress these warnings during the compilation of your tool, you can do so by defining the macro PIN_DEPRECATED_WARNINGS with the value zero.

---

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK)(THREADID threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application signal handler returns. Parameters: threadIndex  The Pin thread ID of the thread that handled the signal. ctxtFrom  Application's register state at end of handler. ctxtTo  Application's register state to which the handler is returning. v  The tool's call-back value. Note: DEPRECATED: See PIN_AddContextChangeFunction().

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK)(THREADID threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application handles a signal. Parameters: threadIndex  The Pin thread ID of the thread that handles the signal. sig  The signal number. ctxtFrom  Application's register state when it was interrupted by the signal. ctxtTo  Application's register state at start of handler. v  The tool's call-back value. Note: DEPRECATED: See PIN_AddContextChangeFunction().

typedef BOOL(* LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK)(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)

Call back function when tool creates its own signal handler. Parameters: threadIndex  The Pin thread ID of the thread that handled the signal. sig  The signal number. ctxt  Application's register state when it was interrupted by the signal. The tool may change this context if desired. If so, the application continues at the modified context. Or, if the application's signal handler is invoked, that handler returns to the modified context. hndlr  Boolean indicating if the application has a registered signal handler. v  The tool's call-back value. Returns: Returning TRUE tells Pin to pass the signal on to the application's handler (if any). If the tool returns FALSE or if the application has no handler, execution continues at ctxt. Note: DEPRECATED: See PIN_InterceptSignal() and PIN_UnblockSignal().

typedef VOID(* LEVEL_PINCLIENT::THREAD_BEGIN_CALLBACK)(THREADID threadIndex, VOID *sp, int flags, VOID *v)

Call back function when thread begins Note: DEPRECATED: See PIN_AddThreadStartFunction().

typedef VOID(* LEVEL_PINCLIENT::THREAD_END_CALLBACK)(THREADID threadIndex, INT32 code, VOID *v)

Call back function when thread ends Note: DEPRECATED: See PIN_AddThreadFiniFunction().

---

Function Documentation

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_ChangeMemOpToBaseRegisterAddressMode (  INS  ins, MEMORY_TYPE  mtype, REG  newBase )

Change this memory access instruction use a base register addressing mode. On IA-32/Intel(R) 64, it will not rewrite all references; See INS_IsRewritableMemOpBaseLimited() for details. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All Note: DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().

PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsDynamicRewritableMemOpBase (  INS  ins, MEMORY_TYPE  mtype, REG &  reg )

Test if this memory operation can be rewritten dynamically and return the base register Note: DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().

PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBase (  INS  ins, MEMORY_TYPE  mtype, REG &  base )

Returns: true if this instruction has a memory op that can be rewritten. Exclude anything with implicit memory operations, but allow the string ops. Exclude a write if has the same base register as a read because we'll rewrite it when we do the read. Exclude some implicit stack operations (associated w/call,ret) as they cannot be rewritten. Note: DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().

PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_IsRewritableMemOpBaseLimited (  INS  ins, MEMORY_TYPE  mtype, REG &  base )

Returns: true if this instruction has a memory op that can be rewritten. Exclude memory accesses with rIP or rSP as the base register. Exclude *anything* with no base register. (This will exclude instructions that have an index reg with no base reg). (This will exclude instructions that just use a displacement to access memory). Exclude anything with a segment prefix. Exclude LEAVE operations. Exclude a write if has the same base register as a read because we'll rewrite it when we do the read. Note: DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().

PIN_DEPRECATED_API ADDRDELTA LEVEL_CORE::INS_MemoryDisplacementSigned (  INS  ins  )

Note: DEPRECATED: See INS_MemoryDisplacement().

PIN_DEPRECATED_API ADDRINT LEVEL_CORE::INS_MemoryOffset (  INS  ins  )

Note: DEPRECATED: See INS_MemoryDisplacement().

PIN_DEPRECATED_API BOOL LEVEL_CORE::INS_OperandReadAndWriten (  INS  ins, UINT32  n )

Old name for the previous function; this name is a typo. For backward compatibility we keep it. Note: DEPRECATED: See INS_OperandReadAndWritten().

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::INS_RewriteMemoryAddressingToBaseRegisterOnly (  INS  ins, MEMORY_TYPE  mtype, REG  newBase )

Change this memory access instruction to reference the virtual memory location contained in the given register. On IA-32 and Intel64, the modified operand uses only base register addressing with the new base register newBase. Any index, scale, or offset fields from that operand in the original instruction are removed. In addition, if the original instruction's operand uses a segment override, the instruction is changed to use the default segment. A memory operand can't be rewritten when: the operand is implicit, but string operations are allowed write operand has the same base register as read some implicit stack operations (associated w/call,ret) Parameters: [in]  ins  input instruction [in]  mtype  controls which operand to rewrite (read, write or second read operand) [in]  newBase  register used as the new memory base address Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: IA-32 and Intel(R) 64 architectures Note: DEPRECATED and NO LONGER SUPPORTED: See INS_RewriteMemoryOperand().

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::ParseCommandLine (  int  xargc, CHAR **  xargv )

Note: DEPRECATED: See the return value from PIN_Init().

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalAfterFunction (  SIGNAL_AFTER_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately after the application returns from a signal handler. This notification only occurs if the application returns "normally" from the signal handler. If the application jumps out of its handler early (e.g. via longjmp), the notification does not occur. Parameters: fun  Call back function to execute immediately after the application's signal handler. val  Value to pass to the function. Returns: TRUE if succeeds, FALSE otherwise Note: DEPRECATED: See PIN_AddContextChangeFunction().

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction (  SIGNAL_BEFORE_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately before the application jumps to a signal handler. The tool is only notified of a signal that the application actually handles. Unhandled signals do not trigger a notification. Parameters: fun  Call back function to execute immediately before the application's signal handler. val  Value to pass to the function. Returns: TRUE if succeeds, FALSE otherwise Note: Function always return FALSE on Windows DEPRECATED: See PIN_AddContextChangeFunction().

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (  INT32  sig, SIGNAL_INTERCEPT_CALLBACK  fun, VOID *  val )

Takes over ownership of a signal for the tool and establishes a tool handler for the signal. Tools should never call sigaction() directly to handle signals. Use this function to take over "ownership" of a signal. If you want to be notified when the application receives a signal, use PIN_AddContextChangeFunction() instead. Tools should take care when intercepting signals, because this can adversely affect the application if it also uses the signal. The application is still allowed to set up its own handler for an intercepted signal. However, the application is prevented from attempts to block the signal. When an intercepted signal is received, the tool's handler is called first. The tool's handler then decides whether the signal should be forwarded to the application's handler (if any). A tool can set only one "intercept" handler for a particular signal, so a new handler overwrites any previous handler for the same signal. To disable a handler, pass a NULL function pointer. Parameters: sig  The signal number to handle. fun  The tool's handler function, or NULL to return ownership of the signal back to the application. val  Value to pass to the handler function. Returns: TRUE if succeeds, FALSE otherwise Availability: Mode: JIT O/S: Linux CPU: All Note: Intercepting a signal immediately forces the current thread to unblock that signal. This ensures that the application cannot prevent the tool from receiving the signal. Any future threads that the application creates will also be prevented from blocking the signal. However, if there are existing threads in the application when the tool intercepts a signal, those threads will not be prevented from blocking the intercepted signal until some future time. There is no guarantee on when the other threads will unblock the intercepted signal, and they may never do so if they are permanently blocked in a system call. To avoid this problem, it is safest to call PIN_AddSignalInterceptFunction() before starting the application with PIN_StartProgram(). Function always return FALSE on Windows DEPRECATED: See PIN_InterceptSignal() and PIN_UnblockSignal().

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadBeginFunction (  THREAD_BEGIN_CALLBACK  fun, VOID *  val )

Call func immediately after a new thread has been created Parameters: fun  Call back function to execute after new thread has been created val  Value to be passed to fun when it is called Note: DEPRECATED: See PIN_AddThreadStartFunction().

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_AddThreadEndFunction (  THREAD_END_CALLBACK  fun, VOID *  val )

Call func immediately before a thread ends Parameters: fun  Call back function to execute before new thread ends val  Value to be passed to fun when it is called Note: DEPRECATED: See PIN_AddThreadFiniFunction().

PIN_DEPRECATED_API ADDRINT LEVEL_PINCLIENT::PIN_FindAlternateAppStack (   )

If we are currently on a pin stack, return a location on the application stack where we can "unswitch to" and continue execution there Note: DEPRECATED.

VOID* LEVEL_PINCLIENT::PIN_GetThreadData (  TLS_KEY  key  )

Get the value stored in the specified TLS slot of the thread. Note: DEPRECATED and NO LONGER SUPPORTED. Please use the version of this function which takes a THREADID argument. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_RegisterItcAuxCallBackPushFun (  AFUNPTR  callBackPushFun  )

This API is only used by the Intel Thread Checker. Calling this API to register the function that libtcheck provides to push the original function pointer of a replaced function onto Thread Checker's internal storage. Once this API is called, the function replacement bridge will call "callBackPushFun" with the original function pointer of the replaced function as the parameter. Note: DEPRECATED.

BOOL LEVEL_PINCLIENT::PIN_SetThreadData (  TLS_KEY  key, const VOID *  data )

Store specified value in the specified TLS slot of the thread. Note: DEPRECATED and NO LONGER SUPPORTED. Please use the version of this function which takes a THREADID argument. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::PIN_StartProbedProgram (   )

Starts program executing, never returns. PIN_Init must be called first. The command line option -probe must be invoked when using PIN_StartProbedProgram(). A probed program only invokes instrumentation at explicitly inserted probe points. Note: DEPRECATED: See PIN_StartProgramProbed().

PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblHead (  RTN  x  )

Returns: A bbl contains the INSs of the RTN. The RTN must have been opened by RTN_Open in order to receive a valid BBL. Note that RTN is not broken up into BBLs. The returned bbl will contain all the INSs of the RTN that Pin could find through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All Note: DEPRECATED: See RTN_InsHead().

PIN_DEPRECATED_API BBL LEVEL_PINCLIENT::RTN_BblTail (  RTN  x  )

Returns: A bbl contains the INSs of the RTN. The RTN must have been opened by RTN_Open in order to receive a valid BBL. Note that RTN is not broken up into BBLs. The returned bbl will contain all the INSs of the RTN that Pin could find through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All Note: DEPRECATED: See RTN_InsTail().

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ComplexReplaceWithUninstrumentedRoutine (  RTN  replacedRtn, AFUNPTR  replacementFun )

Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented. Difference between RTN_ReplaceWithUninstrumentedRoutine() and RTN_ComplexReplaceWithUninstrumentedRoutine() is that the latter does complex replacement (i.e. a call to the callBackPushFun registered will be made before calling to the replacement function). Note: DEPRECATED.

PIN_DEPRECATED_API BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbe (  RTN  rtn  )

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise. Please use RTN_IsSafeForProbedInsertion() if you want to insert a call before or after routine. Note: DEPRECATED: See RTN_IsSafeForProbedReplacement().

PIN_DEPRECATED_API INT32 LEVEL_PINCLIENT::RTN_No (  RTN  x  )

Returns: Number of routine Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All Note: DEPRECATED: See RTN_Id().

PIN_DEPRECATED_API VOID LEVEL_PINCLIENT::RTN_ReplaceWithUninstrumentedRoutine (  RTN  replacedRtn, AFUNPTR  replacementFun )

Replace a function in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented. Note: DEPRECATED: See RTN_Replace() and RTN_ReplaceProbed().

---