Expand description
Reverie ptrace backend.
Part of Hermit. For the command-line interface,
see hermit-run, and for background,
see Hermit: Deterministic Linux for Controlled Testing and Software Bug-finding.
Default features build on stable Rust. The optional nightly feature lets
spawn_fn_with_config clear libtest’s capture of printing macros before
forking; see that function’s documentation for stable test alternatives.
ptraced task implements Guest trait.
TracedTask implements handlers for ptrace events including
seccomp. Notable ptrace events include:
PTRACE_EVENT_EXEC: execvpe is about to return, tracee stopped
at entry point.
PTRACE_EVENT_FORK/VFORK/CLONE: when fork/vfork/clone is about
to return
PTRACE_EVENT_SECCOMP: seccomp stop caused by RET_TRACE
NB: we patch syscall in seccomp ptrace stop.
PTRACE_EVENT_EXIT: process is about to exit
signals: tracee’s pending signal stop.
Modules§
- decoder
- Routines for tracing and decoding instructions to a particular architecture
- regs
- Module provides cross platform access to common registers.
- testing
- Utilities that support constructing tests for Reverie Tools.
Macros§
- ret_
without_ perf - Concisely return when hardware perf counters are unavailable.
Structs§
- Broken
Signal Approval - A Tool’s signal callback approved a delivery (
Guest::deliver_signal) and then broke the approval: an injection or a register write changed the stop the checks read, it returned another signal or none, or it executed a program. Delivering would hand the guest something the checks did not cover, and suppressing would lose an approved signal, so Reverie ends the run. It is a Tool defect. - Captured
Prefix - Bytes actually read from a captured run, without a fabricated guest status.
- Cleanup
Admission Refused - A new ptrace spawn was refused before Tool initialization, pipes, or fork.
- Cleanup
Unconfirmed - A legacy wait reached its bound while its complete cleanup owner was retained.
- InGuest
RcbCounter - A retired-conditional-branch counter owned and read by the current thread.
- Injected
Cleanup Unconfirmed - An injected-mode run failed and its original guard could not confirm cleanup.
- Injected
Syscall Frame - The register frame produced by e9tool’s
statecall-trampoline argument. - Legacy
Cleanup Diagnostics - Typed cleanup context attached to a uniquely owned legacy Tool error.
- Legacy
Failure Projection - A confirmed failed run could not move its primary into the legacy error.
- Pending
Ptrace Cleanup - Retained ordinary-owned cleanup, bound to its original ptracer thread. This includes failed static-injected legacy waits.
- Pending
Sigtrap AtStep - A guest thread had SIGTRAP blocked and one pending when Reverie had to single-step it (https://github.com/rrnewton/hermit/issues/4409).
- PmuConfig
- Processor-specific PMU event settings used by precise ptrace timers.
- Ptrace
Backend - The reference Reverie backend: supervises the guest with
ptrace+seccompand keeps all tool state centralized in the tracer’s address space. - Ptrace
Backend Stats Snapshot - Stable counts of lifecycle transitions observed by the ptrace run loops.
- Ptrace
Backend Stats Source - Live source for a ptrace backend activity snapshot.
- Ptrace
Callback Diagnostic - Original raw callback error and the lifecycle observations that followed it.
- Ptrace
Cleanup Failure - An actual later error, retained without replacing the run’s first cause.
- Ptrace
RunFailure - A failed backend run. This is not a guest exit status.
- Ptrace
Termination Handle - A supervisor trigger obtained before consuming an ordinary tracer’s wait.
- Queued
Sigtrap AtStep - A guest thread had a SIGTRAP of its own queued, with a code that Reverie’s own traps also use, when Reverie had to single-step it.
- Tool
Memory - A stopped task’s memory as a Tool sees it. Reads are
Stopped’s; every write respects the target’s page permissions and never touches Reverie’s private page. - Tool
RunCompletion - Confirmed physical and consuming completion, including failed global state.
- Tracer
- Represents the tracer.
- Tracer
Builder - A builder for creating a tracer.
- Unattributed
Sigtrap - A guest thread took a SIGTRAP that no process sent and that no trap at its stop explains (https://github.com/rrnewton/reverie/issues/1268).
- Unproven
Private Syscall Completion - An injected syscall that Reverie ran between syscall stops, without a single-step, reached its exit stop with its return register equal to its own number and SIGSYS pending for the thread (or that state unreadable).
- Untraced
Stub Syscall - A guest made a syscall through the untraced
syscallof Reverie’s private page, outside any injection, and took the SIGILL of theud2after it. - Vdso
Syscall Site - One vDSO entry point rewritten for an in-guest syscall hook.
Enums§
- Cleanup
Lookup Error - A quarantine lookup failed without removing or changing the retained owner.
- GdbConnection
- Specifies how the GDB server should listen for incoming connections.
- PmuValidation
Error - Why this host’s performance counters failed validation. See
reverie_ptrace::pmu_validation. - Ptrace
Callback Decision - The decision made when the backend actually received a raw callback errno.
- Ptrace
Callback Outcome - The actual result subsequently obtained by the callback’s original owner.
- Ptrace
Callback Refusal - A typed refusal to resolve a raw callback errno against its held lifecycle.
- Ptrace
Callback Stop - The actual kernel-derived class of the callback’s current held stop.
- Tool
RunOutcome - The completed run, or the owner of cleanup which could not yet finish.
Constants§
- SKID_
OVERSHOOT_ MARKER - The single, greppable marker emitted to stderr whenever this backend detects
the RCB fallback overshooting its target. Re-exported from the
backend-agnostic
reveriecrate so that this precise single-step guard and hermit’s detcore log-and-continue path emit the same token — one marker, one source. Seecrate::SKID_OVERSHOOT_MARKERfor the full contract and the retry-harness safety property. 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-agnosticreveriecrate so every layer that can detect an overshoot — thereverie-ptraceprecise single-step guard and hermit’s detcorereport_rcb_overshootlog-and-continue path alike — emits exactly this token. A downstream harness then has a single string to grep for.
Traits§
- Ptrace
Cleanup Resource - A resource needed by a failed traced tree until cleanup is confirmed.
Functions§
- host_
pmu_ profile - Whether this host’s CPU has a PMU profile, the precondition for a ptrace timer. It only reads CPUID and the profile table: it builds no configuration, applies no override and writes nothing, so a tool can ask before it starts and disable or refuse its timeslice rather than run without the timer it asked for.
- is_
perf_ supported - Returns true if the current system configuration supports use of perf for hardware events.
- patch_
current_ vdso - Rewrite the calling process’s vDSO entry points into hookable syscalls.
- patch_
current_ vdso_ trapping - Rewrite the calling process’s vDSO entry points into trapping syscalls.
- patch_
current_ ⚠vdso_ trapping_ owned - Rewrite the actual kernel vDSO with trapping stubs through an owned permission operation, without a writable/executable interval.
- pmu_
validation - Whether this host’s performance counters passed Reverie’s validation: the counters work, and no known counting bug (such as AMD Zen SpecLockMap) is present. Reverie computes this once per process, on the first call here or the first timer, and only logs a failure. A tool that needs exact retired-branch counts, such as a deterministic one, can refuse to run on a host where this returns an error.
- quarantine_
cleanup_ resource - Permanently retain an original resource whose cleanup cannot be confirmed.
- set_
pmu_ config - Installs the PMU configuration used by subsequently created ptrace timers.
- set_
skid_ margin_ override - Records
skid_marginas the margin of the PMU configuration this process builds on first use, without reading this host’s CPUID: a tool can accept a margin before it knows whether the host has a profile, and a host with none is refused only when a timer needs one. - spawn_
fn - Spawn a function to be executed under instrumentation (rather than a subprocess indicated with a Command).
- spawn_
fn_ with_ config - Spawn a function with instrumentation rather than a subprocess indicated with a Command. This still creates a fresh child process and runs it under ptrace. However, the child process is a fork of the current process, and is used to run the indicated function.