Crate reverie 

Reverie is a user space system-call interception framework for Linux. It can be used to intercept, modify, or elide a syscall before the kernel executes it.

Reverie is the instrumentation layer for Hermit. For the command-line interface, see hermit-run. For background, see Hermit: Deterministic Linux for Controlled Testing and Software Bug-finding.

Reverie consists of a family of crates:

• reverie (this one): Primarily provides the Tool trait interface that Reverie tools must implement to intercept syscalls. It also defines the Backend trait, which is the contract a backend implementation must satisfy in order to run an arbitrary tool.
• reverie-ptrace: The backend that uses ptrace to intercept syscalls. This is currently the only non-experimental backend and is the reference implementation of the Backend contract. In the future, we may have a backend that uses binary rewriting to intercept syscalls within the guest process.
• reverie-syscalls: Provides typed syscalls, which provide safer and more ergonomic access to the arguments of a syscall. Also provides pretty printing of syscalls and their arguments.

The rest of the reverie-* crates are used in service to the above crates.

Tools and backends

There are two sides to every Reverie program:

• A Tool decides what to do when the guest hits a trappable event. This is what most users write; see the Tool trait for the full handler API.
• A Backend decides how those events are trapped and how the tool is run against a live guest process tree (spawning, syscall interception, hosting global state, teardown). reverie-ptrace is the reference backend; the Backend trait spells out exactly what any alternative backend must provide.

For examples of usage, please see the reverie-examples folder.

See also README.md for a high-level overview of Reverie.

Re-exports

pub use reverie_process as process;

pub use reverie_syscalls as syscalls;

pub use backend_stats::*;

Modules

backend_stats

Common, lazily collected statistics for Reverie backends.

pmu

Processor-specific PMU event settings shared by execution backends.

vdso

Every function the Linux vDSO exports, with what it reads and what a backend does with it.

Structs

Auxv

Represents the auxv table of a process.

BackendChildWaitEvent

A backend-observed child waitability decision.

BackendFailure

The location of a fatal backend failure. The backend retains its typed cause; this notification only ends dependent waits and must not invent guest status. Host-side ordinary-ptrace capture failures use the run root’s PID/TID with a ptrace stdout capture or ptrace stderr capture phase. Those locations identify the host run owner, not an inferred guest writer or guest failure.

BackendProcessRetirement

Final descriptor cleanup and worker joins for one exact process lifetime.

BackendSignalControl

The single run-level installation carries both publication and selection.

Backtrace

A backtrace is a list of stack frames. These stack frames may have originated from a remote process.

CallbackSignalSite

Exact callback and unconsumed syscall boundary eligible for parked observation.

ChildExitCompletion

A scheduler-authorized terminal child transition.

ChildExitPublication

Receipt for an irreversible child-completion publication.

CpuIdResult

CPUID result. Low-level data-structure to store result of cpuid instruction.

DequeueId

Identity allocated once at removal, never at publication or delivery.

DetlogMemoryRegion

A guest-address-space memory region a backend can expose for deterministic memory-map logging (--detlog-stack / --detlog-heap).

DispatchCounters

Counts of intercepted guest events by the route that delivered them.

DispatchStats

The shared end-of-run dispatch record for one backend run.

Errno

Frame

A stack frame.

IntoGuest

Wraps a Guest<T> such that it implements Guest<U>.

Location

The location of a symbol.

ParkedObservationLease

Scheduler-issued identity echoed by RPCs during one nested observation.

ParkedSignalFailureContext

Identifies a retained effect ledger through caught handoff and cancellation.

ParkedSignalObservation

Actual observation effects; this does not settle any scheduler wait.

Pid

A process ID (PID).

PreparedSignalToken

Backend-owned single-use selected event, awaiting frame/default-action delivery.

PrettyBacktrace

A backtrace with file and line information. This is more heavy-weight than a normal backtrace.

PrettyFrame

A stack frame with debugging information.

ProcessAlarmSignalReceipt

State captured when a process-alarm pending operation commits.

ProcessDispatchStats

The counters attributed to one guest process.

ProcessSignalPublication

An actual process-pending publication; it says nothing about recipient masks.

RdtscResult

Result returned by Tool::handle_rdtsc_event.

RegDisplayOptions

Options for how libc::user_regs_struct can be formatted for the std::fmt::Display implementation.

SignalBoundaryReceipt

A consuming notification, not an ordinary scheduler resource request.

SignalDeliveryPermit

Authorization for one task’s actual return-to-user selection.

SignalDequeue

An irreversible pending-state removal with its original complete metadata.

SignalEvent

A signal selected for deterministic delivery to one stopped guest thread.

SignalProcessId

A process lifetime, independent of PID reuse and disposition generations.

SignalRecipient

One eligible task in an authoritative, process-transaction snapshot.

SignalTaskIdentity

A live task identity, available before its first guest instruction.

SiteCounters

Counts of distinct instrumentation sites.

Subscription

A set of events to subscribe to.

Symbol

A symbol from a frame.

Enums

BackendChildWaitState

A child state and waitability decision observed by an execution backend.

BackendSignalControlMode

Whether the Tool takes responsibility for recipient selection.

ChildExitPublicationEffect

Effect committed by one child-completion publication.

ChildExitPublicationResult

Complete result of publishing one scheduler-authorized child completion.

ChildExitSignalDisposition

Receiver state after accepting one process-directed child-exit event.

ChildExitSignalErrorKind

Why a child-exit event was refused before changing backend state.

ChildExitSignalOutcome

Complete result of a backend’s child-exit pending-state operation.

DetlogRegionKind

The logical kind of a guest memory region reported by Guest::detlog_memory_regions.

Error

A general error.

ExitStatus

Describes the result of a process after it has exited.

PendingDomain

The pending queue actually selected, preserved through Tool replacement.

ProcessAlarmSignalDisposition

Current disposition of a process-pending alarm, before Tool filtering.

ProcessAlarmSignalErrorKind

Why a process-alarm operation was refused without changing backend state.

ProcessAlarmSignalOutcome

Complete result of publishing a process-pending SIGALRM.

ProcessSignalPublicationResult

Publication errors retain the boundary between no effect and committed effect.

Rdtsc

Rdtsc/Rdtscp request.

Signal

Types of operating system signals

SignalBoundaryOutcome

Actual completion of a permitted boundary, before guest entry.

SignalConsumer

The operation that actually removed a pending event.

SignalObservationFailure

Distinguishes refusal from a failure after irreversible removal.

SignalObservationStep

Committed selection outcomes, in their real dequeue order.

SignalObservationStop

Why a sequential parked observation finished.

SignalTarget

Identifies both the selected guest task and whether a signal was originally process-directed or thread-directed.

ThreadOwnership

Who owns a guest thread: the single axis that governs both how the thread executes and who owns its thread-synchronization primitives (futex, CLONE_CHILD_CLEARTID).

TimerSchedule

Options for scheduling a timer event.

Constants

DISPATCH_STATS_SCHEMA_VERSION

Version of the serialized DispatchStats layout.

PERF_EVENT_SIGNAL

signal used by reverie perf counter timer.

SIGNAL_INFO_SIZE

Size of Linux’s userspace siginfo_t representation on supported targets.

SKID_OVERSHOOT_MARKER

The single, greppable marker emitted to stderr whenever an RCB-fallback preemption path overshoots its programmed target by more than the configured skid margin. This is the one canonical shape of the overshoot signal, and it lives in the backend-agnostic reverie crate so every layer that can detect an overshoot — the reverie-ptrace precise single-step guard and hermit’s detcore report_rcb_overshoot log-and-continue path alike — emits exactly this token. A downstream harness then has a single string to grep for.

Traits

Backend

A Reverie backend: a swappable implementation of process supervision and event interception, equivalent in role to reverie-ptrace.

GlobalRPC

A handle to send messages to the global state (potentially a remote, inter-process communication).

GlobalTool

The global half of a complete Reverie tool.

Guest

A representation of a guest task (thread).

ProcessSignalControl

Shared run-owned facade. Implementations must not retain a Tool or Guest.

RegDisplay

Trait providing reusable display formatting for registers

Stack

A low-level stack which stores untyped (but Sized) values

Tool

A trait that every Reverie tool must implement. The primary function of the tool specifies how syscalls and signals are handled.

Functions

record_skid_overshoot

Record that a skid overshoot was detected. Called at every overshoot-detection site (the reverie-ptrace precise single-step guard and hermit’s detcore report_rcb_overshoot log-and-continue path) alongside the SKID_OVERSHOOT_MARKER emission. Cheap and lock-free; the overshoot path is rare.

take_skid_overshoot_count

Atomically read and reset the recorded skid-overshoot count. The in-process supervisor calls this after each verify run to attribute overshoots per run; resetting to zero keeps the two runs’ counts disjoint.

Type Aliases

Never

Never type is a stopgap for the unstable ! type (i.e., the never type).

Tid

The identifier for a specific thread, corresponding to the output of gettid. In many cases, Linux blurs the Pid/Tid distinction, but Reverie should consistently use TIDs when referring to threads, and Pids when referring to shared address spaces that (typically) correspond to processes.

Attribute Macros

backend

Required for impl Backend for MyBackend blocks.

global_tool

Required for impl GlobalTool for MyGlobalTool blocks.

tool

Required for impl Tool for MyTool blocks.