Skip to main content

Crate reverie_ptrace

Crate reverie_ptrace 

Source
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§

BrokenSignalApproval
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.
CapturedPrefix
Bytes actually read from a captured run, without a fabricated guest status.
CleanupAdmissionRefused
A new ptrace spawn was refused before Tool initialization, pipes, or fork.
CleanupUnconfirmed
A legacy wait reached its bound while its complete cleanup owner was retained.
InGuestRcbCounter
A retired-conditional-branch counter owned and read by the current thread.
InjectedCleanupUnconfirmed
An injected-mode run failed and its original guard could not confirm cleanup.
InjectedSyscallFrame
The register frame produced by e9tool’s state call-trampoline argument.
LegacyCleanupDiagnostics
Typed cleanup context attached to a uniquely owned legacy Tool error.
LegacyFailureProjection
A confirmed failed run could not move its primary into the legacy error.
PendingPtraceCleanup
Retained ordinary-owned cleanup, bound to its original ptracer thread. This includes failed static-injected legacy waits.
PendingSigtrapAtStep
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.
PtraceBackend
The reference Reverie backend: supervises the guest with ptrace + seccomp and keeps all tool state centralized in the tracer’s address space.
PtraceBackendStatsSnapshot
Stable counts of lifecycle transitions observed by the ptrace run loops.
PtraceBackendStatsSource
Live source for a ptrace backend activity snapshot.
PtraceCallbackDiagnostic
Original raw callback error and the lifecycle observations that followed it.
PtraceCleanupFailure
An actual later error, retained without replacing the run’s first cause.
PtraceRunFailure
A failed backend run. This is not a guest exit status.
PtraceTerminationHandle
A supervisor trigger obtained before consuming an ordinary tracer’s wait.
QueuedSigtrapAtStep
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.
ToolMemory
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.
ToolRunCompletion
Confirmed physical and consuming completion, including failed global state.
Tracer
Represents the tracer.
TracerBuilder
A builder for creating a tracer.
UnattributedSigtrap
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).
UnprovenPrivateSyscallCompletion
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).
UntracedStubSyscall
A guest made a syscall through the untraced syscall of Reverie’s private page, outside any injection, and took the SIGILL of the ud2 after it.
VdsoSyscallSite
One vDSO entry point rewritten for an in-guest syscall hook.

Enums§

CleanupLookupError
A quarantine lookup failed without removing or changing the retained owner.
GdbConnection
Specifies how the GDB server should listen for incoming connections.
PmuValidationError
Why this host’s performance counters failed validation. See reverie_ptrace::pmu_validation.
PtraceCallbackDecision
The decision made when the backend actually received a raw callback errno.
PtraceCallbackOutcome
The actual result subsequently obtained by the callback’s original owner.
PtraceCallbackRefusal
A typed refusal to resolve a raw callback errno against its held lifecycle.
PtraceCallbackStop
The actual kernel-derived class of the callback’s current held stop.
ToolRunOutcome
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 reverie crate so that this precise single-step guard and hermit’s detcore log-and-continue path emit the same token — one marker, one source. See crate::SKID_OVERSHOOT_MARKER for 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-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§

PtraceCleanupResource
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_margin as 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.