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}