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)
RTN LEVEL_PINCLIENT::RTN_CreateAt (ADDRINT address, string name)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedInsertion (RTN rtn)
BOOL LEVEL_PINCLIENT::RTN_IsSafeForProbedReplacement (RTN rtn)
AFUNPTR LEVEL_PINCLIENT::RTN_ReplaceSignatureProbed (RTN orgRtn, AFUNPTR replacementFunptr,...)
VOID LEVEL_PINCLIENT::RTN_InsertCallProbed (RTN orgRtn, IPOINT action, AFUNPTR funptr,...)
INT32 LEVEL_PINCLIENT::RTN_CodeRangesProbed (RTN rtn, INT32 num, PIN_CODE_RANGE *buffer)
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

INT32 LEVEL_PINCLIENT::RTN_CodeRangesProbed (  RTN  rtn,
INT32  num,
PIN_CODE_RANGE *  buffer
) 
 

Returns all the dynamic code ranges associated with the given RTN. The buffer must be allocated by the tool, and be large enough to contain all code ranges. If num=0, the number of dynamic code ranges is returned.

Parameters:
[in] rtn function that was replaced
[in] num number of elements, or zero.
[out] buffer buffer large enough for all of the code ranges.
Returns:
the number of dynamic code ranges copied into buffer. If num=0,it returns the number of dynamic code ranges associated with the RTN.
PIN_StartProgramProbed() must be used when using this API.

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

RTN LEVEL_PINCLIENT::RTN_CreateAt (  ADDRINT  address,
string  name
) 
 

Create a routine object at given address. In some situations user can calculate address of routine, but Pin doesn't see it because there is no symbol at this point. RTN_CreateAt() allows user to create a routine at given address and assign a name for it. When it is done, the routine can be searched by address or by name. The information is kept in Pin while the containing image is in memory.

The address should point to a code (executable section or segment). Since the whole code is "covered" by routine objects, the address should fail on one of the existing routines. Pin shortens the routine, which contains the given address, and creates a new routine which starts at the given address and continues till the next routine or end of code section. Close any open routine before calling this interface with RTN_Close().

Parameters:
[in] address The start address of the new routine
[in] name The assigned name of the new routine
Returns:
RTN object The routine object is valid if the address fails into code section and there is no another routine object which starts at the same address.
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 unnecessary (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

VOID LEVEL_PINCLIENT::RTN_InsertCallProbed (  RTN  orgRtn,
IPOINT  action,
AFUNPTR  funptr,
  ...
) 
 

Insert a call to an analysis routine relative to a RTN.

Parameters:
orgRtn the application routine to instrument
action use IPOINT_BEFORE or IPOINT_AFTER to call funptr before or after execution.
funptr the analysis function
... Pin IARG_TYPEs. If using IPOINT_AFTER, one IARG_TYPE must be IARG_PROTOTYPE. The list must end with IARG_END.
PIN_StartProgramProbed() must be used when using this API.

Use RTN_IsSafeForProbe() to determine if a function is a suitable candidate for probed function insertion.

Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.

Availability:
Mode: Probe
O/S: Linux, Windows
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_IsSafeForProbedInsertion (  RTN  rtn  ) 
 

Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise. This API should be called before attempting to insert a call to an analysis function using RTN_InsertCallProbed(). If you want to replace the given RTN with RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed() you should use RTN_IsSafeForProbedReplacement()

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

Availability:
Mode: Probe
O/S: Linux, Windows
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
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_IsSafeForProbe() 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. IARG_THREAD_ID is not supported.

Availability:
Mode: Probe
O/S: Linux, Windows
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 Jun 18 03:16:16 2009 for Pin by  doxygen 1.4.6