Skip to main content

detcore/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! Detcore is a Reverie tool that determinizes the execution of a process.
10//!
11//! # Backend-abstraction commandment
12//!
13//! Detcore is a *tool* written against Reverie's **abstract** instrumentation
14//! interface (the `reverie` crate). It depends only on those traits and types
15//! and is deliberately ignorant of how a guest is actually traced.
16//!
17//! Detcore MUST NEVER depend on or import a concrete Reverie backend or support
18//! crate -- any `reverie-*` crate other than the abstract `reverie-core`
19//! interface. Choosing and instantiating a backend, and running a detcore tool
20//! against it, is the sole responsibility of the `hermit-cli` package. There
21//! are no backend-specific hacks in detcore: any tracing-mechanism-specific
22//! behavior belongs behind the Reverie abstraction, not here.
23//!
24//! Why: Hermit follows Reverie's abstract model. A backend dependency in
25//! detcore would couple the determinism engine to one tracing mechanism and
26//! break the clean abstraction boundary that lets the same tool run over any
27//! backend.
28//!
29//! The one allowed exception is test-only: detcore's own integration tests
30//! (under `detcore/tests/`, wired via the `reverie-ptrace` **dev-dependency**)
31//! drive a real tracer to exercise the tool. That coupling never reaches the
32//! shipped library. This invariant is enforced in CI by
33//! `scripts/check-detcore-backend-abstraction.sh`.
34
35#![deny(clippy::all)]
36#![deny(missing_docs)]
37#![allow(clippy::uninlined_format_args)]
38
39mod config;
40mod consts;
41mod cpuid;
42mod digest;
43mod dirents;
44#[cfg(feature = "dispatch-observer")]
45pub mod dispatch_observer;
46/// Schedule-alignment and edit-distance algorithms shared by Hermit tools.
47#[allow(missing_docs)]
48pub mod edit_distance;
49pub mod exec_record;
50pub mod exit_dependencies;
51mod fatal_core;
52mod fd;
53mod fifo_peer;
54pub mod guest_log;
55mod host_inputs;
56pub mod in_guest_launch;
57pub mod in_guest_site_patching;
58mod io_buffers;
59mod iovecs;
60#[allow(unused)]
61mod ivar;
62pub mod logdiff;
63pub mod machine;
64mod memory;
65pub mod native_exec;
66pub mod netlink_route;
67pub mod nonwaiting_write;
68mod pipe_wake;
69mod procfs;
70mod procfs_inode;
71mod procmaps;
72pub mod race_probe;
73pub mod random;
74mod record_or_replay;
75pub mod refused_signal_controls;
76mod resources;
77mod scheduler;
78mod shared_open_files;
79mod sigalrm_phase1;
80mod signal_state;
81mod sock_diag;
82mod stat;
83mod syscall_classification;
84mod syscall_time;
85mod syscalls;
86#[cfg(test)]
87mod test_pages;
88mod tool_global;
89mod tool_local;
90pub mod util;
91
92pub mod detlog;
93pub mod preemptions;
94pub mod types;
95use std::fs::File;
96use std::io::Write;
97use std::os::unix::io::RawFd;
98use std::sync::Arc;
99use std::sync::Mutex;
100use std::time::Duration;
101
102pub use config::BlockingMode;
103pub use config::CONFIG_FINGERPRINT_ENV;
104pub use config::Config;
105pub use config::FatalCoreCapture;
106pub use config::InheritedSeccomp;
107pub use config::LITEINST_CONFIG_FINGERPRINT_ENV;
108pub use config::LaunchImage;
109pub use config::RunsPostFork;
110pub use config::SchedHeuristic;
111pub use config::config_fingerprint_mismatch;
112pub use config::config_wire_fingerprint;
113pub use config::decode_backend_config_json;
114pub use config::encode_backend_config_json;
115pub use config::from_legacy_backend_json;
116pub use config::to_legacy_backend_json;
117// AUTONOMOUS-BOT-IMPLEMENTED
118// TODO-HUMAN-REVIEW(PR-1120): Review the public canonical Detcore root identity.
119pub use consts::ROOT_DETPID;
120use detcore_model::bundled_signal_facts;
121pub use digest::Digest;
122#[cfg(test)]
123use rand::RngExt as _;
124use raw_cpuid::CpuIdResult;
125use raw_cpuid::cpuid;
126pub use record_or_replay::RecordOrReplay;
127use reverie::Error;
128use reverie::ExitStatus;
129use reverie::GlobalRPC;
130use reverie::Guest;
131use reverie::Pid;
132use reverie::Rdtsc;
133use reverie::RdtscResult;
134use reverie::RegDisplay;
135use reverie::Signal;
136use reverie::Subscription;
137use reverie::Tid;
138use reverie::TimerSchedule;
139use reverie::Tool;
140pub use reverie::process::Namespace;
141use reverie::syscalls::CloneFlags;
142use reverie::syscalls::Displayable;
143use reverie::syscalls::EpollCreate1;
144use reverie::syscalls::Errno;
145use reverie::syscalls::InotifyInit1;
146use reverie::syscalls::MemoryAccess;
147use reverie::syscalls::Syscall;
148use reverie::syscalls::SyscallInfo;
149use reverie::syscalls::Sysno;
150pub use scheduler::Priority;
151pub use scheduler::TerminalDeadlockHook;
152pub use scheduler::runqueue::DEFAULT_PRIORITY;
153pub use scheduler::runqueue::FIRST_PRIORITY;
154pub use scheduler::runqueue::LAST_PRIORITY;
155pub use scheduler::set_terminal_deadlock_hook;
156pub use tool_global::BackendFailureCleanup;
157pub use tool_global::GlobalState;
158use tool_global::ThreadDeregistration;
159use tool_global::acknowledge_robust_list_exit_time;
160pub use tool_global::cancel_exec;
161use tool_global::create_child_thread;
162use tool_global::create_vfork_child_thread;
163use tool_global::deregister_thread;
164pub use tool_global::format_unsupported_syscall_warning;
165pub use tool_global::native_exec as native_exec_control;
166pub use tool_global::prepare_exec;
167use tool_global::report_unsupported_syscall;
168use tool_global::robust_list_wakes_after_exec;
169use tool_global::robust_list_wakes_after_exit;
170pub use tool_global::shared_open_file_reply;
171pub use tool_global::shared_open_file_request;
172pub use tool_local::initial_resource_limit;
173
174fn select_thread_exit_detpid(
175    thread_detpid: Option<DetPid>,
176    process_detpid: DetPid,
177) -> (DetPid, bool) {
178    match thread_detpid {
179        Some(detpid) => (detpid, false),
180        None => (process_detpid, true),
181    }
182}
183
184fn select_thread_start_detpid(thread_detpid: Option<DetPid>, guest_pid: Pid) -> DetPid {
185    thread_detpid.unwrap_or_else(|| DetPid::from_raw(guest_pid.into()))
186}
187
188/// What a stop of thread `tid` of `pid` did with a copy of the standard
189/// `signal` (`kept`: resumed into the thread, or else dropped), for the
190/// scheduler's record of copies Linux discarded when they were sent
191/// (`scheduler::discarded_at_send`, <https://github.com/rrnewton/hermit/issues/4293>).
192/// Reads, after the stop, the thread's queues and its mask, which decides
193/// whether a kept copy is requeued at the resume (`ptrace_signal`). `None`
194/// for a signal the record does not track, or a state that cannot be read,
195/// which changes nothing.
196fn consumed_signal_control(
197    pid: Pid,
198    tid: Pid,
199    signal: i32,
200    kept: bool,
201) -> Option<scheduler::discarded_at_send::DiscardedSignalControl> {
202    use scheduler::discarded_at_send::Consumption;
203    use scheduler::discarded_at_send::DiscardedSignalControl;
204    if !(1..32).contains(&signal) {
205        return None;
206    }
207    let state = syscalls::read_kernel_signal_state(pid, tid).ok()?;
208    let bit = scheduler::kernel_signal_bit(signal);
209    let how = if kept {
210        Consumption::KeptResume {
211            blocked: state.blocked & bit != 0,
212        }
213    } else {
214        Consumption::Dropped
215    };
216    Some(DiscardedSignalControl::Consumed {
217        signal,
218        how,
219        thread_holds: state.thread_pending & bit != 0,
220        process_holds: state.shared_pending & bit != 0,
221    })
222}
223
224fn thread_start_needs_registration(
225    is_root_process: bool,
226    past_first_execve: bool,
227    dettid: DetTid,
228    detpid: DetPid,
229) -> bool {
230    dettid == detpid && (is_root_process || !past_first_execve)
231}
232
233// AUTONOMOUS-BOT-IMPLEMENTED
234// TODO-HUMAN-REVIEW(PR-644): Review the typed fail-closed backend signal.
235/// Identifies an unsupported syscall that a backend must terminate without unwinding.
236#[derive(Debug)]
237pub struct UnsupportedSyscallError(pub Sysno);
238
239impl std::fmt::Display for UnsupportedSyscallError {
240    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
241        write!(formatter, "unsupported syscall: {:?}", self.0)
242    }
243}
244
245impl std::error::Error for UnsupportedSyscallError {}
246pub use fd::OpenFileLease;
247pub use fd::OpenFileModel;
248pub use fd::SharedOpenFileChannel;
249pub use fd::SharedOpenFileError;
250pub use fd::install_shared_open_file_channel;
251pub use shared_open_files::ChunkedOpenFileChannel;
252pub use shared_open_files::OpenFileControl;
253pub use shared_open_files::OpenFileControlReply;
254pub use shared_open_files::OpenFileControlTransport;
255pub use tool_local::Detcore;
256pub use tool_local::FileMetadata;
257/// Returns whether the audited runtime policy classifies `sysno` as unsupported.
258// AUTONOMOUS-BOT-IMPLEMENTED
259// TODO-HUMAN-REVIEW(PR-644): Review the copied-DBT-child classification surface.
260pub fn is_unsupported_syscall(sysno: Sysno) -> bool {
261    matches!(
262        syscall_classification::classify_syscall(sysno),
263        syscall_classification::SyscallClassification::Unsupported
264    )
265}
266
267/// Every syscall in the pinned x86_64 table, including the final entry.
268///
269/// Backends that sweep the classification table must use this rather than
270/// `Sysno::iter()`, which stops one short and silently drops the last row.
271pub fn all_pinned_syscalls() -> impl Iterator<Item = Sysno> {
272    syscall_classification::all_pinned_syscalls()
273}
274
275/// Returns whether the audited runtime policy classifies `sysno` as
276/// `Determinized` — that is, Detcore either models the syscall with a handler
277/// or applies an explicit deterministic refusal policy to it.
278///
279/// This is the complement of the refusal boundary below. A backend that
280/// executes guest syscalls outside `handle_syscall_event` needs BOTH: the
281/// refusal set tells it which syscalls to answer with a fixed errno, and this
282/// predicate tells it which syscalls Detcore claims to determinize at all.
283/// Running a `Determinized` syscall natively is a determinism hole even when it
284/// is not in the refusal set, because the modelling that makes it deterministic
285/// lives in a handler the backend never entered.
286pub fn is_determinized_syscall(sysno: Sysno) -> bool {
287    matches!(
288        syscall_classification::classify_syscall(sysno),
289        syscall_classification::SyscallClassification::Determinized
290    )
291}
292
293/// Returns whether `sysno` is a kernel-keyring syscall (`add_key`,
294/// `request_key`, `keyctl`) that Detcore hides behind a deterministic
295/// `CONFIG_KEYS`-absent boundary under the default fail-closed policy.
296// AUTONOMOUS-BOT-IMPLEMENTED
297// TODO-HUMAN-REVIEW(PR-916): Exposed so the copied-DBT-child policy can preserve
298// the same keyring isolation boundary that the reclassification (PR-848) moved
299// out of the Unsupported set.
300pub fn is_kernel_keyring_syscall(sysno: Sysno) -> bool {
301    syscall_classification::is_kernel_keyring_syscall(sysno)
302}
303
304/// Returns whether Detcore deterministically refuses `sysno` with a fixed
305/// errno when the fail-closed policy is active, without consulting the host.
306///
307/// A backend that lets a guest execute a syscall outside Detcore's
308/// `handle_syscall_event` dispatcher consults this to enforce the same fixed
309/// refusal the ptrace path enforces. The only production consumer is the DBT
310/// copied pre-exec child policy in `detcore-dbt`, which runs without a Detcore
311/// tool; the KVM backend, like ptrace, delivers these syscalls to
312/// `handle_syscall_event`. It deliberately excludes emulated / no-op /
313/// host-forwarding families (credential no-ops, `timer_create`, AF_UNIX
314/// autobind), because fail-closing a copied child for those would diverge from
315/// the ptrace path rather than match it.
316// AUTONOMOUS-BOT-IMPLEMENTED
317// TODO-HUMAN-REVIEW(PR-978): Review the copied-DBT-child deterministic-refusal surface.
318pub fn is_deterministically_refused_syscall(sysno: Sysno) -> bool {
319    syscall_classification::is_deterministically_refused_syscall(sysno)
320}
321
322/// Returns whether `sysno` is refused by the default fail-closed policy but
323/// forwarded under the explicit compatibility opt-out. The legacy
324/// `strict_only` name is retained for API compatibility.
325pub fn is_strict_only_deterministic_refusal_syscall(sysno: Sysno) -> bool {
326    syscall_classification::is_strict_only_deterministic_refusal_syscall(sysno)
327}
328
329use tool_local::PosixTimers;
330use tool_local::ProcessCpuTime;
331pub use tool_local::ThreadState;
332pub use tool_local::ThreadStats;
333pub use tool_local::thread_rng_from_parent;
334use tracing::debug;
335use tracing::error;
336use tracing::info;
337use tracing::trace;
338use tracing::warn;
339pub use types::DetTid;
340use types::*;
341pub use util::punch_out_print;
342
343use crate::resources::Permission;
344use crate::resources::ResourceID;
345use crate::scheduler::itimer_coalesce::GuestSigalrmTarget;
346use crate::syscall_classification::SyscallClassification;
347use crate::syscall_classification::classify_syscall;
348use crate::syscall_classification::is_credential_identity_noop_syscall;
349use crate::syscall_classification::is_futex2_enosys_syscall;
350use crate::syscall_classification::is_host_kernel_probe_syscall;
351use crate::syscall_classification::is_host_security_identity_probe_syscall;
352use crate::syscall_classification::is_landlock_sandbox_syscall;
353use crate::syscall_classification::is_mount_introspection_enosys_syscall;
354use crate::syscall_classification::is_mount_ns_admin_refused_syscall;
355use crate::syscall_classification::is_optional_memory_feature_syscall;
356use crate::syscall_classification::is_ownership_change_noop_syscall;
357use crate::syscall_classification::is_perf_event_enosys_syscall;
358use crate::syscall_classification::is_privileged_admin_refused_syscall;
359use crate::syscall_classification::is_privileged_observation_refused_syscall;
360use crate::syscall_classification::is_process_isolation_refused_syscall;
361use crate::syscall_classification::is_remap_file_pages_enosys_syscall;
362use crate::syscall_classification::is_unimplemented_enosys_syscall;
363use crate::syscall_classification::is_unsupported_async_ipc_syscall;
364use crate::syscall_classification::is_zero_copy_pipe_syscall;
365use crate::syscalls::helpers::with_guest_rip;
366use crate::syscalls::helpers::with_guest_time;
367use crate::syscalls::time::guest_clock_time;
368use crate::tool_global::resource_request;
369use crate::tool_global::trace_schedevent;
370use crate::tool_global::unrecoverable_shutdown;
371use crate::types::SigWrapper;
372
373#[macro_use]
374extern crate bitflags;
375
376#[cold]
377fn report_rcb_overshoot(
378    panic_on_rcb_overshoot: bool,
379    clock_value: u64,
380    delta_rcbs: u64,
381    last_timer: u64,
382) {
383    let message = format!(
384        "{} prehook: PMU RCB overshoot! Clock_value: {}. Stepped forward {} RCBs, but should have trapped at {}",
385        reverie::SKID_OVERSHOOT_MARKER,
386        clock_value,
387        delta_rcbs,
388        last_timer
389    );
390    if panic_on_rcb_overshoot {
391        panic!("{}", message);
392    }
393    reverie::record_skid_overshoot();
394    error!("{}", message);
395}
396
397fn rcb_timer_overshot(delta_rcbs: u64, last_timer: u64) -> bool {
398    delta_rcbs > last_timer
399}
400
401/// The branches from `now` to the point the last handler armed the thread's
402/// timer for: `armed` branches past `committed`, that handler's clock value
403/// (`keep_timer_across_dropped_signal`). At least one: a stop at or past the
404/// point fires the event at once, where the backend records any overshoot.
405fn kept_timer_rcbs(committed: u64, armed: u64, now: u64) -> u64 {
406    committed.saturating_add(armed).saturating_sub(now).max(1)
407}
408
409fn choose_rcb_timer(
410    max_rcbs_remaining: u64,
411    current_rcbs: u64,
412    next_interrupt: Option<u64>,
413) -> (u64, bool) {
414    if let Some(next_interrupt) = next_interrupt {
415        let interrupt_rcbs = next_interrupt - current_rcbs;
416        if interrupt_rcbs < max_rcbs_remaining {
417            return (interrupt_rcbs, false);
418        }
419    }
420    (max_rcbs_remaining, true)
421}
422
423/// The registers a syscall's completion leaves, computed from `entry`, the
424/// context at its entry (`rip` at the `syscall` instruction): `rax` holds the
425/// result, `rip` follows the instruction, and the instruction's own clobbers
426/// hold `rcx` = that `rip` and `r11` = `rflags` (signal phase 1's completed
427/// projection, design section 4). Only read, never written back.
428fn completed_syscall_projection(
429    entry: libc::user_regs_struct,
430    result: i64,
431) -> libc::user_regs_struct {
432    const SYSCALL_INSTRUCTION_LENGTH: u64 = 2;
433    let mut completed = entry;
434    completed.rax = result as u64;
435    completed.rip = entry.rip.wrapping_add(SYSCALL_INSTRUCTION_LENGTH);
436    completed.rcx = completed.rip;
437    completed.r11 = entry.eflags;
438    completed
439}
440
441/// What returned control to Detcore, as far as ending a timeslice is concerned.
442#[derive(Clone, Copy, Debug, PartialEq, Eq)]
443enum CheckIn {
444    /// A syscall, signal, timer, exec or thread start: any expired slice ends.
445    Event,
446    /// A trapped `rdtsc` or `cpuid` in the middle of user code: see
447    /// [`ThreadState::instruction_trap_ends_timeslice`].
448    InstructionTrap,
449}
450
451/// The feature words the x86-64-v3 table advertises, as `(leaf, subleaf,
452/// register, bits)` with registers 0-3 for EAX-EDX, for the CLI's check that
453/// the host has every one of them natively
454/// (<https://github.com/rrnewton/hermit/issues/4243>). Leaf 0xD, which comes
455/// from the host, is not among them.
456pub fn v3_feature_words() -> Vec<(u32, u32, usize, u32)> {
457    cpuid::v3_feature_words()
458}
459
460/// Why a v3 configuration cannot run at all, or `None`: Detcore answers a v3
461/// guest from the qualified host's facts, so a configuration without them is
462/// refused rather than given a guessed leaf 0xD. Whether those facts came from
463/// a real qualification is Hermit's to check, at its launch functions
464/// (`cpu_profile_admission::refuse_unadmitted_launch`), before any backend
465/// starts (<https://github.com/rrnewton/hermit/issues/4243>).
466pub fn cpu_profile_admission_refusal(cfg: &Config) -> Option<&'static str> {
467    (!cfg.cpu_profile.is_default() && cfg.cpu_profile_host.is_none())
468        .then_some("the configuration carries no qualified host facts")
469}
470
471/// The digest of the CPUID table and bound host xstate facts `cfg` selects,
472/// which a recording carries so that replay can refuse a different table
473/// (<https://github.com/rrnewton/hermit/issues/4243>).
474pub fn virtual_cpuid_digest(cfg: &Config) -> [u8; 32] {
475    cpuid::InterceptedCpuid::for_config(cfg).digest(cfg.cpu_profile_host.as_ref())
476}
477
478impl<T: RecordOrReplay> Detcore<T> {
479    /// Whether `signal`, passed on to a guest thread without a report, could
480    /// have entered a handler the thread's signal-state copy never saw: where
481    /// the copy is kept against the kernel's own state, for any signal but
482    /// Reverie's preemption signal, SIGKILL and SIGSTOP, which never reach a
483    /// guest handler.
484    fn copy_misses_unreported(&self, signal: i32) -> bool {
485        self.cfg.signal_state_copy
486            && self.cfg.sequentialize_threads
487            && bundled_signal_facts::kernel_signal_state_is_guests(&self.cfg.backend)
488            && signal != reverie::PERF_EVENT_SIGNAL as i32
489            && signal != libc::SIGKILL
490            && signal != libc::SIGSTOP
491    }
492
493    /// Rule 4 for the coalescing ITIMER_REAL: tell the scheduler about a
494    /// committed guest SIGALRM send (https://github.com/rrnewton/hermit/issues/4139).
495    async fn note_guest_sigalrm<G: Guest<Self>>(&self, guest: &mut G, target: GuestSigalrmTarget) {
496        if guest.config().sequentialize_threads {
497            crate::tool_global::note_sigalrm_event(
498                guest,
499                crate::tool_global::GlobalRequest::NoteGuestSigalrm(target),
500            )
501            .await;
502        }
503    }
504
505    /// The table Detcore answers a guest's CPUID instruction from. Both the
506    /// instruction (`handle_cpuid_event`) and `/proc/cpuinfo` take it from
507    /// here, so a CPU profile such as
508    /// <https://github.com/rrnewton/hermit/issues/4243> proposes cannot give
509    /// the two views different CPUs.
510    pub(crate) fn virtual_cpuid(&self) -> cpuid::InterceptedCpuid {
511        cpuid::InterceptedCpuid::for_config(&self.cfg)
512    }
513
514    /// The procfs files this session renders (`procfs::RenderedFiles`):
515    /// `/proc/cpuinfo` among them where the guest's CPUID instruction is
516    /// answered from [`Self::virtual_cpuid`], which is where CPUID is
517    /// virtualized and the backend delivers the instruction to Detcore.
518    ///
519    /// Recomputed at each lookup from this run's configuration and the
520    /// guest's backend: one capability read, no injected call, and no state
521    /// shared with another session in the process. The answer is the same at
522    /// every lookup of a run: Reverie arms CPUID interception before the
523    /// guest's first callback (ptrace in its post-spawn preinit, before
524    /// `handle_thread_start`, and again at each `exec`; KVM from the Tool's
525    /// subscription before the first entry; DBT always intercepts), and a new
526    /// task takes its parent's.
527    pub(crate) fn rendered_files<G: Guest<Self>>(&self, guest: &G) -> procfs::RenderedFiles {
528        procfs::RenderedFiles::of(
529            self.cfg.virtualize_cpuid,
530            guest.has_cpuid_interception(),
531            self.cfg.container_mount_table.is_some(),
532        )
533    }
534
535    /// Give this image's descriptor table the session's answer to whether it
536    /// renders `/proc/cpuinfo` ([`Self::rendered_files`]), at the image's
537    /// first guest callback and before guest code runs, so that a placeholder
538    /// the table rediscovered without a guest at hand (an in-guest backend's
539    /// image after `exec`) is trusted exactly where the session renders the
540    /// file (`FileMetadata::decide_cpuinfo_placeholders`).
541    fn decide_cpuinfo_placeholders<G: Guest<Self>>(&self, guest: &G) -> Result<(), Errno> {
542        let rendered = self.rendered_files(guest).cpuinfo;
543        guest
544            .thread_state()
545            .file_metadata
546            .lock()
547            .unwrap()
548            .decide_cpuinfo_placeholders(rendered)
549    }
550
551    /// Signal phase 1, step I4 (design section 4, "The commit"): when the
552    /// caller's process holds a SIGALRM entry that is due for it, run the
553    /// signal pipeline ptrace runs at a signal-delivery stop (step 2), take
554    /// the entry inside that pipeline's `InboundSignal` turn (step 3), and
555    /// hand the delivery to the backend (steps 4 to 8). An entry taken that
556    /// the backend cannot deliver is a determinism loss.
557    ///
558    /// `before_syscall` is the I4 addendum's point c: the delivery happens at
559    /// the current syscall's entry and the syscall, not yet run, starts again
560    /// after the handler. Returns whether a delivery was handed to the
561    /// backend; at a syscall's entry the caller then must not run the syscall.
562    ///
563    /// `completed` is the syscall's result at its completion (None at its
564    /// entry): the signal pipeline then reads the completed register
565    /// projection (design section 4).
566    async fn deliver_due_sigalrm<G: Guest<Self>>(
567        &self,
568        guest: &mut G,
569        before_syscall: bool,
570        completed: Option<i64>,
571    ) -> bool {
572        if !tool_global::sigalrm_refuses(guest, tool_global::SigalrmControl::DueEntry).await {
573            return false;
574        }
575        if let Some(result) = completed {
576            let entry = guest.regs().await;
577            guest.thread_state_mut().signal_register_projection =
578                Some(completed_syscall_projection(entry, result));
579        }
580        let pipeline = self.handle_signal_event(guest, Signal::SIGALRM).await;
581        guest.thread_state_mut().signal_register_projection = None;
582        let delivering = matches!(pipeline, Ok(Some(_)));
583        // A suppressed signal's entry is dropped and nothing is delivered.
584        if !tool_global::sigalrm_refuses(guest, tool_global::SigalrmControl::TakeEntry).await
585            || !delivering
586        {
587            return false;
588        }
589        let info = scheduler::discarded_at_send::itimer_real_siginfo();
590        let target = reverie::SignalTarget::Process { pid: guest.pid() };
591        let delivered = match reverie::SignalEvent::new(libc::SIGALRM, info, target) {
592            Ok(event) if before_syscall => guest
593                .defer_signal_delivery_before_syscall(event)
594                .await
595                .is_ok(),
596            Ok(event) => guest.defer_signal_delivery(event).await.is_ok(),
597            Err(_) => false,
598        };
599        if !delivered {
600            self.stop_after_sigalrm_loss(guest).await;
601        }
602        if before_syscall {
603            // Faithful in its position relative to the guest's syscalls, but
604            // not in the interrupted registers the handler sees: recorded as a
605            // determinism loss, so verification refuses the run rather than
606            // compare it (round 4 of the I4 review; the faithful alternative
607            // is a delivery from the trampoline's return, before the syscall
608            // instruction runs).
609            tool_global::sigalrm_refuses(
610                guest,
611                tool_global::SigalrmControl::EntryDeliveryUnfaithful,
612            )
613            .await;
614        }
615        delivered
616    }
617
618    /// A SIGALRM entry this thread took cannot be delivered (or its virtual
619    /// mask cannot be read): record the determinism loss in the coordinator,
620    /// where the verifier reads it, and stop the process before any guest
621    /// instruction runs. Linux would have delivered the signal; continuing
622    /// would run the guest as if it never fired.
623    ///
624    /// The stop is the backend's `exit_group`, not `std::process::exit`: under
625    /// in-guest LiteInst the latter is the guest's own `exit`, which runs the
626    /// guest's `atexit` handlers and ELF finalizers.
627    async fn stop_after_sigalrm_loss<G: Guest<Self>>(&self, guest: &mut G) -> ! {
628        tool_global::sigalrm_refuses(guest, tool_global::SigalrmControl::DeliveryLost).await;
629        guest_log::flush_unsent();
630        match guest
631            .tail_inject(
632                reverie::syscalls::ExitGroup::new()
633                    .with_status(detcore_model::HERMIT_POLICY_REFUSAL_EXIT),
634            )
635            .await {}
636    }
637
638    /// Signal phase 1: before a callback can file a scheduler request, make
639    /// the scheduler's SIGALRM-blocked bit match the runtime's virtual mask. A
640    /// handler's start and return change that mask with no syscall, so the bit
641    /// may be stale at any callback (a syscall, or a trapped instruction whose
642    /// hooks may end a timeslice). Reads the runtime's virtual bit (one query
643    /// it answers from its virtual state) and publishes it when it differs from
644    /// the bit this thread last published, inside the thread's turn (no
645    /// firing commits while it holds it). Returns the bit.
646    async fn sync_sigalrm_eligibility<G: Guest<Self>>(&self, guest: &mut G) -> bool {
647        let Ok(blocked) = crate::syscalls::virtual_sigalrm_blocked(guest).await else {
648            self.stop_after_sigalrm_loss(guest).await
649        };
650        if blocked != guest.thread_state().sigalrm_blocked_published {
651            tool_global::sigalrm_refuses(
652                guest,
653                tool_global::SigalrmControl::PublishBlocked(blocked),
654            )
655            .await;
656            guest.thread_state_mut().sigalrm_blocked_published = blocked;
657        }
658        blocked
659    }
660
661    /// Publish the posthook happens-before anchors the current syscall entry
662    /// reached at its prehook, now that `res` is the result the guest will
663    /// get: after the last observer that can replace it, on every path that
664    /// returns a guest result, including an observer's own final errno (the
665    /// Codex review of https://github.com/rrnewton/hermit/pull/4048). Which
666    /// results are a completion is decided by [`posthook_checkpoint`]; the
667    /// pending names are consumed either way.
668    async fn publish_posthook_checkpoint<G: Guest<Self>>(
669        &self,
670        guest: &mut G,
671        count: u64,
672        res: &Result<i64, Error>,
673    ) {
674        let posthook = std::mem::take(&mut guest.thread_state_mut().stats.hb_pending_posthook);
675        if let Some(checkpoint) = posthook_checkpoint(count, posthook, res) {
676            let request = guest.thread_state().mk_request(checkpoint, Permission::R);
677            resource_request(guest, request).await;
678        }
679    }
680
681    /// The completion of a syscall that can resume the guest (a result or an
682    /// errno, not a backend failure): in a process that handles SIGALRM, a due
683    /// entry is delivered here, where Linux would deliver a signal that became
684    /// pending while the call ran (design section 4, point a).
685    async fn complete_syscall<G: Guest<Self>>(
686        &self,
687        guest: &mut G,
688        res: Result<i64, Error>,
689    ) -> Result<i64, Error> {
690        if self.cfg.backend.virtualizes_guest_sigalrm && guest.thread_state().sigalrm_handled {
691            let completed = match &res {
692                Ok(value) => Some(*value),
693                Err(Error::Errno(errno)) => Some(-i64::from(errno.into_raw())),
694                Err(_) => None,
695            };
696            if completed.is_some() {
697                self.deliver_due_sigalrm(guest, false, completed).await;
698            }
699        }
700        res
701    }
702
703    /// Signal phase 1 at a syscall's entry, before its first scheduler
704    /// request, in a process that handles SIGALRM: sync the scheduler's
705    /// blocked bit ([`Self::sync_sigalrm_eligibility`]), and while SIGALRM is
706    /// unblocked deliver an entry that is already due before this syscall (the
707    /// I4 addendum's point c). An entry is due here when it became deliverable
708    /// with no syscall completing (a handler returned and unblocked SIGALRM),
709    /// or committed during a scheduler yield inside a trapped instruction's
710    /// hooks; Linux delivers it before any further guest instruction. Returns
711    /// whether a delivery was prepared; the syscall then must not run.
712    async fn sigalrm_at_syscall_entry<G: Guest<Self>>(&self, guest: &mut G) -> bool {
713        let blocked = self.sync_sigalrm_eligibility(guest).await;
714        !blocked && self.deliver_due_sigalrm(guest, true, None).await
715    }
716
717    /// Registers a child whose native backend executed the clone syscall.
718    ///
719    /// The caller must initialize the child's local thread state from the same
720    /// parent state and clone flags before the child enters its start hook.
721    /// No backend that reaches this keeps a signal-state copy; one that does
722    /// must call `signal_shadow::before_clone` before its native clone, as
723    /// `handle_clone_family` does.
724    // TODO-HUMAN-REVIEW(PR-743): Review the backend-neutral native child registration API.
725    pub async fn register_external_child<G: Guest<Self>>(
726        &self,
727        guest: &mut G,
728        child_tid: Tid,
729        child_tid_addr: usize,
730        flags: CloneFlags,
731        exit_signal: libc::c_int,
732        physical_ids: Option<(i32, i32)>,
733    ) {
734        let child_dettid = DetTid::from_raw(child_tid.into());
735        guest.thread_state_mut().clone_flags = Some(flags);
736        if !flags.contains(CloneFlags::CLONE_THREAD) {
737            guest
738                .thread_state()
739                .prepare_child_process_cpu_time(child_dettid);
740        }
741        let parent_dettid = guest.thread_state().dettid;
742        let parent_pedigree = &mut guest.thread_state_mut().pedigree;
743        let child_pedigree = parent_pedigree.fork_mut();
744        debug!(
745            "[dtid {}] after registering external child (tid {}, pedigree {}) parent's pedigree becomes {}",
746            parent_dettid, child_dettid, child_pedigree, parent_pedigree,
747        );
748        // The kernel clone has already succeeded before an external backend
749        // calls this method, so these parent updates are not speculative. If
750        // registration observes a retired parent, create_child_thread exits
751        // that parent by tail injection; no continuing caller can retry or
752        // roll the successful clone back.
753        tool_global::create_child_thread(
754            guest,
755            child_dettid,
756            tool_global::child_tid_clear_address(flags, child_tid_addr),
757            Some(flags),
758            exit_signal,
759            physical_ids,
760        )
761        .await;
762        guest.thread_state_mut().clone_flags = None;
763    }
764    async fn passthrough<G: Guest<Self>>(
765        &self,
766        guest: &mut G,
767        call: Syscall,
768    ) -> Result<i64, Error> {
769        self.record_or_replay_preserving_tool_errors(guest, call)
770            .await
771    }
772
773    // AUTONOMOUS-BOT-IMPLEMENTED
774    // TODO-HUMAN-REVIEW(PR-643): Review unsupported-syscall reporting and fail-fast behavior.
775    /// Applies the legacy policy to an explicitly listed but unsupported syscall.
776    async fn handle_unsupported_syscall<G: Guest<Self>>(
777        &self,
778        guest: &mut G,
779        call: Syscall,
780        dettid: DetTid,
781        panic_on_unsupported_syscalls: bool,
782    ) -> Result<i64, Error> {
783        if panic_on_unsupported_syscalls {
784            error!(
785                "[detcore, dtid {}] unsupported syscall: {} = ?",
786                dettid,
787                call.display(&guest.memory()),
788            );
789            if guest.config().shutdown_on_unsupported_syscall {
790                // A fail-closed policy decision: the run named a syscall hermit
791                // cannot service and `shutdown_on_unsupported_syscall` says stop.
792                unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT).await;
793            }
794            if guest.config().exit_on_unsupported_syscall {
795                return Err(Error::Tool(anyhow::Error::new(UnsupportedSyscallError(
796                    call.number(),
797                ))));
798            }
799            panic!("unsupported syscall: {:?}", call);
800        }
801        report_unsupported_syscall(guest, call.number()).await;
802        self.passthrough(guest, call).await
803    }
804
805    /// Linux's `restart_syscall`. When no handler runs, the kernel restarts a wait
806    /// that returned `ERESTART_RESTARTBLOCK` by running this call at the
807    /// interrupted call's address, and the wait resumes with its original deadline
808    /// (https://github.com/rrnewton/hermit/issues/3358). Detcore emulates those
809    /// waits, so it resumes them from the record the wait kept
810    /// (`syscalls::helpers::RestartBlock`). Any other `restart_syscall` keeps the
811    /// unsupported-syscall policy.
812    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/pull/3361): Review the
813    // emulated `restart_syscall` resumption and the record it consumes.
814    async fn handle_restart_syscall<G: Guest<Self>>(
815        &self,
816        guest: &mut G,
817        call: Syscall,
818        restart_block: Option<syscalls::helpers::RestartBlock>,
819        dettid: DetTid,
820        panic_on_unsupported_syscalls: bool,
821    ) -> Result<i64, Error> {
822        let rip = guest.regs().await.rip;
823        let Some(block) = restart_block.and_then(|block| block.resumed_at(rip)) else {
824            trace!(
825                "[detcore, dtid {}] restart_syscall at {:#x} restarts no wait Detcore emulated ({:?})",
826                dettid, rip, restart_block
827            );
828            return self
829                .handle_unsupported_syscall(guest, call, dettid, panic_on_unsupported_syscalls)
830                .await;
831        };
832        trace!(
833            "[detcore, dtid {}] restart_syscall resumes {:?}",
834            dettid, block
835        );
836        match block.call {
837            syscalls::helpers::RestartCall::Poll(poll) => {
838                self.handle_internal_poll_until(guest, poll, block.deadline)
839                    .await
840            }
841            syscalls::helpers::RestartCall::Futex(futex) => {
842                self.handle_futex_from(
843                    guest,
844                    futex,
845                    syscalls::FutexDeadline::Restart(block.deadline),
846                )
847                .await
848            }
849            syscalls::helpers::RestartCall::Nanosleep(call) => {
850                let deadline = block
851                    .deadline
852                    .expect("a claimed nanosleep keeps its absolute deadline");
853                self.resume_nanosleep(guest, call, deadline).await
854            }
855        }
856    }
857
858    /// Defense-in-depth determinism for the registers the syscall instruction
859    /// clobbers.
860    ///
861    /// On x86-64 the `syscall` instruction destroys `%rcx` (which the CPU loads
862    /// with the return instruction pointer) and `%r11` (the saved `RFLAGS`).
863    /// After a syscall these are architecturally "undefined", so hermit must not
864    /// assume a well-behaved guest ignores them: a misbehaving guest that reads
865    /// `%rcx`/`%r11` must still observe deterministic values. Reverie's
866    /// injected-syscall path can otherwise leave its *private trampoline page's*
867    /// RIP/RFLAGS in these registers, which is both nondeterministic and an
868    /// information leak of tracer internals.
869    ///
870    /// This forces both registers to the guest's own (deterministic) RIP and
871    /// RFLAGS, which is exactly what a faithful `SYSRET` would leave there. It is
872    /// a no-op when they already hold the canonical values (the common path), so
873    /// it only writes registers when something diverged. Register-preserved
874    /// arguments (`%rdi`..`%r9`, callee-saved) are deliberately left untouched:
875    /// the Linux ABI preserves them, so zeroing them would break faithful,
876    /// well-behaved programs.
877    #[cfg(target_arch = "x86_64")]
878    async fn canonicalize_syscall_clobbers<G: Guest<Self>>(&self, guest: &mut G) {
879        let mut regs = guest.regs().await;
880        // A faithful SYSRET leaves the return RIP in %rcx and RFLAGS in %r11.
881        if regs.rcx != regs.rip || regs.r11 != regs.eflags {
882            regs.rcx = regs.rip;
883            regs.r11 = regs.eflags;
884            if let Err(err) = guest.set_regs(regs).await {
885                // Best-effort: some backends cannot write registers. Do not fail
886                // the syscall over a defense-in-depth hardening step.
887                debug!(
888                    "canonicalize_syscall_clobbers: set_regs unsupported/failed: {}",
889                    err
890                );
891            }
892        }
893    }
894
895    /// No-op on architectures without the x86-64 `%rcx`/`%r11` syscall clobber.
896    #[cfg(not(target_arch = "x86_64"))]
897    async fn canonicalize_syscall_clobbers<G: Guest<Self>>(&self, _guest: &mut G) {}
898
899    /// Update logical thread time with any outstanding ticks of the Reverie clock.  Returns a list
900    /// of corresponding Branch/OtherInstructions events if schedule recording is enabled.
901    ///
902    /// # Arguments
903    ///
904    /// * `precise_branch`: if true, there were no non-branch instructions since the last recorded branch instruction.
905    async fn update_logical_time_rcbs<G: Guest<Self>>(
906        &self,
907        guest: &mut G,
908        precise_branch: bool,
909    ) -> Option<Vec<SchedEvent>> {
910        if self.cfg.max_timeslice.is_some() {
911            let precise_timers = !guest.config().imprecise_timers;
912            // TODO(T86591083): we might need to not always increment as a hack fix
913            // for deterministic virtual time without sequentialize threads.
914            let clock_value = guest.read_clock().expect("Couldn't read clock");
915            // N.B. clock_value does not yet include any updates for the inbound
916            // syscall/instruction because this function is the very first thing that
917            // happens in each type of handler.
918            let thread_state = guest.thread_state_mut();
919            let dettid = thread_state.dettid;
920            assert!(thread_state.committed_clock_value <= clock_value);
921            let delta_rcbs: u64 = clock_value - thread_state.committed_clock_value;
922            if self.cfg.use_rcb_time() {
923                // AUTONOMOUS-BOT-IMPLEMENTED
924                // TODO-HUMAN-REVIEW(PR-1151)
925                if thread_state.chaos_slowdown_active {
926                    let factor = thread_state.rcb_time_multiplier();
927                    thread_state
928                        .thread_logical_time
929                        .add_rcbs_with_multiplier(delta_rcbs, factor);
930                } else {
931                    thread_state.thread_logical_time.add_rcbs(delta_rcbs);
932                }
933            }
934            thread_state.account_process_cpu_time();
935            thread_state.committed_clock_value = clock_value;
936
937            if thread_state.end_of_timeslice.is_some() {
938                if let Some(last_timer) = thread_state.last_rcb_timer
939                    && rcb_timer_overshot(delta_rcbs, last_timer)
940                    && precise_timers
941                {
942                    report_rcb_overshoot(
943                        self.cfg.panic_on_rcb_overshoot,
944                        clock_value,
945                        delta_rcbs,
946                        last_timer,
947                    );
948                    // Preserve timer state. `pre_handler_hook` will yield through the normal
949                    // scheduler path if the slice expired; `post_handler_hook` will otherwise
950                    // re-arm an overshot `interrupt_at` timer.
951                }
952                // Otherwise we're very early, at the prehook of handle_thread_start.
953            } else {
954                panic!(
955                    "Invariant violation: end_of_timeslice is None during update_logical_time_rcbs..."
956                )
957            }
958
959            trace!(
960                "[dtid {}] updated rcb clock, new logical time: {:?}, i.e. {}, timeslice end: {}, local rcb clock_value {:?}",
961                dettid,
962                &thread_state.thread_logical_time,
963                thread_state.thread_logical_time.as_nanos(),
964                thread_state
965                    .end_of_timeslice
966                    .map_or_else(|| "".to_string(), |x| format!("{}", x)),
967                clock_value,
968            );
969            if self.cfg.use_rcb_time() && self.cfg.should_trace_schedevent() {
970                let mut vec = Vec::new();
971                let ev = with_guest_time(
972                    guest,
973                    SchedEvent::branches(
974                        dettid,
975                        delta_rcbs
976                            .try_into()
977                            .expect("should not have more than 2^32 branches at once"),
978                    ),
979                );
980                let ev = if precise_branch {
981                    with_guest_rip(guest, ev).await
982                } else {
983                    ev
984                };
985
986                if delta_rcbs > 0 {
987                    // We don't fill the end_rip here, because the current rip is NOT precisely the
988                    // end of this block of branch events.  Other instructions may have occured
989                    // since the last branch.
990                    vec.push(ev)
991                } else {
992                    trace!(
993                        "[detcore, dtid {}] Refusing to record zero-braches event: {:?}",
994                        &ev.dettid, ev
995                    );
996                }
997                if !precise_branch {
998                    // This will ALWAYS record, even if the branches above are zero.
999                    let ev2 = with_guest_time(
1000                        guest,
1001                        SchedEvent {
1002                            dettid,
1003                            op: Op::OtherInstructions,
1004                            count: 1,
1005                            start_rip: None,
1006                            end_rip: None,
1007                            end_time: None,
1008                        },
1009                    );
1010                    // Fill in end_rip because current rip represents the end of this event.
1011                    let ev2 = with_guest_rip(guest, ev2).await;
1012                    vec.push(ev2);
1013                }
1014                Some(vec)
1015            } else {
1016                None
1017            }
1018        } else {
1019            None
1020        }
1021    }
1022
1023    /// A common hook called at the start of *every* handler, just after we receive
1024    /// control from the guest.
1025    /// The guest's registers as Detcore's hooks report them: the completed
1026    /// projection while a SIGALRM delivery's signal pipeline runs at a
1027    /// syscall's completion, otherwise the backend's.
1028    async fn observed_regs<G: Guest<Self>>(&self, guest: &mut G) -> libc::user_regs_struct {
1029        match guest.thread_state().signal_register_projection {
1030            Some(projection) => projection,
1031            None => guest.regs().await,
1032        }
1033    }
1034
1035    /// Detcore's handling of an inbound signal, for both of Reverie's signal
1036    /// hooks (`Tool::handle_signal_event`, and `Tool::handle_raw_signal_event`
1037    /// for a realtime signal): the signal takes its turn in the schedule
1038    /// before it is delivered. Returns the signal to deliver, or `None` to
1039    /// suppress it.
1040    async fn handle_inbound_signal<G: Guest<Self>>(
1041        &self,
1042        guest: &mut G,
1043        signal: SigWrapper,
1044    ) -> Result<Option<SigWrapper>, Errno> {
1045        // Whether this stop comes straight from the thread's own
1046        // `rt_sigreturn`, taken before any hook of this event clears it.
1047        let from_sigreturn = std::mem::take(&mut guest.thread_state_mut().returned_from_sigreturn);
1048        if signal.signal() == Some(Signal::SIGINT) && self.cfg.sigint_instakill {
1049            warn!("Fatal: Exiting hermit container immediately upon SIGINT");
1050            // ⚠️ NOT A REFUSAL. The operator interrupted the run; hermit examined
1051            // nothing and decided nothing. Reporting `128 + SIGINT` is what every
1052            // other tool reports for this, and it keeps 122 meaning one thing.
1053            unrecoverable_shutdown(guest, detcore_model::HERMIT_SIGINT_DEATH_EXIT).await
1054        } else {
1055            if signal.signal() == Some(Signal::SIGALRM) {
1056                self.normalize_reported_itimer_real(guest).await;
1057            }
1058            if signal.signal() == Some(Signal::SIGCHLD)
1059                && self.cfg.backend.reports_kernel_child_exit_signals
1060                && !self.child_exit_sigchld_delivers(guest).await
1061            {
1062                // A claimed copy that is dropped has no delivery to place, but
1063                // the claim may have held this duplicate while the claimed copy
1064                // is still pending (`syscalls::signal::claim_still_pending`).
1065                let (pid, tid) = (guest.pid(), guest.tid());
1066                let claimed = crate::syscalls::claim_still_pending(
1067                    guest.thread_state().claimed_sigchld,
1068                    || crate::syscalls::read_thread_signal_state(pid, tid),
1069                );
1070                guest.thread_state_mut().claimed_sigchld = claimed;
1071                self.keep_timer_across_dropped_signal(guest);
1072                return Ok(None);
1073            }
1074            // The test-only claim fault drops the claimed copy here, as the
1075            // ledger drops a duplicate above (`syscalls::signal::take_claim_fault`).
1076            if signal.signal() == Some(Signal::SIGCHLD)
1077                && guest.thread_state().claimed_sigchld
1078                && crate::syscalls::take_claim_fault(crate::syscalls::ClaimFault::DropClaimed)
1079            {
1080                warn!(
1081                    "[dtid {}] claim fault hook: dropped the claimed SIGCHLD",
1082                    guest.thread_state().dettid
1083                );
1084                guest.thread_state_mut().claimed_sigchld = false;
1085                self.keep_timer_across_dropped_signal(guest);
1086                return Ok(None);
1087            }
1088            // A POSIX timer's entry: delivered with its own siginfo, or, if its
1089            // timer was set again since it was queued, skipped as Linux skips
1090            // it inside the dequeue, with no turn
1091            // (<https://github.com/rrnewton/hermit/issues/4262>).
1092            let mut timer_entry = false;
1093            let stop_time = guest.thread_state().thread_logical_time.as_nanos();
1094            if scheduler::discarded_at_send::records(&self.cfg) && (1..32).contains(&signal.raw()) {
1095                use scheduler::discarded_at_send::DiscardedSignalAnswer;
1096                use scheduler::discarded_at_send::DiscardedSignalControl;
1097                use scheduler::posix_timer_coalesce::DeliveryAnswer;
1098                let control = DiscardedSignalControl::Dequeue {
1099                    signal: signal.raw(),
1100                    at: stop_time,
1101                };
1102                let answer = tool_global::discarded_signal(guest, control).await;
1103                timer_entry = answer == DiscardedSignalAnswer::Delivery(DeliveryAnswer::TimerEntry);
1104                match answer {
1105                    DiscardedSignalAnswer::Delivery(DeliveryAnswer::Suppress) => {
1106                        info!(
1107                            "[dtid {}] signal {} is a stale POSIX timer entry; skipped",
1108                            guest.thread_state().dettid,
1109                            signal
1110                        );
1111                        self.keep_timer_across_dropped_signal(guest);
1112                        return Ok(None);
1113                    }
1114                    DiscardedSignalAnswer::Delivery(DeliveryAnswer::Rewrite(info)) => {
1115                        if let Err(errno) = guest.set_signal_info(info.to_user()) {
1116                            warn!(
1117                                "[dtid {}] signal {} keeps its physical siginfo: {}",
1118                                guest.thread_state().dettid,
1119                                signal,
1120                                errno
1121                            );
1122                        }
1123                    }
1124                    _ => {}
1125                }
1126            }
1127            // The kernel dequeued `signal` before this stop: a hold for it ends
1128            // here, and this stop's hooks may end the slice
1129            // (`own_signal_turn_hold`).
1130            if guest.thread_state().own_signal_turn_hold == Some(signal.raw()) {
1131                guest.thread_state_mut().own_signal_turn_hold = None;
1132            }
1133            let timeslice = guest.thread_state().stats.timeslice_count;
1134            self.pre_handler_hook(guest, false, CheckIn::Event).await;
1135            // The delivery continues the thread's turn only while the slice
1136            // that ran its `rt_sigreturn` is still open. A stop that ends the
1137            // slice is Linux's TIF_NEED_RESCHED case: other threads run
1138            // (`schedule()`) before this one resumes and delivers, so the
1139            // delivery waits its place behind them instead of being taken
1140            // right after the yield. And at most
1141            // `MAX_SIGRETURN_CONTINUATIONS` in a row
1142            // (`consecutive_continuations`): in every mode, that cap is what
1143            // stops a handler that raises its own signal from holding the
1144            // CPU for ever.
1145            let continues_sigreturn = from_sigreturn
1146                && guest.thread_state().consecutive_continuations
1147                    < crate::tool_local::MAX_SIGRETURN_CONTINUATIONS
1148                && signal.signal() != Some(Signal::SIGCHLD)
1149                && guest.thread_state().stats.timeslice_count == timeslice;
1150
1151            // For `hermit run --verify`: a guest that faulted on an illegal
1152            // instruction may have run code that made syscalls Detcore never
1153            // saw, so the run reports `/`, the ancestor of every path, and
1154            // names no host input change. A false alarm only withholds a name.
1155            // The case this was written for no longer reaches here: on ptrace,
1156            // a syscall issued from the untraced stub of Reverie's private page
1157            // is followed by a `ud2`, and Reverie now ends the run at that
1158            // SIGILL (`UntracedStubSyscall`, a policy refusal) before any Tool
1159            // sees it. A stub syscall that never returns to the `ud2` (execve,
1160            // exit, rt_sigreturn) raises no SIGILL at all
1161            // (https://github.com/rrnewton/reverie/issues/1064). This stays as
1162            // the conservative answer for any other illegal instruction. A
1163            // guest that first rewrites or replaces the page's code is reported
1164            // when it does so (`record_untraced_code_change`).
1165            if signal.signal() == Some(Signal::SIGILL) && self.cfg.record_host_inputs {
1166                tool_global::record_host_mutation(guest, String::from("/")).await;
1167            }
1168
1169            let dettid = guest.thread_state().dettid;
1170            let mycount = guest.thread_state().stats.signal_count;
1171            info!(
1172                "[dtid {}] handling inbound signal (#{}) {}",
1173                dettid, mycount, signal
1174            );
1175            guest.thread_state_mut().stats.count_signal();
1176            let time = &guest.thread_state().thread_logical_time;
1177            let nanos = time.as_nanos();
1178
1179            if self.cfg.sequentialize_threads && self.cfg.should_trace_schedevent() {
1180                trace_schedevent(
1181                    guest,
1182                    SchedEvent {
1183                        dettid,
1184                        op: Op::SignalReceived(signal),
1185                        count: 1,
1186                        start_rip: None,
1187                        end_rip: None,
1188                        end_time: Some(nanos),
1189                    },
1190                    true,
1191                )
1192                .await;
1193            }
1194
1195            // The delivery of a `SIGCHLD` this thread claimed is placed, so its
1196            // turn is not deferred behind runnable work
1197            // (`ThreadState::claimed_sigchld`).
1198            if signal.signal() == Some(Signal::SIGCHLD)
1199                && std::mem::take(&mut guest.thread_state_mut().claimed_sigchld)
1200            {
1201                tool_global::child_exit_sigchld(
1202                    guest,
1203                    scheduler::child_exit_sigchld::ChildExitSigchldControl::ClaimedDelivery,
1204                )
1205                .await;
1206            }
1207            // Read-write marks this as the delivery itself, which the
1208            // scheduler's write-only wakes of a signaled sleeper are not
1209            // (`Scheduler::thread_timer_copies`).
1210            let mut request = guest
1211                .thread_state_mut()
1212                .mk_request(ResourceID::InboundSignal(signal), Permission::RW);
1213            request.continues_sigreturn = continues_sigreturn;
1214            resource_request(guest, request).await;
1215            // Under `--pipe-wake-latency`, a delivery that ends the process
1216            // dooms its threads at this committed turn, before their
1217            // host-timed removal (`scheduler::pipe_wake`).
1218            if self.cfg.pipe_wake_latency_in_effect().is_some()
1219                && match crate::syscalls::signal_shadow::copied_dispositions_for(
1220                    guest,
1221                    signal.raw(),
1222                ) {
1223                    Some(copied) => crate::syscalls::default_action_ends_process(
1224                        copied.ignored,
1225                        copied.caught,
1226                        signal.raw(),
1227                    ),
1228                    None => crate::syscalls::read_kernel_signal_state(guest.pid(), guest.tid())
1229                        .is_ok_and(|state| state.default_action_ends_process(signal.raw())),
1230                }
1231            {
1232                tool_global::record_fatal_signal(guest).await;
1233            }
1234            // A timer entry's siginfo, with its overrun counted now that the
1235            // delivery's turn is granted, where the handler's time begins.
1236            if timer_entry {
1237                use scheduler::discarded_at_send::DiscardedSignalAnswer;
1238                use scheduler::posix_timer_coalesce::DeliveryAnswer;
1239                let control = scheduler::discarded_at_send::DiscardedSignalControl::DeliveryInfo {
1240                    signal: signal.raw(),
1241                    at: guest.thread_state().thread_logical_time.as_nanos(),
1242                };
1243                if let DiscardedSignalAnswer::Delivery(DeliveryAnswer::Rewrite(info)) =
1244                    tool_global::discarded_signal(guest, control).await
1245                    && let Err(errno) = guest.set_signal_info(info.to_user())
1246                {
1247                    warn!(
1248                        "[dtid {}] signal {} keeps its physical siginfo: {}",
1249                        guest.thread_state().dettid,
1250                        signal,
1251                        errno
1252                    );
1253                }
1254            }
1255            if self
1256                .end_thread_group_before_fatal_delivery(guest, signal)
1257                .await
1258            {
1259                // As an exit_group does after its grant, file nothing more:
1260                // the group's turns are held until it has ended, which needs
1261                // this thread to die (Claude review of
1262                // https://github.com/rrnewton/hermit/pull/4387, finding 4).
1263                info!(
1264                    "[dtid {}] finish delivering signal (#{}) {}",
1265                    dettid, mycount, signal
1266                );
1267                return Ok(Some(signal));
1268            }
1269            // A delivered signal may be caught, ignored, or terminate the
1270            // thread group. Reading the lists is harmless; the collected
1271            // wakes remain inert unless the ptrace exit callback later reports
1272            // that this exact signal caused physical exit.
1273            self.stage_thread_group_robust_list_wakes(
1274                guest,
1275                tool_local::RobustListExit::Signal(signal.raw()),
1276            )
1277            .await;
1278            info!(
1279                "[dtid {}] finish delivering signal (#{}) {}",
1280                dettid, mycount, signal
1281            );
1282            self.record_handler_restore_mask(guest, signal).await;
1283
1284            self.post_handler_hook(guest, CheckIn::Event).await;
1285            Ok(Some(signal))
1286        }
1287    }
1288
1289    /// Take back the POSIX timer copies a successful exec flushes
1290    /// (`Scheduler::take_exec_timer_flush`), one zero-timeout
1291    /// `rt_sigtimedwait` each, before the new image runs. Linux discards a
1292    /// queued timer signal at exec (`flush_itimer_signals`) and keeps every
1293    /// other pending signal; Hermit sends a timer's expiration as an ordinary
1294    /// signal, which exec would keep
1295    /// (<https://github.com/rrnewton/hermit/issues/4184>). A copy that cannot
1296    /// be singled out refuses the run by name.
1297    async fn flush_exec_timer_copies<G: Guest<Self>>(&self, guest: &mut G) {
1298        let dettid = guest.thread_state().dettid;
1299        let refusal = match tool_global::exec_timer_flush(guest).await {
1300            Err(reason) => Some(reason),
1301            Ok(flush) => {
1302                let mut refusal = None;
1303                // The thread's own queue is dequeued first, as Linux does.
1304                for set in [flush.own, flush.shared] {
1305                    for signo in
1306                        (1..=64).filter(|signo| set & scheduler::kernel_signal_bit(*signo) != 0)
1307                    {
1308                        match syscalls::take_pending_signal(guest, signo).await {
1309                            Ok(taken) if taken == signo as i64 => info!(
1310                                "[detcore, dtid {}] exec flushed a POSIX timer's pending signal {}",
1311                                dettid, signo
1312                            ),
1313                            other => {
1314                                refusal = Some(format!(
1315                                    "taking back a POSIX timer's pending signal {signo} at exec answered {other:?}"
1316                                ));
1317                                break;
1318                            }
1319                        }
1320                    }
1321                }
1322                refusal
1323            }
1324        };
1325        if let Some(reason) = refusal {
1326            let message = format!(
1327                "hermit: thread {dettid} exec'd with a POSIX timer's signal possibly pending: {reason}; Linux discards a queued timer signal at exec, and Detcore cannot single this one out, so the run is refused (https://github.com/rrnewton/hermit/issues/4184)"
1328            );
1329            error!("{message}");
1330            let _ = writeln!(crate::util::RetryingStderr, "{message}");
1331            tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
1332                .await;
1333        }
1334    }
1335
1336    /// After a dropped signal's delivery stop, which made no other hook run:
1337    /// request the thread's timer event again for the same point of its
1338    /// branch clock as the last handler armed it (`post_handler_hook`). The
1339    /// stop is a Tool callback, which cancels the event, and nothing else
1340    /// re-arms it, so a thread spinning in user code would run on unpreempted
1341    /// until its next system call: measured, a chaos schedule whose sibling
1342    /// took a dropped kernel `SIGCHLD` spun about 4e10 branches past its
1343    /// 2e7-branch slice (https://github.com/rrnewton/hermit/issues/4304). The
1344    /// point is fixed by the clock value of that handler, not by when the
1345    /// host-timed stop came, and no logical time is charged here, so the stop
1346    /// stays invisible to the schedule.
1347    fn keep_timer_across_dropped_signal<G: Guest<Self>>(&self, guest: &mut G) {
1348        if !self.cfg.use_preemption_timer() {
1349            return;
1350        }
1351        let thread_state = guest.thread_state();
1352        let Some(armed) = thread_state.last_rcb_timer else {
1353            return;
1354        };
1355        let thread_state_committed = thread_state.committed_clock_value;
1356        // The stop cancelled the event: an unreadable clock leaves the thread
1357        // unpreempted, so it fails closed, as every handler's clock read does.
1358        let now = guest.read_clock().expect("Couldn't read clock");
1359        assert!(thread_state_committed <= now);
1360        let schedule = TimerSchedule::Rcbs(kept_timer_rcbs(thread_state_committed, armed, now));
1361        let armed = if guest.config().imprecise_timers {
1362            guest.set_timer(schedule)
1363        } else {
1364            guest.set_timer_precise(schedule)
1365        };
1366        armed.expect("Failed to set timer");
1367    }
1368
1369    /// Install Linux timer metadata only for the exact first kept expiry
1370    /// claimed before this callback advances logical time.
1371    async fn normalize_reported_itimer_real<G: Guest<Self>>(&self, guest: &mut G) {
1372        use scheduler::discarded_at_send::DiscardedSignalAnswer;
1373        use scheduler::discarded_at_send::DiscardedSignalControl;
1374        if !scheduler::discarded_at_send::records(&self.cfg) {
1375            return;
1376        }
1377        let Some(info) = guest.signal_info() else {
1378            return;
1379        };
1380        if info == scheduler::discarded_at_send::itimer_real_siginfo() {
1381            // A claimed copy may have requeued after a blocked resume. Its
1382            // canonical payload is already installed; do not claim a newer
1383            // publication that arrived while this copy was in flight.
1384            return;
1385        }
1386        if tool_global::discarded_signal(guest, DiscardedSignalControl::ClaimItimerReal).await
1387            != DiscardedSignalAnswer::ItimerReal(true)
1388        {
1389            return;
1390        }
1391        if let Err(errno) =
1392            guest.set_signal_info(scheduler::discarded_at_send::itimer_real_siginfo())
1393        {
1394            tool_global::report_determinism_loss(
1395                guest,
1396                format!("ITIMER_REAL_SIGINFO_UNAVAILABLE: owned timer delivery cannot install Linux siginfo: {errno}"),
1397            ).await;
1398            guest_log::flush_unsent();
1399            match guest
1400                .tail_inject(
1401                    reverie::syscalls::ExitGroup::new()
1402                        .with_status(detcore_model::HERMIT_POLICY_REFUSAL_EXIT),
1403                )
1404                .await {}
1405        }
1406    }
1407
1408    /// Whether a `SIGCHLD` that stopped this thread is delivered, on a backend
1409    /// that reports child-exit publication, where both the kernel and the
1410    /// scheduler send a child's exit `SIGCHLD` (`scheduler::child_exit_sigchld`).
1411    /// The first one delivered for a child's exit stands for it, and a copy
1412    /// of either kind that arrives after it is not delivered. The scheduler's
1413    /// copy (`SI_USER` from this tracer) is delivered with the siginfo Linux
1414    /// gives the parent. Any other `SIGCHLD` is delivered as it is.
1415    async fn child_exit_sigchld_delivers<G: Guest<Self>>(&self, guest: &mut G) -> bool {
1416        use scheduler::child_exit_sigchld::ChildExitSigchldAnswer;
1417        use scheduler::child_exit_sigchld::OwnCopy;
1418        let Some(info) = guest.signal_info() else {
1419            return true;
1420        };
1421        // A delivery stop: a kept copy's `InboundSignal` request follows.
1422        let control = scheduler::child_exit_sigchld::taken_control(&info, true);
1423        match tool_global::child_exit_sigchld(guest, control).await {
1424            ChildExitSigchldAnswer::Claimed(dropped) => !dropped,
1425            ChildExitSigchldAnswer::OwnCopy(OwnCopy::Duplicate) => false,
1426            ChildExitSigchldAnswer::OwnCopy(OwnCopy::Deliver(own))
1427            | ChildExitSigchldAnswer::ClaimedFor(own) => {
1428                if let Err(errno) = guest.set_signal_info(own.to_bytes()) {
1429                    warn!(
1430                        "[dtid {}] the SIGCHLD for child {} keeps its siginfo: {}",
1431                        guest.thread_state().dettid,
1432                        own.pid,
1433                        errno
1434                    );
1435                }
1436                true
1437            }
1438            _ => true,
1439        }
1440    }
1441
1442    async fn pre_handler_hook<G: Guest<Self>>(
1443        &self,
1444        guest: &mut G,
1445        precise_branch: bool,
1446        boundary: CheckIn,
1447    ) {
1448        // A handler that left early (an error return) may not have cleared
1449        // these; no request made by this new handler belongs to that syscall,
1450        // and a wake that syscall made no longer ends the slice.
1451        guest.thread_state_mut().in_uncharged_bootstrap_syscall = false;
1452        guest.thread_state_mut().yield_after_futex_wake = false;
1453        // Any event ends the window right after an `rt_sigreturn`; a signal
1454        // stop reads the flag before calling this hook.
1455        guest.thread_state_mut().returned_from_sigreturn = false;
1456        let dettid = guest.thread_state().dettid;
1457        let evs = self.update_logical_time_rcbs(guest, precise_branch).await;
1458
1459        if guest.thread_state().guest_past_first_execve() {
1460            detlog_debug!(
1461                "(pre) registers [dtid {}][rcbs {}]. {}",
1462                dettid,
1463                guest.thread_state().thread_logical_time.rcbs(),
1464                self.observed_regs(guest).await.display()
1465            );
1466        }
1467        trace!(
1468            "prehook [dtid {}] Updating rcbs and checking time remaining.",
1469            dettid
1470        );
1471        if let Some(vec) = evs {
1472            for ev in vec {
1473                trace_schedevent(guest, ev, false).await;
1474            }
1475        }
1476
1477        self.pipe_hand_off_if_due(guest).await;
1478        self.end_timeslice_if_needed(guest, boundary).await;
1479    }
1480
1481    // AUTONOMOUS-BOT-IMPLEMENTED
1482    /// Yield when accumulated logical time reaches the syscall-boundary target deadline.
1483    async fn end_timeslice_if_needed<G: Guest<Self>>(&self, guest: &mut G, boundary: CheckIn) {
1484        let thread_state = guest.thread_state();
1485        // A thread that sent a signal to its own process keeps its turn until
1486        // it dequeues that signal (`own_signal_turn_hold`).
1487        if let Some(signal) = thread_state.own_signal_turn_hold {
1488            trace!(
1489                "[dtid {}] keeps its turn until it takes signal {}",
1490                thread_state.dettid, signal
1491            );
1492            return;
1493        }
1494        let Some(slice_end) = thread_state.end_of_timeslice else {
1495            return;
1496        };
1497        let ends = match boundary {
1498            CheckIn::Event => thread_state.timeslice_expired(),
1499            CheckIn::InstructionTrap => thread_state.instruction_trap_ends_timeslice(&self.cfg),
1500        };
1501        if !ends {
1502            return;
1503        }
1504
1505        trace!(
1506            "[dtid {}] logical time {} reached timeslice target {}",
1507            thread_state.dettid,
1508            thread_state.thread_logical_time.as_nanos(),
1509            slice_end
1510        );
1511        self.end_timeslice(guest).await;
1512    }
1513
1514    /// A common hook called at the end of *every* handler, just before returning control
1515    /// to the guest. This enforces the logical target and resets the PMU maximum timer.
1516    ///
1517    /// However, note that the thread's timeslice (turn) may have expired DURING this handler.
1518    /// Therefore the timeslice can end in the posthook as well as in the prehook.
1519    async fn post_handler_hook<G: Guest<Self>>(&self, guest: &mut G, boundary: CheckIn) {
1520        // Only `kill` and `rt_sigqueueinfo` set the hold, and they wake no
1521        // futex waiter (https://github.com/rrnewton/hermit/issues/4034).
1522        assert!(
1523            guest.thread_state().own_signal_turn_hold.is_none()
1524                || !guest.thread_state().yield_after_futex_wake,
1525            "a futex wake must not end the turn a signal to the sender's own process holds"
1526        );
1527        if std::mem::take(&mut guest.thread_state_mut().yield_after_futex_wake) {
1528            // A turn of its own, outside the timeslice bookkeeping: the slice
1529            // keeps its deadlines, draws nothing from the thread's chaos PRNG
1530            // and consumes no recorded preemption point, so a replay that
1531            // makes the same decision stays aligned with its record. (Under
1532            // a random `--sched-heuristic` the turn's selection draws from the
1533            // run queue's generator, as every turn does, identically in record
1534            // and replay.)
1535            trace!(
1536                "posthook [dtid {}] FUTEX_WAKE woke a waiter; yielding to it",
1537                guest.thread_state().dettid
1538            );
1539            let request = Self::yield_request(guest);
1540            resource_request(guest, request).await;
1541        }
1542        self.pipe_hand_off_if_due(guest).await;
1543        self.end_timeslice_if_needed(guest, boundary).await;
1544
1545        let dettid = guest.thread_state().dettid;
1546        let mut current_time = guest.thread_state().thread_logical_time.as_nanos();
1547
1548        if let Some(mut max_timeslice_end) = guest.thread_state().max_timeslice_end {
1549            assert!(guest.config().max_timeslice.is_some());
1550            let mut replay_rcb_end = guest.thread_state().replay_rcb_end;
1551            // TODO: get rid of fractional NANOS_PER_RCB so it's clear that this does not lose precision:
1552            // AUTONOMOUS-BOT-IMPLEMENTED
1553            // TODO-HUMAN-REVIEW(PR-1151)
1554            let clock_multiplier = guest.config().clock_multiplier.unwrap_or(1.0)
1555                * guest.thread_state().rcb_time_multiplier().as_f64();
1556            let epsilon = Duration::from_nanos((NANOS_PER_RCB * clock_multiplier).ceil() as u64);
1557
1558            if replay_rcb_end.is_none() && current_time + epsilon > max_timeslice_end {
1559                if guest.thread_state().own_signal_turn_hold.is_some() {
1560                    // No guest instruction runs before the delivery stop that
1561                    // ends the hold, and that stop's post-hook ends this slice
1562                    // and sets the next timer (`own_signal_turn_hold`).
1563                    trace!(
1564                        "posthook [dtid {}] past PMU maximum {} while it keeps its turn",
1565                        dettid, max_timeslice_end
1566                    );
1567                    return;
1568                }
1569                trace!(
1570                    "posthook [dtid {}] less than one RCB remains before PMU maximum {}; ending slice",
1571                    dettid, max_timeslice_end
1572                );
1573                self.end_timeslice(guest).await;
1574                max_timeslice_end = guest
1575                    .thread_state()
1576                    .max_timeslice_end
1577                    .expect("ending a PMU-backed timeslice must install a new maximum");
1578                current_time = guest.thread_state().thread_logical_time.as_nanos();
1579                replay_rcb_end = guest.thread_state().replay_rcb_end;
1580            }
1581            if replay_rcb_end.is_none() && current_time + epsilon > max_timeslice_end {
1582                panic!(
1583                    "Ended time slice, but current time {} is still beyond PMU maximum {}",
1584                    current_time, max_timeslice_end
1585                );
1586            }
1587
1588            let current_rcbs = guest.thread_state().thread_logical_time.rcbs();
1589            let current_pmu_rcbs = guest.thread_state().committed_clock_value;
1590            let (ns_remaining, max_rcbs_remaining) = if let Some(replay_rcb_end) = replay_rcb_end {
1591                assert!(
1592                    replay_rcb_end > current_pmu_rcbs,
1593                    "recorded PMU RCB deadline {} is not ahead of current {}",
1594                    replay_rcb_end,
1595                    current_pmu_rcbs
1596                );
1597                let logical_remaining = if max_timeslice_end > current_time {
1598                    max_timeslice_end - current_time
1599                } else {
1600                    LogicalTime::ZERO
1601                };
1602                (logical_remaining, replay_rcb_end - current_pmu_rcbs)
1603            } else {
1604                let logical_remaining = max_timeslice_end - current_time;
1605                (
1606                    logical_remaining,
1607                    logical_remaining.into_rcbs_with_multiplier(clock_multiplier),
1608                )
1609            };
1610            let next_interrupt = self
1611                .cfg
1612                .use_rcb_time()
1613                .then(|| {
1614                    guest
1615                        .thread_state()
1616                        .interrupt_at
1617                        .range((current_rcbs + 1)..)
1618                        .next()
1619                        .copied()
1620                })
1621                .flatten();
1622            let (rcbs_remaining, timer_is_max) =
1623                choose_rcb_timer(max_rcbs_remaining, current_rcbs, next_interrupt);
1624            if let Some(next_interrupt) = next_interrupt {
1625                debug!(
1626                    "[dtid: {}] current rcbs: {}, next interrupt_at: {}",
1627                    dettid, current_rcbs, next_interrupt
1628                )
1629            }
1630
1631            trace!(
1632                "posthook [dtid {}] {} remaining before PMU maximum ({} rcbs).",
1633                dettid, ns_remaining, rcbs_remaining,
1634            );
1635
1636            if replay_rcb_end.is_none() && ns_remaining.is_zero() {
1637                panic!(
1638                    "Timer invariant broken: we should not exit a handler with 0 timeslice remaining."
1639                );
1640            }
1641            assert!(rcbs_remaining > 0);
1642            // The maximum also governs logical expiry and instruction traps.
1643            // Delivery capability gates only the physical arm and its record.
1644            if guest.config().use_preemption_timer() {
1645                trace!(
1646                    "posthook [dtid {}] Resetting timer to {:?} RCBs in the future (current {})",
1647                    dettid,
1648                    rcbs_remaining,
1649                    guest.thread_state().thread_logical_time.rcbs()
1650                );
1651                {
1652                    let thread_state = guest.thread_state_mut();
1653                    thread_state.last_rcb_timer = Some(rcbs_remaining);
1654                    thread_state.last_rcb_timer_is_max = timer_is_max;
1655                }
1656
1657                if guest.config().imprecise_timers {
1658                    guest
1659                        .set_timer(TimerSchedule::Rcbs(rcbs_remaining))
1660                        .expect("Failed to set timer");
1661                } else {
1662                    guest
1663                        .set_timer_precise(TimerSchedule::Rcbs(rcbs_remaining))
1664                        .expect("Failed to set timer");
1665                }
1666            } else {
1667                guest.thread_state_mut().last_rcb_timer = None;
1668                guest.thread_state_mut().last_rcb_timer_is_max = false;
1669            }
1670        } else {
1671            assert!(guest.config().max_timeslice.is_none());
1672            guest.thread_state_mut().last_rcb_timer = None;
1673            guest.thread_state_mut().last_rcb_timer_is_max = false;
1674        }
1675
1676        if guest.thread_state().guest_past_first_execve() {
1677            detlog_debug!(
1678                "(post) registers [dtid {}][rcbs {}]. {}",
1679                dettid,
1680                guest.thread_state().thread_logical_time.rcbs(),
1681                self.observed_regs(guest).await.display(),
1682            );
1683        }
1684    }
1685
1686    /// End this logical timeslice and talk to the scheduler before continuing.
1687    ///
1688    /// Effects
1689    ///  - ends timeslice (mutating thread stats and both deadlines)
1690    ///  - priority change / yield RPC
1691    async fn end_timeslice<G: Guest<Self>>(&self, guest: &mut G) {
1692        self.end_timeslice_with_sched_yield(guest, false).await;
1693    }
1694
1695    async fn end_timeslice_for_sched_yield<G: Guest<Self>>(&self, guest: &mut G) {
1696        self.end_timeslice_with_sched_yield(guest, true).await;
1697    }
1698
1699    async fn end_timeslice_with_sched_yield<G: Guest<Self>>(
1700        &self,
1701        guest: &mut G,
1702        mut explicit_sched_yield: bool,
1703    ) {
1704        let chaos = guest.config().chaos;
1705        loop {
1706            let thread_state = guest.thread_state();
1707            let dettid = thread_state.dettid;
1708            let end_time = thread_state.thread_logical_time.as_nanos();
1709            info!(
1710                "[detcore, dtid {}] ending timeslice T{}. {} syscalls and {} signals this timeslice.",
1711                dettid,
1712                thread_state.stats.timeslice_count,
1713                thread_state.stats.timeslice_syscall_count,
1714                thread_state.stats.timeslice_signal_count,
1715            );
1716            let maybe_prio = guest.thread_state_mut().next_timeslice(&self.cfg);
1717
1718            // Depending on chaos mode, a received timer event is either a preemption or a changepoint
1719            let req = if let Some(prio) = maybe_prio {
1720                Self::priority_changepoint_request(guest, end_time, prio)
1721            } else if chaos {
1722                Self::random_priority_changepoint_request(guest, end_time)
1723            } else if explicit_sched_yield && self.cfg.replay_schedule_from.is_none() {
1724                Self::sched_yield_request(guest)
1725            } else {
1726                Self::yield_request(guest)
1727            };
1728            resource_request(guest, req).await;
1729
1730            // AUTONOMOUS-BOT-IMPLEMENTED
1731            // TODO-HUMAN-REVIEW(PR-1151)
1732            // Multiple scheduler commits can occur without an intervening
1733            // conditional branch. Exact-RCB replay represents those as
1734            // adjacent zero-RCB slices, which must be consumed before the
1735            // guest resumes.
1736            if !guest.thread_state().timeslice_expired() {
1737                break;
1738            }
1739            explicit_sched_yield = false;
1740        }
1741    }
1742
1743    /// Hash the guest REGISTER FILE and log it.
1744    ///
1745    /// # The sampling boundary: GUEST-LOGICAL CONTROL, never handler interior
1746    ///
1747    /// This is called from exactly one place -- immediately after a syscall has finished and its
1748    /// result has been written back, before the guest resumes. At that instant the guest
1749    /// LOGICALLY HAS CONTROL: the architectural state is what the guest itself would observe at
1750    /// its own RIP, and it is the same instant at which stack and heap are already hashed.
1751    ///
1752    /// It is deliberately NOT sampled anywhere inside a tool handler. A backend that runs its
1753    /// handler IN-GUEST (sabre, liteinst, e9patch) executes instructions the ptrace reference
1754    /// never executes, using guest registers as scratch while it does. Registers there
1755    /// legitimately differ across backends, so comparing them would report correct behaviour as a
1756    /// divergence and burn the prefix-depth ratchet on artifacts. Handler-interior state is out of
1757    /// the domain, not excluded from it by a filter -- the same "define the domain" rule the heap
1758    /// definition follows.
1759    ///
1760    /// # What is in the hash, and what is deliberately not
1761    ///
1762    /// Included: the general-purpose registers the guest can observe, `rip`, `rsp`, `rflags`,
1763    /// `orig_rax`, and the TLS bases `fs_base`/`gs_base`.
1764    ///
1765    /// EXCLUDED, with reasons rather than by convenience:
1766    /// * `rcx` and `r11` -- architecturally clobbered by the `SYSCALL` instruction, which stores
1767    ///   the return RIP and RFLAGS in them. They carry no information beyond `rip`/`eflags`, which
1768    ///   ARE hashed, and a patching backend that reaches the kernel by some route other than a
1769    ///   bare `SYSCALL` will leave different values there for a reason that is not a determinism
1770    ///   defect.
1771    /// * The segment selectors `cs`/`ss`/`ds`/`es`/`fs`/`gs` -- constant for a 64-bit userspace
1772    ///   guest, so they add no signal; the TLS BASES are what a guest actually observes and those
1773    ///   are hashed.
1774    fn detlog_registers<G: Guest<Self>>(
1775        &self,
1776        guest: &mut G,
1777        regs: &libc::user_regs_struct,
1778        seq: u64,
1779    ) {
1780        if !self.cfg.detlog_regs {
1781            return;
1782        }
1783        // COST TIER: cadence 1 == full (every control point); N > 1 == spot-check every Nth.
1784        // The cadence index is a PER-THREAD counter, NOT a shared one: a global atomic would be
1785        // incremented in whatever order threads happen to reach it, so the cadence -- and
1786        // therefore which points got sampled -- would itself be nondeterministic. A determinism
1787        // instrument must not have a nondeterministic sampling schedule.
1788        //
1789        // It is `stats.syscall_count`, which starts at ZERO, rather than the syscall ORDINAL used
1790        // in the log (which starts at 2). With the ordinal, a guest whose control points never
1791        // land on a multiple of the cadence emitted NOTHING and the run still reported PASS -- a
1792        // spot-tier green backed by zero samples. Indexing from zero makes the first control point
1793        // of every thread always sampled, so a spot-tier run can never be silently empty.
1794        let cadence = self.cfg.detlog_regs_cadence.max(1);
1795        let index = {
1796            let stats = &mut guest.thread_state_mut().stats;
1797            let i = stats.regs_sample_index;
1798            stats.regs_sample_index = i.saturating_add(1);
1799            i
1800        };
1801        let _ = seq;
1802        if !index.is_multiple_of(cadence) {
1803            return;
1804        }
1805        let tier = if cadence == 1 {
1806            "full".to_string()
1807        } else {
1808            format!("spot-1/{cadence}")
1809        };
1810        let mut bytes = Vec::with_capacity(19 * 8);
1811        for v in [
1812            regs.rax,
1813            regs.rbx,
1814            regs.rdx,
1815            regs.rsi,
1816            regs.rdi,
1817            regs.rbp,
1818            regs.rsp,
1819            regs.r8,
1820            regs.r9,
1821            regs.r10,
1822            regs.r12,
1823            regs.r13,
1824            regs.r14,
1825            regs.r15,
1826            regs.rip,
1827            regs.eflags,
1828            regs.orig_rax,
1829            regs.fs_base,
1830            regs.gs_base,
1831        ] {
1832            bytes.extend_from_slice(&v.to_le_bytes());
1833        }
1834        detlog!(
1835            "[registers][dtid {}] control_point=syscall-exit tier={} {}",
1836            guest.thread_state().dettid,
1837            tier,
1838            Digest::new(&bytes)
1839        );
1840    }
1841
1842    fn detlog_memory_maps<G: Guest<Self>>(&self, guest: &mut G) -> Result<(), reverie::Error> {
1843        if !(self.cfg.detlog_stack || self.cfg.detlog_heap) {
1844            // Don't incur the *significant* performance penalty for reading
1845            // /proc/maps unless one of these flags is enabled.
1846            return Ok(());
1847        }
1848        // ...and don't incur it when nothing would observe the record either.
1849        //
1850        // The hash below is an argument to `detlog!`, so `tracing` already skips
1851        // it when INFO is disabled. Enumerating the maps is NOT: it happens
1852        // before the macro, on every syscall, whether or not a record is ever
1853        // written. Measured on a QEMU/Linux boot with `RUST_LOG` unset, where
1854        // each run emitted 123 bytes of log in total: no flag 43.71s,
1855        // `--detlog-stack` 190.37s (4.36x), `--detlog-heap` 207.90s (4.76x).
1856        // `--detlog-regs` was already inert because everything it does before
1857        // its own `detlog!` is trivial; this restores the same property here.
1858        //
1859        // Skipping is invisible to the guest: enumerating maps and hashing guest
1860        // memory are host-side observations of the tracee that neither issue a
1861        // guest syscall nor advance virtual time, so a run that skips them
1862        // executes the same guest instruction stream as one that does not.
1863        if !detlog_observed!() {
1864            return Ok(());
1865        }
1866        // Out-of-process backends (e.g. KVM) report their guest memory regions
1867        // directly, because `guest.pid()` is the host VMM process there and its
1868        // `/proc/<pid>/maps` describes the VMM, not the guest address space.
1869        // Reading those host addresses through `guest.memory()` (guest-address
1870        // space) would fault and abort the syscall. When the backend supplies
1871        // regions, hash those guest ranges; otherwise fall back to the ptrace
1872        // path of parsing `/proc/<pid>/maps`.
1873        if let Some(regions) = guest.detlog_memory_regions() {
1874            for region in regions {
1875                let want = match region.kind {
1876                    reverie::DetlogRegionKind::Stack => self.cfg.detlog_stack,
1877                    reverie::DetlogRegionKind::Heap => self.cfg.detlog_heap,
1878                };
1879                if !want {
1880                    continue;
1881                }
1882                let dettid = guest.thread_state().dettid;
1883                detlog!(
1884                    "[memory][dtid {}] {:?} {:#x}-{:#x}->{}",
1885                    dettid,
1886                    region.kind,
1887                    region.start,
1888                    region.end,
1889                    procmaps::compute_hash_range(guest, region.start, region.end)?
1890                )
1891            }
1892            return Ok(());
1893        }
1894        // Where Detcore answers brk from its model (a launcher run), the
1895        // kernel's `[heap]` is the launcher's, not the guest's.
1896        let modeled_brk = guest
1897            .thread_state()
1898            .memory_metadata
1899            .lock()
1900            .expect("memory metadata mutex poisoned")
1901            .brk_model
1902            .is_some();
1903        let mut labelled_heap = false;
1904        for mmap in procmaps::from_pid(guest.pid(), |map| match map.pathname {
1905            procmaps::MMapPath::Stack if self.cfg.detlog_stack => true,
1906            procmaps::MMapPath::Heap if self.cfg.detlog_heap && !modeled_brk => true,
1907            _ => false,
1908        })? {
1909            labelled_heap |= matches!(mmap.pathname, procmaps::MMapPath::Heap);
1910            let dettid = guest.thread_state().dettid;
1911            detlog!(
1912                "[memory][dtid {}] {}->{}",
1913                dettid,
1914                procmaps::display(&mmap),
1915                procmaps::compute_hash(guest, &mmap)?
1916            )
1917        }
1918
1919        // The kernel labels `[heap]` only for `[mm->start_brk, mm->brk)`. Under a
1920        // backend that loads the guest itself (DynamoRIO) that break belongs to
1921        // the loader, so the guest's heap is an unlabelled anonymous mapping and
1922        // the filter above matches nothing. Emitting no record there is worse
1923        // than a wrong one: downstream a zero-record heap comparison reads as
1924        // "compared and matched" rather than "never measured". Fall back to the
1925        // brk range Detcore observed, which identifies the heap on every backend.
1926        // Where Detcore models the break, the observed range is the model's.
1927        if self.cfg.detlog_heap && !labelled_heap {
1928            self.detlog_brk_heap(guest)?;
1929        }
1930        Ok(())
1931    }
1932
1933    /// Emit the `[heap]` record from the observed program break, for backends
1934    /// where the kernel does not label the guest's heap.
1935    ///
1936    /// Reports `[start_brk, brk)` -- the range Detcore observed -- taking the
1937    /// non-address columns from the enclosing anonymous mapping, so the record
1938    /// is textually comparable with the labelled record another backend
1939    /// produces for the same guest.
1940    ///
1941    /// ⚠️ THE EXTENT IS THE OBSERVED BREAK, NOT THE MAPPING THAT CONTAINS IT,
1942    /// and the two are not the same region. The selector below admits any
1943    /// anonymous mapping with `address.0 <= start && end <= address.1`, which
1944    /// is a SUPERSET by construction. Reporting that mapping instead would make
1945    /// the comparability claim above true only when the arena happens to
1946    /// coincide with the break, and would fold non-heap bytes into the digest.
1947    /// On the backend this path exists for, the premise is that the LOADER owns
1948    /// the break, so those extra bytes are loader arena -- the least
1949    /// reproducible region in the process. A silently empty record would become
1950    /// a loudly divergent one, for a reason that is not the guest's heap.
1951    ///
1952    /// The labelled path above hashes its mapping directly, which is correct
1953    /// there because the kernel defines `[heap]` as exactly `[start_brk, brk)`.
1954    /// Both paths therefore report the same quantity.
1955    fn detlog_brk_heap<G: Guest<Self>>(&self, guest: &mut G) -> Result<(), reverie::Error> {
1956        let Some((start, end)) = guest
1957            .thread_state()
1958            .memory_metadata
1959            .lock()
1960            .expect("memory metadata mutex poisoned")
1961            .brk_heap_range()
1962        else {
1963            return Ok(());
1964        };
1965        let modeled = guest
1966            .thread_state()
1967            .memory_metadata
1968            .lock()
1969            .expect("memory metadata mutex poisoned")
1970            .brk_model
1971            .is_some();
1972        if modeled {
1973            return self.detlog_modeled_brk_heap(guest, start, end);
1974        }
1975        let enclosing = procmaps::from_pid(guest.pid(), |map| {
1976            matches!(map.pathname, procmaps::MMapPath::Anonymous)
1977                && map.address.0 <= start
1978                && end <= map.address.1
1979        })?;
1980        let Some(mmap) = enclosing.into_iter().next() else {
1981            return Ok(());
1982        };
1983        let dettid = guest.thread_state().dettid;
1984        detlog!(
1985            "[memory][dtid {}] {}->{}",
1986            dettid,
1987            procmaps::display_range_as(&mmap, start, end, "[heap]"),
1988            procmaps::compute_hash_range(guest, start, end)?
1989        );
1990        Ok(())
1991    }
1992
1993    /// The heap records where Detcore models the break (a launcher run): one
1994    /// per anonymous mapping that holds part of the modeled `[start, end)`,
1995    /// clipped to it, as Linux's `[heap]` is one mapping per piece once an
1996    /// mprotect splits it, and up to the break's page-aligned end, where the
1997    /// kernel's `[heap]` mapping ends. So the records are the ones the
1998    /// kernel's `[heap]` mappings give where the kernel's break is the
1999    /// guest's, and a heap whose pages the guest unmapped gives none, as
2000    /// Linux's label goes with its last page.
2001    fn detlog_modeled_brk_heap<G: Guest<Self>>(
2002        &self,
2003        guest: &mut G,
2004        start: u64,
2005        end: u64,
2006    ) -> Result<(), reverie::Error> {
2007        // The page brk(2) rounds the break up to.
2008        let end = end.checked_add(4095).map_or(end, |end| end & !4095);
2009        let pieces = procmaps::from_pid(guest.pid(), |map| {
2010            matches!(map.pathname, procmaps::MMapPath::Anonymous)
2011                && map.address.0 < end
2012                && start < map.address.1
2013        })?;
2014        let dettid = guest.thread_state().dettid;
2015        for piece in pieces {
2016            let (from, to) = (piece.address.0.max(start), piece.address.1.min(end));
2017            detlog!(
2018                "[memory][dtid {}] {}->{}",
2019                dettid,
2020                procmaps::display_range_as(&piece, from, to, "[heap]"),
2021                procmaps::compute_hash_range(guest, from, to)?
2022            );
2023        }
2024        Ok(())
2025    }
2026}
2027
2028/// Render a finished syscall for the `finish syscall` DETLOG line.
2029///
2030/// Output pointers are dereferenced only when the kernel can have written
2031/// them. Linux leaves the output buffer of the syscalls listed in
2032/// [`failure_leaves_outputs_unwritten`] untouched when they fail with any errno
2033/// other than EFAULT, so rendering it would publish whatever the guest
2034/// happened to have there -- typically uninitialized stack -- as if it were a
2035/// result, and two otherwise identical runs would diverge on it
2036/// (<https://github.com/rrnewton/hermit/issues/3153>). For those syscalls such
2037/// a failure renders the pointer arguments without their pointees; the errno
2038/// is printed next to this rendering from the result itself.
2039///
2040/// EFAULT keeps the outputs rendered, because it is also the error of a copy
2041/// that faulted part way: `copy_to_user()` may already have stored a prefix of
2042/// the struct, which the guest can read and DETLOG must show. A tool error is
2043/// not a guest errno and proves nothing about the buffer, so it keeps them
2044/// rendered too.
2045///
2046/// Every other syscall keeps rendering its outputs on failure, because some
2047/// Linux syscalls do write an output on an error return (for example
2048/// `gettimeofday` stores `tv` before it faults on a bad `tz`). Hiding such an
2049/// output would remove real evidence from DETLOG.
2050fn display_syscall_finished<'a, M: MemoryAccess>(
2051    syscall: &'a Syscall,
2052    memory: &'a M,
2053    result: &Result<i64, Error>,
2054) -> reverie::syscalls::Display<'a, M, Syscall> {
2055    match syscall {
2056        Syscall::Fstat(_) => syscall.display(memory), //FIXME: T136880615 - fstat structure isn't fully deterministic yet
2057        _ if failure_proves_outputs_unwritten(result)
2058            && failure_leaves_outputs_unwritten(syscall) =>
2059        {
2060            syscall.display(memory)
2061        }
2062        _ => syscall.display_with_outputs(memory),
2063    }
2064}
2065
2066/// Syscalls whose output buffer Linux does not write when the syscall fails
2067/// with an errno other than EFAULT, restricted to those whose output the pinned Reverie formatter dereferences.
2068///
2069/// This is deliberately a list of syscalls PROVEN not to write on failure,
2070/// rather than a list of exceptions that do: a syscall missing from it keeps
2071/// its outputs rendered, which can at worst show stale guest memory, whereas a
2072/// syscall wrongly missing from an exception list would silently hide a value
2073/// the kernel really wrote.
2074///
2075/// Kernel behaviour (Linux `fs/stat.c`, `kernel/time/posix-timers.c`):
2076///
2077/// - `stat`, `lstat`, `fstat`, `newfstatat`: `vfs_stat()`, `vfs_lstat()`,
2078///   `vfs_fstat()` and `vfs_fstatat()` return their error before
2079///   `cp_new_stat()` is called, so the `struct stat` is never copied out.
2080///   Hermit's `handle_stat_family` likewise returns the injected syscall's
2081///   error before it rewrites the buffer.
2082/// - `statx`: `do_statx()` returns the `vfs_statx()` error before
2083///   `cp_statx()` copies the `struct statx` out.
2084/// - `clock_gettime`: `put_timespec64()` runs only when
2085///   `kc->clock_get_timespec()` succeeded (`if (!error && put_timespec64(..))`),
2086///   and an unknown clock returns `-EINVAL` before that. Hermit's
2087///   `handle_clock_gettime` writes `tp` only on its success path.
2088///
2089/// In every case the one failure that follows a copy attempt is the `-EFAULT`
2090/// from the copy itself, where `copy_to_user()` may have stored a prefix of
2091/// the struct before faulting. [`failure_proves_outputs_unwritten`] therefore
2092/// keeps rendering EFAULT failures, so that partial prefix stays visible.
2093///
2094/// `gettimeofday` is intentionally absent: `SYSCALL_DEFINE2(gettimeofday)` in
2095/// `kernel/time/time.c` stores `tv` and then returns `-EFAULT` if copying
2096/// `tz` faults, so its rendered output can be kernel-written on failure.
2097fn failure_leaves_outputs_unwritten(syscall: &Syscall) -> bool {
2098    matches!(
2099        syscall,
2100        Syscall::Stat(_)
2101            | Syscall::Lstat(_)
2102            | Syscall::Fstat(_)
2103            | Syscall::Newfstatat(_)
2104            | Syscall::Statx(_)
2105            | Syscall::ClockGettime(_)
2106    )
2107}
2108
2109/// Whether `result` is a failure that, for a syscall listed in
2110/// [`failure_leaves_outputs_unwritten`], proves Linux stored no output: a
2111/// guest errno other than EFAULT. EFAULT can follow a partial copy, and a
2112/// tool error is not the syscall's result.
2113fn failure_proves_outputs_unwritten(result: &Result<i64, Error>) -> bool {
2114    matches!(result, Err(Error::Errno(errno)) if *errno != Errno::EFAULT)
2115}
2116
2117/// The happens-before request a syscall entry makes once its result is
2118/// decided, for the posthook anchors it reached at its prehook (`anchors`), or
2119/// `None` (<https://github.com/rrnewton/hermit/issues/3929>):
2120/// - a value or a guest errno other than an internal restart code is a
2121///   completion: Linux returns it unchanged, so the anchors fire
2122///   ([`ResourceID::HappensBeforeSyscallCheckpoint`]);
2123/// - an internal restart code (`ERESTARTSYS`, `ERESTARTNOINTR`,
2124///   `ERESTARTNOHAND`, `ERESTART_RESTARTBLOCK`) is refused
2125///   ([`ResourceID::HappensBeforePosthookInterrupted`]): the kernel decides
2126///   only at signal delivery, after this point, whether the guest sees `EINTR`
2127///   or the entry is restarted and never returns, so neither firing nor not
2128///   firing would keep the anchor's promise;
2129/// - a tool or backend failure is not a result the guest receives; nothing
2130///   fires, and the failure ends the run on its own path.
2131fn posthook_checkpoint(
2132    count: u64,
2133    anchors: Vec<String>,
2134    result: &Result<i64, Error>,
2135) -> Option<ResourceID> {
2136    if anchors.is_empty() {
2137        return None;
2138    }
2139    match result {
2140        Err(Error::Errno(
2141            errno @ (Errno::ERESTARTSYS
2142            | Errno::ERESTARTNOINTR
2143            | Errno::ERESTARTNOHAND
2144            | Errno::ERESTART_RESTARTBLOCK),
2145        )) => Some(ResourceID::HappensBeforePosthookInterrupted {
2146            count,
2147            anchors,
2148            code: errno
2149                .name()
2150                .map_or_else(|| errno.to_string(), str::to_owned),
2151        }),
2152        Ok(_) | Err(Error::Errno(_)) => {
2153            Some(ResourceID::HappensBeforeSyscallCheckpoint { count, anchors })
2154        }
2155        Err(_) => None,
2156    }
2157}
2158
2159#[reverie::tool]
2160impl<T: RecordOrReplay> Tool for Detcore<T> {
2161    type GlobalState = GlobalState;
2162    type ThreadState = ThreadState<T::ThreadState>;
2163
2164    /// Only a sequentialized run on a backend with process signal control
2165    /// can install that control. Whether this run observes dequeues is
2166    /// decided after installation by [`GlobalState`]'s
2167    /// `GlobalTool::observe_signal_dequeues`.
2168    fn may_observe_signal_dequeues(config: &Config) -> bool {
2169        config.backend.provides_process_signal_control && config.sequentialize_threads
2170    }
2171
2172    /// The same runs require the control: real-timer signals on such a run
2173    /// travel only through acknowledged shared dequeues. Reverie refuses it
2174    /// before any guest code, with ENOSYS on a runner that offers no control,
2175    /// as Detcore's own installation did before this check moved into
2176    /// Reverie, and with EINVAL on a runner whose offer was not taken. So
2177    /// Detcore's scheduler needs no refusal of its own for a capable backend
2178    /// without a control.
2179    fn requires_signal_control(config: &Config) -> bool {
2180        config.backend.provides_process_signal_control && config.sequentialize_threads
2181    }
2182
2183    /// A sequentialized run lets one guest thread run guest code at a time,
2184    /// and Detcore refuses every way to install a seccomp filter: `seccomp(2)`
2185    /// (`handle_seccomp`, EOPNOTSUPP or an earlier argument error) and
2186    /// `prctl(PR_SET_SECCOMP)` (not a supported option, ENOSYS). Both
2187    /// refusals need the call intercepted, so the declaration also requires
2188    /// both in the subscriptions. The ptrace backend then keeps the guest's
2189    /// SIGTRAP action and mask across its own single-steps
2190    /// (<https://github.com/rrnewton/hermit/issues/4409>).
2191    ///
2192    /// One exception to "one at a time": a call the scheduler runs in the
2193    /// background (`BlockingExternalIO`, `BlockingRtSigsuspend`) is injected
2194    /// with a returning `inject`, so its thread runs only that syscall, in the
2195    /// kernel, and stops before any guest instruction. It can install no
2196    /// filter. Its injection is single-stepped, though, and that step's trap,
2197    /// at a host-timed moment, can reset the process's shared SIGTRAP action
2198    /// while another thread's injection is kept. An ignored, or caught and
2199    /// blocked, SIGTRAP can then end at `SIG_DFL`, where an undeclared run
2200    /// always leaves it; the blocked mask is per thread and is not affected.
2201    fn enforces_serialized_execution(config: &Config) -> bool {
2202        let subscriptions = Self::subscriptions(config);
2203        config.sequentialize_threads
2204            && subscriptions
2205                .iter_syscalls()
2206                .any(|sysno| sysno == Sysno::seccomp)
2207            && subscriptions
2208                .iter_syscalls()
2209                .any(|sysno| sysno == Sysno::prctl)
2210    }
2211
2212    async fn handle_signal_dequeue<G: Guest<Self>>(
2213        &self,
2214        guest: &mut G,
2215        dequeue: reverie::SignalDequeue,
2216    ) -> Result<(), Errno> {
2217        tool_global::signal_dequeued(guest, dequeue).await
2218    }
2219
2220    /// Constructor for Detcore process-local state.
2221    fn new(pid: Pid, cfg: &Config) -> Self {
2222        let detpid = DetPid::from_raw(pid.into()); // TODO(T78538674): virtualize pid.
2223        cfg.validate_invariants();
2224        if let Some(policy) = &cfg.in_guest_detlog_forward_policy {
2225            // This image's forwarder was set up before the Tool (SaBRe's
2226            // connect, the LiteInst constructor); without one, or with another
2227            // policy, refuse.
2228            detlog::require_forwarding(policy);
2229        }
2230        if cfg.in_guest_site_patching_off {
2231            // Record the host's request; the preload constructor compares it
2232            // with the settings the runtime captured once installation
2233            // returns (see in_guest_site_patching).
2234            in_guest_site_patching::require_site_patching_off();
2235        }
2236        // Read before any guest syscall, so a readlink of another process's
2237        // pipe or socket never depends on the tracer's descriptors then. The
2238        // outcome is kept; a failure is reported only if a guest needs it.
2239        let _ = syscalls::anonymous_object_devices();
2240        Self {
2241            detpid,
2242            cfg: cfg.clone(),
2243            record_or_replay: T::new(pid, cfg),
2244        }
2245    }
2246
2247    /// The signal-state copy follows handler returns from the backend's
2248    /// reports where it has them (`syscalls::signal_shadow`).
2249    fn observes_sigreturns(config: &Config) -> bool {
2250        crate::syscalls::signal_shadow::observes_sigreturns(config)
2251    }
2252
2253    fn handle_sigreturn(
2254        &self,
2255        thread_state: &mut Self::ThreadState,
2256        report: reverie::SigreturnReport,
2257    ) {
2258        crate::syscalls::signal_shadow::record_sigreturn_report(thread_state, report);
2259        // Where the backend reports the call instead of passing it to
2260        // `handle_syscall_event` (ptrace), this is the thread's last event
2261        // before a signal its restored mask unblocks is delivered
2262        // (`returned_from_sigreturn`).
2263        thread_state.returned_from_sigreturn = true;
2264    }
2265
2266    /// Counts each signal the backend passes on without reporting it, which
2267    /// could reach a guest handler, so the delivery counters show what no
2268    /// delivery check saw (A5 step 3.2b).
2269    fn note_unreported_signal(
2270        &self,
2271        thread_state: &mut Self::ThreadState,
2272        signal: &reverie::UnreportedSignal,
2273        kept: bool,
2274    ) {
2275        if kept && self.copy_misses_unreported(signal.number()) {
2276            let dettid = thread_state.dettid;
2277            thread_state
2278                .delivery_counters
2279                .count_unreported(dettid, signal.reason());
2280        }
2281    }
2282
2283    /// NOTE: these subscriptions are used ONLY for hermit run mode.  Hermit record has its own
2284    /// subscriptions specified in recorder/mod.rs.
2285    fn subscriptions(config: &Config) -> Subscription {
2286        let do_sched =
2287            config.sched_heuristic != SchedHeuristic::None || config.sequentialize_threads;
2288
2289        if !config.passthru_opt {
2290            // Fail closed by default in every build profile. Besides allowing syscall-specific
2291            // handlers to run, interception is what charges generic syscall logical time.
2292            //
2293            // `cpuid` is the one exception. With CPUID virtualization off the handler only
2294            // re-executes the host instruction, so trapping does not change what the guest
2295            // sees, but the subscription makes Reverie probe and enable CPUID faulting and log
2296            // an ERROR for each exec on hosts that lack it
2297            // (https://github.com/rrnewton/hermit/issues/3460). No backend installs a CPUID
2298            // table of its own, so an untrapped guest CPUID is the host's on every backend.
2299            let mut subscription = Subscription::all_syscalls();
2300            subscription.rdtsc();
2301            if config.virtualize_cpuid {
2302                subscription.cpuid();
2303            }
2304            subscription
2305        } else {
2306            // Explicit performance opt-in: unlisted syscalls bypass Detcore entirely. Keep this
2307            // path separate so its allow-list can be tightened without weakening the default.
2308            let mut subscription = Subscription::none();
2309            subscription.syscalls([
2310                Sysno::write,
2311                // AUTONOMOUS-BOT-IMPLEMENTED
2312                // TODO-HUMAN-REVIEW(#547)
2313                Sysno::writev,
2314                // Timer-slack procfs virtualization must see every scalar and
2315                // vectored read/write form that Linux accepts for the file.
2316                Sysno::readv,
2317                Sysno::preadv,
2318                Sysno::preadv2,
2319                Sysno::pwritev,
2320                Sysno::pwritev2,
2321                // AUTONOMOUS-BOT-IMPLEMENTED
2322                // TODO-HUMAN-REVIEW(#683)
2323                Sysno::pwrite64,
2324                Sysno::openat,
2325                Sysno::open,
2326                Sysno::creat,
2327                // Detcore answers access and extended-attribute requests on the
2328                // procfs files it renders
2329                // (https://github.com/rrnewton/hermit/issues/4213); a backend
2330                // keeps no copy of them, so these must not bypass Detcore.
2331                Sysno::access,
2332                Sysno::faccessat,
2333                Sysno::faccessat2,
2334                Sysno::getxattr,
2335                Sysno::lgetxattr,
2336                Sysno::setxattr,
2337                Sysno::lsetxattr,
2338                Sysno::removexattr,
2339                Sysno::lremovexattr,
2340                Sysno::listxattr,
2341                Sysno::llistxattr,
2342                Sysno::close,
2343                Sysno::read,
2344                Sysno::pread64,
2345                Sysno::lseek,
2346                Sysno::fadvise64,
2347                Sysno::mmap,
2348                Sysno::madvise,
2349                Sysno::munmap,
2350                Sysno::mremap,
2351                Sysno::fcntl,
2352                Sysno::arch_prctl,
2353                // AUTONOMOUS-BOT-IMPLEMENTED
2354                // TODO-HUMAN-REVIEW(PR-2150): Timer-slack prctl state is
2355                // virtual and must not bypass Detcore under passthru_opt.
2356                Sysno::prctl,
2357                Sysno::ioctl,
2358                Sysno::futex,
2359                Sysno::clone,
2360                Sysno::clone3,
2361                Sysno::fork,
2362                Sysno::vfork,
2363                Sysno::wait4,
2364                Sysno::waitid,
2365                Sysno::setsid,
2366                Sysno::uname,
2367                Sysno::exit_group,
2368                Sysno::exit,
2369                // AUTONOMOUS-BOT-IMPLEMENTED
2370                // The scheduler must observe changes to the address used for
2371                // its modeled CHILD_CLEARTID wake, including record/replay's
2372                // passthrough optimization.
2373                Sysno::set_tid_address,
2374                // AUTONOMOUS-BOT-IMPLEMENTED
2375                // Rare (once per thread) but load-bearing: without it the exit
2376                // hook cannot replay `exit_robust_list()` and robust-mutex
2377                // waiters are never woken.
2378                Sysno::set_robust_list,
2379                Sysno::dup,
2380                Sysno::dup2,
2381                Sysno::dup3,
2382                Sysno::pipe,
2383                Sysno::pipe2,
2384                Sysno::getrandom,
2385                Sysno::utime,
2386                Sysno::utimes,
2387                Sysno::utimensat,
2388                Sysno::futimesat,
2389                Sysno::socket,
2390                Sysno::socketpair,
2391                Sysno::eventfd,
2392                Sysno::eventfd2,
2393                Sysno::sched_getaffinity,
2394                Sysno::sched_setaffinity,
2395                Sysno::signalfd,
2396                Sysno::signalfd4,
2397                Sysno::timerfd_create,
2398                Sysno::timerfd_settime,
2399                Sysno::timerfd_gettime,
2400                Sysno::inotify_init,
2401                Sysno::inotify_init1,
2402                Sysno::inotify_add_watch,
2403                Sysno::inotify_rm_watch,
2404                Sysno::memfd_create,
2405                // AUTONOMOUS-BOT-IMPLEMENTED
2406                // TODO-HUMAN-REVIEW(PR-862): Keep modeled pidfd creation intercepted.
2407                Sysno::pidfd_open,
2408                // AUTONOMOUS-BOT-IMPLEMENTED
2409                // TODO-HUMAN-REVIEW(PR-1175): Keep pidfd signal/get-fd
2410                // determinization from being bypassed under the passthru opt-in.
2411                Sysno::pidfd_send_signal,
2412                Sysno::pidfd_getfd,
2413                Sysno::userfaultfd,
2414                Sysno::io_uring_setup,
2415                Sysno::io_uring_enter,
2416                Sysno::io_uring_register,
2417                Sysno::accept,
2418                Sysno::accept4,
2419                Sysno::nanosleep,
2420                Sysno::clock_nanosleep,
2421                Sysno::sched_yield,
2422                Sysno::poll,
2423                Sysno::ppoll,
2424                Sysno::prlimit64,
2425                Sysno::epoll_create,
2426                Sysno::epoll_create1,
2427                Sysno::epoll_ctl,
2428                Sysno::epoll_pwait,
2429                Sysno::epoll_wait,
2430                Sysno::epoll_wait_old,
2431                Sysno::epoll_ctl_old,
2432                Sysno::recvfrom,
2433                Sysno::rt_sigsuspend,
2434                Sysno::rt_sigtimedwait,
2435                Sysno::execve,
2436                Sysno::execveat,
2437                Sysno::rseq,
2438                Sysno::getpid,
2439                Sysno::gettid,
2440                Sysno::getcpu,
2441                Sysno::rt_sigprocmask,
2442                Sysno::rt_sigaction,
2443                Sysno::getrusage,
2444                Sysno::sysinfo,
2445                // AUTONOMOUS-BOT-IMPLEMENTED
2446                // TODO-HUMAN-REVIEW(#686): Review scratch fd sets and scheduler polling.
2447                Sysno::pselect6,
2448                // `select` is included by the Determinized sweep below;
2449                // T137258824 tracks improving its implementation.
2450            ]);
2451
2452            if do_sched {
2453                subscription.syscalls([
2454                    // TODO: some of the above could probably move to this bucket.
2455                    Sysno::alarm,
2456                    Sysno::pause,
2457                ]);
2458            }
2459
2460            if config.virtualize_metadata {
2461                subscription.syscalls([
2462                    Sysno::getdents,
2463                    Sysno::getdents64,
2464                    Sysno::stat,
2465                    Sysno::lstat,
2466                    Sysno::fstat,
2467                    Sysno::newfstatat,
2468                    Sysno::statx,
2469                ]);
2470            }
2471
2472            if true
2473            // TODO: could introduce a flag for this:
2474            /* config.virtualize_keys */
2475            {
2476                subscription.syscalls([Sysno::add_key, Sysno::request_key, Sysno::keyctl]);
2477            }
2478
2479            if do_sched {
2480                subscription.syscall(Sysno::connect);
2481            }
2482            if do_sched || config.warn_non_zero_binds {
2483                subscription.syscall(Sysno::bind);
2484            }
2485
2486            if config.warn_non_zero_binds {
2487                subscription.syscall(Sysno::bind);
2488            }
2489
2490            if config.virtualize_time {
2491                subscription.rdtsc();
2492                subscription.syscalls([
2493                    Sysno::gettimeofday,
2494                    Sysno::time,
2495                    Sysno::clock_gettime,
2496                    Sysno::clock_getres,
2497                ]);
2498            }
2499
2500            if config.virtualize_cpuid {
2501                subscription.cpuid();
2502            }
2503
2504            // AUTONOMOUS-BOT-IMPLEMENTED
2505            // TODO-HUMAN-REVIEW(PR-978): Keep the passthru-opt allow-list in sync
2506            // with the complete Determinized classification AND with the
2507            // Unsupported set. Even under the performance opt-in, Detcore must
2508            // see every syscall that its audited policy says it models or
2509            // deterministically refuses. Otherwise record/replay can bypass a
2510            // Detcore handler and execute the syscall natively against the host.
2511            //
2512            // `Determinized` and `Unsupported` are disjoint classifications, so
2513            // the determinized filter alone leaves the Unsupported set
2514            // unsubscribed: record/replay would silently execute an unsupported
2515            // syscall on the live host instead of invalidating its determinism
2516            // claim. Both halves are required; neither implies the other.
2517            // NOTE: `all_pinned_syscalls()`, not `Sysno::iter()`. The latter
2518            // stops one short of the end of the table, which silently dropped
2519            // `lsm_list_modules` out of this sweep.
2520            subscription.syscalls(crate::all_pinned_syscalls().filter(|sysno| {
2521                crate::is_determinized_syscall(*sysno) || crate::is_unsupported_syscall(*sysno)
2522            }));
2523
2524            // Make sure we also intercept everything that the record-or-replay tool
2525            // wants.
2526            subscription | T::subscriptions(config)
2527        }
2528    }
2529
2530    async fn handle_cpuid_event<G: Guest<Self>>(
2531        &self,
2532        guest: &mut G,
2533        eax: u32,
2534        ecx: u32,
2535    ) -> Result<CpuIdResult, Errno> {
2536        trace!("handle_cpuid_event: eax: {}, ecx: {}", eax, ecx);
2537        // A trapped instruction stops the guest in user code (A5 step 3.2).
2538        guest.thread_state_mut().delivery_interruption = Some(reverie::Interruption::NotInSyscall);
2539        if self.cfg.backend.virtualizes_guest_sigalrm && guest.thread_state().sigalrm_handled {
2540            self.sync_sigalrm_eligibility(guest).await;
2541        }
2542        self.pre_handler_hook(guest, false, CheckIn::InstructionTrap)
2543            .await;
2544        let res = if self.cfg.virtualize_cpuid {
2545            let dettid = guest.thread_state().dettid;
2546            let time = &mut guest.thread_state_mut().thread_logical_time;
2547            let intercepted = self.virtual_cpuid();
2548            time.add_cpuid();
2549            let nanos = time.as_nanos();
2550            trace!(
2551                "[dtid {}] inbound cpuid, new logical time: {:?}",
2552                dettid, time
2553            );
2554            if self.cfg.should_trace_schedevent() {
2555                trace_schedevent(
2556                    guest,
2557                    SchedEvent {
2558                        dettid,
2559                        op: Op::Cpuid,
2560                        count: 1,
2561                        start_rip: None,
2562                        end_rip: None,
2563                        end_time: Some(nanos),
2564                    },
2565                    true,
2566                )
2567                .await;
2568            }
2569            intercepted.cpuid(eax, ecx).unwrap_or_else(|| {
2570                warn!(
2571                    "[dtid {}] cpuid leaf 0x{:x} subleaf 0x{:x} not in deterministic table; returning zero result",
2572                    dettid, eax, ecx
2573                );
2574                CpuIdResult {
2575                    eax: 0,
2576                    ebx: 0,
2577                    ecx: 0,
2578                    edx: 0,
2579                }
2580            })
2581        } else {
2582            cpuid!(eax, ecx)
2583        };
2584        self.post_handler_hook(guest, CheckIn::InstructionTrap)
2585            .await;
2586        Ok(res)
2587    }
2588
2589    async fn handle_rdtsc_event<G: Guest<Self>>(
2590        &self,
2591        guest: &mut G,
2592        request: Rdtsc,
2593    ) -> Result<RdtscResult, Errno> {
2594        trace!("handle_rdtsc_event: {:?}", request);
2595        // A trapped instruction stops the guest in user code (A5 step 3.2).
2596        guest.thread_state_mut().delivery_interruption = Some(reverie::Interruption::NotInSyscall);
2597        if self.cfg.backend.virtualizes_guest_sigalrm && guest.thread_state().sigalrm_handled {
2598            self.sync_sigalrm_eligibility(guest).await;
2599        }
2600        self.pre_handler_hook(guest, false, CheckIn::InstructionTrap)
2601            .await;
2602        let result = if guest.config().virtualize_time {
2603            let dettid = guest.thread_state().dettid;
2604            guest.thread_state_mut().thread_logical_time.add_rdtsc();
2605            info!(
2606                "[dtid {}] inbound rdtsc, new logical time: {:?}",
2607                dettid,
2608                guest.thread_state().thread_logical_time
2609            );
2610            if self.cfg.should_trace_schedevent() {
2611                let ev = with_guest_time(
2612                    guest,
2613                    SchedEvent {
2614                        dettid,
2615                        op: Op::Rdtsc,
2616                        count: 1,
2617                        start_rip: None,
2618                        end_rip: None,
2619                        end_time: None,
2620                    },
2621                );
2622                trace_schedevent(guest, ev, true).await;
2623            }
2624            // The guest TSC must name the same instant as `clock_gettime`. Both
2625            // now read the coordinator's clock through the shared per-process
2626            // floor, so a guest comparing the two -- a clocksource watchdog, a
2627            // delay loop calibrated against a device timer, a second vCPU
2628            // reading the TSC -- sees one time base instead of two.
2629            //
2630            // The `add_rdtsc()` charge above is folded into global time by the
2631            // same RPC that reads it back (`send_and_update_time` updates the
2632            // coordinator before dispatching the request), so consecutive reads
2633            // from one thread still advance.
2634            let tsc = guest_clock_time(guest).await;
2635            Ok(RdtscResult {
2636                // We treat virtual cycles as equivalent to virtual nanoseconds.
2637                tsc: tsc.as_nanos(),
2638                aux: None,
2639            })
2640        } else {
2641            self.record_or_replay
2642                .handle_rdtsc_event(&mut guest.into_guest(), request)
2643                .await
2644        };
2645        self.post_handler_hook(guest, CheckIn::InstructionTrap)
2646            .await;
2647        result
2648    }
2649
2650    // Note: we will not see SIGSTKFLT used for timers.
2651    async fn handle_signal_event<G: Guest<Self>>(
2652        &self,
2653        guest: &mut G,
2654        signal: Signal,
2655    ) -> Result<Option<Signal>, Errno> {
2656        let delivered = self
2657            .handle_inbound_signal(guest, SigWrapper::from(signal))
2658            .await?;
2659        if scheduler::discarded_at_send::records(&self.cfg)
2660            && let Some(control) = consumed_signal_control(
2661                guest.pid(),
2662                guest.tid(),
2663                signal as i32,
2664                delivered.is_some(),
2665            )
2666        {
2667            tool_global::discarded_signal(guest, control).await;
2668        }
2669        if delivered.is_some() {
2670            crate::syscalls::signal_shadow::check_and_record_delivery(guest, signal as i32).await;
2671        }
2672        Ok(delivered.map(|_| signal))
2673    }
2674
2675    /// A realtime signal (32 to 64), which `Signal` cannot name: handled as
2676    /// any other (`handle_inbound_signal`), so it takes its turn in the
2677    /// schedule (<https://github.com/rrnewton/reverie/issues/207>).
2678    async fn handle_raw_signal_event<G: Guest<Self>>(
2679        &self,
2680        guest: &mut G,
2681        signal: i32,
2682    ) -> Result<Option<i32>, Errno> {
2683        let delivered = self
2684            .handle_inbound_signal(guest, SigWrapper(signal))
2685            .await?;
2686        if delivered.is_some() {
2687            crate::syscalls::signal_shadow::check_and_record_delivery(guest, signal).await;
2688        }
2689        Ok(delivered.map(|signal| signal.raw()))
2690    }
2691
2692    /// A `SIGCHLD` the backend passes on without reporting it is dropped when
2693    /// it is the kernel's copy of a child-exit notification the scheduler
2694    /// sends itself (`scheduler::child_exit_sigchld`). A copy the scheduler
2695    /// sent is kept, with the siginfo the tracer gave it: this hook cannot
2696    /// replace it.
2697    ///
2698    /// Either way, the scheduler's record of copies Linux discarded when they
2699    /// were sent learns what became of the copy (`consumed_signal_control`,
2700    /// <https://github.com/rrnewton/hermit/issues/4293>).
2701    async fn filter_unreported_signal<R: GlobalRPC<Self::GlobalState>>(
2702        &self,
2703        rpc: &R,
2704        unreported: reverie::UnreportedSignal,
2705    ) -> bool {
2706        if unreported.signal() == Some(Signal::SIGALRM)
2707            && scheduler::discarded_at_send::records(&self.cfg)
2708        {
2709            let tid = DetTid::from_raw(unreported.tid().as_raw());
2710            rpc.send_rpc((
2711                DetTime::default(),
2712                MmId::initial(tid),
2713                tool_global::GlobalRequest::DiscardedSignal(
2714                    scheduler::discarded_at_send::DiscardedSignalControl::UnreportedAlarm,
2715                ),
2716            ))
2717            .await;
2718        }
2719        // A POSIX timer's stale entry is skipped, as Linux skips it inside the
2720        // dequeue (<https://github.com/rrnewton/hermit/issues/4262>).
2721        let stale_timer_entry = scheduler::discarded_at_send::records(&self.cfg)
2722            && (1..32).contains(&unreported.number())
2723            && {
2724                let tid = DetTid::from_raw(unreported.tid().as_raw());
2725                let control = scheduler::discarded_at_send::DiscardedSignalControl::Unreported {
2726                    signal: unreported.number(),
2727                };
2728                // Carries no logical time; answered before any clock accounting.
2729                let (_, response) = rpc
2730                    .send_rpc((
2731                        DetTime::default(),
2732                        MmId::initial(tid),
2733                        tool_global::GlobalRequest::DiscardedSignal(control),
2734                    ))
2735                    .await;
2736                matches!(
2737                    response,
2738                    tool_global::GlobalResponse::DiscardedSignal(
2739                        scheduler::discarded_at_send::DiscardedSignalAnswer::Delivery(
2740                            scheduler::posix_timer_coalesce::DeliveryAnswer::Suppress
2741                        )
2742                    )
2743                )
2744            };
2745        let kept = !stale_timer_entry && async {
2746            // The test-only claim fault drops the claimed copy here too, where a
2747            // relative `nanosleep`'s restart code makes the backend pass it on
2748            // unreported (`syscalls::signal::take_claim_fault`).
2749            if unreported.signal() == Some(Signal::SIGCHLD)
2750                && crate::syscalls::take_claim_fault(crate::syscalls::ClaimFault::DropClaimed)
2751            {
2752                warn!(
2753                    "[tid {}] claim fault hook: dropped the claimed SIGCHLD",
2754                    unreported.tid()
2755                );
2756                return false;
2757            }
2758            if unreported.signal() != Some(Signal::SIGCHLD)
2759                || !self.cfg.backend.reports_kernel_child_exit_signals
2760            {
2761                return true;
2762            }
2763            let Some(info) = unreported.siginfo() else {
2764                return true;
2765            };
2766            let tid = DetTid::from_raw(unreported.tid().as_raw());
2767            // Passed on unreported, a kept copy makes no `InboundSignal` request.
2768            match scheduler::child_exit_sigchld::control_for(&info, std::process::id(), false) {
2769                None => true,
2770                Some(control) => {
2771                    use scheduler::child_exit_sigchld::ChildExitSigchldAnswer;
2772                    use scheduler::child_exit_sigchld::OwnCopy;
2773                    // The control message carries no logical time; the scheduler answers
2774                    // it before any clock accounting.
2775                    let (_, response) = rpc
2776                        .send_rpc((
2777                            DetTime::default(),
2778                            MmId::initial(tid),
2779                            tool_global::GlobalRequest::ChildExitSigchld(control),
2780                        ))
2781                        .await;
2782                    match response {
2783                        tool_global::GlobalResponse::ChildExitSigchld(
2784                            ChildExitSigchldAnswer::Claimed(dropped),
2785                        ) => !dropped,
2786                        tool_global::GlobalResponse::ChildExitSigchld(
2787                            ChildExitSigchldAnswer::OwnCopy(OwnCopy::Duplicate),
2788                        ) => false,
2789                        tool_global::GlobalResponse::ChildExitSigchld(
2790                            ChildExitSigchldAnswer::OwnCopy(OwnCopy::Deliver(own))
2791                            | ChildExitSigchldAnswer::ClaimedFor(own),
2792                        ) => {
2793                            warn!(
2794                                "[dtid {}] the SIGCHLD for child {} passed on unreported keeps its delivered siginfo",
2795                                tid, own.pid
2796                            );
2797                            true
2798                        }
2799                        _ => true,
2800                    }
2801                }
2802            }
2803
2804        }
2805        .await;
2806        if scheduler::discarded_at_send::records(&self.cfg)
2807            && let Some(control) = consumed_signal_control(
2808                unreported.pid(),
2809                unreported.tid(),
2810                unreported.number(),
2811                kept,
2812            )
2813        {
2814            let tid = DetTid::from_raw(unreported.tid().as_raw());
2815            // Carries no logical time; answered before any clock accounting.
2816            rpc.send_rpc((
2817                DetTime::default(),
2818                MmId::initial(tid),
2819                tool_global::GlobalRequest::DiscardedSignal(control),
2820            ))
2821            .await;
2822        }
2823        // The signal-state copy lives in this process wherever it is kept
2824        // (`syscalls::signal_shadow`); a signal that reaches a handler
2825        // unreported is one it never saw.
2826        let signal = unreported.number();
2827        if kept && self.copy_misses_unreported(signal) {
2828            crate::syscalls::signal_shadow::note_unreported(
2829                unreported.pid().as_raw(),
2830                unreported.tid().as_raw(),
2831                signal,
2832            );
2833        }
2834        kept
2835    }
2836
2837    fn init_thread_state(
2838        &self,
2839        tid: Tid,
2840        parent: Option<(Tid, &Self::ThreadState)>,
2841    ) -> Self::ThreadState {
2842        trace!("[tid {}] detcore init new thread state", tid);
2843
2844        let record_or_replay = self
2845            .record_or_replay
2846            .init_thread_state(tid, parent.map(|(ptid, ts)| (ptid, ts.as_ref())));
2847
2848        // TODO(T78538674): virtualize tid, extend tid<=>dettid mapping here.
2849        match parent {
2850            None => ThreadState::new(DetPid::from_raw(tid.into()), &self.cfg, record_or_replay),
2851            Some(pts) => {
2852                let clone_flags = pts
2853                    .1
2854                    .clone_flags
2855                    .expect("clone_flags must be set by parent");
2856                let dettid = DetPid::from_raw(tid.into());
2857
2858                // If we had mutable access to the parent state, we could update it here, but
2859                // instead we leave that to the clone/fork handling.
2860                let (_next_parent_pedigree, child_pedigree) = pts.1.pedigree.fork();
2861                let child_logical_time = pts.1.thread_logical_time.clone_for_child();
2862                let last_accounted_user_time = child_logical_time.user_cpu_time();
2863                let last_accounted_system_time = child_logical_time.system_cpu_time();
2864                if !clone_flags.contains(CloneFlags::CLONE_THREAD) {
2865                    pts.1.prepare_child_process_cpu_time(dettid);
2866                }
2867                let guest_clock = Arc::clone(&pts.1.guest_clock);
2868                // A pending unreported signal may already have changed the
2869                // parent's actions unseen: the child gets no copy then.
2870                let child_signal_shadow = pts
2871                    .1
2872                    .signal_shadow
2873                    .as_ref()
2874                    .filter(|_| !crate::syscalls::signal_shadow::unreported_pending())
2875                    .and_then(|shadow| shadow.for_clone(clone_flags.bits()));
2876                // A child sharing the actions without a copy could change them
2877                // unrecorded: they become unknown to every sharer.
2878                if child_signal_shadow.is_none()
2879                    && clone_flags.contains(CloneFlags::CLONE_SIGHAND)
2880                    && let Some(shadow) = pts.1.signal_shadow.as_ref()
2881                {
2882                    shadow.forget_dispositions();
2883                }
2884                if child_signal_shadow.is_some() {
2885                    trace!(
2886                        "[dtid {}] signal-state copy: child {} gets a copy",
2887                        pts.1.dettid, dettid
2888                    );
2889                } else if pts.1.signal_shadow.is_some() {
2890                    debug!(
2891                        "[dtid {}] signal-state copy: child {} gets none (created inside a \
2892                         handler, an unreported signal pending, or the actions unknown)",
2893                        pts.1.dettid, dettid
2894                    );
2895                } else if pts.1.signal_shadow_lost {
2896                    debug!(
2897                        "[dtid {}] signal-state copy: child {} gets none (its creator's was lost)",
2898                        pts.1.dettid, dettid
2899                    );
2900                }
2901                debug!(
2902                    "[init_thread-state, parent dtid = {}] child thread {}, clone_flags = {:x?}",
2903                    pts.0, tid, clone_flags
2904                );
2905                let file_metadata = if clone_flags.contains(CloneFlags::CLONE_FILES) {
2906                    pts.1.file_metadata.clone()
2907                } else {
2908                    Arc::new(Mutex::new(
2909                        pts.1.file_metadata.lock().unwrap().fork_for(dettid),
2910                    ))
2911                };
2912                // A thread is of its creator's process. A new process leads a
2913                // thread group of its own, whose table is the one it starts
2914                // with: its creator's under CLONE_FILES, a copy otherwise.
2915                let process_files = if clone_flags.contains(CloneFlags::CLONE_THREAD) {
2916                    pts.1.process_files
2917                } else {
2918                    Some(file_metadata.lock().unwrap().files_id)
2919                };
2920
2921                ThreadState {
2922                    dettid,
2923                    detpid: None, // Initialized later.
2924                    thread_start_entered: false,
2925                    physical_tid: None,
2926                    signal_task_identity: None,
2927                    open_file_creator: None,
2928                    mm_id: MmId::for_clone(
2929                        pts.1.mm_id,
2930                        dettid,
2931                        clone_flags.contains(CloneFlags::CLONE_VM),
2932                    ),
2933                    memory_metadata: if clone_flags.contains(CloneFlags::CLONE_VM) {
2934                        Arc::clone(&pts.1.memory_metadata)
2935                    } else {
2936                        Arc::new(Mutex::new(
2937                            pts.1
2938                                .memory_metadata
2939                                .lock()
2940                                .expect("memory metadata mutex poisoned")
2941                                .clone(),
2942                        ))
2943                    },
2944                    pedigree: child_pedigree.clone(),
2945                    initialized_random_auxv: None,
2946                    stats: ThreadStats::new(),
2947                    file_metadata,
2948                    process_files,
2949                    tool_shares_guest_descriptor_table: pts.1.tool_shares_guest_descriptor_table,
2950                    // Linux copies the creating thread's current timer slack
2951                    // into both fields of every new task (thread or process).
2952                    timer_slack_ns: pts.1.timer_slack_ns,
2953                    default_timer_slack_ns: pts.1.timer_slack_ns,
2954                    // A new process created with CLONE_NEWPID is the init of
2955                    // a namespace below its creator's; everything else lives
2956                    // in its creator's.
2957                    nested_pid_namespace: pts.1.nested_pid_namespace
2958                        || (clone_flags.contains(CloneFlags::CLONE_NEWPID)
2959                            && !clone_flags.contains(CloneFlags::CLONE_THREAD)),
2960                    // A new task starts in its creator's root, and with
2961                    // CLONE_FS keeps sharing it.
2962                    changed_root: if clone_flags.contains(CloneFlags::CLONE_FS) {
2963                        Arc::clone(&pts.1.changed_root)
2964                    } else {
2965                        Arc::new(std::sync::atomic::AtomicBool::new(
2966                            pts.1.changed_root.load(std::sync::atomic::Ordering::SeqCst),
2967                        ))
2968                    },
2969                    // A new task runs its creator's image.
2970                    exe: pts.1.exe.clone(),
2971                    // POSIX timers are shared among threads of a process but are
2972                    // NOT inherited across fork(2). Share the table for a new
2973                    // thread (CLONE_THREAD); give a new process a fresh, empty
2974                    // one.
2975                    posix_timers: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
2976                        Arc::clone(&pts.1.posix_timers)
2977                    } else {
2978                        Arc::new(Mutex::new(PosixTimers::default()))
2979                    },
2980                    // Resource limits are process state: threads share them,
2981                    // while a forked process inherits a snapshot.
2982                    resource_limits: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
2983                        Arc::clone(&pts.1.resource_limits)
2984                    } else {
2985                        Arc::new(Mutex::new(
2986                            pts.1
2987                                .resource_limits
2988                                .lock()
2989                                .expect("resource limits mutex poisoned")
2990                                .clone(),
2991                        ))
2992                    },
2993                    process_cpu_time: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
2994                        Arc::clone(&pts.1.process_cpu_time)
2995                    } else {
2996                        Arc::new(Mutex::new(ProcessCpuTime::default()))
2997                    },
2998                    // Wall time belongs to the traced process tree, not to an
2999                    // individual process. Forked processes and cloned threads
3000                    // therefore retain one monotonic view of raw logical time.
3001                    guest_clock,
3002                    parent_process_cpu_time: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
3003                        pts.1.parent_process_cpu_time.clone()
3004                    } else {
3005                        Some(Arc::clone(&pts.1.process_cpu_time))
3006                    },
3007                    parent_cpu_publication: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
3008                        pts.1.parent_cpu_publication.clone()
3009                    } else if self.cfg.backend.emulates_child_waits
3010                        && self.cfg.sequentialize_threads
3011                    {
3012                        Some(pts.1.prepare_child_cpu_publication(dettid))
3013                    } else {
3014                        None
3015                    },
3016                    // A new thread has made no syscall yet.
3017                    restart_block: None,
3018                    // A fork child inherits its parent's signal dispositions.
3019                    sigalrm_handled: pts.1.sigalrm_handled,
3020                    signal_shadow: child_signal_shadow.clone(),
3021                    // A parent whose shared actions were unknown gives its
3022                    // child no copy, and that child is never seeded either.
3023                    // Only a divergence marks a lineage as never to be seeded
3024                    // again; a child denied a copy for a quiet reason is
3025                    // seeded at its exec.
3026                    signal_shadow_lost: pts.1.signal_shadow_lost,
3027                    // A new thread's first stop is at the exit of the call
3028                    // that made it, which Detcore did not finish for it.
3029                    delivery_interruption: None,
3030                    delivery_frame_handler: 0,
3031                    delivery_counters: Default::default(),
3032                    // The threads of a process share the record of what the
3033                    // scheduler holds for it; a new process has nothing
3034                    // published.
3035                    // The scheduler holds no mask for a new thread.
3036                    published_mask: Some(None),
3037                    published_dispositions: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
3038                        Arc::clone(&pts.1.published_dispositions)
3039                    } else {
3040                        Arc::default()
3041                    },
3042                    sigalrm_blocked_published: pts.1.sigalrm_blocked_published,
3043                    handler_restore_rt_reported: pts.1.handler_restore_rt_reported,
3044                    signal_register_projection: None,
3045                    last_accounted_user_time,
3046                    last_accounted_system_time,
3047                    thread_cpu_start_user_time: last_accounted_user_time,
3048                    thread_cpu_start_system_time: last_accounted_system_time,
3049                    clone_flags: None,
3050                    pending_vfork: pts.1.pending_vfork.clone(),
3051
3052                    // Child RNG identity follows the deterministic creation
3053                    // pedigree, never the backend/host Tid. Guest-visible IDs
3054                    // and scheduler targeting continue to use `dettid`.
3055                    prng: tool_local::thread_rng_from_parent_pedigree(
3056                        "USER RAND",
3057                        &pts.1.prng,
3058                        &child_pedigree,
3059                        tool_local::ChildRngStream::User,
3060                    ),
3061                    chaos_prng: tool_local::thread_rng_from_parent_pedigree(
3062                        "CHAOSRAND",
3063                        &pts.1.chaos_prng,
3064                        &child_pedigree,
3065                        tool_local::ChildRngStream::Chaos,
3066                    ),
3067
3068                    // For comparing progress to other threads, it is important that our
3069                    // child thread start at a sensible place, rather than starting back
3070                    // at zero:
3071                    thread_logical_time: child_logical_time,
3072                    // A new thread gets a new clock, so we've committed 0 ticks
3073                    committed_clock_value: 0,
3074                    // A new thread or process is never the backend runtime's
3075                    // bootstrapping thread, so it starts outside any window.
3076                    uncharged_bootstrap_syscalls: 0,
3077                    in_uncharged_bootstrap_syscall: false,
3078                    yield_after_futex_wake: false,
3079                    pipe_handoff_due: None,
3080                    own_signal_turn_hold: None,
3081                    returned_from_sigreturn: false,
3082                    consecutive_continuations: 0,
3083
3084                    end_of_timeslice: None,
3085                    replay_rcb_end: None,
3086                    // AUTONOMOUS-BOT-IMPLEMENTED
3087                    // TODO-HUMAN-REVIEW(PR-1151)
3088                    chaos_epoch: tool_local::chaos_epoch_sentinel(),
3089                    chaos_slowdown_factor: RcbTimeMultiplier::ONE,
3090                    chaos_slowdown_active: false,
3091                    claimed_sigchld: false,
3092                    pending_chaos_epochs: Vec::new(),
3093                    max_timeslice_end: None,
3094                    last_grant_deadline: None,
3095                    published_runtime_private_memory: None,
3096                    last_rcb_timer: None,
3097                    last_rcb_timer_is_max: false,
3098
3099                    record_or_replay,
3100                    preemption_points: None,
3101
3102                    // We only get to the point of creating child threads if we're past the first execve.
3103                    past_global_first_execve: true,
3104                    interrupt_at: self.cfg.interrupts_for_thread(dettid),
3105
3106                    // `copy_process()` sets `p->robust_list = NULL` for every
3107                    // new task, thread or process alike. The child re-registers
3108                    // its own head before it can own a robust futex.
3109                    robust_list_head: None,
3110                    robust_list_process: if clone_flags.contains(CloneFlags::CLONE_THREAD) {
3111                        Arc::clone(&pts.1.robust_list_process)
3112                    } else {
3113                        Arc::new(Mutex::new(tool_local::RobustListProcessState::default()))
3114                    },
3115                }
3116            }
3117        }
3118    }
3119
3120    async fn handle_thread_start<G: Guest<Self>>(&self, guest: &mut G) -> Result<(), Error> {
3121        guest.thread_state_mut().thread_start_entered = true;
3122        self.decide_cpuinfo_placeholders(guest)?;
3123        let new_dettid = DetTid::from_raw(guest.tid().into()); // TODO(T78538674): virtualize pid/tid:
3124        assert_eq!(new_dettid, guest.thread_state().dettid);
3125        let detpid = select_thread_start_detpid(guest.thread_state().detpid, guest.pid());
3126        let needs_registration = thread_start_needs_registration(
3127            guest.is_root_process(),
3128            guest.thread_state().past_global_first_execve,
3129            new_dettid,
3130            detpid,
3131        );
3132        trace!(
3133            "[tid {}] detcore handle_thread_start, pid={}",
3134            guest.tid(),
3135            detpid
3136        );
3137
3138        // Delayed initialization of thread_state for this new thread:
3139        let thread_state = guest.thread_state_mut();
3140        thread_state.detpid = Some(detpid);
3141        if thread_state.recover_process_mm_id(detpid) {
3142            debug!(
3143                "[detcore, dtid {}] recovered process memory identity {} for unparented thread state",
3144                new_dettid, detpid
3145            );
3146        }
3147
3148        if let Some(vfork) = guest.thread_state_mut().pending_vfork.take() {
3149            create_vfork_child_thread(guest, new_dettid, vfork).await;
3150        } else if needs_registration {
3151            // A root has no parent registration. A fresh runtime after exec
3152            // also needs this handshake, even when the Guest has an in-tree
3153            // parent: the global owner consumes its prepared exec and returns
3154            // the replacement MmId before any ordinary image request. State
3155            // inherited from a parent is already past the first exec and does
3156            // not register a second birth here.
3157            debug!(
3158                "[detcore, dtid {}] thread start registration, scheduling.. full config:\n {:?}",
3159                &new_dettid,
3160                guest.config()
3161            );
3162            let physical_ids = if guest
3163                .config()
3164                .backend
3165                .requires_thread_directed_process_signals
3166            {
3167                Some((
3168                    guest.pid().as_raw(),
3169                    guest
3170                        .thread_state()
3171                        .physical_tid
3172                        .expect("backend requires a host thread ID before registration"),
3173                ))
3174            } else {
3175                None
3176            };
3177            if let Some(post_exec_mm) =
3178                create_child_thread(guest, new_dettid, 0, None, libc::SIGCHLD, physical_ids).await
3179            {
3180                guest.thread_state_mut().mm_id = post_exec_mm;
3181            }
3182        }
3183        if new_dettid.as_raw() == detpid.as_raw() {
3184            // A process's first thread, with its final address space: a forked
3185            // child's copy of its parent's unsent warning count is not its own.
3186            guest_log::starts_new_process(guest.thread_state().mm_id);
3187        }
3188
3189        // Except for the root task, let's block until it's our turn to go:
3190        let th = tool_global::thread_start_request(&self.cfg, guest, detpid).await;
3191
3192        // Finish the delayed initialization of the full threadstate:
3193        {
3194            let ts = guest.thread_state_mut();
3195            ts.preemption_points = th.map(|x| x.into_iter());
3196            ts.next_timeslice(&self.cfg); // Must be after preemption_points is set.
3197        }
3198        // The start grant's deadline hint arrived before the first slice
3199        // existed; cap the slice now.
3200        let deadline = guest.thread_state_mut().last_grant_deadline.take();
3201        tool_global::cap_timeslice_at_deadline(guest, deadline);
3202
3203        // The prehook is a noop for a thread just starting.  Can't end the timeslice.  There's no
3204        // RCB progress to record.  However, we call it for consistency with all the other handlers.
3205        self.pre_handler_hook(guest, true, CheckIn::Event).await;
3206        // ^ precise_branch=true: There should have been ZERO prior instructions before this,
3207        // because the thread hasn't done anything yet.
3208
3209        self.record_or_replay
3210            .handle_thread_start(&mut guest.into_guest())
3211            .await?;
3212
3213        self.post_handler_hook(guest, CheckIn::Event).await;
3214        Ok(())
3215    }
3216
3217    async fn handle_post_exec<G: Guest<Self>>(&self, guest: &mut G) -> Result<(), Errno> {
3218        // The new image's first stop is at the exit of the exec Detcore did not
3219        // finish (A5 step 3.2). The old image's delivery counts are logged
3220        // under the identity they were taken under, and the new image counts
3221        // afresh.
3222        guest.thread_state_mut().delivery_interruption = None;
3223        let dettid = guest.thread_state().dettid;
3224        let counters = std::mem::take(&mut guest.thread_state_mut().delivery_counters);
3225        counters.log(dettid);
3226        // The new image's table may hold placeholders it rediscovered before
3227        // this, the image's first guest callback.
3228        self.decide_cpuinfo_placeholders(guest)?;
3229        // Exec resets caught signals to their defaults, on a private copy of
3230        // the actions; a thread without a copy (the first image, or one given
3231        // up quietly) is seeded instead. Before any request: a nonleader
3232        // exec's reconnect asks for a turn, and every request first publishes
3233        // the process's dispositions, which must be the new image's.
3234        crate::syscalls::signal_shadow::at_exec(guest);
3235        // A nonleader exec preserves the survivor's state and PMU counter, but
3236        // Linux changes its TID. Bind that state before any image callback RPC.
3237        match tool_global::reconnect_exec(guest).await {
3238            Err(Errno::EOPNOTSUPP) => {
3239                let message = "unsupported: preemption recording and replay across nonleader exec";
3240                error!("{message}");
3241                // Report even when logging is disabled or redirected. The
3242                // ordinary refusal helper preserves the policy exit class;
3243                // reconnect already bound identity, so its diagnostic RPC is
3244                // authenticated and cannot silently retire an unbound owner.
3245                let _ = writeln!(crate::util::RetryingStderr, "{message}");
3246                tool_global::unrecoverable_shutdown(
3247                    guest,
3248                    detcore_model::HERMIT_POLICY_REFUSAL_EXIT,
3249                )
3250                .await;
3251            }
3252            result => result?,
3253        }
3254        // Under x86-64-v3 the guest's CPUID must come from Detcore's table: a
3255        // native CPUID would show the host's features and leaf 0xD. Reverie
3256        // re-arms CPUID faulting for each new image before this callback and
3257        // only warns when that fails, so a v3 run ends here, by name, instead
3258        // of running on with the host's CPUID
3259        // (https://github.com/rrnewton/hermit/issues/4243).
3260        if self.cfg.cpu_profile == detcore_model::cpu_profile::CpuProfile::X86_64V3
3261            && !guest.has_cpuid_interception()
3262        {
3263            let message = "--cpu-profile x86-64-v3 refused: CPUID faulting is not active for \
3264                           this image, so the guest would see the host's CPUID";
3265            error!("{message}");
3266            let _ = writeln!(crate::util::RetryingStderr, "{message}");
3267            tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
3268                .await;
3269        }
3270        // A v3 configuration without host facts ends here, by name, before the
3271        // guest's first instruction, instead of reaching the CPUID table.
3272        if let Some(why) = cpu_profile_admission_refusal(&self.cfg) {
3273            let message = format!("--cpu-profile x86-64-v3 refused: {why}");
3274            error!("{message}");
3275            let _ = writeln!(crate::util::RetryingStderr, "{message}");
3276            tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
3277                .await;
3278        }
3279        // Exec gives the task filesystem information of its own
3280        // (`unshare_fs_struct`): a root it shared through CLONE_FS is now its
3281        // own, as it stands.
3282        let changed_root = guest
3283            .thread_state()
3284            .changed_root
3285            .load(std::sync::atomic::Ordering::SeqCst);
3286        guest.thread_state_mut().changed_root =
3287            Arc::new(std::sync::atomic::AtomicBool::new(changed_root));
3288        // The exec'ing thread is its process's only thread now, and leads
3289        // it, so the table it holds is the process's. (Where Detcore handles
3290        // the execve, `handle_execveat` already installed it; a backend that
3291        // runs execve natively, as DBT does, reaches only this callback.)
3292        guest.thread_state_mut().adopt_process_files();
3293        // The guest's first image is entered by an execve. A backend that traces
3294        // the guest from before it (ptrace) intercepts that execve and counts it
3295        // as the guest's first syscall. A backend that starts the guest already
3296        // executing its image (DBT under DynamoRIO, SaBRe) reaches this callback
3297        // with nothing counted, so under DBT, which then sees every later
3298        // syscall, numbers and virtual time ran exactly one syscall behind
3299        // ptrace's. Count that execve here, at its own cost. (SaBRe also misses
3300        // the dynamic loader's syscalls before its plugin starts; this closes
3301        // only the execve's share of that gap.)
3302        let thread = guest.thread_state_mut();
3303        if !thread.past_global_first_execve && thread.stats.syscall_count == 0 {
3304            thread.stats.count_syscall();
3305            thread
3306                .thread_logical_time
3307                .add_syscall_with_cost(syscall_time::cost_ns(Sysno::execve));
3308        }
3309        guest.thread_state_mut().past_global_first_execve = true;
3310        // exec resets a handled signal to its default action.
3311        guest.thread_state_mut().sigalrm_handled = false;
3312        guest.thread_state_mut().sigalrm_blocked_published = false;
3313        // Only a successful exec reaches this callback. Delete the old image's
3314        // POSIX timer IDs while exec still owns its scheduler turn; the global
3315        // notification below cancels their deadlines before the pre-handler
3316        // can yield. alarm()/ITIMER_REAL and the continuous clock survive exec.
3317        guest
3318            .thread_state()
3319            .posix_timers
3320            .lock()
3321            .unwrap()
3322            .clear_for_exec();
3323        // A successful exec clears the kernel's clear_child_tid registration.
3324        // Mirror that reset before any replacement-image syscall can run.
3325        if guest.config().sequentialize_threads {
3326            tool_global::set_child_tid_address(guest, 0).await;
3327        }
3328        // The exec walked the old thread group's robust lists; wake one waiter
3329        // per owner word it marked FUTEX_OWNER_DIED.
3330        let robust_wakes = guest.thread_state().take_robust_list_wakes_for_exec();
3331        let identities: Vec<_> = robust_wakes
3332            .iter()
3333            .map(|(owner, wake)| (*owner, wake.futex))
3334            .collect();
3335        let counts = robust_list_wakes_after_exec(guest, robust_wakes).await;
3336        for ((owner, futex), count) in identities.into_iter().zip(counts) {
3337            info!(
3338                "[detcore, dtid {}] robust-list owner death woke {} waiter(s) on futex {:?} at exec",
3339                owner, count, futex,
3340            );
3341        }
3342
3343        // In a run that declares a launcher, an exec Detcore did not prepare
3344        // leaves the new image without a record: resolve it here from the
3345        // path the exec was given.
3346        let unprepared_exe = if self.declares_launcher() {
3347            self.exec_image_from_execfn(guest)
3348        } else {
3349            None
3350        };
3351        tool_global::mark_past_first_execve(guest, unprepared_exe).await;
3352        // That request also took the process out of its old descriptor table
3353        // in `procfs::locks::LockLedger`; name the descriptions whose locks
3354        // Detcore follows that survived the exec (its close-on-exec slots are
3355        // gone from this table). A failed exec reaches neither.
3356        let surviving = guest.thread_state().lock_tracked_slots();
3357        if !surviving.is_empty() {
3358            tool_global::note_table_exec(guest, surviving).await;
3359        }
3360        // The new image's auxiliary vector, as it finds it on its initial
3361        // stack, for its `/proc/<pid>/auxv` (package K slice K2 of
3362        // https://github.com/rrnewton/hermit/issues/4213). Not under record
3363        // and replay, where Detcore renders no procfs file.
3364        // Boxed, so its injected calls do not grow the post-exec future,
3365        // which a backend may poll on a small stack.
3366        if !self.cfg.recordreplay_modes {
3367            Box::pin(self.record_process_auxv(guest)).await;
3368        }
3369        // The new image's program-break model, checked against the kernel's
3370        // once its exec record is in place.
3371        self.check_brk_model(guest).await;
3372        // Linux discards every queued POSIX timer signal at exec
3373        // (`flush_itimer_signals`), and Hermit's are ordinary signals it sent:
3374        // take them back before the new image runs
3375        // (https://github.com/rrnewton/hermit/issues/4184).
3376        if scheduler::timer_copies_recorded() || scheduler::real_time_expiration_kept_pending() {
3377            self.flush_exec_timer_copies(guest).await;
3378        }
3379        self.pre_handler_hook(guest, false, CheckIn::Event).await;
3380
3381        let auxv = guest.auxv();
3382        let initialized = guest
3383            .thread_state_mut()
3384            .complete_initial_random_auxv(auxv.at_random().map(|p| p.as_raw()))
3385            .expect("authenticated initial random handoff no longer matches this image");
3386        // A backend that wrote AT_RANDOM before this callback (the loader
3387        // handoff) emitted no record: emit it here from the bytes it wrote, with
3388        // no second draw or write, so the record sits where every backend puts
3389        // it, after the root thread's seeding records. The loader's getrandom
3390        // fills (glibc's early initialization makes one) and resource-limit
3391        // reads (glibc's startup reads RLIMIT_STACK) emitted none either: their
3392        // records follow, in order, as when this thread's own handlers serve
3393        // them after this callback.
3394        if let Some((bytes, early_requests)) = initialized {
3395            let dettid = guest.thread_state().dettid;
3396            random::record_initial_auxv(dettid, &bytes);
3397            for request in early_requests {
3398                match request {
3399                    random::EarlyRequest::Getrandom(fill) => {
3400                        random::record_early_getrandom(dettid, fill)
3401                    }
3402                    random::EarlyRequest::LimitRead {
3403                        call,
3404                        resource,
3405                        current,
3406                        maximum,
3407                    } => {
3408                        syscalls::sysinfo::record_early_limit_read(call, resource, current, maximum)
3409                    }
3410                }
3411            }
3412        } else if let Some(ptr) = auxv.at_random() {
3413            // It is safe to mutate this address since libc has not yet had a
3414            // chance to modify or copy the auxv table.
3415            let memory = guest.memory();
3416            let dettid = guest.thread_state().dettid;
3417            let ptr = unsafe { ptr.into_mut() };
3418            random::initialize_auxv(
3419                guest.thread_state_mut().thread_prng(),
3420                memory,
3421                ptr.cast(),
3422                dettid,
3423            )?;
3424        }
3425
3426        // Successful exec never returns through handle_syscall_event, so the
3427        // nested recorder/replayer needs this callback to commit or retire its
3428        // pending exec state before the replacement image issues another exec.
3429        self.record_or_replay
3430            .handle_post_exec(&mut guest.into_guest())
3431            .await?;
3432
3433        self.post_handler_hook(guest, CheckIn::Event).await;
3434        Ok(())
3435    }
3436
3437    /// A timer fires to preempt the guest and give other threads a turn.
3438    async fn handle_timer_event<G: Guest<Self>>(&self, guest: &mut G) {
3439        // A preemption stops the guest in user code (A5 step 3.2).
3440        guest.thread_state_mut().delivery_interruption = Some(reverie::Interruption::NotInSyscall);
3441        info!(
3442            "[detcore, dtid {}] inbound timer preemption event",
3443            guest.thread_state().dettid
3444        );
3445        if guest.config().preemption_stacktrace {
3446            let mut file_writer: Box<dyn Write> =
3447                match &guest.config().preemption_stacktrace_log_file {
3448                    Some(path) => Box::new(
3449                        File::create(path).expect("Failed to open preemption stacktrace log file"),
3450                    ),
3451                    // Under --max-log-bytes a full stderr must not stop the
3452                    // run before the cap; see `util::DroppingStderr`.
3453                    None if crate::nonwaiting_write::diagnostics_must_not_wait() => {
3454                        Box::new(crate::util::DroppingStderr)
3455                    }
3456                    None => Box::new(std::io::stderr()),
3457                };
3458            let ts = guest.thread_state();
3459            writeln!(
3460                file_writer,
3461                "\n>>> Guest tid {} preempted at thread time {} with stack trace:",
3462                ts.dettid,
3463                ts.thread_logical_time.as_nanos(),
3464            )
3465            .unwrap();
3466            if let Some(backtrace) = guest.backtrace() {
3467                if let Ok(pbt) = backtrace.pretty() {
3468                    writeln!(file_writer, "{}", pbt).unwrap();
3469                } else {
3470                    writeln!(file_writer, "{}", backtrace).unwrap();
3471                }
3472            } else {
3473                warn!("Could not read backtrace!");
3474            }
3475        }
3476        // This may LOOK like a noop, but actually all of the logic for ending the timeslice is in
3477        // the prehook.  All the timer has to do is interrupt the guest and generate an extra call
3478        // to this prehook.
3479        self.pre_handler_hook(guest, true, CheckIn::Event).await;
3480        if guest.config().no_rcb_time && guest.thread_state().last_rcb_timer_is_max {
3481            let max_timeslice_end = guest
3482                .thread_state()
3483                .max_timeslice_end
3484                .expect("PMU maximum timer requires a deadline");
3485            guest
3486                .thread_state_mut()
3487                .thread_logical_time
3488                .advance_to(max_timeslice_end);
3489            if self.cfg.should_trace_schedevent() {
3490                let dettid = guest.thread_state().dettid;
3491                let ev = with_guest_time(
3492                    guest,
3493                    SchedEvent {
3494                        dettid,
3495                        op: Op::OtherInstructions,
3496                        count: 1,
3497                        start_rip: None,
3498                        end_rip: None,
3499                        end_time: None,
3500                    },
3501                );
3502                let ev = with_guest_rip(guest, ev).await;
3503                trace_schedevent(guest, ev, false).await;
3504            }
3505            if self.cfg.replay_schedule_from.is_some() {
3506                let fallback_deadline = max_timeslice_end
3507                    + Duration::from_nanos(u64::from(
3508                        self.cfg
3509                            .max_timeslice
3510                            .expect("PMU maximum must be configured"),
3511                    ));
3512                let thread_state = guest.thread_state_mut();
3513                let replay_deadline = thread_state
3514                    .end_of_timeslice
3515                    .filter(|deadline| *deadline > max_timeslice_end)
3516                    .unwrap_or(fallback_deadline);
3517                thread_state.end_of_timeslice = Some(replay_deadline);
3518                thread_state.max_timeslice_end = Some(replay_deadline);
3519                thread_state.last_rcb_timer = None;
3520                thread_state.last_rcb_timer_is_max = false;
3521                thread_state.stats.reset_timeslice();
3522            } else if guest.thread_state().own_signal_turn_hold.is_none() {
3523                self.end_timeslice(guest).await;
3524            }
3525        }
3526        self.post_handler_hook(guest, CheckIn::Event).await;
3527    }
3528
3529    async fn handle_syscall_event<G: Guest<Self>>(
3530        &self,
3531        guest: &mut G,
3532        call: Syscall,
3533    ) -> Result<i64, Error> {
3534        #[cfg(feature = "dispatch-observer")]
3535        if let Some(observer) = dispatch_observer::installed() {
3536            // This is the genuine incoming event. An entry record does not
3537            // establish that subsequent signal gates or handling completed.
3538            let registers = guest.regs().await;
3539            let (number, arguments) = call.into_parts();
3540            observer(dispatch_observer::Entry {
3541                pid: guest.pid().as_raw(),
3542                tid: guest.tid().as_raw(),
3543                dettid: guest.thread_state().dettid.as_raw(),
3544                number: number as u64,
3545                instruction_pointer: registers.rip,
3546                arguments: [
3547                    arguments.arg0 as u64,
3548                    arguments.arg1 as u64,
3549                    arguments.arg2 as u64,
3550                    arguments.arg3 as u64,
3551                    arguments.arg4 as u64,
3552                    arguments.arg5 as u64,
3553                ],
3554            });
3555        }
3556        // A FIFO open's path page that a killed task of this address space
3557        // left mapped goes before this call runs (and, below, before a call
3558        // that was waiting returns).
3559        Self::unmap_orphaned_staging_pages(guest).await;
3560        crate::syscalls::signal_shadow::at_syscall_entry(guest);
3561        // Until Detcore finishes it, the kernel may run it (A5 step 3.2).
3562        guest.thread_state_mut().delivery_interruption = Some(reverie::Interruption::KernelRun {
3563            syscall: call.number() as i64,
3564        });
3565        // Signal controls an in-guest runtime refused since this process's
3566        // last report, which Detcore did not see as calls.
3567        crate::refused_signal_controls::report(guest).await;
3568        // Signal phase 1: before this syscall's first scheduler request. A
3569        // delivery prepared here runs the guest's handler before the syscall,
3570        // which then starts again; what this returns is discarded.
3571        if self.cfg.backend.virtualizes_guest_sigalrm
3572            && guest.thread_state().sigalrm_handled
3573            && self.sigalrm_at_syscall_entry(guest).await
3574        {
3575            return Ok(0);
3576        }
3577
3578        // A thread that keeps its turn for a signal it sent its own process
3579        // takes that signal before it can make another syscall.
3580        if let Some(signal) = guest.thread_state_mut().own_signal_turn_hold.take() {
3581            tracing::error!(
3582                "[detcore, dtid {}] reached a syscall without taking signal {} it sent to its own \
3583                 process (https://github.com/rrnewton/hermit/issues/4034)",
3584                guest.thread_state().dettid,
3585                signal
3586            );
3587        }
3588        // A claimed `SIGCHLD` stays claimed only while it is still pending for
3589        // this thread (`syscalls::signal::claim_still_pending`).
3590        let (pid, tid) = (guest.pid(), guest.tid());
3591        let claimed =
3592            crate::syscalls::claim_still_pending(guest.thread_state().claimed_sigchld, || {
3593                crate::syscalls::read_thread_signal_state(pid, tid)
3594            });
3595        guest.thread_state_mut().claimed_sigchld = claimed;
3596        self.pre_handler_hook(guest, false, CheckIn::Event).await;
3597
3598        // Linux's restart of an interrupted wait is the thread's very next syscall,
3599        // so the record a wait kept for it lives only until then
3600        // (`handle_restart_syscall`).
3601        let restart_block = guest.thread_state_mut().restart_block.take();
3602
3603        let dettid = guest.thread_state().dettid;
3604
3605        if guest.thread_state().guest_past_first_execve() {
3606            detlog!(
3607                event = crate::detlog::DetLogEvent::Syscall;
3608                "[syscall][detcore, dtid {}] inbound syscall: {} = ?",
3609                dettid,
3610                call.display(&guest.memory())
3611            );
3612        }
3613
3614        // The hot syscall path only reads a few Copy flags from the config, so copy
3615        // just those out instead of cloning the entire Config on every intercepted
3616        // syscall (previously flagged inline as an unnecessary copy). guest.config()
3617        // borrows guest immutably; bind the flags in a tight scope so the borrow ends
3618        // before the later thread_state_mut()/&mut guest borrows below.
3619        let (sequentialize_threads, virtualize_time, panic_on_unsupported_syscalls) = {
3620            let config = guest.config();
3621            (
3622                config.sequentialize_threads,
3623                config.virtualize_time,
3624                config.panic_on_unsupported_syscalls,
3625            )
3626        };
3627
3628        if sequentialize_threads && self.cfg.should_trace_schedevent() {
3629            trace_schedevent(
3630                guest,
3631                with_guest_time(
3632                    guest,
3633                    SchedEvent::syscall(dettid, call.number(), SyscallPhase::Prehook),
3634                ),
3635                true,
3636            )
3637            .await;
3638        }
3639
3640        let syscall_cost_ns = syscall_time::cost_ns(call.number());
3641        // The backend-runtime bootstrap window. A backend-resident runtime (the
3642        // LiteInst preload constructor) issues hundreds to thousands of syscalls
3643        // on one thread (315 for a small C program, 6,970 for emacs; see
3644        // `syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS`) between its validated
3645        // begin trap and the trap that ends its bootstrap: the ready report, or
3646        // the report that preparation failed.
3647        // Reverie reports that window only for the bootstrapping thread; every
3648        // other thread and every forked process sees no window.
3649        //
3650        // What is withheld: the per-syscall cost below, for the bootstrapping
3651        // thread only, for each syscall it makes inside the window that does not
3652        // observe virtual time, up to
3653        // `syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS` per window. That
3654        // includes syscalls made by guest code the runtime calls into, such as
3655        // an interposed malloc or open64. Charging the runtime's own syscalls
3656        // would make guest-visible virtual time (uptime, CLOCK_MONOTONIC, CPU
3657        // time) depend on which backend ran the program. Every withheld syscall
3658        // is still counted and fully handled below, so Detcore keeps tracking
3659        // the fds, mappings and inodes it creates.
3660        //
3661        // What is always charged, inside the window too: syscalls that observe
3662        // virtual time (`syscall_time::observes_virtual_time`), so two clock
3663        // reads on the bootstrapping thread differ by at least one syscall cost
3664        // exactly as outside the window; and every syscall past the cap, so a
3665        // loop inside the window, or a runtime that never reports ready, again
3666        // advances the clock at each syscall.
3667        //
3668        // When it matters: with a syscall-driven clock (no PMU, or
3669        // --max-timeslice=disabled, which Hermit selects when perf counters are
3670        // unavailable, or --no-rcb-time) these charges are the thread's only
3671        // per-syscall progress, and with sequentialized threads the 500x no-RCB
3672        // multiplier makes each one large. With RCB time on a PMU host, retired
3673        // branches still advance the thread's clock inside the window and only
3674        // the syscall costs are withheld.
3675        //
3676        // The decision depends only on the window the backend reports (opened
3677        // and closed by trap instructions the runtime executes), the syscall
3678        // number and the count of earlier uncharged syscalls in the same
3679        // window: all functions of the guest's own execution. Record/replay and
3680        // both --verify runs therefore make the same decisions. The clock is
3681        // never reset: the first syscall after the window continues from the
3682        // value the window left. See https://github.com/rrnewton/hermit/issues/3338
3683        // and https://github.com/rrnewton/hermit/pull/3430#issuecomment-5928691696.
3684        //
3685        // The scheduler turns such a syscall needs are withheld the same way.
3686        // Handling an uncharged syscall can still commit scheduler turns (for
3687        // example the file resources of a read of /proc/self/maps), and each
3688        // committed turn normally advances global time by the per-turn
3689        // scheduler cost. While the syscall is being handled the thread is
3690        // marked `in_uncharged_bootstrap_syscall`, `tool_global::resource_request`
3691        // copies that mark into the request, and the scheduler does not
3692        // advance global time for a marked turn unless it is an IO-polling
3693        // retry, whose time enforces timeouts. Without this, a LiteInst run of
3694        // the clock-trajectory fixture reached its first clock read 11.5 ms of
3695        // virtual time later than with it, and each exec added 12.0 ms more
3696        // (measured locally), which was enough for its sysinfo uptime to
3697        // differ from the ptrace backend's on the hosted runner
3698        // (https://github.com/rrnewton/hermit/issues/3517). A charged syscall
3699        // (one that observes virtual time, or any past the cap) is not marked,
3700        // so its turns advance the clock as everywhere else.
3701        let in_backend_runtime_bootstrap = guest.is_backend_runtime_bootstrap();
3702        let new_count = {
3703            // which results from not being able to borrow guest twice.
3704            let thread_state = guest.thread_state_mut();
3705            thread_state.stats.count_syscall();
3706
3707            // Every intercepted syscall advances logical time, including configurations that do
3708            // not serialize threads. This keeps virtual clocks productive during syscall loops.
3709            // The one exception is the bootstrap window described above: on the bootstrapping
3710            // thread, up to MAX_UNCHARGED_BOOTSTRAP_SYSCALLS syscalls per window that do not
3711            // observe virtual time are left uncharged.
3712            let charged =
3713                thread_state.charge_syscall_time(in_backend_runtime_bootstrap, call.number());
3714            if charged {
3715                thread_state
3716                    .thread_logical_time
3717                    .add_syscall_with_cost(syscall_cost_ns);
3718            }
3719            thread_state.in_uncharged_bootstrap_syscall = !charged;
3720            // This only folds the thread's new user and system time into the process total.
3721            // An uncharged syscall added none, so it needs no guard.
3722            thread_state.account_process_cpu_time();
3723            thread_state.stats.syscall_count
3724        };
3725
3726        // Happens-before enforcement checkpoint. When the run carries a
3727        // happens-before program and an anchor at exactly
3728        // `Position::SyscallCount(new_count)` names this thread (by dettid, or by
3729        // a spawn ordinal only the scheduler can resolve), this syscall checks in
3730        // with the scheduler at its prehook, carrying this thread's running
3731        // syscall count.
3732        // The scheduler fires any anchor at that count on this thread and parks
3733        // the thread (out of the run queue) when that anchor is the AFTER
3734        // endpoint of a Hard edge whose BEFORE endpoint has not fired yet. For
3735        // any other (thread, count) the scheduler would find no anchor and do
3736        // nothing, so the request is skipped: one scheduler round trip per anchor
3737        // the thread reaches rather than per syscall
3738        // (https://github.com/rrnewton/hermit/issues/3877), and threads the spec
3739        // does not name keep their schedule.
3740        // This is the gate that makes an authored partial order reproduce a known
3741        // race deterministically (see detcore-model `happens_before`). It
3742        // requires sequentialized threads (enforced by the CLI) so the scheduler
3743        // owns ordering.
3744        //
3745        // A syscall-occurrence anchor ("the thread's Nth writev to fd 9") is
3746        // counted here, in this thread's own counters, once per syscall entry;
3747        // the thread checks in only when a call is some such anchor's nth
3748        // occurrence, naming the anchors it reached.
3749        let hb_checkpoint = if guest.config().happens_before.is_some() {
3750            let dettid = guest.thread_state().dettid;
3751            let mut counters = std::mem::take(&mut guest.thread_state_mut().stats.hb_occurrences);
3752            let program = guest
3753                .config()
3754                .happens_before
3755                .as_ref()
3756                .expect("checked above");
3757            // A posthook anchor this entry reaches checks in when the call
3758            // completes, below, not here
3759            // (https://github.com/rrnewton/hermit/issues/3929).
3760            let mut reached = if program.has_syscall_occurrence_anchors() {
3761                let (sysno, args) = call.into_parts();
3762                program.count_syscall_occurrences(
3763                    &mut counters,
3764                    dettid,
3765                    sysno,
3766                    [args.arg0, args.arg1],
3767                    new_count,
3768                )
3769            } else {
3770                Vec::new()
3771            };
3772            let posthook: Vec<String> = reached
3773                .extract_if(.., |name| {
3774                    program
3775                        .anchors
3776                        .get(name)
3777                        .is_some_and(|a| a.fires_at_posthook())
3778                })
3779                .collect();
3780            let checkpoint = if !reached.is_empty() {
3781                Some(ResourceID::HappensBeforeSyscallCheckpoint {
3782                    count: new_count,
3783                    anchors: reached,
3784                })
3785            } else if program.may_have_syscall_count_anchor_at(dettid, new_count) {
3786                Some(ResourceID::HappensBeforeCheckpoint(new_count))
3787            } else {
3788                None
3789            };
3790            guest.thread_state_mut().stats.hb_occurrences = counters;
3791            guest.thread_state_mut().stats.hb_pending_posthook = posthook;
3792            checkpoint
3793        } else {
3794            None
3795        };
3796        if let Some(checkpoint) = hb_checkpoint {
3797            let request = guest.thread_state().mk_request(checkpoint, Permission::R);
3798            resource_request(guest, request).await;
3799        }
3800
3801        // For `hermit run --verify`: a name the guest itself rebinds is not a
3802        // host input change (see `detcore_model::host_input`). Reported before
3803        // the call runs, whatever its outcome, so that a change the kernel
3804        // commits is never missing from the record, even if the run ends
3805        // before this handler returns.
3806        if self.cfg.record_host_inputs {
3807            self.record_host_namespace_change(guest, &call).await;
3808            self.record_untraced_code_change(guest, &call).await;
3809        }
3810
3811        // The inodes whose last name this call removes, stat'ed before it runs
3812        // and retired once it succeeds, so that a host reusing one cannot hand
3813        // a new file the old file's number
3814        // (https://github.com/rrnewton/hermit/issues/3840).
3815        let removed_inodes = self.last_names_removed_by(guest, &call).await;
3816        // The guest-made FIFOs whose name this call removes, forgotten once it
3817        // succeeds (https://github.com/rrnewton/hermit/issues/2203).
3818        let removed_guest_fifos = self.guest_made_fifos_removed_by(guest, &call).await;
3819
3820        // Only an emulated RNG readv supplies authoritative imported geometry.
3821        // A generic pre-dispatch snapshot would become stale across pipe waits.
3822        let mut rng_readv_output = None;
3823        // Signal phase 1: a process that handles SIGALRM runs only the calls
3824        // its table places (`sigalrm_phase1`).
3825        let sigalrm_refusal = if guest.thread_state().sigalrm_handled {
3826            self.sigalrm_phase1_gate(guest, call)
3827        } else {
3828            None
3829        };
3830        // A `/proc` name outside the run's `--proc` level does not exist. A
3831        // procfs file Detcore renders answers, as Linux does, the calls that
3832        // would reach the placeholder standing in for it.
3833        // A rendered procfs descriptor that reached this table over
3834        // SCM_RIGHTS is adopted as the file it is before anything answers a
3835        // call through it.
3836        let adoption = if sigalrm_refusal.is_none() {
3837            self.adopt_received_placeholders(guest, &call).await
3838        } else {
3839            Ok(())
3840        };
3841        let rendered_procfs_answer = if let Err(error) = adoption {
3842            Some(Err(error))
3843        } else if sigalrm_refusal.is_none() {
3844            match self
3845                .refuse_procfs_name_outside_level(guest, &call)
3846                .await
3847                .transpose()
3848            {
3849                Some(refusal) => Some(refusal),
3850                None => match self.answer_rendered_procfs_operation(guest, &call).await {
3851                    Some(answer) => Some(answer),
3852                    None => match self.answer_rendered_procfs_mapping(guest, &call).await {
3853                        Some(answer) => Some(answer),
3854                        None => self
3855                            .answer_rendered_procfs_path_call(guest, &call)
3856                            .await
3857                            .transpose(),
3858                    },
3859                },
3860            }
3861        } else {
3862            None
3863        };
3864        let res = match classify_syscall(call.number()) {
3865            _ if sigalrm_refusal.is_some() => Err(sigalrm_refusal.expect("checked").into()),
3866            _ if rendered_procfs_answer.is_some() => rendered_procfs_answer.expect("checked"),
3867            SyscallClassification::PassThrough if call.number() == Sysno::chroot => {
3868                let result = self.passthrough(guest, call).await;
3869                if result.is_ok() {
3870                    guest
3871                        .thread_state()
3872                        .changed_root
3873                        .store(true, std::sync::atomic::Ordering::SeqCst);
3874                    // Another process's view of this one's mount table
3875                    // follows its root (`Detcore::rendered_procfs_at`).
3876                    crate::tool_global::mark_changed_root(guest).await;
3877                }
3878                result
3879            }
3880            // Outbound TCP channels under a network trace mode; never with no mode.
3881            _ if self.network_trace_owns(guest, &call) => {
3882                self.handle_network_trace_syscall(guest, call).await
3883            }
3884            // Rseq is not type-safe in the pinned Reverie revision. Dispatch by Sysno so a
3885            // future typed representation preserves this explicit policy.
3886            SyscallClassification::Determinized if call.number() == Sysno::rseq => {
3887                if panic_on_unsupported_syscalls {
3888                    Err(Error::Errno(Errno::ENOSYS))
3889                } else {
3890                    self.passthrough(guest, call).await
3891                }
3892            }
3893            // AUTONOMOUS-BOT-IMPLEMENTED
3894            // TODO-HUMAN-REVIEW(#663)
3895            // The pinned Reverie revision exposes process_madvise only as a raw call.
3896            SyscallClassification::Determinized if call.number() == Sysno::process_madvise => {
3897                match call {
3898                    Syscall::Other(_, args) => Self::handle_process_madvise(args.arg0, args.arg4),
3899                    _ => unreachable!("process_madvise unexpectedly gained a typed variant"),
3900                }
3901            }
3902            // AUTONOMOUS-BOT-IMPLEMENTED
3903            // TODO-HUMAN-REVIEW(PR-1175): The pinned Reverie revision exposes
3904            // pidfd_send_signal/pidfd_getfd only as raw calls, so dispatch on the
3905            // Sysno. See the handlers in syscalls/files.rs for the determinism
3906            // argument.
3907            SyscallClassification::Determinized if call.number() == Sysno::pidfd_send_signal => {
3908                match call {
3909                    Syscall::Other(_, args) => {
3910                        let result = self
3911                            .handle_pidfd_send_signal(
3912                                guest,
3913                                call,
3914                                args.arg0 as RawFd,
3915                                args.arg1 as i32,
3916                                args.arg3 as u32,
3917                            )
3918                            .await;
3919                        if args.arg1 as i32 == libc::SIGALRM && result.is_ok() {
3920                            self.note_guest_sigalrm(guest, GuestSigalrmTarget::Unclassified)
3921                                .await;
3922                        }
3923                        result
3924                    }
3925                    _ => unreachable!("pidfd_send_signal unexpectedly gained a typed variant"),
3926                }
3927            }
3928            // AUTONOMOUS-BOT-IMPLEMENTED
3929            // TODO-HUMAN-REVIEW(PR-1175): pidfd_getfd, likewise untyped.
3930            SyscallClassification::Determinized if call.number() == Sysno::pidfd_getfd => {
3931                match call {
3932                    Syscall::Other(_, args) => {
3933                        self.handle_pidfd_getfd(
3934                            guest,
3935                            call,
3936                            args.arg0 as RawFd,
3937                            args.arg1 as RawFd,
3938                            args.arg2 as u32,
3939                        )
3940                        .await
3941                    }
3942                    _ => unreachable!("pidfd_getfd unexpectedly gained a typed variant"),
3943                }
3944            }
3945            // AUTONOMOUS-BOT-IMPLEMENTED
3946            // TODO-HUMAN-REVIEW(#715): Deterministic ENOSYS for syscalls the pinned
3947            // x86_64 kernel leaves unimplemented (sys_ni_syscall). A fixed -ENOSYS is
3948            // deterministic by construction and identical to the modern kernel's own
3949            // return, so no guest-visible behavior changes versus the legacy
3950            // pass-through. These are untyped (Syscall::Other) in the pinned Reverie,
3951            // so dispatch on the Sysno before the typed match below.
3952            SyscallClassification::Determinized
3953                if is_unimplemented_enosys_syscall(call.number()) =>
3954            {
3955                Err(Error::Errno(Errno::ENOSYS))
3956            }
3957            // AUTONOMOUS-BOT-IMPLEMENTED
3958            // TODO-HUMAN-REVIEW(PR-852): Review the futex2 fallback contract.
3959            // Detcore models legacy futex but not the newer vector/sized futex2
3960            // ABI. Match a kernel without futex2 so runtimes take their
3961            // established legacy-futex fallback without consulting the host.
3962            SyscallClassification::Determinized if is_futex2_enosys_syscall(call.number()) => {
3963                Err(Error::Errno(Errno::ENOSYS))
3964            }
3965            // AUTONOMOUS-BOT-IMPLEMENTED
3966            // TODO-HUMAN-REVIEW(PR-836): Host filesystem and mount
3967            // introspection are outside the deterministic model. Return the
3968            // portable feature-absence errno so callers use /proc fallbacks.
3969            // AUTONOMOUS-BOT-IMPLEMENTED
3970            // TODO-HUMAN-REVIEW(PR-859): Extend this boundary to obsolete ustat
3971            // host-filesystem capacity counters.
3972            SyscallClassification::Determinized
3973                if is_mount_introspection_enosys_syscall(call.number()) =>
3974            {
3975                Err(Error::Errno(Errno::ENOSYS))
3976            }
3977            // AUTONOMOUS-BOT-IMPLEMENTED
3978            // TODO-HUMAN-REVIEW(PR-848): Hide unmodeled shared keyrings and
3979            // request-key upcalls behind the portable CONFIG_KEYS-absent errno.
3980            // TODO-HUMAN-REVIEW(PR-916): Fail closed whenever the
3981            // panic-on-unsupported policy is active; ordinary runs select that
3982            // policy by default. The explicit compatibility opt-out keeps the
3983            // pre-848 host pass-through so the guest observes a real working
3984            // keyring, restoring the enabled rr `keyctl` compatibility test.
3985            // Under fail-closed execution the deterministic ENOSYS boundary is
3986            // preserved.
3987            SyscallClassification::Determinized if is_kernel_keyring_syscall(call.number()) => {
3988                if panic_on_unsupported_syscalls {
3989                    Err(Error::Errno(Errno::ENOSYS))
3990                } else {
3991                    self.passthrough(guest, call).await
3992                }
3993            }
3994            // AUTONOMOUS-BOT-IMPLEMENTED
3995            // TODO-HUMAN-REVIEW(PR-855): Fail-closed runs cannot expose
3996            // unmodeled pipe-buffer ownership or vmsplice page pinning, but
3997            // preserve host pass-through under the explicit compatibility
3998            // opt-out, `hermit run --allow-unsupported-syscalls`. splice and tee
3999            // refuse with EINVAL, the errno Linux returns when a descriptor
4000            // pair cannot be spliced and the one callers fall back to
4001            // read/write on: GNU grep 3.12 drains a pipe into /dev/null with
4002            // splice and falls back on EINVAL, but on ENOSYS it reports a read
4003            // error and exits 2. vmsplice keeps ENOSYS.
4004            SyscallClassification::Determinized if is_zero_copy_pipe_syscall(call.number()) => {
4005                if panic_on_unsupported_syscalls {
4006                    if call.number() == Sysno::vmsplice {
4007                        Err(Error::Errno(Errno::ENOSYS))
4008                    } else {
4009                        Err(Error::Errno(Errno::EINVAL))
4010                    }
4011                } else {
4012                    self.passthrough(guest, call).await
4013                }
4014            }
4015            // AUTONOMOUS-BOT-IMPLEMENTED
4016            // TODO-HUMAN-REVIEW(PR-860): Host LSM attributes are outside
4017            // Detcore's model. Present a stable feature-absence boundary
4018            // instead of forwarding probes.
4019            SyscallClassification::Determinized
4020                if is_host_security_identity_probe_syscall(call.number()) =>
4021            {
4022                Err(Error::Errno(Errno::ENOSYS))
4023            }
4024            // AUTONOMOUS-BOT-IMPLEMENTED
4025            // TODO-HUMAN-REVIEW(#722): Deterministic EPERM for privileged
4026            // system-administration syscalls (module load/unload, kexec, reboot,
4027            // swap, raw I/O ports, root-mount pivot, host/domain name, tty
4028            // hangup, disk quotas). The deterministic guest does not hold the
4029            // capabilities these require against the host kernel, so a fixed
4030            // -EPERM matches the unprivileged errno, never perturbs global host
4031            // state, and is identical across --verify and record/replay. These
4032            // are untyped (Syscall::Other) in the pinned Reverie, so dispatch on
4033            // the Sysno before the typed match below.
4034            SyscallClassification::Determinized
4035                if is_privileged_admin_refused_syscall(call.number()) =>
4036            {
4037                Err(Error::Errno(Errno::EPERM))
4038            }
4039            // AUTONOMOUS-BOT-IMPLEMENTED
4040            // TODO-HUMAN-REVIEW(PR-844): Enforce a deterministic boundary
4041            // around host-global process accounting and cross-process memory.
4042            SyscallClassification::Determinized
4043                if is_process_isolation_refused_syscall(call.number()) =>
4044            {
4045                Err(Error::Errno(Errno::EPERM))
4046            }
4047            // AUTONOMOUS-BOT-IMPLEMENTED
4048            // TODO-HUMAN-REVIEW(PR-876): Guest performance events
4049            // expose host PMU availability, policy, and asynchronous counter
4050            // state that Detcore does not model. A fixed ENOSYS preserves the
4051            // portable feature-probe fallback without creating an untracked fd.
4052            SyscallClassification::Determinized if is_perf_event_enosys_syscall(call.number()) => {
4053                Err(Error::Errno(Errno::ENOSYS))
4054            }
4055            // AUTONOMOUS-BOT-IMPLEMENTED
4056            // TODO-HUMAN-REVIEW(PR-853): Refuse nested tracing, host-object
4057            // comparison at the deterministic boundary.
4058            SyscallClassification::Determinized
4059                if is_privileged_observation_refused_syscall(call.number()) =>
4060            {
4061                Err(Error::Errno(Errno::EPERM))
4062            }
4063            // AUTONOMOUS-BOT-IMPLEMENTED
4064            // TODO-HUMAN-REVIEW(#720): set_mempolicy_home_node is untyped in the
4065            // pinned Reverie revision. Hermit exposes a single virtual NUMA node,
4066            // so setting a memory range's home node has no observable effect: a
4067            // deterministic no-op.
4068            SyscallClassification::Determinized
4069                if call.number() == Sysno::set_mempolicy_home_node =>
4070            {
4071                Ok(0)
4072            }
4073            // AUTONOMOUS-BOT-IMPLEMENTED
4074            // TODO-HUMAN-REVIEW(#724): Deterministic EPERM for privileged mount
4075            // and namespace administration syscalls (mount/umount2/mount_setattr/
4076            // move_mount/open_tree/fsopen/fsmount/fsconfig/fspick, unshare, setns,
4077            // open_by_handle_at, fanotify_init/fanotify_mark, settimeofday). A
4078            // deterministic container pins the guest's namespaces, mount
4079            // hierarchy, and virtual clock for the whole run, so these are
4080            // refused with a fixed -EPERM: the unprivileged errno for the
4081            // capability-gated operations and a deliberate deterministic refusal
4082            // otherwise. Never forwarded to the host; identical across --verify
4083            // and record/replay. Untyped (Syscall::Other) in the pinned Reverie,
4084            // so dispatch on the Sysno before the typed match below.
4085            SyscallClassification::Determinized
4086                if is_mount_ns_admin_refused_syscall(call.number()) =>
4087            {
4088                Err(Error::Errno(Errno::EPERM))
4089            }
4090            // AUTONOMOUS-BOT-IMPLEMENTED
4091            // TODO-HUMAN-REVIEW(#731): Deterministic ENOSYS for the
4092            // asynchronous and message-passing I/O and IPC interfaces Detcore
4093            // does not model: Linux native AIO (io_setup/io_destroy/io_submit/
4094            // io_cancel/io_getevents/io_pgetevents), POSIX message queues
4095            // (mq_*), and System V message queues (msg*). AIO completion is
4096            // kernel-driven and lives outside logical time; the message-queue
4097            // families operate on global, key/name-addressed kernel objects
4098            // shared with the whole host. A fixed -ENOSYS is the errno a kernel
4099            // built without AIO/CONFIG_POSIX_MQUEUE/CONFIG_SYSVIPC returns, is
4100            // never forwarded to the host, and is identical across --verify and
4101            // record/replay (mirrors the io_uring refusal). Untyped
4102            // (Syscall::Other) in the pinned Reverie, so dispatch on the Sysno
4103            // before the typed match below.
4104            // AUTONOMOUS-BOT-IMPLEMENTED
4105            // TODO-HUMAN-REVIEW(PR-859): Include System V semaphore and shared-
4106            // memory objects in the existing CONFIG_SYSVIPC refusal boundary.
4107            SyscallClassification::Determinized
4108                if is_unsupported_async_ipc_syscall(call.number()) =>
4109            {
4110                Err(Error::Errno(Errno::ENOSYS))
4111            }
4112            // AUTONOMOUS-BOT-IMPLEMENTED
4113            // TODO-HUMAN-REVIEW(PR-882): Legacy nonlinear page
4114            // remapping has host-dependent kernel support and VMA behavior that
4115            // Detcore does not model. Preserve the documented mmap fallback.
4116            SyscallClassification::Determinized
4117                if is_remap_file_pages_enosys_syscall(call.number()) =>
4118            {
4119                Err(Error::Errno(Errno::ENOSYS))
4120            }
4121            // AUTONOMOUS-BOT-IMPLEMENTED
4122            // TODO-HUMAN-REVIEW(#787): BATCH 38. openat2 is untyped (Syscall::Other)
4123            // in the pinned Reverie revision. It is a superset of openat whose
4124            // callers must fall back to openat when it returns ENOSYS (kernels
4125            // before 5.6 lack openat2), so a fixed -ENOSYS routes them onto the
4126            // already-determinized openat path with no host dependency and behavior
4127            // identical across --verify and record/replay.
4128            SyscallClassification::Determinized if call.number() == Sysno::openat2 => {
4129                Err(Error::Errno(Errno::ENOSYS))
4130            }
4131            // AUTONOMOUS-BOT-IMPLEMENTED
4132            // TODO-HUMAN-REVIEW(#787): BATCH 38. The credential-setting family
4133            // (setuid/setgid and their re-/res-/fs- variants, and setgroups) is
4134            // untyped (Syscall::Other) in the pinned Reverie. Detcore presents a
4135            // fixed virtual-root identity (getuid/geteuid/getgid/getegid are
4136            // virtualized to 0) and never tracks a credential change, so these
4137            // succeed as deterministic no-ops returning 0 -- the value a real root
4138            // process gets for a permitted credential change (and the previous
4139            // fs-id, virtual 0, for setfsuid/setfsgid). That lets privilege-
4140            // dropping programs proceed instead of fail-closing and is identical
4141            // across --verify and record/replay.
4142            SyscallClassification::Determinized
4143                if is_credential_identity_noop_syscall(call.number()) =>
4144            {
4145                Ok(0)
4146            }
4147            // AUTONOMOUS-BOT-IMPLEMENTED
4148            // TODO-HUMAN-REVIEW(#1851): The file-ownership mutation family
4149            // (chown/fchown/fchownat/lchown) completes the fixed virtual-root
4150            // identity that the credential query (#1549) and credential set
4151            // (#787) families already implement. A real root process's chown
4152            // succeeds for any uid, so 0 is the value the virtual identity must
4153            // observe; forwarding instead returned the errno of whatever host
4154            // identity the backend happened to run under (EPERM with no user
4155            // namespace, EINVAL for an unmapped uid inside a one-uid map, and
4156            // backend-dependent for in-process backends).
4157            //
4158            // The emulation covers the IDENTITY half only. Root privilege
4159            // waives the ownership permission check; it does not waive pathname,
4160            // descriptor, or flag errors, so handle_ownership_change_noop
4161            // translates the target arguments into a side-effect-free metadata
4162            // lookup and returns 0 only if that validation succeeds. ENOENT,
4163            // EBADF, EFAULT, ENOTDIR and the fchownat flag EINVAL therefore
4164            // still reach the guest; the host-identity-dependent EPERM/EINVAL
4165            // cannot be produced at all. No setattr is attempted, so host
4166            // ownership, mode bits, and timestamps are never modified, and
4167            // Detcore does not model per-file ownership, so the success is not
4168            // observable through a later stat -- see
4169            // is_ownership_change_noop_syscall and handle_ownership_change_noop
4170            // for the full boundary, and
4171            // hermit-cli/tests/chown_virtual_root_identity.rs for the bracket
4172            // that fails if this arm's RESULT regresses.
4173            SyscallClassification::Determinized
4174                if is_ownership_change_noop_syscall(call.number()) =>
4175            {
4176                self.handle_ownership_change_noop(guest, call).await
4177            }
4178            // AUTONOMOUS-BOT-IMPLEMENTED
4179            // TODO-HUMAN-REVIEW(#827): Deterministic ENOSYS for the Landlock
4180            // unprivileged-sandbox syscalls (landlock_create_ruleset,
4181            // landlock_add_rule, landlock_restrict_self). Landlock availability
4182            // and ABI version depend on the host kernel build
4183            // (CONFIG_SECURITY_LANDLOCK) and runtime LSM stacking, so forwarding
4184            // them (the legacy pass-through) is host-dependent and, because a
4185            // ruleset restricts the whole thread tree, a global-state isolation
4186            // hole. A fixed -ENOSYS is the errno a kernel built without Landlock
4187            // returns, so the guest sees a consistent "sandbox unavailable"
4188            // answer regardless of host; never forwarded to the host and
4189            // bitwise-identical across --verify and record/replay. Untyped
4190            // (Syscall::Other) in the pinned Reverie, so dispatch on the Sysno
4191            // before the typed match below.
4192            SyscallClassification::Determinized if is_landlock_sandbox_syscall(call.number()) => {
4193                Err(Error::Errno(Errno::ENOSYS))
4194            }
4195            // AUTONOMOUS-BOT-IMPLEMENTED
4196            // TODO-HUMAN-REVIEW(PR-847): Refuse unmodeled host-kernel probes
4197            // with a fixed ENOSYS so guest behavior does not depend on BPF/LSM
4198            // configuration or mutable page-cache state.
4199            SyscallClassification::Determinized if is_host_kernel_probe_syscall(call.number()) => {
4200                Err(Error::Errno(Errno::ENOSYS))
4201            }
4202            // AUTONOMOUS-BOT-IMPLEMENTED
4203            // TODO-HUMAN-REVIEW(PR-838): Review close_range descriptor-table
4204            // synchronization. The pinned Reverie exposes close_range as a raw
4205            // call, so dispatch by Sysno before the typed match.
4206            SyscallClassification::Determinized if call.number() == Sysno::close_range => {
4207                self.handle_close_range(guest, call).await
4208            }
4209            // AUTONOMOUS-BOT-IMPLEMENTED
4210            // TODO-HUMAN-REVIEW(PR-839): Optional modern memory APIs vary with
4211            // host kernel configuration, CET support, and pidfd lifecycle.
4212            // Present the portable feature-absence result instead.
4213            SyscallClassification::Determinized
4214                if is_optional_memory_feature_syscall(call.number()) =>
4215            {
4216                Err(Error::Errno(Errno::ENOSYS))
4217            }
4218            // AUTONOMOUS-BOT-IMPLEMENTED
4219            // TODO-HUMAN-REVIEW(#773): epoll_pwait2 is untyped (Syscall::Other)
4220            // in the pinned Reverie revision. It is epoll_pwait with a
4221            // `struct timespec *` timeout; recent glibc routes epoll_wait/
4222            // epoll_pwait through it. Handled identically to epoll_pwait
4223            // (scheduler yield + record/replay forwarding).
4224            SyscallClassification::Determinized if call.number() == Sysno::epoll_pwait2 => {
4225                self.handle_epoll_pwait2(guest, call).await
4226            }
4227            SyscallClassification::Determinized => match call {
4228                Syscall::Getpid(_) | Syscall::Gettid(_) => {
4229                    // Keep the inner Tool's syscall observation/injection and
4230                    // all errors, then project a successful own ID from shared
4231                    // state. Do not return early past the normal posthooks.
4232                    self.passthrough(guest, call)
4233                        .await
4234                        .map(|result| self.project_own_getter_result(guest, call, result))
4235                }
4236                Syscall::Write(w) => self.handle_write(guest, w).await,
4237                // AUTONOMOUS-BOT-IMPLEMENTED
4238                // TODO-HUMAN-REVIEW(#547)
4239                Syscall::Writev(w) => self.handle_writev(guest, w).await,
4240                Syscall::Openat(o) => self.handle_openat(guest, o).await,
4241                Syscall::Open(o) => self.handle_openat(guest, o.into()).await,
4242                Syscall::Creat(o) => self.handle_openat(guest, o.into()).await,
4243                Syscall::Close(s) => self.handle_close(guest, s).await,
4244                Syscall::Read(s) if self.sock_diag_reply_fd(guest, s.fd()) => {
4245                    self.handle_sock_diag_read(guest, s).await
4246                }
4247                Syscall::Read(s) => self.handle_read(guest, s).await,
4248                Syscall::Pread64(s) => self.handle_pread64(guest, s).await,
4249                Syscall::Lseek(s) => self.handle_lseek(guest, s).await,
4250                // AUTONOMOUS-BOT-IMPLEMENTED
4251                // TODO-HUMAN-REVIEW(PR-838): Review regular-file sendfile mediation.
4252                Syscall::Sendfile(s) => self.handle_sendfile(guest, s).await,
4253                // AUTONOMOUS-BOT-IMPLEMENTED
4254                // TODO-HUMAN-REVIEW(PR-887): Present a stable pre-4.5-kernel
4255                // boundary so callers use determinized read/write copying.
4256                Syscall::CopyFileRange(_) => Err(Error::Errno(Errno::ENOSYS)),
4257                // TODO-HUMAN-REVIEW(#794): vectored scatter/gather I/O, mirroring
4258                // read/pread64/pwrite64/writev.
4259                Syscall::Readv(s) if self.sock_diag_reply_fd(guest, s.fd()) => {
4260                    self.handle_sock_diag_readv(guest, s).await
4261                }
4262                Syscall::Readv(s) => {
4263                    self.handle_readv_with_output(guest, s, &mut rng_readv_output)
4264                        .await
4265                }
4266                Syscall::Preadv(s) => {
4267                    self.handle_preadv_with_output(guest, s, &mut rng_readv_output)
4268                        .await
4269                }
4270                Syscall::Preadv2(s) => {
4271                    self.handle_preadv2_with_output(guest, s, &mut rng_readv_output)
4272                        .await
4273                }
4274                Syscall::Pwritev(s) => self.handle_pwritev(guest, s).await,
4275                Syscall::Pwritev2(s) => self.handle_pwritev2(guest, s).await,
4276                // AUTONOMOUS-BOT-IMPLEMENTED
4277                // TODO-HUMAN-REVIEW(#683)
4278                Syscall::Pwrite64(s) => self.handle_pwrite64(guest, s).await,
4279                // This syscall is advisory; fixed success preserves its API contract.
4280                Syscall::Fadvise64(_) => Ok(0),
4281                Syscall::Mmap(s) => self.handle_mmap(guest, s).await,
4282                Syscall::Madvise(s) => self.handle_madvise(guest, s).await,
4283                // AUTONOMOUS-BOT-IMPLEMENTED
4284                // TODO-HUMAN-REVIEW(#775)
4285                Syscall::Mincore(s) => self.handle_mincore(guest, s).await,
4286                Syscall::Munmap(s) => self.handle_munmap(guest, s).await,
4287                Syscall::Mremap(s) => self.handle_mremap(guest, s).await,
4288                Syscall::Stat(s) => self.handle_stat_family(guest, s.into()).await,
4289                Syscall::Lstat(s) => self.handle_stat_family(guest, s.into()).await,
4290                Syscall::Fstat(s) => self.handle_stat_family(guest, s.into()).await,
4291                Syscall::Newfstatat(s) => self.handle_stat_family(guest, s.into()).await,
4292                Syscall::Statx(s) => self.handle_statx(guest, s).await,
4293                // AUTONOMOUS-BOT-IMPLEMENTED
4294                // TODO-HUMAN-REVIEW(#877)
4295                Syscall::Readlink(s) => self.handle_readlink(guest, s).await,
4296                // AUTONOMOUS-BOT-IMPLEMENTED
4297                Syscall::Readlinkat(s) => self.handle_readlinkat(guest, s).await,
4298                Syscall::Fcntl(s) => self.handle_fcntl(guest, s).await,
4299                // AUTONOMOUS-BOT-IMPLEMENTED
4300                // TODO-HUMAN-REVIEW(PR-912)
4301                Syscall::Ioctl(s)
4302                    if syscalls::socket_timestamp_ioctl::is_socket_timestamp_ioctl(s) =>
4303                {
4304                    self.handle_socket_timestamp_ioctl(guest, s).await
4305                }
4306                Syscall::Ioctl(s) => self.handle_ioctl(guest, s).await,
4307                Syscall::Futex(s) => self.handle_futex(guest, s).await,
4308
4309                Syscall::Clone(s) => self.handle_clone_family(guest, s.into()).await,
4310                Syscall::Clone3(s) => self.handle_clone_family(guest, s.into()).await,
4311                Syscall::Fork(s) => self.handle_clone_family(guest, s.into()).await,
4312
4313                // Forward vfork as vfork (rather than rewriting to fork) so the
4314                // kernel enforces the CLONE_VFORK parent-blocking contract while the
4315                // child registers itself and runs to exec/exit.
4316                Syscall::Vfork(s) => self.handle_clone_family(guest, s.into()).await,
4317                Syscall::Wait4(s) => self.handle_wait4(guest, s).await,
4318                Syscall::Waitid(s) => self.handle_waitid(guest, s).await,
4319
4320                Syscall::Setpgid(s) => self.handle_setpgid(guest, s).await,
4321                Syscall::Setsid(s) => self.handle_setsid(guest, s).await,
4322                // AUTONOMOUS-BOT-IMPLEMENTED
4323                Syscall::Getpgrp(_) | Syscall::Getpgid(_) | Syscall::Getsid(_) => {
4324                    self.handle_group_or_session_getter(guest, call).await
4325                }
4326                // Without virtual time the guest reads the host clock. Each of these
4327                // must have a record/replay handler: a recording captures the value
4328                // the guest observed, and replay returns it without reading the host.
4329                Syscall::Gettimeofday(s) => {
4330                    if virtualize_time {
4331                        self.handle_gettimeofday(guest, s).await
4332                    } else {
4333                        self.passthrough(guest, call).await
4334                    }
4335                }
4336                Syscall::Time(s) => {
4337                    if virtualize_time {
4338                        self.handle_time(guest, s).await
4339                    } else {
4340                        self.passthrough(guest, call).await
4341                    }
4342                }
4343                Syscall::ClockGettime(s) => {
4344                    if virtualize_time {
4345                        self.handle_clock_gettime(guest, s).await
4346                    } else {
4347                        self.passthrough(guest, call).await
4348                    }
4349                }
4350                Syscall::ClockGetres(s) => {
4351                    if virtualize_time {
4352                        self.handle_clock_getres(guest, s).await
4353                    } else {
4354                        self.passthrough(guest, call).await
4355                    }
4356                }
4357                // AUTONOMOUS-BOT-IMPLEMENTED
4358                // TODO-HUMAN-REVIEW(#663)
4359                Syscall::ClockSettime(_) => Err(Error::Errno(Errno::EPERM)),
4360                // AUTONOMOUS-BOT-IMPLEMENTED
4361                // TODO-HUMAN-REVIEW(PR-892)
4362                Syscall::Getitimer(s) => self.handle_getitimer(guest, s).await,
4363                // AUTONOMOUS-BOT-IMPLEMENTED
4364                // TODO-HUMAN-REVIEW(#663)
4365                Syscall::Setitimer(s) => self.handle_setitimer(guest, s).await,
4366                // AUTONOMOUS-BOT-IMPLEMENTED
4367                // TODO-HUMAN-REVIEW(PR-857): Virtual NTP query and fixed mutation refusal.
4368                Syscall::Adjtimex(s) => {
4369                    if virtualize_time {
4370                        self.handle_adjtimex(guest, s).await
4371                    } else {
4372                        self.handle_unsupported_syscall(
4373                            guest,
4374                            call,
4375                            dettid,
4376                            panic_on_unsupported_syscalls,
4377                        )
4378                        .await
4379                    }
4380                }
4381                // AUTONOMOUS-BOT-IMPLEMENTED
4382                // TODO-HUMAN-REVIEW(PR-857): Clock-id form of virtual NTP query.
4383                Syscall::ClockAdjtime(s) => {
4384                    if virtualize_time {
4385                        self.handle_clock_adjtime(guest, s).await
4386                    } else {
4387                        self.handle_unsupported_syscall(
4388                            guest,
4389                            call,
4390                            dettid,
4391                            panic_on_unsupported_syscalls,
4392                        )
4393                        .await
4394                    }
4395                }
4396                // AUTONOMOUS-BOT-IMPLEMENTED
4397                // TODO-HUMAN-REVIEW(PR-857): Empty virtual kernel ring buffer.
4398                Syscall::Syslog(s) => self.handle_syslog(guest, s).await,
4399                Syscall::ArchPrctl(s) => self.handle_arch_prctl(guest, s).await,
4400                // AUTONOMOUS-BOT-IMPLEMENTED
4401                Syscall::Seccomp(s) => self.handle_seccomp(guest, s).await,
4402                // AUTONOMOUS-BOT-IMPLEMENTED
4403                // TODO-HUMAN-REVIEW(#663)
4404                Syscall::Prctl(s) => self.handle_prctl(guest, s).await,
4405                // AUTONOMOUS-BOT-IMPLEMENTED
4406                // TODO-HUMAN-REVIEW(#663)
4407                Syscall::Getpriority(s) => self.handle_getpriority(guest, s).await,
4408                // AUTONOMOUS-BOT-IMPLEMENTED
4409                // TODO-HUMAN-REVIEW(#663)
4410                Syscall::Setpriority(s) => self.handle_setpriority(guest, s).await,
4411                Syscall::Uname(s) => self.handle_uname(guest, s).await,
4412                Syscall::ExitGroup(s) => self.handle_exit_group(guest, s).await,
4413                Syscall::Exit(s) => self.handle_exit(guest, s).await,
4414
4415                Syscall::Dup(w) => self.handle_dup(guest, w).await.map_err(Into::into),
4416                Syscall::Dup2(w) => self.handle_dup2(guest, w).await,
4417                Syscall::Dup3(w) => self.handle_dup3(guest, w).await,
4418                Syscall::Pipe(w) => self.handle_pipe2(guest, w.into()).await,
4419                Syscall::Pipe2(w) => self.handle_pipe2(guest, w).await,
4420                Syscall::Getrandom(s) => self.handle_getrandom(guest, s).await,
4421                Syscall::Utime(s) => self.handle_utime(guest, s).await.map_err(Into::into),
4422                Syscall::Utimes(s) => self.handle_utimes(guest, s).await.map_err(Into::into),
4423                // NB: lutimes is a libc function not a syscall
4424                Syscall::Utimensat(s) => self.handle_utimensat(guest, s).await.map_err(Into::into),
4425                // NB: futimes/futimens are libc functions not a syscall,
4426                // futimesat is obsolete, return -ENOSYS for simplicity.
4427                Syscall::Futimesat(_s) => Err(Error::Errno(Errno::ENOSYS)),
4428                // io_uring completion and memory-sharing semantics are not deterministic.
4429                Syscall::IoUringSetup(_)
4430                | Syscall::IoUringEnter(_)
4431                | Syscall::IoUringRegister(_) => Err(Error::Errno(Errno::ENOSYS)),
4432                Syscall::Socket(s) => self.handle_socket(guest, s).await,
4433                Syscall::Socketpair(s) => self.handle_socketpair(guest, s).await,
4434                Syscall::Connect(s) => self.handle_connect(guest, s).await,
4435                Syscall::Bind(s) => self.handle_bind(guest, s).await,
4436                // AUTONOMOUS-BOT-IMPLEMENTED
4437                // TODO-HUMAN-REVIEW(#663)
4438                Syscall::Setsockopt(s) => self.handle_setsockopt(guest, s).await,
4439                // AUTONOMOUS-BOT-IMPLEMENTED
4440                // TODO-HUMAN-REVIEW(#663)
4441                Syscall::Listen(s) => self.handle_listen(guest, s).await,
4442                // AUTONOMOUS-BOT-IMPLEMENTED
4443                // TODO-HUMAN-REVIEW(#663)
4444                Syscall::Getsockname(s) => self.handle_getsockname(guest, s).await,
4445                // AUTONOMOUS-BOT-IMPLEMENTED
4446                // TODO-HUMAN-REVIEW(#663)
4447                Syscall::Getpeername(s) => self.handle_getpeername(guest, s).await,
4448                // AUTONOMOUS-BOT-IMPLEMENTED
4449                // TODO-HUMAN-REVIEW(#663)
4450                Syscall::Getsockopt(s) => self.handle_getsockopt(guest, s).await,
4451                // AUTONOMOUS-BOT-IMPLEMENTED
4452                // TODO-HUMAN-REVIEW(#818): shutdown is the lone remaining
4453                // socket-family syscall; half-closes a tracked socket and
4454                // forwards via record_or_replay (KVM ratchet round 12).
4455                Syscall::Shutdown(s) => self.handle_shutdown(guest, s).await,
4456                Syscall::Eventfd(s) => self.handle_eventfd2(guest, s.into()).await,
4457                Syscall::Eventfd2(s) => self.handle_eventfd2(guest, s).await,
4458                Syscall::Signalfd(s) => self.handle_signalfd4(guest, s.into()).await,
4459                Syscall::Signalfd4(s) => self.handle_signalfd4(guest, s).await,
4460                Syscall::TimerfdCreate(s) => self.handle_timerfd_create(guest, s).await,
4461                Syscall::TimerfdSettime(s) => self.handle_timerfd_settime(guest, s).await,
4462                Syscall::TimerfdGettime(s) => self.handle_timerfd_gettime(guest, s).await,
4463                Syscall::InotifyInit(s) => {
4464                    self.handle_inotify_init1(guest, InotifyInit1::from(s))
4465                        .await
4466                }
4467                Syscall::InotifyInit1(s) => self.handle_inotify_init1(guest, s).await,
4468                Syscall::InotifyAddWatch(s) => self.handle_inotify_add_watch(guest, s).await,
4469                Syscall::InotifyRmWatch(s) => self.handle_inotify_rm_watch(guest, s).await,
4470                Syscall::MemfdCreate(s) => self.handle_memfd_create(guest, s).await,
4471                // AUTONOMOUS-BOT-IMPLEMENTED
4472                // TODO-HUMAN-REVIEW(PR-862): Record/replay and register pidfds.
4473                Syscall::PidfdOpen(s) => self.handle_pidfd_open(guest, s).await,
4474                // AUTONOMOUS-BOT-IMPLEMENTED
4475                // TODO-HUMAN-REVIEW(PR-899): Host object handles and mount IDs
4476                // are outside Detcore's filesystem identity model.
4477                Syscall::NameToHandleAt(_) => Err(Error::Errno(Errno::EOPNOTSUPP)),
4478                Syscall::Userfaultfd(s) => self.handle_userfaultfd(guest, s).await,
4479                Syscall::Accept(s) => self.handle_accept4(guest, s.into()).await,
4480                Syscall::Accept4(s) => self.handle_accept4(guest, s).await,
4481
4482                Syscall::Nanosleep(s) => self.handle_nanosleep_family(guest, s.into()).await,
4483                Syscall::ClockNanosleep(s) => self.handle_nanosleep_family(guest, s.into()).await,
4484                Syscall::SchedYield(s) => self.handle_sched_yield(guest, s).await,
4485
4486                // NB: getdents is not recommended, (g)libc should call getdents64 only
4487                // see: sysdeps/unix/sysv/linux/getdents.c.
4488                Syscall::Getdents(s) => self.handle_getdents(guest, s).await,
4489                Syscall::Getdents64(s) => self.handle_getdents64(guest, s).await,
4490
4491                Syscall::Poll(s) => self.handle_poll(guest, s).await,
4492                // AUTONOMOUS-BOT-IMPLEMENTED
4493                // TODO-HUMAN-REVIEW(#686): Review scratch fd sets and scheduler polling.
4494                Syscall::Pselect6(s) => self.handle_pselect6(guest, s).await,
4495                // AUTONOMOUS-BOT-IMPLEMENTED
4496                // TODO-HUMAN-REVIEW(#800): select is the timeval sibling of pselect6.
4497                Syscall::Select(s) => self.handle_select(guest, s).await,
4498                // AUTONOMOUS-BOT-IMPLEMENTED
4499                Syscall::Ppoll(s) => self.handle_ppoll(guest, s).await,
4500                Syscall::EpollCreate(s) => {
4501                    self.handle_epoll_create1(guest, EpollCreate1::from(s))
4502                        .await
4503                }
4504                Syscall::EpollCreate1(s) => self.handle_epoll_create1(guest, s).await,
4505                Syscall::EpollCtl(s) => self.handle_epoll_ctl(guest, s).await,
4506                Syscall::EpollPwait(s) => self.handle_epoll_pwait(guest, s).await,
4507                Syscall::EpollWait(s) => self.handle_epoll_wait(guest, s).await,
4508                Syscall::EpollWaitOld(s) => panic!(
4509                    "Not handling deprecated syscall: {}",
4510                    s.display(&guest.memory())
4511                ),
4512                // AUTONOMOUS-BOT-IMPLEMENTED
4513                // TODO-HUMAN-REVIEW(#549)
4514                // The obsolete x86_64 entry point is absent from modern Linux kernels.
4515                Syscall::EpollCtlOld(_) => Err(Error::Errno(Errno::ENOSYS)),
4516
4517                Syscall::SchedGetaffinity(s) => self.handle_sched_getaffinity(guest, s).await,
4518                Syscall::SchedSetaffinity(s) => self.handle_sched_setaffinity(guest, s).await,
4519
4520                // ===== BATCH 3: NUMA memory-placement and Linux CPU-scheduling
4521                // policy. Hermit exposes a single virtual NUMA node and replaces
4522                // the Linux scheduler with Detcore, so these are inoperative and
4523                // are virtualized to fixed, host-independent results (see the
4524                // determinism argument in syscall_classification.rs). Setters and
4525                // count-returning calls are no-ops; getters emulate a default
4526                // single-node / SCHED_OTHER answer.
4527                // AUTONOMOUS-BOT-IMPLEMENTED
4528                // TODO-HUMAN-REVIEW(#720)
4529                Syscall::Mbind(_) => Ok(0),
4530                Syscall::SetMempolicy(_) => Ok(0),
4531                Syscall::GetMempolicy(s) => self.handle_get_mempolicy(guest, s).await,
4532                Syscall::MigratePages(_) => Ok(0),
4533                Syscall::MovePages(s) => self.handle_move_pages(guest, s).await,
4534                Syscall::SchedSetscheduler(_) => Ok(0),
4535                Syscall::SchedSetparam(_) => Ok(0),
4536                // Report the fixed default policy SCHED_OTHER (0).
4537                Syscall::SchedGetscheduler(_) => Ok(0),
4538                Syscall::SchedGetparam(s) => self.handle_sched_getparam(guest, s).await,
4539                Syscall::SchedRrGetInterval(s) => self.handle_sched_rr_get_interval(guest, s).await,
4540
4541                // ===== BATCH 51: fail-closed utility syscalls, re-enabling chrt,
4542                // ionice, and flock under --strict. Detcore replaces the Linux
4543                // scheduler, exposes a single virtual CPU, and serializes guest
4544                // threads, so a thread's Linux scheduling attributes (sched_getattr)
4545                // and I/O priority (ioprio_set) are inert: those two have no
4546                // deterministic effect and are emulated to fixed, host-independent
4547                // results (see syscall_classification.rs).
4548                //
4549                // flock is NOT in that inert group and is not emulated. This comment
4550                // used to claim it "is never contended inside the serialized
4551                // container"; that was measured false -- two open file descriptions
4552                // in ONE process both held the same LOCK_EX under the old no-op,
4553                // where native Linux excluded the second -- and the no-op was
4554                // removed. Serializing THREADS does not make a whole-file lock
4555                // uncontended, because flock conflicts are between OPEN FILE
4556                // DESCRIPTIONS. flock is now forwarded to the kernel, like fcntl's
4557                // POSIX record locks; handle_flock carries the determinism argument
4558                // and the one case Detcore refuses (a contended BLOCKING request,
4559                // which it cannot park a thread on deterministically).
4560                // AUTONOMOUS-BOT-IMPLEMENTED
4561                // TODO-HUMAN-REVIEW(#791)
4562                Syscall::SchedGetattr(s) => self.handle_sched_getattr(guest, s).await,
4563                // AUTONOMOUS-BOT-IMPLEMENTED
4564                // TODO-HUMAN-REVIEW(PR-841): Review virtual sched_setattr no-op policy.
4565                Syscall::SchedSetattr(s) => self.handle_sched_setattr(guest, s).await,
4566                // AUTONOMOUS-BOT-IMPLEMENTED
4567                // TODO-HUMAN-REVIEW(#791)
4568                Syscall::IoprioSet(s) => self.handle_ioprio_set(guest, s).await,
4569                // AUTONOMOUS-BOT-IMPLEMENTED
4570                // TODO-HUMAN-REVIEW(PR-881): Review virtual ioprio_get defaults.
4571                Syscall::IoprioGet(s) => self.handle_ioprio_get(guest, s).await,
4572                // AUTONOMOUS-BOT-IMPLEMENTED
4573                // TODO-HUMAN-REVIEW(#2373)
4574                Syscall::Flock(s) => self.handle_flock(guest, s).await,
4575
4576                // TODO-HUMAN-REVIEW(PR-1064): recvfrom/read/readv/recvmmsg reach
4577                // a NETLINK_SOCK_DIAG dump exactly as recvmsg does. Until they
4578                // were routed through the same sanitizer, four of the five
4579                // usable receive syscalls returned raw host socket inode
4580                // numbers, which made the determinization optional from the
4581                // guest's point of view: `socket.recv()` alone was enough to
4582                // skip it. Non-socket-diag descriptors take the same path as
4583                // before; the predicate is checked inside.
4584                Syscall::Recvfrom(s) if self.sock_diag_reply_fd(guest, s.fd()) => {
4585                    self.handle_sock_diag_recvfrom(guest, s).await
4586                }
4587                Syscall::Recvfrom(s) => self.handle_socket_receive(guest, s, s.fd(), true).await,
4588                // AUTONOMOUS-BOT-IMPLEMENTED
4589                // TODO-HUMAN-REVIEW(PR-901)
4590                Syscall::Recvmsg(s) => self.handle_recvmsg(guest, s).await,
4591                Syscall::Sendto(s) => self.handle_sendrecv(guest, s).await,
4592                Syscall::Sendmsg(s) => self.handle_sendmsg(guest, s).await,
4593                Syscall::Sendmmsg(s) => self.handle_sendmmsg(guest, s).await,
4594
4595                // AUTONOMOUS-BOT-IMPLEMENTED
4596                // TODO-HUMAN-REVIEW(#788): recvmmsg is the multi-message form of
4597                // recvmsg and shares its NonblockableSyscall impl. The fd is made
4598                // temporarily nonblocking, the kernel fills the mmsghdr array
4599                // atomically, and the Detcore scheduler owns any blocking, so the
4600                // timeout argument (deliberately ignored, see helpers.rs) does not
4601                // introduce nondeterminism.
4602                // TODO-HUMAN-REVIEW(PR-901): Review batched ancillary timestamp rewriting.
4603                Syscall::Recvmmsg(s) if self.sock_diag_reply_fd(guest, s.fd()) => {
4604                    self.handle_sock_diag_recvmmsg(guest, s).await
4605                }
4606                Syscall::Recvmmsg(s) => self.handle_recvmmsg(guest, s).await,
4607                Syscall::RtSigtimedwait(s) => self.handle_rt_sigtimedwait(guest, s).await,
4608                Syscall::RtSigsuspend(s) => self.handle_rt_sigsuspend(guest, s).await,
4609                // AUTONOMOUS-BOT-IMPLEMENTED
4610                // TODO-HUMAN-REVIEW(#663)
4611                Syscall::RtSigpending(s) => self.handle_rt_sigpending(guest, s).await,
4612                // AUTONOMOUS-BOT-IMPLEMENTED
4613                // TODO-HUMAN-REVIEW(#663)
4614                Syscall::Kill(s) => {
4615                    let result = self.handle_kill(guest, s).await;
4616                    let result = self
4617                        .report_backend_signal_refusal(guest, Sysno::kill, result)
4618                        .await;
4619                    if s.sig() == libc::SIGALRM && result.is_ok() {
4620                        let target = if guest.thread_state().nested_pid_namespace {
4621                            Some(GuestSigalrmTarget::Unclassified)
4622                        } else {
4623                            match s.pid() {
4624                                pid if pid > 0 => {
4625                                    Some(GuestSigalrmTarget::Process(DetPid::from_raw(pid)))
4626                                }
4627                                0 => Some(GuestSigalrmTarget::Group(None)),
4628                                -1 => Some(GuestSigalrmTarget::All),
4629                                libc::pid_t::MIN => None,
4630                                pid => {
4631                                    Some(GuestSigalrmTarget::Group(Some(DetPid::from_raw(-pid))))
4632                                }
4633                            }
4634                        };
4635                        if let Some(target) = target {
4636                            self.note_guest_sigalrm(guest, target).await;
4637                        }
4638                    }
4639                    result
4640                }
4641                // AUTONOMOUS-BOT-IMPLEMENTED
4642                // TODO-HUMAN-REVIEW(#663)
4643                Syscall::Tgkill(s) => {
4644                    let result = self.handle_tgkill(guest, s).await;
4645                    self.report_backend_signal_refusal(guest, Sysno::tgkill, result)
4646                        .await
4647                }
4648                // AUTONOMOUS-BOT-IMPLEMENTED
4649                // TODO-HUMAN-REVIEW(#812)
4650                Syscall::Tkill(s) => {
4651                    let result = self.handle_tkill(guest, s).await;
4652                    self.report_backend_signal_refusal(guest, Sysno::tkill, result)
4653                        .await
4654                }
4655                // AUTONOMOUS-BOT-IMPLEMENTED
4656                // TODO-HUMAN-REVIEW(#812)
4657                Syscall::RtSigqueueinfo(s) => {
4658                    let result = self.handle_rt_sigqueueinfo(guest, s).await;
4659                    let result = self
4660                        .report_backend_signal_refusal(guest, Sysno::rt_sigqueueinfo, result)
4661                        .await;
4662                    if s.sig() == libc::SIGALRM && result.is_ok() {
4663                        let target = if guest.thread_state().nested_pid_namespace {
4664                            GuestSigalrmTarget::Unclassified
4665                        } else {
4666                            GuestSigalrmTarget::Process(DetPid::from_raw(s.tgid()))
4667                        };
4668                        self.note_guest_sigalrm(guest, target).await;
4669                    }
4670                    result
4671                }
4672                // AUTONOMOUS-BOT-IMPLEMENTED
4673                // TODO-HUMAN-REVIEW(#812)
4674                Syscall::RtTgsigqueueinfo(s) => {
4675                    let result = self.handle_rt_tgsigqueueinfo(guest, s).await;
4676                    self.report_backend_signal_refusal(guest, Sysno::rt_tgsigqueueinfo, result)
4677                        .await
4678                }
4679
4680                Syscall::Execve(s) => self.handle_execveat(guest, s.into()).await,
4681                Syscall::Execveat(s) => self.handle_execveat(guest, s).await,
4682
4683                Syscall::Getcpu(s) => self.handle_getcpu(guest, s).await,
4684
4685                // AUTONOMOUS-BOT-IMPLEMENTED
4686                // TODO-HUMAN-REVIEW(#1549): Credential-query
4687                // family emulated to the fixed virtual-root identity (0). See
4688                // syscall_classification.rs for the determinism rationale.
4689                // getuid/geteuid/getgid/getegid return the constant directly;
4690                // getresuid/getresgid write the constant to each provided result
4691                // pointer. Never forwarded to the host, so the answer no longer
4692                // depends on whether the backend runs the guest in a
4693                // CLONE_NEWUSER namespace.
4694                Syscall::Getuid(_)
4695                | Syscall::Geteuid(_)
4696                | Syscall::Getgid(_)
4697                | Syscall::Getegid(_) => Ok(0),
4698                Syscall::Getresuid(s) => self.handle_getresuid(guest, s).await,
4699                Syscall::Getresgid(s) => self.handle_getresgid(guest, s).await,
4700                Syscall::RtSigprocmask(s) => self.handle_rt_sigprocmask(guest, s).await,
4701                Syscall::RtSigaction(s) => {
4702                    let result = self.handle_rt_sigaction(guest, s).await;
4703                    // Rule 5, decided from the installed disposition: an
4704                    // old-action fault after the install still installed it
4705                    // (https://github.com/rrnewton/hermit/issues/4139).
4706                    if s.signum() == libc::SIGALRM
4707                        && s.action().is_some()
4708                        && guest.config().sequentialize_threads
4709                    {
4710                        crate::tool_global::note_sigalrm_event(
4711                            guest,
4712                            crate::tool_global::GlobalRequest::NoteSigalrmDisposition,
4713                        )
4714                        .await;
4715                    }
4716                    result
4717                }
4718                Syscall::Alarm(s) => self.handle_alarm(guest, s).await,
4719                Syscall::Pause(s) => self.handle_pause(guest, s).await,
4720
4721                Syscall::Getrusage(s) => self.handle_getrusage(guest, s).await,
4722                Syscall::Sysinfo(s) => self.handle_sysinfo(guest, s).await,
4723                // AUTONOMOUS-BOT-IMPLEMENTED
4724                Syscall::Times(s) => self.handle_times(guest, s).await,
4725                Syscall::Prlimit64(s) => self.handle_prlimit64(guest, s).await,
4726                // AUTONOMOUS-BOT-IMPLEMENTED
4727                // TODO-HUMAN-REVIEW(#663)
4728                Syscall::Getrlimit(s) => self.handle_getrlimit(guest, s).await,
4729                // AUTONOMOUS-BOT-IMPLEMENTED
4730                // TODO-HUMAN-REVIEW(#663)
4731                Syscall::Setrlimit(s) => self.handle_setrlimit(guest, s).await,
4732
4733                // POSIX per-process timers use the virtual clock and scheduler
4734                // for deterministic arming and supported signal delivery.
4735                Syscall::TimerCreate(s) => self.handle_timer_create(guest, s).await,
4736                Syscall::TimerSettime(s) => self.handle_timer_settime(guest, s).await,
4737                Syscall::TimerGettime(s) => self.handle_timer_gettime(guest, s).await,
4738                Syscall::TimerGetoverrun(s) => self.handle_timer_getoverrun(guest, s).await,
4739                Syscall::TimerDelete(s) => self.handle_timer_delete(guest, s).await,
4740
4741                // Serialized threads share a total memory order, so process-wide
4742                // memory barriers are trivially satisfied and can be no-ops.
4743                Syscall::Membarrier(s) => self.handle_membarrier(guest, s).await,
4744
4745                // Filesystem statistics: passthrough is record/replay-aware so the
4746                // (otherwise host-dependent) result is captured and reproduced.
4747                // statfs/fstatfs run the real syscall, then canonicalize the
4748                // host-varying fields (free blocks/inodes, fsid) so the result is
4749                // deterministic under --verify (a bare passthrough diverged, e.g.
4750                // for tar).
4751                Syscall::Statfs(s) => self.handle_statfs(guest, s).await,
4752                Syscall::Fstatfs(s) => self.handle_fstatfs(guest, s).await,
4753
4754                unexpected => {
4755                    self.handle_unsupported_syscall(
4756                        guest,
4757                        unexpected,
4758                        dettid,
4759                        panic_on_unsupported_syscalls,
4760                    )
4761                    .await
4762                }
4763            },
4764            // Where the run declares a launcher, the kernel's program break
4765            // is the launcher's: Detcore answers brk from its model of the
4766            // guest's (`Detcore::handle_brk`).
4767            SyscallClassification::PassThrough
4768                if call.number() == Sysno::brk && self.declares_launcher() =>
4769            {
4770                self.handle_brk(guest, call).await
4771            }
4772            // AUTONOMOUS-BOT-IMPLEMENTED
4773            // TODO-HUMAN-REVIEW(PR-2985): Review scheduler tracking of set_tid_address.
4774            // Linux and the backend own the pass-through call. Detcore also
4775            // mirrors its successful registration into the scheduler because
4776            // the scheduler supplies the logical CHILD_CLEARTID wake.
4777            SyscallClassification::PassThrough if call.number() == Sysno::set_tid_address => {
4778                match call {
4779                    Syscall::SetTidAddress(s) => self.handle_set_tid_address(guest, s).await,
4780                    _ => unreachable!("set_tid_address unexpectedly lost its typed variant"),
4781                }
4782            }
4783            // AUTONOMOUS-BOT-IMPLEMENTED
4784            // TODO-HUMAN-REVIEW(PR-2223): Review observing
4785            // the robust-list registration without changing its pass-through
4786            // classification. This is still a pass-through — Linux owns the
4787            // registration and supplies its result — but Detcore remembers the
4788            // head address so thread exit can replay `exit_robust_list()`
4789            // against its own futex waiter pool.
4790            SyscallClassification::PassThrough if call.number() == Sysno::set_robust_list => {
4791                match call {
4792                    Syscall::SetRobustList(s) => self.handle_set_robust_list(guest, s).await,
4793                    _ => self.passthrough(guest, call).await,
4794                }
4795            }
4796            // faccessat2 and fchmodat2 are untyped in the pinned Reverie revision; the
4797            // reviewed classification table routes them, and every other reviewed
4798            // PassThrough syscall, through the blanket arm below.
4799            // AUTONOMOUS-BOT-IMPLEMENTED
4800            // TODO-HUMAN-REVIEW(PR-644): Keep dispatch aligned with the reviewed classification.
4801            // A pass-through whose restored mask may deliver a pending real-time
4802            // timer expiration (https://github.com/rrnewton/hermit/issues/4089).
4803            SyscallClassification::PassThrough if call.number() == Sysno::rt_sigreturn => {
4804                crate::syscalls::signal_shadow::record_rt_sigreturn(guest).await;
4805                self.observe_sigreturn_mask(guest).await;
4806                // A signal the restored mask unblocks is delivered on this
4807                // same return to user space (`returned_from_sigreturn`).
4808                guest.thread_state_mut().returned_from_sigreturn = true;
4809                self.passthrough(guest, call).await
4810            }
4811            SyscallClassification::PassThrough => self.passthrough(guest, call).await,
4812            // The kernel's restart of a wait Detcore emulates resumes it; any other
4813            // `restart_syscall` keeps the unsupported-syscall policy below.
4814            // AUTONOMOUS-BOT-IMPLEMENTED
4815            SyscallClassification::Unsupported if call.number() == Sysno::restart_syscall => {
4816                self.handle_restart_syscall(
4817                    guest,
4818                    call,
4819                    restart_block,
4820                    dettid,
4821                    panic_on_unsupported_syscalls,
4822                )
4823                .await
4824            }
4825            SyscallClassification::Unsupported => {
4826                self.handle_unsupported_syscall(guest, call, dettid, panic_on_unsupported_syscalls)
4827                    .await
4828            }
4829        };
4830
4831        // A copy may already have changed guest memory before reporting a
4832        // terminal backend error. Do not perform even the syscall-result
4833        // display's memory reads, or later observers/posthooks/timer effects.
4834        // Random-device reads have completed their release RPC before returning;
4835        // getrandom acquired no file resource. Physical cleanup belongs to the
4836        // backend failure owner, not to this observer fence.
4837        if res.as_ref().is_err_and(crate::random::is_copy_failure) {
4838            return res;
4839        }
4840
4841        if res.is_ok() && !removed_inodes.is_empty() {
4842            self.retire_removed_inodes(guest, removed_inodes).await;
4843        }
4844        if res.is_ok() {
4845            for fifo in removed_guest_fifos {
4846                crate::fifo_peer::forget_guest_made(fifo);
4847            }
4848            self.note_guest_made_fifo(guest, &call).await;
4849        }
4850        // A read or write that moved bytes through a pipe or FIFO readies the
4851        // threads polling its other direction (`--pipe-wake-latency`).
4852        if let Ok(moved) = res
4853            && moved > 0
4854            && let Some((fd, wants)) = crate::pipe_wake::progress_of(&call)
4855        {
4856            self.note_fd_readied(guest, fd, wants).await;
4857        }
4858        Self::unmap_orphaned_staging_pages(guest).await;
4859
4860        // With asynchronous exit completion, a descriptor that would make this
4861        // guest serve another guest's exit ends the run before anything
4862        // observes the result (crate::exit_dependencies).
4863        if let Ok(ret) = res {
4864            self.refuse_exit_dependencies(guest, &call, ret).await;
4865        }
4866
4867        // The guest resumes with this result in its return register (A5 step
4868        // 3.2). An error that is not an errno names no register value.
4869        let finished = match &res {
4870            Ok(value) => Some(*value),
4871            Err(Error::Errno(errno)) => Some(-(errno.into_raw() as i64)),
4872            Err(_) => None,
4873        };
4874        if let Some(result) = finished {
4875            guest.thread_state_mut().delivery_interruption = Some(reverie::Interruption::Return {
4876                syscall: call.number() as i64,
4877                result,
4878            });
4879        }
4880        detlog!(
4881            event = crate::detlog::DetLogEvent::SyscallResult {
4882                finished_syscall_number: new_count,
4883            };
4884            "[syscall][detcore, dtid {}] finish syscall #{}: {} = {:?}",
4885            dettid,
4886            new_count,
4887            display_syscall_finished(&call, &guest.memory(), &res),
4888            res
4889        );
4890
4891        // Same guest-logical-control point that already anchors the stack/heap hashes: the
4892        // syscall is complete and its result written back, so the guest logically has control.
4893        // Reading registers is itself backend work, so keep the disabled path inert.  In
4894        // particular, a run that does not request register evidence must not be perturbed by
4895        // collecting data that will immediately be discarded.
4896        if self.cfg.detlog_regs {
4897            let control_point_regs = guest.regs().await;
4898            let regs_seq = guest.thread_state().stats.syscall_count;
4899            self.detlog_registers(guest, &control_point_regs, regs_seq);
4900        }
4901
4902        // brk is PassThrough, so nothing else records where the guest's heap is.
4903        // Both brk(NULL) and brk(addr) return the break in effect afterwards.
4904        if let Syscall::Brk(_) = &call
4905            && let Ok(brk) = res
4906            && brk > 0
4907        {
4908            guest
4909                .thread_state()
4910                .memory_metadata
4911                .lock()
4912                .expect("memory metadata mutex poisoned")
4913                .observe_brk(brk as u64);
4914        }
4915
4916        if let Err(error) = self.detlog_memory_maps(guest) {
4917            let res = Err(error);
4918            self.publish_posthook_checkpoint(guest, new_count, &res)
4919                .await;
4920            return self.complete_syscall(guest, res).await;
4921        }
4922        // Same control point again, for the bytes this syscall moved through a guest buffer.
4923        // Unlike the two mapping hashes above, the extent comes from the syscall's OWN
4924        // arguments, so it does not matter whether the buffer lives on the stack, in the brk
4925        // heap, in BSS or in an anonymous mmap -- the last two of which neither mapping hash
4926        // can see. Only successful calls moved anything.
4927        if let Ok(ret) = &res
4928            && self.cfg.detlog_io_buffers
4929            && let Err(error) = io_buffers::detlog_io_buffers(
4930                guest,
4931                &call,
4932                *ret,
4933                dettid,
4934                rng_readv_output.as_deref(),
4935            )
4936        {
4937            let res = Err(error);
4938            self.publish_posthook_checkpoint(guest, new_count, &res)
4939                .await;
4940            return self.complete_syscall(guest, res).await;
4941        }
4942
4943        if sequentialize_threads && self.cfg.should_trace_schedevent() {
4944            trace_schedevent(
4945                guest,
4946                with_guest_time(
4947                    guest,
4948                    SchedEvent::syscall(dettid, call.number(), SyscallPhase::Posthook),
4949                ),
4950                true,
4951            )
4952            .await;
4953        }
4954
4955        // Posthook happens-before anchors this call reached fire now that its
4956        // result is decided and before the guest resumes
4957        // (https://github.com/rrnewton/hermit/issues/3929).
4958        self.publish_posthook_checkpoint(guest, new_count, &res)
4959            .await;
4960
4961        // The syscall is finished; a turn the post-hook takes (a timeslice
4962        // end) is the thread's own and advances global time as usual.
4963        guest.thread_state_mut().in_uncharged_bootstrap_syscall = false;
4964        self.post_handler_hook(guest, CheckIn::Event).await;
4965
4966        // Defense-in-depth: unless the backend already owns this guarantee,
4967        // force the syscall-clobbered registers (%rcx/%r11 on x86-64) to
4968        // deterministic values before returning to the guest.
4969        if !self.cfg.backend.virtualizes_syscall_clobbers {
4970            self.canonicalize_syscall_clobbers(guest).await;
4971        }
4972
4973        // Signal phase 1, step I4: a due SIGALRM entry is delivered here.
4974        self.complete_syscall(guest, res).await
4975    }
4976
4977    async fn on_exit_thread<G: GlobalRPC<Self::GlobalState>>(
4978        &self,
4979        tid: Tid,
4980        global_state: &G,
4981        mut thread_state: Self::ThreadState,
4982        exit_status: ExitStatus,
4983    ) -> Result<(), Error> {
4984        let dettid = thread_state.dettid;
4985        thread_state.delivery_counters.log(dettid);
4986        // Cancellation can consume the backend's transferred state before the
4987        // successful-exec callback has rebound its logical identity.
4988        let current = DetTid::from_raw(tid.as_raw());
4989        let transferred_exec = current != dettid;
4990        debug!(
4991            "[detcore, dtid {}] thread exit hook, deregistering from scheduler.",
4992            dettid
4993        );
4994        // Close the final in-progress timeslice so this thread contributes its
4995        // last (partial) slice to the run report, even if it never exhausted a
4996        // full slice.
4997        let now = thread_state.thread_logical_time.as_nanos();
4998        thread_state.stats.close_final_timeslice(now);
4999        // Ptrace keeps its exit event stopped while this hook runs. KVM runs
5000        // this owner hook after worker joins and child waitability publication.
5001        // Publish final CPU in this synchronous prefix: serial KVM waitid waits
5002        // for that owned notification before consuming, not for the hook tail.
5003        // DETERMINISTIC RECOVERY (TODO-HUMAN-REVIEW(PR-1147)). `ThreadState::detpid`
5004        // is `Option` and starts as `None` ("Initialized later" at the clone site),
5005        // so a thread that reaches the exit hook before its per-thread identity is
5006        // populated used to `.expect()` here. That panic fires inside a Reverie
5007        // teardown callback, while the backend still owns the exit event, which is
5008        // the worst place to abort: it can wedge the supervisor rather than fail one
5009        // thread. Fall back to the PROCESS-level `self.detpid`, which is
5010        // non-optional and preserves the identity source selected for this
5011        // backend: virtual for the current DBT ABI, physical for ABI v1. Warn so
5012        // the exceptional window is observable instead of silently papered over.
5013        //
5014        // CORRECTED BY #2348, and stated rather than quietly dropped: the normal
5015        // current-ABI DBT path pre-populates `thread_state.detpid` with the
5016        // client-published virtual process identity, so thread start and exit
5017        // agree on that value. This recovery is only for a thread that exits
5018        // before that initialization. In that exceptional window thread start
5019        // would fall back to `guest.pid()` (the physical host pid for `DbtGuest`),
5020        // while this exit path uses `self.detpid`. ABI v1 also intentionally keeps
5021        // physical callback identities. The warning makes either compatibility
5022        // or recovery path observable; this comment does not claim those fallback
5023        // identities are virtual or independently deterministic.
5024        let (detpid, used_process_detpid) =
5025            select_thread_exit_detpid(thread_state.detpid, self.detpid);
5026        if used_process_detpid {
5027            tracing::warn!(
5028                "[detcore, dtid {}] thread exited before its per-thread detpid was \
5029                 initialized; falling back to the process detpid {}",
5030                dettid,
5031                self.detpid
5032            );
5033        }
5034        // The transferred survivor is the final leader even if cancellation
5035        // precedes local rebinding. Its snapshot includes the worker's tail;
5036        // the earlier displaced-leader snapshot is only a prefix.
5037        if current == detpid {
5038            if !thread_state.record_exited_child_process_cpu_time(detpid) {
5039                return Err(Error::Tool(anyhow::anyhow!(
5040                    "child CPU publication ownership changed before final exit"
5041                )));
5042            }
5043        } else {
5044            thread_state.account_process_cpu_time();
5045        }
5046        let mm_id = thread_state.mm_id;
5047        let exit_signal = match &exit_status {
5048            ExitStatus::Signaled(signal, _) => Some(*signal as i32),
5049            ExitStatus::SignaledRaw(signal, _) => Some(*signal),
5050            ExitStatus::Exited(_) => None,
5051        };
5052        // Publish each owner's final clock under its own RPC identity before
5053        // counting that owner in the complete physical-exit barrier. Otherwise
5054        // the group's maximum could be charged to whichever callback finishes
5055        // last, followed by a backwards update from its real deregistration.
5056        // Exec preparation already cleared the old image's robust list. An
5057        // unbound transfer must authenticate its consuming cleanup before any
5058        // ordinary RPC can publish the survivor's clock under the leader TID.
5059        let exit_time_accounted = !transferred_exec
5060            && (!thread_state.has_matching_robust_list_exit(exit_signal)
5061                || acknowledge_robust_list_exit_time(
5062                    thread_state.thread_logical_time.clone(),
5063                    global_state,
5064                    mm_id,
5065                )
5066                .await);
5067        if !exit_time_accounted {
5068            // Preserve benign cleanup for a retired incarnation without
5069            // acknowledging an unaccounted owner or releasing its staged wakes.
5070            thread_state.drop_robust_list_head_at_exit();
5071        }
5072        if exit_time_accounted
5073            && let Some((_group_time, ready)) = thread_state.take_robust_list_wakes_after_exit(
5074                exit_signal,
5075                thread_state.thread_logical_time.clone(),
5076            )
5077        {
5078            let identities: Vec<_> = ready
5079                .iter()
5080                .map(|(owner, wake)| (*owner, wake.futex))
5081                .collect();
5082            let counts = robust_list_wakes_after_exit(
5083                thread_state.thread_logical_time.clone(),
5084                global_state,
5085                mm_id,
5086                ready,
5087            )
5088            .await;
5089            for ((owner, futex), count) in identities.into_iter().zip(counts) {
5090                info!(
5091                    "[detcore, dtid {}] robust-list owner death woke {} waiter(s) on futex {:?} after physical exit",
5092                    owner, count, futex,
5093                );
5094            }
5095        }
5096        // Warnings this address space could not send, this hook's own among
5097        // them, go out while the hook's connection still serves it
5098        // (`crate::guest_log`).
5099        guest_log::flush_unsent_through(global_state).await;
5100        let pending_chaos_epochs = thread_state.take_pending_chaos_epochs();
5101        let deregistration = ThreadDeregistration {
5102            dettid,
5103            detpid,
5104            mm: mm_id,
5105            thread_start_entered: thread_state.thread_start_entered,
5106            timeslice_stats: thread_state.stats.timeslice_stats,
5107            syscall_count: thread_state.stats.syscall_count,
5108            chaos_epochs: pending_chaos_epochs,
5109        };
5110        if transferred_exec {
5111            tool_global::retire_exec(
5112                thread_state.thread_logical_time.clone(),
5113                global_state,
5114                deregistration,
5115                exit_status.signal().is_some(),
5116            )
5117            .await?;
5118        } else {
5119            deregister_thread(
5120                thread_state.thread_logical_time.clone(),
5121                &self.cfg,
5122                global_state,
5123                deregistration,
5124            )
5125            .await;
5126        }
5127
5128        self.record_or_replay
5129            .on_exit_thread(
5130                tid,
5131                global_state,
5132                thread_state.record_or_replay,
5133                exit_status,
5134            )
5135            .await?;
5136
5137        Ok(())
5138    }
5139}
5140
5141#[cfg(test)]
5142mod subscription_tests {
5143    use super::*;
5144
5145    fn strict_config(passthru_opt: bool) -> Config {
5146        Config {
5147            sequentialize_threads: true,
5148            deterministic_io: true,
5149            passthru_opt,
5150            ..Default::default()
5151        }
5152    }
5153
5154    /// The last row of the pinned table is the one a `Sysno::iter()` sweep
5155    /// drops. `lsm_list_modules` is Determinized AND deterministically refused,
5156    /// so before this was fixed it executed natively against the host under
5157    /// `--passthru-opt` — which is the default for `hermit record` and
5158    /// `hermit replay` — instead of receiving its fixed refusal.
5159    #[test]
5160    fn passthru_opt_covers_the_final_row_of_the_pinned_table() {
5161        let last = Sysno::last();
5162        // Guard the premise: if the table endpoint moves, this test must be
5163        // re-derived rather than silently passing on a different syscall.
5164        assert_eq!(last, Sysno::lsm_list_modules);
5165        assert!(crate::is_determinized_syscall(last));
5166        assert!(crate::is_deterministically_refused_syscall(last));
5167        // The bug this pins: the final row is absent from `Sysno::iter()`.
5168        assert!(!Sysno::iter().any(|sysno| sysno == last));
5169
5170        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5171        assert!(
5172            subscriptions.iter_syscalls().any(|sysno| sysno == last),
5173            "{last} must be intercepted under passthru_opt; it is deterministically refused"
5174        );
5175    }
5176
5177    #[test]
5178    fn passthru_opt_intercepts_every_unsupported_syscall() {
5179        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5180        let unsupported: Vec<Sysno> = crate::all_pinned_syscalls()
5181            .filter(|sysno| crate::is_unsupported_syscall(*sysno))
5182            .collect();
5183
5184        assert_eq!(unsupported, [Sysno::restart_syscall]);
5185        for syscall in unsupported {
5186            assert!(
5187                subscriptions
5188                    .iter_syscalls()
5189                    .any(|subscribed| subscribed == syscall),
5190                "passthru_opt allowed unsupported {syscall} to bypass Detcore"
5191            );
5192        }
5193    }
5194
5195    /// `passthru_opt` is not a niche flag: `record_or_replay_config` turns it on
5196    /// for every `hermit record` / `hermit replay`, so this covers the record
5197    /// and replay subscription too.
5198    #[test]
5199    fn passthru_opt_subscribes_every_determinized_syscall() {
5200        let determinized: Vec<Sysno> = crate::all_pinned_syscalls()
5201            .filter(|sysno| crate::is_determinized_syscall(*sysno))
5202            .collect();
5203        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5204        let delivered: Vec<Sysno> = subscriptions.iter_syscalls().collect();
5205        let missing = determinized
5206            .iter()
5207            .filter(|sysno| !delivered.contains(sysno))
5208            .copied()
5209            .collect::<Vec<_>>();
5210
5211        assert!(
5212            missing.is_empty(),
5213            "passthru_opt let Determinized syscalls bypass Detcore: {}",
5214            missing
5215                .iter()
5216                .map(|sysno| sysno.to_string())
5217                .collect::<Vec<_>>()
5218                .join(" ")
5219        );
5220        assert!(
5221            delivered.contains(&Sysno::syslog),
5222            "syslog must reach its deterministic Detcore handler"
5223        );
5224        for sysno in [
5225            Sysno::access,
5226            Sysno::faccessat,
5227            Sysno::faccessat2,
5228            Sysno::getxattr,
5229            Sysno::lgetxattr,
5230            Sysno::setxattr,
5231            Sysno::lsetxattr,
5232            Sysno::removexattr,
5233            Sysno::lremovexattr,
5234            Sysno::listxattr,
5235            Sysno::llistxattr,
5236        ] {
5237            assert!(
5238                delivered.contains(&sysno),
5239                "{sysno} must reach Detcore, which answers it for the procfs files it renders"
5240            );
5241        }
5242    }
5243
5244    #[test]
5245    fn passthru_opt_intercepts_thread_exit_registrations() {
5246        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5247        for syscall in [Sysno::set_tid_address, Sysno::set_robust_list] {
5248            assert!(
5249                subscriptions
5250                    .iter_syscalls()
5251                    .any(|subscribed| subscribed == syscall),
5252                "passthru_opt allowed {syscall} to bypass Detcore's thread-exit state"
5253            );
5254        }
5255    }
5256
5257    #[test]
5258    fn passthru_opt_leaves_unlisted_passthrough_syscalls_unsubscribed() {
5259        assert_eq!(
5260            syscall_classification::classify_syscall(Sysno::chdir),
5261            syscall_classification::SyscallClassification::PassThrough
5262        );
5263
5264        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5265        assert!(
5266            !subscriptions
5267                .iter_syscalls()
5268                .any(|sysno| sysno == Sysno::chdir),
5269            "chdir is PassThrough and must remain outside the partial subscription"
5270        );
5271    }
5272
5273    /// Io-buffer hashing can only hash a syscall Detcore is subscribed to.
5274    /// Under `--passthru-opt` the subscription narrows, so the check's coverage
5275    /// narrows with it -- silently, because a syscall that never reaches
5276    /// Detcore produces no record and no record is indistinguishable from a
5277    /// syscall that moved no bytes.
5278    ///
5279    /// Measured 2026-08-21 on `f05bf04e4f`, one probe calling `getcwd`,
5280    /// `recvmsg`, `readv` and `readlink`:
5281    ///
5282    /// ```text
5283    /// hermit --log=info run                --detlog-io-buffers -- ./probe   12 [iobuf] records
5284    /// hermit --log=info run --passthru-opt --detlog-io-buffers -- ./probe   11 [iobuf] records
5285    /// ```
5286    ///
5287    /// The single lost syscall is `getcwd`, and the reason is structural: 9 of
5288    /// the 20 are in the literal allow-list and 10 more arrive via the
5289    /// unconditional Determinized sweep at the end of `subscriptions`, but
5290    /// `getcwd` is classified `PassThrough`, so neither path picks it up.
5291    ///
5292    /// WHY THIS IS A TEST AND NOT A RUNTIME WARNING. The set is stable, so a
5293    /// warning would print the same sentence on every `--passthru-opt` run
5294    /// forever and be tuned out within a week. The exposure is not today's
5295    /// one-syscall gap; it is that 19 of 20 holds only because two
5296    /// INDEPENDENTLY MAINTAINED lists happen to agree -- the classification
5297    /// table in `syscall_classification.rs` and the match arms in
5298    /// `io_buffers.rs`. Reclassifying any one of those ten from `Determinized`
5299    /// to `PassThrough` would drop it out of the sweep and out of io-buffers'
5300    /// reach with nothing failing. This asserts the relationship so that edit
5301    /// cannot land quietly.
5302    ///
5303    /// It is deliberately an EQUALITY, not a subset check, so it fails in both
5304    /// directions: a nineteenth syscall going missing, and `getcwd` becoming
5305    /// covered while this expectation still claims it is not.
5306    #[test]
5307    fn passthru_opt_leaves_io_buffer_hashing_blind_only_for_getcwd() {
5308        let subscribed: Vec<Sysno> = <Detcore as Tool>::subscriptions(&strict_config(true))
5309            .iter_syscalls()
5310            .collect();
5311        let unreachable: Vec<Sysno> = crate::io_buffers::HASHED_SYSCALLS
5312            .iter()
5313            .copied()
5314            .filter(|sysno| !subscribed.contains(sysno))
5315            .collect();
5316
5317        assert_eq!(
5318            unreachable,
5319            vec![Sysno::getcwd],
5320            "--passthru-opt changes which syscalls io-buffer hashing can reach, and the set \
5321             moved. {} of {} reachable. If a syscall was RECLASSIFIED out of Determinized, that \
5322             silently shrank an enabled determinism check -- re-derive rather than editing this \
5323             expectation to match.",
5324            crate::io_buffers::HASHED_SYSCALLS.len() - unreachable.len(),
5325            crate::io_buffers::HASHED_SYSCALLS.len()
5326        );
5327    }
5328
5329    /// The other direction, and the reason the check above is worth having:
5330    /// with the default subscription every buffer-carrying syscall is
5331    /// reachable, so there is nothing to report on an ordinary run.
5332    #[test]
5333    fn the_default_subscription_reaches_every_io_buffer_syscall() {
5334        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(false));
5335        let unreachable: Vec<Sysno> = crate::io_buffers::HASHED_SYSCALLS
5336            .iter()
5337            .copied()
5338            .filter(|sysno| !subscriptions.iter_syscalls().any(|s| s == *sysno))
5339            .collect();
5340
5341        assert!(
5342            unreachable.is_empty(),
5343            "without --passthru-opt every io-buffer syscall must be reachable; missing {unreachable:?}"
5344        );
5345    }
5346
5347    #[test]
5348    fn strict_subscriptions_intercept_every_event_by_default() {
5349        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(false));
5350
5351        assert_eq!(subscriptions, Subscription::all());
5352        assert!(
5353            subscriptions
5354                .iter_syscalls()
5355                .any(|sysno| sysno == Sysno::ppoll)
5356        );
5357
5358        // On a backend without its own CPUID table (ptrace), `--no-virtualize-cpuid`
5359        // must not subscribe to `cpuid` in either mode. The
5360        // subscription is what makes Reverie probe and enable CPUID faulting, and
5361        // a host without faulting then logs an ERROR for each traced exec
5362        // (https://github.com/rrnewton/hermit/issues/3460). Everything else stays
5363        // as intercepted as it is with CPUID virtualization on.
5364        for passthru_opt in [false, true] {
5365            let virtualized = <Detcore as Tool>::subscriptions(&strict_config(passthru_opt));
5366            let config = Config {
5367                virtualize_cpuid: false,
5368                ..strict_config(passthru_opt)
5369            };
5370            let subscriptions = <Detcore as Tool>::subscriptions(&config);
5371
5372            assert!(virtualized.has_cpuid(), "passthru_opt={passthru_opt}");
5373            assert!(!subscriptions.has_cpuid(), "passthru_opt={passthru_opt}");
5374            assert!(subscriptions.has_rdtsc(), "passthru_opt={passthru_opt}");
5375            assert!(
5376                subscriptions
5377                    .iter_syscalls()
5378                    .eq(virtualized.iter_syscalls()),
5379                "passthru_opt={passthru_opt}: the syscall set must not depend on CPUID virtualization"
5380            );
5381        }
5382    }
5383
5384    /// Detcore declares the serialized-execution contract only where it holds:
5385    /// threads sequentialized, and both seccomp-filter routes intercepted and
5386    /// refused.
5387    #[test]
5388    fn serialized_execution_is_declared_only_where_detcore_enforces_it() {
5389        let enforces = <Detcore as Tool>::enforces_serialized_execution;
5390        for passthru_opt in [false, true] {
5391            let config = strict_config(passthru_opt);
5392            let subscriptions = <Detcore as Tool>::subscriptions(&config);
5393            for sysno in [Sysno::seccomp, Sysno::prctl] {
5394                assert!(
5395                    subscriptions.iter_syscalls().any(|s| s == sysno),
5396                    "passthru_opt={passthru_opt}: {sysno} must reach its refusal"
5397                );
5398            }
5399            assert!(enforces(&config), "passthru_opt={passthru_opt}");
5400        }
5401        assert!(!enforces(&Config {
5402            sequentialize_threads: false,
5403            ..strict_config(false)
5404        }));
5405        // The refusals themselves are pinned in `syscalls::misc`'s tests.
5406    }
5407
5408    #[test]
5409    fn passthru_opt_uses_the_partial_subscription_set() {
5410        let subscriptions = <Detcore as Tool>::subscriptions(&strict_config(true));
5411
5412        assert_ne!(subscriptions, Subscription::all());
5413        assert!(
5414            subscriptions
5415                .iter_syscalls()
5416                .any(|sysno| sysno == Sysno::clock_gettime)
5417        );
5418        assert!(
5419            subscriptions
5420                .iter_syscalls()
5421                .any(|sysno| sysno == Sysno::rt_sigsuspend)
5422        );
5423        assert!(
5424            subscriptions
5425                .iter_syscalls()
5426                .any(|sysno| sysno == Sysno::ppoll)
5427        );
5428        assert!(
5429            subscriptions
5430                .iter_syscalls()
5431                .any(|sysno| sysno == Sysno::madvise)
5432        );
5433        assert!(
5434            subscriptions
5435                .iter_syscalls()
5436                .any(|sysno| sysno == Sysno::arch_prctl)
5437        );
5438        assert!(
5439            subscriptions
5440                .iter_syscalls()
5441                .any(|sysno| sysno == Sysno::writev)
5442        );
5443        for sysno in [
5444            Sysno::read,
5445            Sysno::write,
5446            Sysno::pread64,
5447            Sysno::pwrite64,
5448            Sysno::readv,
5449            Sysno::writev,
5450            Sysno::preadv,
5451            Sysno::preadv2,
5452            Sysno::pwritev,
5453            Sysno::pwritev2,
5454            Sysno::prctl,
5455        ] {
5456            assert!(
5457                subscriptions
5458                    .iter_syscalls()
5459                    .any(|subscribed| subscribed == sysno),
5460                "timer-slack mediation requires {sysno:?}"
5461            );
5462        }
5463        assert!(
5464            subscriptions
5465                .iter_syscalls()
5466                .any(|sysno| sysno == Sysno::pwrite64)
5467        );
5468        assert!(
5469            subscriptions
5470                .iter_syscalls()
5471                .any(|sysno| sysno == Sysno::pidfd_open)
5472        );
5473    }
5474}
5475
5476#[cfg(test)]
5477mod rcb_overshoot_tests {
5478    use std::fmt::Write;
5479    use std::sync::Arc;
5480    use std::sync::Mutex;
5481
5482    use tracing::Event;
5483    use tracing::Id;
5484    use tracing::Level;
5485    use tracing::Metadata;
5486    use tracing::Subscriber;
5487    use tracing::field::Field;
5488    use tracing::field::Visit;
5489    use tracing::span::Attributes;
5490    use tracing::span::Record;
5491    use tracing::subscriber::with_default;
5492
5493    use super::rcb_timer_overshot;
5494    use super::report_rcb_overshoot;
5495
5496    struct ErrorSubscriber(Arc<Mutex<Option<String>>>);
5497
5498    struct EventVisitor(String);
5499
5500    impl Visit for EventVisitor {
5501        fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
5502            let _ = write!(self.0, "{}={:?}", field.name(), value);
5503        }
5504    }
5505
5506    impl Subscriber for ErrorSubscriber {
5507        fn enabled(&self, metadata: &Metadata<'_>) -> bool {
5508            *metadata.level() == Level::ERROR
5509        }
5510
5511        fn new_span(&self, _span: &Attributes<'_>) -> Id {
5512            Id::from_u64(1)
5513        }
5514
5515        fn record(&self, _span: &Id, _values: &Record<'_>) {}
5516
5517        fn record_follows_from(&self, _span: &Id, _follows: &Id) {}
5518
5519        fn event(&self, event: &Event<'_>) {
5520            if *event.metadata().level() == Level::ERROR {
5521                let mut visitor = EventVisitor(String::new());
5522                event.record(&mut visitor);
5523                *self.0.lock().unwrap() = Some(visitor.0);
5524            }
5525        }
5526
5527        fn enter(&self, _span: &Id) {}
5528
5529        fn exit(&self, _span: &Id) {}
5530    }
5531
5532    #[test]
5533    fn default_overshoot_policy_emits_error_and_returns() {
5534        let _ = reverie::take_skid_overshoot_count();
5535        let error = Arc::new(Mutex::new(None));
5536        with_default(ErrorSubscriber(error.clone()), || {
5537            report_rcb_overshoot(false, 16_249, 139, 100);
5538        });
5539
5540        let error = error.lock().unwrap().take().expect("missing ERROR event");
5541        assert!(error.contains(reverie::SKID_OVERSHOOT_MARKER), "{error}");
5542        assert!(error.contains("PMU RCB overshoot"), "{error}");
5543        assert!(error.contains("16249"), "{error}");
5544        assert!(error.contains("139"), "{error}");
5545        assert!(error.contains("100"), "{error}");
5546        assert_eq!(
5547            reverie::take_skid_overshoot_count(),
5548            1,
5549            "the log-and-continue path must feed the supervisor's structural count"
5550        );
5551    }
5552
5553    #[test]
5554    fn exact_rcb_timer_hit_is_not_an_overshoot() {
5555        assert!(!rcb_timer_overshot(100, 100));
5556        assert!(!rcb_timer_overshot(99, 100));
5557        assert!(rcb_timer_overshot(101, 100));
5558    }
5559
5560    #[test]
5561    #[should_panic(expected = "PMU RCB overshoot")]
5562    fn opt_in_overshoot_policy_panics() {
5563        report_rcb_overshoot(true, 16_249, 139, 100);
5564    }
5565}
5566
5567#[cfg(test)]
5568mod timeslice_timer_tests {
5569    use super::*;
5570
5571    /// A dropped signal's stop re-requests the timer event for the point the
5572    /// last handler armed, whenever the host-timed stop came: before it, the
5573    /// remaining branches; at or past it, at once
5574    /// (https://github.com/rrnewton/hermit/issues/4304).
5575    #[test]
5576    fn a_kept_timer_aims_at_the_armed_point() {
5577        assert_eq!(kept_timer_rcbs(1_000, 500, 1_000), 500);
5578        assert_eq!(kept_timer_rcbs(1_000, 500, 1_200), 300);
5579        assert_eq!(kept_timer_rcbs(1_000, 500, 1_499), 1);
5580        assert_eq!(kept_timer_rcbs(1_000, 500, 1_500), 1);
5581        assert_eq!(kept_timer_rcbs(1_000, 500, 40_000_000_000), 1);
5582        assert_eq!(kept_timer_rcbs(u64::MAX - 10, 500, u64::MAX - 5), 5);
5583    }
5584
5585    #[test]
5586    fn manual_interrupts_can_shorten_but_not_extend_maximum() {
5587        assert_eq!(choose_rcb_timer(100, 100, Some(150)), (50, false));
5588        assert_eq!(choose_rcb_timer(100, 100, Some(250)), (100, true));
5589        assert_eq!(choose_rcb_timer(100, 100, None), (100, true));
5590    }
5591
5592    #[test]
5593    fn pmu_duration_conversion_applies_clock_multiplier() {
5594        let duration = crate::types::LogicalTime::from_nanos(100);
5595        assert_eq!(duration.into_rcbs_with_multiplier(2.0), 5);
5596        assert_eq!(duration.into_rcbs_with_multiplier(0.5), 20);
5597        assert_eq!(
5598            crate::types::LogicalTime::from_nanos(101).into_rcbs_with_multiplier(2.0),
5599            5
5600        );
5601    }
5602
5603    #[test]
5604    #[should_panic(expected = "max_timeslice must be at least one RCB")]
5605    fn detcore_constructor_validates_programmatic_config() {
5606        let config = Config {
5607            max_timeslice: std::num::NonZeroU64::new(1),
5608            ..Default::default()
5609        };
5610
5611        let _ = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5612    }
5613}
5614
5615#[cfg(test)]
5616mod process_tree_guest_clock_tests {
5617    use super::*;
5618
5619    #[test]
5620    fn forked_process_shares_guest_clock_domain() {
5621        let config = Config::default();
5622        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5623        let mut parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5624        parent.clone_flags = Some(CloneFlags::empty());
5625
5626        let child = <Detcore as Tool>::init_thread_state(
5627            &tool,
5628            Tid::from_raw(2),
5629            Some((Tid::from_raw(1), &parent)),
5630        );
5631
5632        assert!(Arc::ptr_eq(&parent.guest_clock, &child.guest_clock));
5633    }
5634}
5635
5636#[cfg(test)]
5637mod process_files_tests {
5638    use super::*;
5639
5640    fn child(
5641        tool: &Detcore,
5642        parent: &mut ThreadState<()>,
5643        tid: i32,
5644        clone_flags: CloneFlags,
5645    ) -> ThreadState<()> {
5646        parent.clone_flags = Some(clone_flags);
5647        let mut child = <Detcore as Tool>::init_thread_state(
5648            tool,
5649            Tid::from_raw(tid),
5650            Some((Tid::from_raw(parent.dettid.as_raw()), parent)),
5651        );
5652        child.detpid = Some(if clone_flags.contains(CloneFlags::CLONE_THREAD) {
5653            parent.detpid.unwrap()
5654        } else {
5655            DetPid::from_raw(tid)
5656        });
5657        child
5658    }
5659
5660    /// The table a thread group's leader holds, which procfs reads for the
5661    /// process's descriptor links, is known to every thread of the group,
5662    /// through every way a table is made: the root's, a thread's shared or
5663    /// own, a forked process's, a process made with `CLONE_FILES` (whose
5664    /// table was made for another process) and its threads, and the table an
5665    /// exec gives a thread that did not lead its process.
5666    #[test]
5667    fn every_thread_knows_the_table_its_process_holds() {
5668        let config = Config::default();
5669        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5670        let thread = CloneFlags::CLONE_VM
5671            | CloneFlags::CLONE_FS
5672            | CloneFlags::CLONE_FILES
5673            | CloneFlags::CLONE_SIGHAND
5674            | CloneFlags::CLONE_THREAD;
5675        let mut root = ThreadState::new(DetPid::from_raw(3), &config, ());
5676        root.detpid = Some(DetPid::from_raw(3));
5677        assert!(root.holds_process_files());
5678
5679        // A thread that shares the leader's table holds it; one cloned
5680        // without CLONE_FILES holds its own.
5681        let shared = child(&tool, &mut root, 4, thread);
5682        assert_eq!(shared.process_files, root.process_files);
5683        assert!(shared.holds_process_files());
5684        let split = child(&tool, &mut root, 5, thread - CloneFlags::CLONE_FILES);
5685        assert_eq!(split.process_files, root.process_files);
5686        assert!(!split.holds_process_files());
5687
5688        // A forked process holds its copy; its creator's group is unchanged.
5689        let mut forked = child(&tool, &mut root, 6, CloneFlags::empty());
5690        assert_ne!(forked.process_files, root.process_files);
5691        assert!(forked.holds_process_files());
5692        assert_eq!(root.process_files, Some(root.files_id()));
5693
5694        // A process made with CLONE_FILES shares its creator's table, made
5695        // for that creator, and leads a group of its own: its thread holds
5696        // the process's table although the table's creator is neither the
5697        // thread nor its leader.
5698        let mut shares_files = child(&tool, &mut forked, 7, CloneFlags::CLONE_FILES);
5699        assert_eq!(shares_files.files_id(), forked.files_id());
5700        assert_eq!(shares_files.process_files, Some(forked.files_id()));
5701        let its_thread = child(&tool, &mut shares_files, 8, thread);
5702        assert_ne!(its_thread.files_id().creator(), DetPid::from_raw(7));
5703        assert!(its_thread.holds_process_files());
5704
5705        // A thread that did not lead its process execs, as handle_execveat
5706        // gives it its new table: the new table is the process's, and a
5707        // thread the new image creates holds it. A failed exec restores
5708        // both.
5709        let mut worker = child(&tool, &mut root, 9, thread);
5710        let old_metadata = Arc::clone(&worker.file_metadata);
5711        let old_process_files = worker.process_files;
5712        let new_metadata = worker.file_metadata.lock().unwrap().for_exec(worker.dettid);
5713        worker.file_metadata = Arc::new(Mutex::new(new_metadata));
5714        worker.adopt_process_files();
5715        assert_eq!(worker.files_id().creator(), DetPid::from_raw(9));
5716        assert!(worker.holds_process_files());
5717        assert_ne!(worker.process_files, root.process_files);
5718        assert_eq!(root.process_files, Some(root.files_id()));
5719        let after_exec = child(&tool, &mut worker, 10, thread);
5720        assert!(after_exec.holds_process_files());
5721        worker.file_metadata = old_metadata;
5722        worker.process_files = old_process_files;
5723        assert_eq!(worker.process_files, root.process_files);
5724        assert!(worker.holds_process_files());
5725    }
5726}
5727
5728#[cfg(test)]
5729mod child_rng_identity_tests {
5730    use super::*;
5731
5732    fn child_state(
5733        tool: &Detcore,
5734        parent: &mut ThreadState<()>,
5735        host_tid: i32,
5736        clone_flags: CloneFlags,
5737    ) -> ThreadState<()> {
5738        parent.clone_flags = Some(clone_flags);
5739        <Detcore as Tool>::init_thread_state(
5740            tool,
5741            Tid::from_raw(host_tid),
5742            Some((Tid::from_raw(parent.dettid.as_raw()), parent)),
5743        )
5744    }
5745
5746    fn rng_sample(child: &ThreadState<()>) -> [u64; 4] {
5747        let mut rng = child.prng.clone();
5748        std::array::from_fn(|_| rng.random())
5749    }
5750
5751    fn chaos_rng_sample(child: &ThreadState<()>) -> [u64; 4] {
5752        let mut rng = child.chaos_prng.clone();
5753        std::array::from_fn(|_| rng.random())
5754    }
5755
5756    #[test]
5757    fn common_child_rng_identity_ignores_backend_tid_for_every_clone_shape() {
5758        let config = Config::default();
5759        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5760        for (label, clone_flags) in [
5761            ("fork", CloneFlags::empty()),
5762            ("vfork", CloneFlags::CLONE_VM | CloneFlags::CLONE_VFORK),
5763            ("clone-process", CloneFlags::CLONE_VM),
5764            (
5765                "clone-thread",
5766                CloneFlags::CLONE_VM | CloneFlags::CLONE_THREAD,
5767            ),
5768        ] {
5769            let mut low_tid_parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5770            let mut high_tid_parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5771            let low_tid_child = child_state(&tool, &mut low_tid_parent, 2, clone_flags);
5772            let high_tid_child = child_state(&tool, &mut high_tid_parent, 42_002, clone_flags);
5773
5774            assert_eq!(format!("{}", low_tid_child.pedigree), "C", "{label}");
5775            assert_eq!(low_tid_child.dettid.as_raw(), 2, "{label}");
5776            assert_eq!(high_tid_child.dettid.as_raw(), 42_002, "{label}");
5777            assert_eq!(
5778                rng_sample(&low_tid_child),
5779                rng_sample(&high_tid_child),
5780                "{label} child RNG depended on the backend Tid"
5781            );
5782            assert_eq!(
5783                chaos_rng_sample(&low_tid_child),
5784                chaos_rng_sample(&high_tid_child),
5785                "{label} child chaos RNG depended on the backend Tid"
5786            );
5787            assert_ne!(
5788                rng_sample(&low_tid_child),
5789                chaos_rng_sample(&low_tid_child),
5790                "{label} child guest and chaos RNG streams were coupled"
5791            );
5792        }
5793    }
5794
5795    #[test]
5796    fn serialized_siblings_receive_distinct_child_rng_streams() {
5797        let config = Config::default();
5798        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5799        let mut parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5800
5801        let first = child_state(&tool, &mut parent, 2, CloneFlags::empty());
5802        let first_pedigree = parent.pedigree.fork_mut();
5803        assert_eq!(format!("{}", first.pedigree), format!("{first_pedigree}"));
5804        let second = child_state(&tool, &mut parent, 3, CloneFlags::empty());
5805
5806        assert_eq!(format!("{}", second.pedigree), "PC");
5807        assert_ne!(rng_sample(&first), rng_sample(&second));
5808    }
5809}
5810
5811#[cfg(test)]
5812mod thread_exit_identity_tests {
5813    use super::*;
5814
5815    #[test]
5816    fn initialized_thread_exit_identity_is_preserved() {
5817        let thread_detpid = DetPid::from_raw(41);
5818        let process_detpid = DetPid::from_raw(7);
5819        assert_eq!(
5820            select_thread_exit_detpid(Some(thread_detpid), process_detpid),
5821            (thread_detpid, false)
5822        );
5823    }
5824
5825    #[test]
5826    fn missing_thread_exit_identity_uses_process_identity() {
5827        let process_detpid = DetPid::from_raw(7);
5828        assert_eq!(
5829            select_thread_exit_detpid(None, process_detpid),
5830            (process_detpid, true)
5831        );
5832    }
5833}
5834
5835#[cfg(test)]
5836mod completed_syscall_projection_tests {
5837    use super::*;
5838
5839    /// Signal phase 1: the signal pipeline at a syscall's completion reads
5840    /// the result in rax, rip after the two-byte syscall instruction, and the
5841    /// instruction's clobbers; every other register is the entry's.
5842    #[test]
5843    fn a_completed_syscall_shows_its_result_and_return_address() {
5844        let mut entry: libc::user_regs_struct = unsafe { std::mem::zeroed() };
5845        entry.rip = 0x40_1000;
5846        entry.rax = libc::SYS_pause as u64;
5847        entry.rcx = 0x1111;
5848        entry.r11 = 0x2222;
5849        entry.eflags = 0x246;
5850        entry.rdi = 7;
5851        entry.rsp = 0x7ffd_0000;
5852        let completed = completed_syscall_projection(entry, -i64::from(libc::EINTR));
5853        assert_eq!(completed.rax, (-i64::from(libc::EINTR)) as u64);
5854        assert_eq!(completed.rip, 0x40_1002);
5855        assert_eq!(completed.rcx, 0x40_1002);
5856        assert_eq!(completed.r11, 0x246);
5857        assert_eq!(completed.rdi, 7);
5858        assert_eq!(completed.rsp, 0x7ffd_0000);
5859        assert_eq!(completed.eflags, 0x246);
5860    }
5861}
5862
5863#[cfg(test)]
5864mod thread_start_identity_tests {
5865    use super::*;
5866
5867    #[test]
5868    fn backend_process_identity_is_preserved() {
5869        let backend_detpid = DetPid::from_raw(3);
5870        assert_eq!(
5871            select_thread_start_detpid(Some(backend_detpid), Pid::from_raw(42_001)),
5872            backend_detpid
5873        );
5874        assert_eq!(
5875            select_thread_start_detpid(None, Pid::from_raw(42_001)),
5876            DetPid::from_raw(42_001)
5877        );
5878    }
5879
5880    #[test]
5881    fn root_thread_uses_deterministic_process_identity() {
5882        let detpid = DetPid::from_raw(3);
5883        for past_first_execve in [false, true] {
5884            assert!(thread_start_needs_registration(
5885                true,
5886                past_first_execve,
5887                DetTid::from_raw(3),
5888                detpid
5889            ));
5890            for is_root_process in [false, true] {
5891                assert!(!thread_start_needs_registration(
5892                    is_root_process,
5893                    past_first_execve,
5894                    DetTid::from_raw(4),
5895                    detpid
5896                ));
5897            }
5898        }
5899        assert!(thread_start_needs_registration(
5900            false,
5901            false,
5902            DetTid::from_raw(3),
5903            detpid
5904        ));
5905        assert!(!thread_start_needs_registration(
5906            false,
5907            true,
5908            DetTid::from_raw(3),
5909            detpid
5910        ));
5911    }
5912}
5913
5914#[cfg(test)]
5915mod thread_cpu_time_tests {
5916    use super::*;
5917
5918    #[test]
5919    fn cloned_threads_and_processes_keep_absolute_time_without_inheriting_work() {
5920        for clone_flags in [
5921            CloneFlags::CLONE_THREAD,
5922            CloneFlags::empty(),
5923            CloneFlags::CLONE_VFORK | CloneFlags::CLONE_VM,
5924        ] {
5925            let config = Config::default();
5926            let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5927            let mut parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5928            parent.thread_logical_time.add_rcbs(7);
5929            parent.thread_logical_time.add_syscall_with_cost(101);
5930            parent.clone_flags = Some(clone_flags);
5931            let child = <Detcore as Tool>::init_thread_state(
5932                &tool,
5933                Tid::from_raw(2),
5934                Some((Tid::from_raw(1), &parent)),
5935            );
5936            assert_eq!(
5937                child.thread_logical_time.as_nanos(),
5938                parent.thread_logical_time.as_nanos()
5939            );
5940            assert_eq!(
5941                child.thread_logical_time.inherited_nanos(),
5942                LogicalTime::from_nanos(171)
5943            );
5944            let mut global = GlobalTime::new(&config);
5945            let epoch = global.as_nanos();
5946            for thread in [&parent, &child] {
5947                global.update_global_time(
5948                    thread.dettid,
5949                    thread.thread_logical_time.as_nanos(),
5950                    thread.thread_logical_time.inherited_nanos(),
5951                );
5952            }
5953            assert_eq!(global.as_nanos(), epoch + LogicalTime::from_nanos(171));
5954        }
5955    }
5956
5957    #[test]
5958    fn cloned_thread_and_fork_child_start_with_zero_thread_cpu() {
5959        for clone_flags in [CloneFlags::CLONE_THREAD, CloneFlags::empty()] {
5960            let config = Config::default();
5961            let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
5962            let mut parent = ThreadState::new(DetPid::from_raw(1), &config, ());
5963
5964            // Give the parent nonzero CPU before the child exists. The child's
5965            // absolute logical clock inherits this position for scheduler
5966            // ordering, but Linux per-thread CPU accounting must not.
5967            parent.thread_logical_time.add_rcbs(200);
5968            parent.thread_logical_time.add_syscall();
5969            parent.clone_flags = Some(clone_flags);
5970
5971            let mut child = <Detcore as Tool>::init_thread_state(
5972                &tool,
5973                Tid::from_raw(2),
5974                Some((Tid::from_raw(1), &parent)),
5975            );
5976            assert_eq!(
5977                child.thread_cpu_time(),
5978                (LogicalTime::ZERO, LogicalTime::ZERO),
5979                "clone flags {clone_flags:?} inherited pre-creation CPU"
5980            );
5981
5982            child.thread_logical_time.add_rcbs(4);
5983            child.thread_logical_time.add_syscall();
5984            let (user, system) = child.thread_cpu_time();
5985            assert!(user > LogicalTime::ZERO);
5986            assert!(system > LogicalTime::ZERO);
5987            assert!(user < parent.thread_logical_time.user_cpu_time());
5988            assert!(system <= parent.thread_logical_time.system_cpu_time());
5989        }
5990    }
5991}
5992
5993/// Regression tests for <https://github.com/rrnewton/hermit/issues/3153>: a
5994/// failed syscall must not render an output buffer the kernel never wrote.
5995///
5996/// Each buffer is pre-filled with sentinel values standing in for the
5997/// uninitialized guest stack the issue observed, and the rendering is checked
5998/// through the same `finish syscall` format the DETLOG line uses.
5999#[cfg(test)]
6000mod finished_syscall_display_tests {
6001    use std::ffi::CString;
6002
6003    use reverie::syscalls::AddrMut;
6004    use reverie::syscalls::AtFlags;
6005    use reverie::syscalls::ClockGettime;
6006    use reverie::syscalls::ClockId;
6007    use reverie::syscalls::Gettimeofday;
6008    use reverie::syscalls::LocalMemory;
6009    use reverie::syscalls::Newfstatat;
6010    use reverie::syscalls::PathPtr;
6011    use reverie::syscalls::StatPtr;
6012    use reverie::syscalls::Statx;
6013    use reverie::syscalls::StatxMask;
6014    use reverie::syscalls::StatxPtr;
6015    use reverie::syscalls::Timespec;
6016    use reverie::syscalls::TimespecMutPtr;
6017    use reverie::syscalls::Timeval;
6018    use reverie::syscalls::TimevalMutPtr;
6019
6020    use super::*;
6021
6022    /// A value no real `st_size` or timestamp in these tests can take.
6023    const SENTINEL: i64 = 0x5EED_0BAD_F00D;
6024
6025    /// Render exactly what the `finish syscall` DETLOG line renders.
6026    fn finish_line(syscall: &Syscall, result: Result<i64, Error>) -> String {
6027        let memory = LocalMemory::new();
6028        format!(
6029            "{} = {:?}",
6030            display_syscall_finished(syscall, &memory, &result),
6031            result
6032        )
6033    }
6034
6035    fn sentinel_stat() -> libc::stat {
6036        // SAFETY: all-zero is a valid `struct stat`.
6037        let mut stat: libc::stat = unsafe { std::mem::zeroed() };
6038        stat.st_mode = libc::S_IFREG | 0o644;
6039        stat.st_size = SENTINEL;
6040        stat
6041    }
6042
6043    fn sentinel_statx() -> libc::statx {
6044        // SAFETY: all-zero is a valid `struct statx`.
6045        let mut statx: libc::statx = unsafe { std::mem::zeroed() };
6046        statx.stx_mode = (libc::S_IFREG | 0o644) as u16;
6047        statx.stx_size = SENTINEL as u64;
6048        statx
6049    }
6050
6051    fn newfstatat(path: &CString, stat: &libc::stat) -> Syscall {
6052        Syscall::Newfstatat(
6053            Newfstatat::new()
6054                .with_dirfd(libc::AT_FDCWD)
6055                .with_path(PathPtr::from_ptr(path.as_ptr()))
6056                .with_stat(StatPtr::from_ptr(stat as *const libc::stat))
6057                .with_flags(AtFlags::empty()),
6058        )
6059    }
6060
6061    fn statx(path: &CString, statx: &libc::statx) -> Syscall {
6062        Syscall::Statx(
6063            Statx::new()
6064                .with_dirfd(libc::AT_FDCWD)
6065                .with_path(PathPtr::from_ptr(path.as_ptr()))
6066                .with_flags(AtFlags::empty())
6067                .with_mask(StatxMask::STATX_BASIC_STATS)
6068                .with_statx(StatxPtr::from_ptr(statx as *const libc::statx)),
6069        )
6070    }
6071
6072    fn assert_no_struct_rendered(line: &str) {
6073        assert!(!line.contains("st_mode"), "rendered st_mode: {line}");
6074        assert!(!line.contains("st_size"), "rendered st_size: {line}");
6075        assert!(
6076            !line.contains(&SENTINEL.to_string()),
6077            "rendered the unwritten sentinel: {line}"
6078        );
6079    }
6080
6081    #[test]
6082    fn failed_newfstatat_renders_pointer_and_errno_but_not_the_buffer() {
6083        let path = CString::new("/nonexistent/issue-3153").unwrap();
6084        let stat = sentinel_stat();
6085        let line = finish_line(&newfstatat(&path, &stat), Err(Errno::ENOENT.into()));
6086
6087        assert_no_struct_rendered(&line);
6088        assert!(
6089            line.contains(&format!("{:p}", &stat as *const libc::stat)),
6090            "stat pointer missing: {line}"
6091        );
6092        assert!(
6093            line.contains("\"/nonexistent/issue-3153\""),
6094            "path missing: {line}"
6095        );
6096        assert!(line.contains("ENOENT"), "errno missing: {line}");
6097    }
6098
6099    #[test]
6100    fn successful_newfstatat_still_renders_the_buffer() {
6101        let path = CString::new("/dev/null").unwrap();
6102        let stat = sentinel_stat();
6103        let line = finish_line(&newfstatat(&path, &stat), Ok(0));
6104
6105        assert!(
6106            line.contains(&format!(
6107                "{:p} -> {{st_mode=SFlag(S_IFREG) | 0644, st_size={}, ...}}",
6108                &stat as *const libc::stat, SENTINEL
6109            )),
6110            "stat struct missing: {line}"
6111        );
6112    }
6113
6114    #[test]
6115    fn failed_statx_renders_pointer_and_errno_but_not_the_buffer() {
6116        let path = CString::new("/nonexistent/issue-3153").unwrap();
6117        let buf = sentinel_statx();
6118        let line = finish_line(&statx(&path, &buf), Err(Errno::ENOENT.into()));
6119
6120        assert_no_struct_rendered(&line);
6121        assert!(
6122            line.contains(&format!("{:p}", &buf as *const libc::statx)),
6123            "statx pointer missing: {line}"
6124        );
6125        assert!(line.contains("ENOENT"), "errno missing: {line}");
6126    }
6127
6128    #[test]
6129    fn successful_statx_still_renders_the_buffer() {
6130        let path = CString::new("/dev/null").unwrap();
6131        let buf = sentinel_statx();
6132        let line = finish_line(&statx(&path, &buf), Ok(0));
6133
6134        assert!(
6135            line.contains(&format!(
6136                "{:p} -> {{st_mode=SFlag(S_IFREG) | 0644, st_size={}, ...}}",
6137                &buf as *const libc::statx, SENTINEL
6138            )),
6139            "statx struct missing: {line}"
6140        );
6141    }
6142
6143    #[test]
6144    fn failed_clock_gettime_does_not_render_the_timespec() {
6145        let tp = Timespec {
6146            tv_sec: SENTINEL,
6147            tv_nsec: 0,
6148        };
6149        let call = Syscall::ClockGettime(
6150            ClockGettime::new()
6151                .with_clockid(ClockId::CLOCK_MONOTONIC)
6152                .with_tp(Some(TimespecMutPtr(
6153                    AddrMut::from_ptr(&tp as *const Timespec).unwrap(),
6154                ))),
6155        );
6156
6157        let failed = finish_line(&call, Err(Errno::EINVAL.into()));
6158        assert!(!failed.contains("tv_sec"), "rendered tv_sec: {failed}");
6159        assert!(
6160            failed.contains(&format!("{:p}", &tp as *const Timespec)),
6161            "tp pointer missing: {failed}"
6162        );
6163        assert!(failed.contains("EINVAL"), "errno missing: {failed}");
6164
6165        let succeeded = finish_line(&call, Ok(0));
6166        assert!(
6167            succeeded.contains(&format!("tv_sec: {SENTINEL}")),
6168            "timespec missing on success: {succeeded}"
6169        );
6170    }
6171
6172    /// EFAULT is also the error of a copy-out that faulted part way, after
6173    /// `copy_to_user()` stored a prefix the guest can read, so it must keep
6174    /// the buffer rendered for every allowlisted syscall.
6175    #[test]
6176    fn efault_failures_still_render_a_possible_partial_copy() {
6177        let path = CString::new("/dev/null").unwrap();
6178        let stat = sentinel_stat();
6179        let line = finish_line(&newfstatat(&path, &stat), Err(Errno::EFAULT.into()));
6180        assert!(
6181            line.contains(&format!(
6182                "{:p} -> {{st_mode=SFlag(S_IFREG) | 0644, st_size={}, ...}}",
6183                &stat as *const libc::stat, SENTINEL
6184            )),
6185            "partial stat copy hidden on EFAULT: {line}"
6186        );
6187        assert!(line.contains("EFAULT"), "errno missing: {line}");
6188
6189        let buf = sentinel_statx();
6190        let line = finish_line(&statx(&path, &buf), Err(Errno::EFAULT.into()));
6191        assert!(
6192            line.contains(&format!(
6193                "{:p} -> {{st_mode=SFlag(S_IFREG) | 0644, st_size={}, ...}}",
6194                &buf as *const libc::statx, SENTINEL
6195            )),
6196            "partial statx copy hidden on EFAULT: {line}"
6197        );
6198
6199        let tp = Timespec {
6200            tv_sec: SENTINEL,
6201            tv_nsec: 0,
6202        };
6203        let call = Syscall::ClockGettime(
6204            ClockGettime::new()
6205                .with_clockid(ClockId::CLOCK_MONOTONIC)
6206                .with_tp(Some(TimespecMutPtr(
6207                    AddrMut::from_ptr(&tp as *const Timespec).unwrap(),
6208                ))),
6209        );
6210        let line = finish_line(&call, Err(Errno::EFAULT.into()));
6211        assert!(
6212            line.contains(&format!("tv_sec: {SENTINEL}")),
6213            "partial timespec copy hidden on EFAULT: {line}"
6214        );
6215    }
6216
6217    /// A posthook anchor fires on a value or a final guest errno, `EINTR`
6218    /// included; an internal restart code is refused; a tool error and an
6219    /// entry with no posthook anchor make no request
6220    /// (https://github.com/rrnewton/hermit/issues/3929).
6221    #[test]
6222    fn a_posthook_checkpoint_fires_only_on_a_final_result() {
6223        let anchors = || vec!["p".to_owned()];
6224        let fires = |result: Result<i64, Error>| {
6225            matches!(
6226                posthook_checkpoint(9, anchors(), &result),
6227                Some(ResourceID::HappensBeforeSyscallCheckpoint { count: 9, anchors })
6228                    if anchors == ["p"]
6229            )
6230        };
6231        assert!(fires(Ok(0)));
6232        assert!(fires(Ok(6)));
6233        for errno in [Errno::EINTR, Errno::EAGAIN, Errno::EBADF, Errno::EFAULT] {
6234            assert!(fires(Err(errno.into())), "{errno}");
6235        }
6236        for errno in [
6237            Errno::ERESTARTSYS,
6238            Errno::ERESTARTNOINTR,
6239            Errno::ERESTARTNOHAND,
6240            Errno::ERESTART_RESTARTBLOCK,
6241        ] {
6242            match posthook_checkpoint(9, anchors(), &Err(errno.into())) {
6243                Some(ResourceID::HappensBeforePosthookInterrupted {
6244                    count: 9,
6245                    anchors,
6246                    code,
6247                }) => {
6248                    assert_eq!(anchors, ["p"]);
6249                    assert_eq!(Some(code.as_str()), errno.name());
6250                }
6251                other => panic!("{errno}: {other:?}"),
6252            }
6253        }
6254        assert!(
6255            posthook_checkpoint(9, anchors(), &Err(Error::Tool(anyhow::anyhow!("tool")))).is_none()
6256        );
6257        assert!(posthook_checkpoint(9, Vec::new(), &Ok(0)).is_none());
6258        assert!(posthook_checkpoint(9, Vec::new(), &Err(Errno::ERESTARTSYS.into())).is_none());
6259    }
6260
6261    /// A tool error is not the syscall's result and proves nothing about the
6262    /// buffer, so only a guest errno other than EFAULT hides it.
6263    #[test]
6264    fn only_non_efault_guest_errnos_prove_the_buffer_unwritten() {
6265        for errno in [Errno::ENOENT, Errno::EINVAL, Errno::EBADF, Errno::ENOMEM] {
6266            assert!(failure_proves_outputs_unwritten(&Err(errno.into())));
6267        }
6268        assert!(!failure_proves_outputs_unwritten(
6269            &Err(Errno::EFAULT.into())
6270        ));
6271        assert!(!failure_proves_outputs_unwritten(&Ok(0)));
6272        assert!(!failure_proves_outputs_unwritten(&Err(Error::Tool(
6273            anyhow::anyhow!("tool failure")
6274        ))));
6275
6276        let path = CString::new("/dev/null").unwrap();
6277        let stat = sentinel_stat();
6278        let line = finish_line(
6279            &newfstatat(&path, &stat),
6280            Err(Error::Tool(anyhow::anyhow!("tool failure"))),
6281        );
6282        assert!(
6283            line.contains(&format!("st_size={SENTINEL}")),
6284            "buffer hidden on a tool error: {line}"
6285        );
6286    }
6287
6288    /// `gettimeofday` stores `tv` before it can fail with `EFAULT` on a bad
6289    /// `tz`, so a failed call can carry a kernel-written output. It must stay
6290    /// rendered: suppressing it would hide real evidence from DETLOG.
6291    #[test]
6292    fn failed_gettimeofday_still_renders_the_timeval() {
6293        let tv = Timeval {
6294            tv_sec: SENTINEL,
6295            tv_usec: 0,
6296        };
6297        let call = Syscall::Gettimeofday(
6298            Gettimeofday::new()
6299                .with_tv(Some(TimevalMutPtr(
6300                    AddrMut::from_ptr(&tv as *const Timeval).unwrap(),
6301                )))
6302                .with_tz(None),
6303        );
6304
6305        let line = finish_line(&call, Err(Errno::EFAULT.into()));
6306        assert!(
6307            line.contains(&format!("tv_sec: {SENTINEL}")),
6308            "kernel-written timeval hidden on failure: {line}"
6309        );
6310        assert!(line.contains("EFAULT"), "errno missing: {line}");
6311    }
6312
6313    /// `fstat` never renders its buffer (T136880615); the result must not
6314    /// change that in either direction.
6315    #[test]
6316    fn fstat_never_renders_the_buffer() {
6317        let stat = sentinel_stat();
6318        let call = Syscall::Fstat(
6319            reverie::syscalls::Fstat::new()
6320                .with_fd(3)
6321                .with_stat(StatPtr::from_ptr(&stat as *const libc::stat)),
6322        );
6323        for result in [Ok(0), Err(Errno::EBADF.into())] {
6324            assert_no_struct_rendered(&finish_line(&call, result));
6325        }
6326    }
6327}