pub unsafe extern "C" fn drmgr_register_bb_instrumentation_event(
analysis_func: drmgr_analysis_cb_t,
insertion_func: drmgr_insertion_cb_t,
priority: *mut drmgr_priority_t,
) -> bool_Expand description
Registers callback functions for the second and third instrumentation stages: application analysis and instrumentation insertion. drmgr will call \p func as the second of five instrumentation stages for each dynamic application basic block.
The first stage performed any changes to the original application code, and later stages are not allowed to change application code. Application analysis passes in the second stage are not allowed to add to or change the instruction list other than adding label instructions, and are intended for analysis of application code either for immediate use or for use by the third stage. Label instructions can be used to store data for use in subsequent stages with custom tags inserted as notes via drmgr_reserve_note_range() and custom data stored via instr_get_label_data_area().
The third instrumentation stage is instrumentation insertion. Unlike the other stages, this one passes only one instruction to the callback, allowing each registered component to act on one instruction before moving to the next instruction. Instrumentation insertion passes are allowed to insert meta instructions only immediately prior to the passed-in instruction: not before any prior non-meta instruction nor after any subsequent non-meta instruction. They are not allowed to insert new non-meta instructions or change existing non-meta instructions. Because other components may have already acted on the instruction list, be sure to ignore already existing meta instructions.
The \p analysis_func and \p insertion_func share the same priority. Their user_data parameter can be used to pass data from the analysis stage to the insertion stage.
All instrumentation must follow the guidelines for #dr_register_bb_event().
On ARM, for the instrumentation insertion event, drmgr does not set the predicate for all meta instructions inserted by each callback to match the predicate of the corresponding application instruction. It is the client’s responsibility to set proper predicates for all meta instructions. At the end of all instrumentation stages, drmgr automatically adds enough IT instructions to create legal IT blocks in Thumb mode.
\return false if the given priority request cannot be satisfied (e.g., \p priority->before is already ordered after \p priority->after) or the given name is already taken.
@param[in] analysis_func The analysis callback to be called for the second stage. Can be NULL if insertion_func is non-NULL, in which case the user_data passed to insertion_func is NULL and drmgr_unregister_bb_insertion_event() must be used to unregister. @param[in] insertion_func The insertion callback to be called for the third stage. Can be NULL if analysis_func is non-NULL. @param[in] priority Specifies the relative ordering of both callbacks. Can be NULL, in which case a default priority is used.
\note It is possible for meta instructions to be present and passed to the analysis and/or insertion stages, if they were added in the app2app or analysis stages. While this is discouraged, it is sometimes unavoidable, such as for drwrap_replace_native(). We recommend that all instrumentation stages check for meta instructions (and ignore them, typically).