pub unsafe extern "C" fn dr_register_restore_state_event(
func: Option<unsafe extern "C" fn(drcontext: *mut c_void, tag: *mut c_void, mcontext: *mut dr_mcontext_t, restore_memory: bool_, app_code_consistent: bool_)>,
)Expand description
Registers a callback function for the machine state restoration event. DR calls \p func whenever it needs to translate a code cache machine context from the code cache to its corresponding original application context. DR needs to translate when instructions fault in the cache as well as when a suspended thread is examined or relocated for internal purposes.
If a client is only adding instrumentation (meta-code: see #instr_is_meta()) that does not reference application memory, and is not reordering or removing application instructions, then it need not register for this event. If, however, a client is modifying application code or is adding code that can fault, the client must be capable of restoring the original context.
When DR needs to translate a code cache context, DR recreates the faulting instruction’s containing fragment, storing translation information along the way, by calling the basic block and/or trace event callbacks with the \p translating parameter set to true. DR uses the recreated code to identify the application instruction (\p mcontext.pc) corresponding to the faulting code cache instruction. If the client asked to store translation information by returning #DR_EMIT_STORE_TRANSLATIONS from the basic block or trace event callback, then this step of re-calling the event callback is skipped and the stored value is used as the application address (\p mcontext.pc).
DR then calls the fault state restoration event to allow the client to restore the registers and application memory to their proper values as they would have appeared if the original application code had been executed up to the \p mcontext.pc instruction. Memory should only be restored if the \p restore_memory parameter is true; if it is false, DR may only be querying for the address (\p mcontext.pc) or register state and may not relocate this thread.
DR will call this event for all translation attempts, even when the register state already contains application values, to allow clients to restore memory.
The \p app_code_consistent parameter indicates whether the original application code containing the instruction being translated is guaranteed to still be in the same state it was when the code was placed in the code cache. This guarantee varies depending on the type of cache consistency being used by DR.
The client can update \p mcontext.pc in this callback. The client should not change \p mcontext.flags: it should remain DR_MC_ALL.
\note The passed-in \p drcontext may correspond to a different thread than the thread executing the callback. Do not assume that the executing thread is the target thread.