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) )
|
|
Call back function used to instrument routines |
|
|
PROBE_MODE enumerator allows user to set probe mode instrumentation other than default for a particular function. Usually, non-default mode is used when Pin can't instrument a routine in a regular way. A non default mode is usually less safe and tool-writer takes responsibility for correctness in this case. PROBE_MODE_ALLOW_RELOCATION Doing probed instrumentation Pin inserts a jumper in the first bytes of the instrumented routine. If the first basic block calculated within static discovery is not long enough, Pin can't insert a jumper and the instrumentation request is rejected. One more chance to insert a jumper in such case is to relocate the whole routine. It is not always possible, of course. The routine can be relocated by Pin if
The routine relocation may destabilize the application since ability to propagate exceptions is not preserved. Doing static analysis Pin also does not see additional entry points in the routine code. In PROBE_MODE_ALLOW_RELOCATION mode Pin tries to keep the instrumented routine in place, and considers relocation when "in-place" instrumentation is impossible. In PROBE_MODE_DEFAULT the relocation is not allowed. Routine relocation is not supported on Windows and IA-64. |
|
|
Clear history of routine check |
|
||||||||||||
|
Add a function used to instrument at routine granularity
|
|
|
|
|
|
|
|
|
|
|
|
Close the given rtn. This must be called before opening a new rtn.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||
|
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 fall in 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().
|
|
|
|
|
||||||||||||
|
|
|
|
Return the name of a function. If more than one name is associated with this address, the first name found is returned.
|
|
|
an rtn to a funptr
|
|
||||||||||||||||||||
|
Insert call relative to a rtn.
|
|
||||||||||||||||||||
|
Insert a call to an analysis routine relative to a RTN.
Use RTN_IsSafeForProbedInsertion() 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.
|
|
||||||||||||||||||||||||
|
Insert a call to an analysis routine relative to a RTN.
Use RTN_IsSafeForProbedInsertionEx() 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.
|
|
|
You must call RTN_Open() before the first time this is called for an 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()
|
|
||||||||||||
|
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_InsertCallProbedEx(). If you want to replace the given RTN with RTN_ReplaceSignatureProbedEx() or RTN_ReplaceProbedEx() you should use RTN_IsSafeForProbedReplacementEx()
|
|
|
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 not guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.
|
|
||||||||||||
|
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_ReplaceSignatureProbedEx(). Note that this routine does not guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.
|
|
|
|
|
|
|
|
|
|
|
|
Open the given rtn. This must be called before RTN_InsHead() or RTN_InsertCall().
|
|
|
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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 or jump to the returned function pointer, which is a copy of the entry point that is not redirected.
Use RTN_IsSafeForProbedReplacement() to determine if a function is a suitable candidate for probed function replacement.
|
|
||||||||||||||||
|
Replace a routine in the application (replacedRtn) by another function defined in the Pintool (replacementFun) using probes. This API is an analog to RTN_ReplaceProbed.
Use RTN_IsSafeForProbedReplacementEx(rtn, mode) to determine if a function is a suitable candidate for probed function replacement.
|
|
||||||||||||||||
|
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.
Some restrictions apply using IARG_CONTEXT. See Instrumentation arguments for more information.
|
|
||||||||||||||||
|
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.
Use RTN_IsSafeForProbeReplacement() 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.
|
|
||||||||||||||||||||
|
Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes.
|
|
|
|
|
|
|
|
|
|
|
|
|
1.4.6