Struct NoopTool 

pub struct NoopTool;

The concrete empty subtool supported by this first typed snapshot domain. A tool that only injects the syscall it receives.

Trait Implementations

impl Debug for NoopTool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NoopTool

fn default() -> NoopTool

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for NoopTool

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for NoopTool

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Tool for NoopTool

type GlobalState = GlobalState

The type of the global half that goes along with this Local tool. By including this type, the Tool is actually a complete specification for an instrumentation tool.

type ThreadState = ()

Tool-state specific to each guest thread. If unset, this defaults to the unit type (), indicating that the tool does not have thread-level state.

fn stream_role() -> ToolStreamRole

Pure static role of this Tool’s stream, independent of Config booleans.

fn native_mm_ownership(_cfg: &Config) -> NativeMmOwnership

Declare native executor ownership for Tool code running in the observed address space. See [NativeMmOwnership] for the complete obligation.

fn subscriptions(_cfg: &Config) -> Subscription

Events the tool subscribes to. This is only called once for the entire tree. By default, all syscalls are traced (but CPUID/RDTSC instructions are not).

fn handle_syscall_event<'life0, 'life1, 'async_trait, T>( &'life0 self, guest: &'life1 mut T, call: Syscall, ) -> Pin<Box<dyn Future<Output = Result<i64, Error>> + Send + 'async_trait>>

where T: 'async_trait + Guest<Self>, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The tool receives an event from the guest, via the Reverie program instrumentation. A Reverie syscall handler fires in the moment before a guest syscall executes (like a “prehook”).

fn new(_pid: Pid, _cfg: &<Self::GlobalState as GlobalTool>::Config) -> Self

A common constructor that initializes state when a process is created, including the guest’s initial, root process. Of course, every process includes at least one thread, but the process level state is allocated before thread level-state for the process’s main thread is allocated.

fn observes_native_syscalls( _cfg: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Pure opt-in to synchronous final-native-call observations. The default performs no additional native queries or descriptor pinning.

fn observe_native_syscall( &self, _state: &Self::ThreadState, _facts: &dyn NativeSyscallFacts, _call: &NativeSyscallCall, ) -> Result<Option<Arc<dyn NativeSyscallObserver>>, Error>

Observe an actual request after all guest-capable preparation and before native issue. The provider cannot inject, resume or await. Returned cookies are retained by the backend, independently of callback lifetime.

fn facility_admission( _cfg: &<Self::GlobalState as GlobalTool>::Config, ) -> Result<(), Error>

Operational facility admission before global initialization or launch. Backends call this explicitly; subscription queries must remain pure.

fn reserved_input_requirement( _cfg: &<Self::GlobalState as GlobalTool>::Config, ) -> Option<ReservedInputRequirement>

Pure request for one fixed private input page, or no mapping at all. Backends additionally require serialized execution before enabling it.

fn thread_ownership( _cfg: &<Self::GlobalState as GlobalTool>::Config, ) -> ThreadOwnership

How this tool’s guest threads (children created via CLONE_THREAD) are owned. See [ThreadOwnership]. Called once per tree, like [Tool::subscriptions].

fn init_thread_state( &self, _child: Pid, _parent: Option<(Pid, &Self::ThreadState)>, ) -> Self::ThreadState

A guest process creates additional threads, which need their tool state initialized. This method returns a newly-allocated thread state. This method necessarily runs before the first instruction of a newly created guest thread.

fn on_initial_image_attached( &self, _tid: Pid, _thread_state: &mut Self::ThreadState, ) -> Result<(), Error>

Bind a fresh root state to an initial image whose launch exec has already completed before this Tool’s first registration.

fn handle_thread_start<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Similar to handle_syscall_event, except this traps the first instruction executed by a new thread. Typical uses of this method include delaying thread execution or running initialization actions (injections or rpcs).

fn on_thread_state_ready( &self, _tid: Pid, _global_state: &Self::GlobalState, _thread_state: &Self::ThreadState, ) -> Result<(), Error>

Observe this backend’s actual thread state after a successful handle_thread_start or handle_post_exec, before ordinary guest execution resumes. The ptrace backend supplies this synchronous hook; other backends must implement an equivalent owned lifecycle boundary before relying on it. The default performs no work.

fn handle_post_exec<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, ) -> Pin<Box<dyn Future<Output = Result<(), Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Called upon a successful execve. In handle_syscall_event, after injecting execve, it is not possible to run code after a successful execve because it never returns.

fn handle_exec_commit<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, ) -> Pin<Box<dyn Future<Output = Result<(), Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Called once an execve or execveat this Tool injected can no longer fail, on a backend that carries the exec out itself rather than through a host kernel exec (today the KVM backend). The backend has finished every step that could fail: it has read the path, the argument strings and the environment strings out of guest memory and validated the new image. The old image’s memory is still this guest’s, and the image is replaced only after this returns; handle_post_exec then follows in the new image, and the injection does not return. This is the point Linux’s begin_new_exec reaches past point_of_no_return, where exec_mmap runs exec_mm_release on the old address space (fs/exec.c), after do_execveat_common has copied the strings. A Tool that models what Linux does to the old image there, such as the robust-futex walk futex_exec_release makes, does it here, where the strings the new image receives can no longer change.

fn handle_cpuid_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, eax: u32, ecx: u32, ) -> Pin<Box<dyn Future<Output = Result<CpuIdResult, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

CPUID is trapped, the tool should implement this function to return [eax, ebx, ecx, edx].

fn handle_rdtsc_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, request: Rdtsc, ) -> Pin<Box<dyn Future<Output = Result<RdtscResult, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

rdtsc/rdtscp is trapped, the tool should implement this function to return the counter.

fn handle_signal_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, signal: Signal, ) -> Pin<Box<dyn Future<Output = Result<Option<Signal>, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Handles a guest’s signal before it is delivered to guest.

fn handle_raw_signal_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, signal: i32, ) -> Pin<Box<dyn Future<Output = Result<Option<i32>, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Handles a guest’s signal that [Signal] cannot name before it is delivered to the guest: a realtime signal, numbered 32 to 64 (glibc reserves 32 and 33, so SIGRTMIN() is 34). signal is the raw number. A backend reports every other signal to [Tool::handle_signal_event] (https://github.com/rrnewton/reverie/issues/207).

fn announce_signal_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, signal: i32, ) -> Pin<Box<dyn Future<Output = Result<Option<SignalAnnouncement>, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

The first half of a signal delivery reported in two phases, by a backend that knows of a delivery before the kernel dequeues the signal: an in-guest backend predicts the deliveries the kernel will make when its runtime returns to guest code. signal is the raw number, 1 to 64; any other is EINVAL.

fn commit_signal_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, _announcement: SignalAnnouncement, ) -> Pin<Box<dyn Future<Output = Result<(), Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

The second half of a two-phase delivery ([Tool::announce_signal_event]): the backend’s final read confirmed that the kernel delivers the announced signal when the runtime returns to guest code, and the Tool records the delivery. It must not wait for a turn in its schedule, and cannot suppress or replace the signal; an Err ends the run. The default refuses with EOPNOTSUPP.

fn withdraw_signal_event( &self, _thread_state: &mut Self::ThreadState, _announcement: SignalAnnouncement, )

Settles an announcement ([Tool::announce_signal_event]) whose delivery does not happen at the runtime’s return: another signal pushed it out. The signal stays pending in the kernel, to be announced again at a later return. It can only record: it gets the thread’s state and no access to the guest. The default records nothing.

fn exit_for_predicted_death<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, _status: ExitStatus, ) -> Pin<Box<dyn Future<Output = Result<(), Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Called once, after the commits of a final read that predicts the thread group’s death at the runtime’s return ([Tool::announce_signal_event], step 3): the last committed delivery is default-fatal, and status names the signal it dies of ([crate::PredictionEnd::Death]). status is not a wait status and must not be forwarded as one: its core flag is always false, because whether a core is written is known only when the kernel has tried (whether the default action asks for one is [crate::PredictedAction::Fatal]’s core_dump); the wait status a parent sees comes from the kernel at the reap. The backend has already withdrawn every announcement behind that delivery.

fn filter_unreported_signal<'life0, 'life1, 'async_trait, R>( &'life0 self, _rpc: &'life1 R, _signal: UnreportedSignal, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, R: 'async_trait + GlobalRPC<Self::GlobalState>, Self: 'async_trait,

Decides whether a signal that the backend passes to the guest without reporting it to [Tool::handle_signal_event] reaches the guest at all.

fn observes_sigreturns( _config: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Whether this Tool wants every guest rt_sigreturn reported to [Tool::handle_sigreturn], known from configuration alone. A backend whose capabilities say it reports sigreturns (BackendCapabilities::reports_sigreturns) then reports each one, except those the capability names; the ptrace backend stops at each guest rt_sigreturn only for such a Tool, and not while its gdbserver is attached. The default wants none, so a backend adds no stop.

fn in_guest_signal_delivery( _config: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Whether this Tool, known from configuration alone, takes an in-guest backend’s own signal delivery: while its runtime runs, the runtime blocks every signal it does not reserve, and at each return to guest code it predicts the kernel’s deliveries ([crate::predict_deliveries]), reports them in two phases ([Tool::announce_signal_event]), and makes a predicted death a scheduled one ([Tool::exit_for_predicted_death]). Such a backend reads it once, when its runtime starts in a process, and keeps its existing delivery when it does not hold.

fn enforces_serialized_execution( _config: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Whether this Tool, known from configuration alone, enforces a serialized-execution contract:

fn handle_sigreturn( &self, _thread_state: &mut Self::ThreadState, _report: SigreturnReport, )

Records one guest rt_sigreturn before it runs, for a Tool for which [Tool::observes_sigreturns] holds, on a backend that reports sigreturns. The backend then carries the call out exactly as it would without the hook.

fn note_unreported_signal( &self, _thread_state: &mut Self::ThreadState, _signal: &UnreportedSignal, _kept: bool, )

Records, in the taking thread’s state, one signal the backend passes on unreported, after [Tool::filter_unreported_signal] decided about it: kept is that hook’s answer. A kept signal is resumed into the guest, and Linux then delivers it, puts it back in the queue when the thread’s mask blocks it (a later stop can take the same instance again and pass it once more), queues a new instance with a kernel siginfo (a syscall stop), or discards it (an ignored signal, or a ptrace event stop or group stop); a dropped one is not resumed. So the hook sees passes, not deliveries. The signal’s [crate::UnreportedSignal::reason] says why it was not reported, so that a Tool can count what its signal callback never saw.

fn may_observe_signal_dequeues( _config: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Admits acknowledgment of real KVM pending removals before thread start. Other Tools retain their existing pending-state behavior by default.

fn requires_signal_control( _config: &<Self::GlobalState as GlobalTool>::Config, ) -> bool

Whether this run cannot proceed without process signal control, known from configuration alone.

fn handle_signal_dequeue<'life0, 'life1, 'async_trait, G>( &'life0 self, _guest: &'life1 mut G, _dequeue: SignalDequeue, ) -> Pin<Box<dyn Future<Output = Result<(), Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, G: 'async_trait + Guest<Self>, Self: 'async_trait,

Acknowledges one irreversible pending removal before any later Tool/guest work. The backend retains the journal entry until this returns success. An error is terminal; it is never a rollback or an ordinary guest syscall errno. Notifications are process-wide FIFO, but each runs on its removing Guest. Another owner can wait here before posting its next Tool scheduler request. An opted-in Tool must complete this acknowledgment without requiring that waiting owner to make progress or relinquish its scheduler token. FIFO sequencing alone does not establish deterministic event membership.

fn handle_structured_signal_event<'life0, 'life1, 'async_trait, T>( &'life0 self, guest: &'life1 mut T, event: SignalEvent, ) -> Pin<Box<dyn Future<Output = Result<Option<SignalEvent>, Errno>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Handles a structured guest signal immediately before a virtual backend delivers it.

fn handle_timer_event<'life0, 'life1, 'async_trait, T>( &'life0 self, _guest: &'life1 mut T, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait + Guest<Self>, Self: 'async_trait,

Handles a timer event generated by a call to Guest::set_timer

fn on_exit_thread<'life0, 'life1, 'async_trait, G>( &'life0 self, _tid: Pid, _global_state: &'life1 G, _thread_state: Self::ThreadState, _exit_status: ExitStatus, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, G: 'async_trait + GlobalRPC<Self::GlobalState>, Self: 'async_trait,

Called when a thread will exit shortly or has exited. That means there will be no more intercepted events on this thread.

fn on_exit_process<'life0, 'async_trait, G>( self, _pid: Pid, _global_state: &'life0 G, _exit_status: ExitStatus, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, G: 'async_trait + GlobalRPC<Self::GlobalState>, Self: 'async_trait,

Called when a process will exit shortly or has exited. That means there will be no more intercepted events on from any thread within this process.