RTN: Routine Object


Typedefs

typedef VOID(* LEVEL_PINCLIENT::RTN_INSTRUMENT_CALLBACK )(RTN rtn, VOID *v)

Functions

SEC LEVEL_PINCLIENT::RTN_Sec (RTN x)
RTN LEVEL_PINCLIENT::RTN_Next (RTN x)
RTN LEVEL_PINCLIENT::RTN_Prev (RTN x)
RTN LEVEL_PINCLIENT::RTN_Invalid ()
BOOL LEVEL_PINCLIENT::RTN_Valid (RTN x)
BBL LEVEL_PINCLIENT::RTN_BblHead (RTN x)
BBL LEVEL_PINCLIENT::RTN_BblTail (RTN x)
const string & LEVEL_PINCLIENT::RTN_Name (RTN x)
SYM LEVEL_PINCLIENT::RTN_Sym (RTN x)
AFUNPTR LEVEL_PINCLIENT::RTN_Funptr (RTN x)
INT32 LEVEL_PINCLIENT::RTN_No (RTN x)
VOID LEVEL_PINCLIENT::RTN_AddInstrumentFunction (RTN_INSTRUMENT_CALLBACK fun, VOID *val)
USIZE LEVEL_PINCLIENT::RTN_Size (RTN rtn)
string LEVEL_PINCLIENT::RTN_FindNameByAddress (ADDRINT address)
RTN LEVEL_PINCLIENT::RTN_FindByAddress (ADDRINT address)
RTN LEVEL_PINCLIENT::RTN_FindByName (IMG img, const CHAR *name)
VOID LEVEL_PINCLIENT::RTN_Open (RTN rtn)
VOID LEVEL_PINCLIENT::RTN_Close (RTN rtn)
INS LEVEL_PINCLIENT::RTN_InsHead (RTN rtn)
VOID LEVEL_PINCLIENT::RTN_InsertCall (RTN rtn, IPOINT action, AFUNPTR funptr,...)
ADDRINT LEVEL_PINCLIENT::RTN_Address (RTN rtn)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacement (RTN rtn)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed (RTN orgRtn, AFUNPTR replacementFunptr,...)
AFUNPTR LEVEL_PINCLIENT::RTN_Replace (RTN replacedRtn, AFUNPTR replacementFun)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignature (RTN replacedRtn, AFUNPTR replacementFun,...)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbed (RTN replacedRtn, AFUNPTR replacementFun)

Detailed Description

A RTN represents the functions/routines/procedures typically produced by a compiler for a procedural programming language such as C. Pin finds routines by using the symbol table information. You must call PIN_InitSymbols() so that symbol table information will be available. Can be accessed at instrumentation time and analysis time.

Iteration idioms:

  // Forward pass over all routines in a section
  for( RTN rtn= SEC_RtnHead(sec); RTN_Valid(rtn); rtn = RTN_Next(rtn) )

  // Reverse pass over all routines in a section
  for( RTN rtn= SEC_RtnTail(sec); RTN_Valid(rtn); rtn = RTN_Prev(rtn) )

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::RTN_INSTRUMENT_CALLBACK)(RTN rtn, VOID *v)
 

Call back function used to instrument routines


Function Documentation

VOID LEVEL_PINCLIENT::RTN_AddInstrumentFunction RTN_INSTRUMENT_CALLBACK  fun,
VOID *  val
 

Add a function used to instrument at routine granularity

Parameters:
fun Instrumentation function for routines
val Passed as the second argument to the instrumentation function
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

ADDRINT LEVEL_PINCLIENT::RTN_Address RTN  rtn  ) 
 

Returns:
Address in memory of rtn
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

BBL LEVEL_PINCLIENT::RTN_BblHead RTN  x  ) 
 

Returns:
First bbl of rtn
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

BBL LEVEL_PINCLIENT::RTN_BblTail RTN  x  ) 
 

Returns:
Last bbl of rtn
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_Close RTN  rtn  ) 
 

Close the given rtn. This must be called before opening a new rtn.

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_FindByAddress ADDRINT  address  ) 
 

Parameters:
Address Memory address that corresponds to the RTN
Returns:
Handle to the RTN found. If not found returns RTN_Invalid() In a multithreaded program, the returned RTN handle could go stale if another thread unloaded the shared object that contains the RTN. Use PIN_LockClient() before calling this routine and PIN_UnlockClient() after the last use of the returned RTN handle. Locking is automatic from an instrumentation routine, so it unecessary (but harmless) to lock calls to this function from an instrumentation routine. If you just want the name, call RTN_FindNameByAddress, which automatically does the locking and returns a string which will not go stale if the shared library is unloaded
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_FindByName IMG  img,
const CHAR *  name
 

Parameters:
Img Image in which to search for RTN
Name Name of the RTN to search in IMG
Returns:
Handle to the RTN found. If not found returns RTN_Invalid()
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

string LEVEL_PINCLIENT::RTN_FindNameByAddress ADDRINT  address  ) 
 

Return the name of a function. If more than one name is associated with this address, the first name found is returned.

Parameters:
Address Memory address that corresponds to the RTN
Returns:
Name of routine, or "" if it is not found
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_Funptr RTN  x  ) 
 

an rtn to a funptr

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_InsertCall RTN  rtn,
IPOINT  action,
AFUNPTR  funptr,
  ...
 

Insert call relative to a rtn.

Parameters:
rtn Routine to instrument
action Use IPOINT_BEFORE to call funptr before execution, or IPOINT_AFTER for immediately before the return
funptr Analysis function to call
... Arguments to pass to funptr
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

INS LEVEL_PINCLIENT::RTN_InsHead RTN  rtn  ) 
 

You must call RTN_Open() before the first time this is called for an rtn

Returns:
First instruction of rtn, or RTN_Invalid() if no instructions
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Invalid  ) 
 

Returns:
RTN value that indicates no valid image
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacement RTN  rtn  ) 
 

Return TRUE if the given RTN is a candidate for probed function replacement, and FALSE otherwise. This API should be called before attempting to replace a function using RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed(). Note that this routine does guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.

Parameters:
rtn the application routine to be replaced.
Returns:
TRUE if the function can be replaced, FALSE if it cannot.
PIN_StartProgramProbed() must be used when using this API.

Availability:
Mode: Probe
O/S: Linux, Windows & MacOS
CPU: All

const string& LEVEL_PINCLIENT::RTN_Name RTN  x  ) 
 

Returns:
Name of routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Next RTN  x  ) 
 

Returns:
Routine that follows x, or RTN_Invalid() if x is the last in the section
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

INT32 LEVEL_PINCLIENT::RTN_No RTN  x  ) 
 

Returns:
Number of routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

VOID LEVEL_PINCLIENT::RTN_Open RTN  rtn  ) 
 

Open the given rtn. This must be called before RTN_InsHead() or RTN_InsertCall().

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

RTN LEVEL_PINCLIENT::RTN_Prev RTN  x  ) 
 

Returns:
Routine that precedes x, or RTN_Invalid() if x is the first in the section
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_Replace RTN  replacedRtn,
AFUNPTR  replacementFun
 

Please use RTN_ReplaceSignature() for IA-32 and Intel(R) 64 architectures.

Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented. The signature of the replacement function must be the same as the replaced application routine. Replacement functions typically need to call the replaced routines, therefore this routine returns the address of the original function.

Parameters:
replacedRtn the application routine to be replaced.
replacementFun the replacement function
Returns:
a function pointer to replaced application routine's entry point. This allows the replacement function to execute the replaced routine.
PIN_StartProgram() must be used when using this API.

Availability:
Mode: JIT
O/S: Linux
CPU: IA-64 architecture. Use RTN_ReplaceSignature() for IA-32 and Intel(R) 64 architectures.

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceProbed RTN  replacedRtn,
AFUNPTR  replacementFun
 

Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun) using probes. The replacement function is not instrumented. The signature of the replacement function must be the same as the replaced application routine. Replacement functions typically need to call the replaced routines. However, calls to RTN_Funptr(replacedRtn) will be redirected to replacementFun. Replacement functions must instead call the returned function pointer, which is a copy of the entry point that is not redirected.

Parameters:
replacedRtn the application routine to be replaced.
replacementFun the replacement function
Returns:
a function pointer to replaced application routine's entry point. This allows the replacement function to execute the replaced routine.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbedReplacement() to determine if a function is a suitable candidate for probed function replacement.

Availability:
Mode: Probe
O/S: Linux & Windows
CPU: All

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignature RTN  replacedRtn,
AFUNPTR  replacementFun,
  ...
 

Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun). The replacement function is not instrumented. The signature of the replacement function can be different than the replaced application routine's signature. For instance, the context could be passed as an argument into the replacement functions. Replacement functions typically need to call the replaced routines, therefore this routine returns the address of the original function address.

Parameters:
replacedRtn the application routine to be replaced
replacementFun the replacement function
... the arguments to pass to the replacement function
Returns:
a function pointer to replaced application routine's entry point This allows the replacement function to execute the replaced routine.
PIN_StartProgram() must be used when using this API.

Some restrictions apply using IARG_CONTEXT. See Instrumentation arguments for more information.

Availability:
Mode: JIT only.
O/S: Linux & Windows
CPU: All.

AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed RTN  orgRtn,
AFUNPTR  replacementFunptr,
  ...
 

Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes. The replacement function is not instrumented. Replacement functions typically need to call the replaced routines. However, calls to RTN_Funptr(orgRtn) will be redirected to replacementFunptr. Replacement functions must instead call the returned function pointer, which is a copy of the entry point that is not redirected. The replacement function signature does not have to be the same as the replaced function. In fact while the replaced function may have the CALLINGSTD_REGPARMS calling convention, the replacement function calling convention must not be PIN_FAST_ANALYSIS_CALL (i.e. the replaced function may have register parameters, the replacement function must not). The replacement function arguments must be passed to the replacement function using the Pin IARG_TYPEs, in the same way as RTN_InsertCall(). A prototype of the routine in the application must also be passed in as an argument. See PROTO_Allocate for more information.

Parameters:
orgRtn the application routine to be replaced.
replacementFunptr the replacement function
... Pin IARG_TYPEs. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END.
Returns:
a function pointer to the relocated application function entry point. This allows the replacement routine to execute the replaced routine.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbedReplacement() to determine if a function is a suitable candidate for probed function replacement.

Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information.

Availability:
Mode: Probe
O/S: Linux, Windows & MacOS
CPU: All

SEC LEVEL_PINCLIENT::RTN_Sec RTN  x  ) 
 

Returns:
Section that contains this routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

USIZE LEVEL_PINCLIENT::RTN_Size RTN  rtn  ) 
 

Returns:
size of routine in bytes
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

SYM LEVEL_PINCLIENT::RTN_Sym RTN  x  ) 
 

Returns:
SYM associated with the given routine
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All

BOOL LEVEL_PINCLIENT::RTN_Valid RTN  x  ) 
 

Returns:
True if x is not RTN_Invalid(). RTN_Valid() returns false in certain cases when there is no static image of the code available, includiing dynamically generated code.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & MacOS
CPU: All


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