Crate detcore 

Detcore is a Reverie tool that determinizes the execution of a process.

Backend-abstraction commandment

Detcore is a tool written against Reverie’s abstract instrumentation interface (the reverie crate). It depends only on those traits and types and is deliberately ignorant of how a guest is actually traced.

Detcore MUST NEVER depend on or import a concrete Reverie backend or support crate – any reverie-* crate other than the abstract reverie-core interface. Choosing and instantiating a backend, and running a detcore tool against it, is the sole responsibility of the hermit-cli package. There are no backend-specific hacks in detcore: any tracing-mechanism-specific behavior belongs behind the Reverie abstraction, not here.

Why: Hermit follows Reverie’s abstract model. A backend dependency in detcore would couple the determinism engine to one tracing mechanism and break the clean abstraction boundary that lets the same tool run over any backend.

The one allowed exception is test-only: detcore’s own integration tests (under detcore/tests/, wired via the reverie-ptrace dev-dependency) drive a real tracer to exercise the tool. That coupling never reaches the shipped library. This invariant is enforced in CI by scripts/check-detcore-backend-abstraction.sh.

Re-exports

pub use util::punch_out_print;

Modules

detlog

Module contains macroses that help tracing DETLOG entires for the purpose of verifiying determinism [‘detlog’] can be used to write a deterministic log entry at INFO level [’detlog_debug] can be use to write a deterministic log entry at DEBUG level

edit_distance

Schedule-alignment and edit-distance algorithms shared by Hermit tools.

logdiff

Everything to do with post-processing hermit/detcore logs.

netlink_route

Determinize the statistics counters carried by NETLINK_ROUTE link dumps.

preemptions

A datatype to abstract a record of thread preemptions, as generated during chaos mode execution.

random

Shared guest random-state and memory operations, independent of a backend. These synchronous operations preserve draws even when a later write fails.

types

Widely-shared type definitions.

util

Widely useful small utilities.

Macros

detlog

Macro used to encapsulate tracing should-be-deterministic information. This is currently at the INFO log level.

detlog_debug

Macro used to encapsulate tracing should-be-deterministic information. This variant is at a higher log level and requires that logging verbosity is set to DEBUG.

detlog_observed

Whether a detlog! record emitted at this point would reach anything.

Structs

BackendFailureCleanup

Separate terminal cleanup outcomes; neither replaces the backend failure.

Config

Configuration options for detcore.

Detcore

The detcore tool and its per-process state.

Digest

A SHA-256 content digest.

FileMetadata

The metadata associated with the file system view of a particular process.

GlobalState

Global state associated with the detcore tool.

Namespace

A namespace that may be unshared with Command::unshare.

ThreadState

The Detcore per-thread state.

ThreadStats

Various measurements of one guest thread’s execution. This is useful for printing context in logs as we go and printing a final summary.

UnsupportedSyscallError

Identifies an unsupported syscall that a backend must terminate without unwinding.

Enums

BlockingMode

How should we handle syscalls which may block, but are internal to the hermit container? These syscalls are determinizable, but there are multiple methods of doing so. These choices do not apply to blocking syscalls that wait for external conditions outside the container, such as network responses.

RunsPostFork

Which side of an ordinary fork/clone receives the first post-registration turn.

SchedHeuristic

Apply a specialized scheduling heuristic which may help exercise certain bugs.

Constants

CONFIG_FINGERPRINT_ENV

N.B. we don’t want to specify two different notions of “default”, so we use the Clap instance above. Environment variable carrying the coordinator’s config_wire_fingerprint to an out-of-process plugin.

DEFAULT_PRIORITY

The default priority for a thread. If chaos mode is not enabled, all threads have this priority.

FIRST_PRIORITY

The lowest/highest priority a thread can have.

LAST_PRIORITY

The last/lowest (numerically largest) priority a thread can have.

ROOT_DETPID

A convention of how we set up our PID namespace leaves us with a starting pid of 3.

Traits

RecordOrReplay

Helper trait.

Functions

all_pinned_syscalls

Every syscall in the pinned x86_64 table, including the final entry.

config_wire_fingerprint

format_unsupported_syscall_warning

Formats one deterministic warning for a set of unsupported syscall names.

is_deterministically_refused_syscall

Returns whether Detcore deterministically refuses sysno with a fixed errno when the fail-closed policy is active, without consulting the host.

is_determinized_syscall

Returns whether the audited runtime policy classifies sysno as Determinized — that is, Detcore either models the syscall with a handler or applies an explicit deterministic refusal policy to it.

is_kernel_keyring_syscall

Returns whether sysno is a kernel-keyring syscall (add_key, request_key, keyctl) that Detcore hides behind a deterministic CONFIG_KEYS-absent boundary under the default fail-closed policy.

is_strict_only_deterministic_refusal_syscall

Returns whether sysno is refused by the default fail-closed policy but forwarded under the explicit compatibility opt-out. The legacy strict_only name is retained for API compatibility.

is_unsupported_syscall

Returns whether the audited runtime policy classifies sysno as unsupported.

prepare_exec

Notifies the coordinator that guest is about to execve, recording the pre-exec address space mm and any file-descriptor blocking overrides. A backend that handles execve outside Detcore’s syscall handler must call this before the native syscall so the next image reconnects to the existing scheduler identity and logical clock.

thread_rng_from_parent

Generate a new thread-local PRNG from the parent’s PRNG state, mixing in the new DetTid for some deterministic entropy. This ensures sequentially-spawned threads get distinct PRNG states.

Type Aliases

DetTid

Deterministic “virtual” version of reverie::Tid

Priority

The user-accessible priority of a thread. Lowest runs first.