Pin
|
Typedefs | |
typedef VOID(* | RTN_INSTRUMENT_CALLBACK) (RTN rtn, VOID *v) |
Enumerations | |
enum | PROBE_MODE { PROBE_MODE_DEFAULT = 0, PROBE_MODE_ALLOW_RELOCATION = (1 << 0), PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET = (1 << 1) } |
Functions | |
SEC | RTN_Sec (RTN x) |
RTN | RTN_Next (RTN x) |
RTN | RTN_Prev (RTN x) |
RTN | RTN_Invalid () |
BOOL | RTN_Valid (RTN x) |
const std::string & | RTN_Name (RTN x) |
BOOL | RTN_IsArtificial (RTN x) |
SYM | RTN_Sym (RTN x) |
UINT | RTN_DynamicMethodId (RTN x) |
AFUNPTR | RTN_Funptr (RTN x) |
UINT32 | RTN_Id (RTN x) |
PIN_CALLBACK | RTN_AddInstrumentFunction (RTN_INSTRUMENT_CALLBACK fun, VOID *val) |
USIZE | RTN_Range (RTN rtn) |
USIZE | RTN_Size (RTN rtn) |
RTN | RTN_IFuncResolver (RTN rtn) |
RTN | RTN_IFuncImplementation (RTN rtn) |
std::string | RTN_FindNameByAddress (ADDRINT address) |
RTN | RTN_FindByAddress (ADDRINT address) |
RTN | RTN_FindByName (IMG img, const CHAR *name) |
VOID | RTN_Open (RTN rtn) |
VOID | RTN_Close (RTN rtn) |
INS | RTN_InsHead (RTN rtn) |
INS | RTN_InsHeadOnly (RTN rtn) |
INS | RTN_InsTail (RTN rtn) |
UINT32 | RTN_NumIns (RTN rtn) |
VOID | RTN_InsertCall (RTN rtn, IPOINT action, AFUNPTR funptr,...) |
ADDRINT | RTN_Address (RTN rtn) |
RTN | RTN_CreateAt (ADDRINT address, std::string name) |
BOOL | RTN_IsDynamic (RTN rtn) |
BOOL | RTN_IsSafeForProbedInsertion (RTN rtn) |
BOOL | RTN_IsSafeForProbedInsertionEx (RTN rtn, PROBE_MODE mode) |
BOOL | RTN_IsSafeForProbedReplacement (RTN rtn) |
BOOL | RTN_IsSafeForProbedReplacementEx (RTN rtn, PROBE_MODE mode) |
AFUNPTR | RTN_ReplaceSignatureProbed (RTN replacedRtn, AFUNPTR replacementFun,...) |
AFUNPTR | RTN_ReplaceSignatureProbedEx (RTN replacedRtn, PROBE_MODE mode, AFUNPTR replacementFun,...) |
BOOL | RTN_InsertCallProbed (RTN orgRtn, IPOINT action, AFUNPTR funptr,...) |
BOOL | RTN_InsertCallProbedEx (RTN orgRtn, IPOINT action, PROBE_MODE mode, AFUNPTR funptr,...) |
AFUNPTR | RTN_Replace (RTN replacedRtn, AFUNPTR replacementFun) |
AFUNPTR | RTN_ReplaceSignature (RTN replacedRtn, AFUNPTR replacementFun,...) |
AFUNPTR | RTN_ReplaceProbed (RTN replacedRtn, AFUNPTR replacementFun) |
AFUNPTR | RTN_ReplaceProbedEx (RTN replacedRtn, PROBE_MODE mode, AFUNPTR replacementFun) |
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.
APIs from this group are available in any thread, including any internal thread spawned by the tool.
Iteration idioms:
typedef VOID(* RTN_INSTRUMENT_CALLBACK) (RTN rtn, VOID *v) |
Call back function used to instrument routines
enum PROBE_MODE |
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.
PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET
In PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET mode Pin will allow inserting a probe on top of what might be a potential branch target.
A potential branch target are bytes that come after an unconditional branch.
If Pin can identify direct jumps to those bytes then it is considered a branch target and instrumentation is rejected.
Otherwise they are considered a potential branch target.
It is possible, by using PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET mode, to place a probe on those bytes.
However please be advised that if there is a branch to this address somewhere in the application then the application will crash as the bytes of the original instruction in this address have changed.
Please note it is possible to combine two enum values in the call, i.e. (PROBE_MODE_ALLOW_RELOCATION | PROBE_MODE_ALLOW_POTENTIAL_BRANCH_TARGET)
PIN_CALLBACK RTN_AddInstrumentFunction | ( | RTN_INSTRUMENT_CALLBACK | fun, |
VOID * | val | ||
) |
Add a function used to instrument at routine granularity
fun | Instrumentation function for routines |
val | Passed as the second argument to the instrumentation function |
ADDRINT RTN_Address | ( | RTN | rtn | ) |
VOID RTN_Close | ( | RTN | rtn | ) |
Close the given rtn. This must be called before opening a new rtn.
RTN RTN_CreateAt | ( | ADDRINT | address, |
std::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 a given address and assign a name to it. When it is done, the routine can be searched for by address or by name. The information is kept in Pin as long as the containing image is in memory.
The address should point to code (an 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 the end of the code section. Close any open routine before calling this interface with RTN_Close().
[in] | address | The start address of the new routine |
[in] | name | The assigned name of the new routine |
[in] | isIFunc | True if the symbol's type which corresponds to the new routine location is ifunc symbol. |
UINT RTN_DynamicMethodId | ( | RTN | x | ) |
RTN RTN_FindByAddress | ( | ADDRINT | address | ) |
Address | Memory address that corresponds to the RTN |
RTN RTN_FindByName | ( | IMG | img, |
const CHAR * | name | ||
) |
Img | Image in which to search for RTN |
Name | Name of the RTN to search in IMG |
std::string 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.
Address | Memory address that corresponds to the RTN |
AFUNPTR RTN_Funptr | ( | RTN | x | ) |
@convert an rtn to a funptr
UINT32 RTN_Id | ( | RTN | x | ) |
Pin assigns each routine a unique ID. The ID is globally unique, i.e. an ID will not appear in two images. If the same routine name exists in two different images (i.e. they are in different addresses), each will have a different ID. If an image is unloaded and then reloaded, the routines within it will most likely have different IDs than before.
RTN RTN_IFuncImplementation | ( | RTN | rtn | ) |
RTN RTN_IFuncResolver | ( | RTN | rtn | ) |
VOID RTN_InsertCall | ( | RTN | rtn, |
IPOINT | action, | ||
AFUNPTR | funptr, | ||
... | |||
) |
Insert call relative to a rtn.
rtn | Routine to instrument |
action | Use IPOINT_BEFORE to call funptr before execution, or IPOINT_AFTER for immediately before the return NOTE: IPOINT_AFTER is implemented by instrumenting each return instruction in a routine. Pin tries to find all return instructions, but success is not guaranteed |
funptr | Analysis function to call |
... | IARG_TYPE. Arguments to pass to funptr |
BOOL RTN_InsertCallProbed | ( | RTN | orgRtn, |
IPOINT | action, | ||
AFUNPTR | funptr, | ||
... | |||
) |
Insert a call to an analysis routine relative to a RTN.
orgRtn | the application routine to instrument |
action | use IPOINT_BEFORE or IPOINT_AFTER to call funptr before or after execution. |
funptr | the analysis function |
... | IARG_TYPE. 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.
Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.
BOOL RTN_InsertCallProbedEx | ( | RTN | orgRtn, |
IPOINT | action, | ||
PROBE_MODE | mode, | ||
AFUNPTR | funptr, | ||
... | |||
) |
Insert a call to an analysis routine relative to a RTN.
orgRtn | the application routine to instrument |
action | use IPOINT_BEFORE or IPOINT_AFTER to call funptr before or after execution. |
mode | |
funptr | the analysis function |
... | IARG_TYPE. 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.
Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.
INS RTN_InsHead | ( | RTN | rtn | ) |
You must call RTN_Open() before the first time this is called for an rtn
Note that Pin find the INSs of the RTN through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. If you need completely reliable instructions, use normal JIT time instrumentation, where Pin can guarantee that the instructions are correct.
INS RTN_InsHeadOnly | ( | RTN | rtn | ) |
You must call RTN_Open() before the first time this is called for an rtn
Note that tools should use this function when they want to examine ONLY the first INS of an RTN, and NO others. The INS_Next() of the INS returned by this function may be INS_Invalid() even if there are more INSs in the RTN. Tools that want to examine further INSs of the RTN should call the RTN_InsHead() function instead of this one.
INS RTN_InsTail | ( | RTN | rtn | ) |
You must call RTN_Open() before the first time this is called for an rtn
Note that Pin finds the INSs of the RTN through static discovery, so Pin does not guarantee that it will find all the INSs in the RTN. If you need completely reliable instructions, use normal JIT time instrumentation, where Pin can guarantee that the instructions are correct.
RTN RTN_Invalid | ( | ) |
BOOL RTN_IsArtificial | ( | RTN | x | ) |
An artificial RTN is an RTN which was introduced by PIN for internal management and does not really represent an actual routine in the application. For example, PIN might cover code pieces that are not associated with symbols with artificial RTNs in order to meet the requirement that all code must be covered with RTNs.
BOOL RTN_IsDynamic | ( | RTN | rtn | ) |
A routine can be marked as dynamically created using Jit Profiling API only.
BOOL RTN_IsSafeForProbedInsertion | ( | RTN | rtn | ) |
Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise.
This API is expected to be deprecated in future Pin versions. It is recommended to evaluate the return value of RTN_InsertCallProbed() instead. If you want to replace the given RTN with RTN_ReplaceSignatureProbed() or RTN_ReplaceProbed(), please refer to RTN_IsSafeForProbedReplacement()
rtn | the application routine to be replaced. |
PIN_StartProgramProbed() must be used when using this API.
BOOL RTN_IsSafeForProbedInsertionEx | ( | RTN | rtn, |
PROBE_MODE | mode | ||
) |
Return TRUE if the given RTN is a candidate for function insertion using probes, and FALSE otherwise.
This API is expected to be deprecated in future Pin versions. It is recommended to evaluate the return value of RTN_InsertCallProbedEx() instead. If you want to replace the given RTN with RTN_ReplaceSignatureProbedEx() or RTN_ReplaceProbedEx(), please refer to RTN_IsSafeForProbedReplacementEx()
rtn | the application routine to be replaced. |
mode | instrumentation mode, see PROBE_MODE |
PIN_StartProgramProbed() must be used when using this API.
BOOL 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 not guarantee it is safe to place a probe, it merely indicates that certain conditions are not present.
rtn | the application routine to be replaced. |
PIN_StartProgramProbed() must be used when using this API.
BOOL RTN_IsSafeForProbedReplacementEx | ( | RTN | rtn, |
PROBE_MODE | mode | ||
) |
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.
rtn | the application routine to be replaced. |
mode | instrumentation mode, see PROBE_MODE |
PIN_StartProgramProbed() must be used when using this API.
const std::string& RTN_Name | ( | RTN | x | ) |
RTN RTN_Next | ( | RTN | x | ) |
UINT32 RTN_NumIns | ( | RTN | rtn | ) |
Compute number of static INSs inside RTN.
VOID RTN_Open | ( | RTN | rtn | ) |
Open the given rtn. This must be called before RTN_InsHead() or RTN_InsertCall() or RTN_InsHeadOnly()
RTN RTN_Prev | ( | RTN | x | ) |
USIZE RTN_Range | ( | RTN | rtn | ) |
AFUNPTR RTN_Replace | ( | RTN | replacedRtn, |
AFUNPTR | replacementFun | ||
) |
Replace a routine in the application (replacedRtn) by another function defined in the Pin tool (replacementFun). The replacement function is not instrumented. The signature of the replacement function must be exactly the same as the replaced application routine. However, see RTN_ReplaceSignature(), which allows you to have a different signature.
This API returns a function pointer to the replaced application routine's entry point, which allows the replacement function to call back to the original routine. If you do this, be sure to call the original routine via PIN_CallApplicationFunction(). Directly calling the application's function pointer from the replacement function may result in a crash.
This API works in JIT mode, so you must start the application with PIN_StartProgram().
[in] | replacedRtn | The application routine to be replaced. |
[in] | replacementFun | The replacement function. |
AFUNPTR 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 or jump to the returned function pointer, which is a copy of the entry point that is not redirected.
replacedRtn | the application routine to be replaced. |
replacementFun | the replacement function |
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.
AFUNPTR RTN_ReplaceProbedEx | ( | RTN | replacedRtn, |
PROBE_MODE | mode, | ||
AFUNPTR | replacementFun | ||
) |
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.
replacedRtn | the application routine to be replaced. |
mode | instrumentation mode, see PROBE_MODE |
replacementFun | the replacement function |
PIN_StartProgramProbedEx() must be used when using this API.
Use RTN_IsSafeForProbedReplacementEx(rtn, mode) to determine if a function is a suitable candidate for probed function replacement.
AFUNPTR RTN_ReplaceSignature | ( | RTN | replacedRtn, |
AFUNPTR | replacementFun, | ||
... | |||
) |
Replace a routine in the application (replacedRtn) by another function defined in the Pin tool (replacementFun). The replacement function is not instrumented. The signature of the replacement function can be different from the replaced application routine's signature, which allows the tool to pass more (or fewer) parameters than were passed to the original application routine.
The IARG_ORIG_FUNCPTR argument is especially useful because it allows the replacement function to call back to the original routine. Other useful arguments are IARG_FUNCARG_ENTRYPOINT_VALUE, which allows you to pass a parameter from the original routine to the replacement function, and IARG_PROTOTYPE, which allows you define the prototype of the original routine. The IARG_PROTOTYPE argument is recommended whenever you use IARG_FUNCARG_ENTRYPOINT_VALUE. It is required if the original routine has any parameters that are not simple integral or pointer values.
If your replacement function calls back to the original application routine, be sure to do so via PIN_CallApplicationFunction(). Directly calling the application's function pointer from the replacement function may result in a crash.
This API works in JIT mode, so you must start the application with PIN_StartProgram().
[in] | replacedRtn | The application routine to be replaced. |
[in] | replacementFun | The replacement function. |
[in] | ... | Any additional arguments define parameters that are passed to the replacement function, see IARG_TYPE. This list must end with IARG_END. |
AFUNPTR RTN_ReplaceSignatureProbed | ( | RTN | replacedRtn, |
AFUNPTR | replacementFun, | ||
... | |||
) |
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.
orgRtn | the application routine to be replaced. |
replacementFunptr | the replacement function |
... | IARG_TYPE. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END. |
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. IARG_THREAD_ID is not supported.
AFUNPTR RTN_ReplaceSignatureProbedEx | ( | RTN | replacedRtn, |
PROBE_MODE | mode, | ||
AFUNPTR | replacementFun, | ||
... | |||
) |
Replace a routine in the application (orgRtn) by another function defined in the Pintool (replacementFunptr) using probes.
replacedRtn | the application routine to be replaced. |
mode | instrumentation mode, see PROBE_MODE |
replacementFun | the replacement function |
... | IARG_TYPE. One IARG_TYPE must be IARG_PROTOTYPE, and the list must end with IARG_END. |
Use RTN_IsSafeForProbedReplacementEx() to determine if a function is a suitable candidate for probed function replacement.
SEC RTN_Sec | ( | RTN | x | ) |
USIZE RTN_Size | ( | RTN | rtn | ) |
SYM RTN_Sym | ( | RTN | x | ) |
BOOL RTN_Valid | ( | RTN | x | ) |