Skip to main content

detcore/syscalls/
threads.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//! System calls for dealing with threads and concurrency.
10
11use std::collections::HashMap;
12use std::marker::PhantomData;
13use std::sync::Arc;
14use std::sync::Mutex;
15use std::time::Duration;
16
17use detcore_model::bundled_signal_facts;
18use procfs::process::Process;
19use rand::Rng;
20use reverie::BackendCapabilities;
21use reverie::Error;
22use reverie::Guest;
23use reverie::Pid;
24use reverie::Stack;
25use reverie::syscalls;
26use reverie::syscalls::Addr;
27use reverie::syscalls::AddrMut;
28use reverie::syscalls::CloneFlags;
29use reverie::syscalls::Errno;
30use reverie::syscalls::MemoryAccess;
31use reverie::syscalls::ReadAddr;
32use reverie::syscalls::Syscall;
33use reverie::syscalls::SyscallInfo;
34use reverie::syscalls::Timespec;
35use reverie::syscalls::WaitPidFlag;
36use tracing::debug;
37use tracing::error;
38use tracing::info;
39use tracing::trace;
40
41use crate::SharedMemoryObjectId;
42use crate::config::BlockingMode;
43use crate::config::Config;
44use crate::config::SchedHeuristic;
45use crate::memory::MemoryMetadata;
46use crate::record_or_replay::RecordOrReplay;
47use crate::resources::ExternalOpId;
48use crate::resources::Permission;
49use crate::resources::ResourceID;
50use crate::resources::Resources;
51use crate::scheduler::FutexSignalWatch;
52use crate::scheduler::HostTimedSignalScope;
53use crate::scheduler::SchedValue;
54use crate::scheduler::pid_namespaces::GuestPidAnswer;
55use crate::syscalls::helpers::NonblockableSyscall;
56use crate::syscalls::helpers::RestartCall;
57use crate::syscalls::helpers::keep_restart_block;
58use crate::syscalls::helpers::record_retry_event;
59use crate::syscalls::helpers::retry_nonblocking_syscall;
60use crate::syscalls::helpers::retry_nonblocking_syscall_with_timeout;
61use crate::syscalls::robust_list;
62use crate::tool_global::FutexAction;
63use crate::tool_global::ResumeStatus;
64use crate::tool_global::await_exact_child_physical_exit;
65use crate::tool_global::cancel_exec;
66use crate::tool_global::child_tid_clear_address;
67use crate::tool_global::consume_child_wait;
68use crate::tool_global::create_child_thread;
69use crate::tool_global::futex_action;
70use crate::tool_global::hold_turn_for_group_exit;
71use crate::tool_global::host_timed_signals;
72use crate::tool_global::prepare_exec;
73use crate::tool_global::process_group;
74use crate::tool_global::ready_child_wait;
75use crate::tool_global::record_host_timed_signals;
76use crate::tool_global::resource_request;
77use crate::tool_global::set_child_tid_address;
78use crate::tool_global::thread_is_live;
79use crate::tool_global::thread_observe_time;
80use crate::tool_global::wait_for_child_lifecycle;
81use crate::tool_global::yield_once;
82use crate::tool_local::Detcore;
83use crate::tool_local::PendingVfork;
84use crate::tool_local::RobustListExit;
85use crate::tool_local::RobustListOwner;
86use crate::tool_local::RobustListWake;
87use crate::types::ChildWaitExitClass;
88use crate::types::ChildWaitSelector;
89use crate::types::ChildWaitSpec;
90use crate::types::DetPid;
91use crate::types::DetTid;
92use crate::types::ExactChildWaitState;
93use crate::types::FutexID;
94use crate::types::LogicalTime;
95use crate::types::SigWrapper;
96
97#[path = "emulated_waitid.rs"]
98mod emulated_waitid;
99
100// Preserve the historical Detcore ABI while hiding the host's configured CPU
101// count. This represents one virtual CPU in a fixed 128-bit kernel mask.
102pub(crate) const VIRTUAL_CPUSET_BYTES: usize = 16;
103
104const IOPRIO_WHO_PROCESS: libc::c_int = 1;
105const IOPRIO_WHO_PGRP: libc::c_int = 2;
106const IOPRIO_WHO_USER: libc::c_int = 3;
107const IOPRIO_CLASS_SHIFT: libc::c_int = 13;
108const IOPRIO_CLASS_BE: libc::c_int = 2;
109const IOPRIO_BE_NORM: libc::c_int = 4;
110const IOPRIO_DEFAULT_EFFECTIVE: libc::c_int =
111    (IOPRIO_CLASS_BE << IOPRIO_CLASS_SHIFT) | IOPRIO_BE_NORM;
112
113// sched_attr wire contract, from include/uapi/linux/sched/types.h. These are
114// spelled out rather than derived from `size_of::<libc::sched_attr>()`: the
115// value the kernel reports back on the E2BIG paths and the offset past which
116// trailing bytes must be zero are properties of the KERNEL's struct, which is
117// larger than the libc crate's 48-byte mirror. Deriving either from a Rust type
118// would silently re-point the contract if that type ever grows a field.
119const SCHED_ATTR_SIZE_VER0: u32 = 48; // first published struct
120const SCHED_ATTR_SIZE_VER1: u32 = 56; // adds sched_util_{min,max}
121/// The kernel's own `sizeof(struct sched_attr)`. Two things key off it: bytes at
122/// or beyond this offset must be zero, and it is the value written back into
123/// `uattr->size` when the request is refused with E2BIG.
124const SCHED_ATTR_KERNEL_SIZE: u32 = SCHED_ATTR_SIZE_VER1;
125/// `sched_copy_attr` refuses a buffer larger than one page. Hermit is x86-64
126/// only, where PAGE_SIZE is 4096.
127const SCHED_ATTR_MAX_SIZE: u32 = 4096;
128
129/// The scheduling policy Detcore presents as every thread's current one.
130///
131/// This is not a guess about the host. It is the value `handle_sched_getattr`
132/// writes back for every thread, so it is the policy a guest observes and the
133/// only policy `SCHED_FLAG_KEEP_POLICY` can be keeping.
134const VIRTUAL_CURRENT_POLICY: u32 = libc::SCHED_OTHER as u32;
135
136/// Outcome of scanning the bytes past the kernel's `struct sched_attr`.
137#[derive(Debug, Eq, PartialEq)]
138enum TailVerdict {
139    AllZero,
140    /// A byte the kernel does not understand was set: `copy_struct_from_user`
141    /// reports this as E2BIG, after storing its own size back.
142    NotZeroed,
143    /// Guest memory could not be read before any non-zero byte was seen.
144    Faulted,
145}
146
147/// Reads of eight bytes or fewer take safeptrace's `PTRACE_PEEKDATA` path,
148/// which reads a whole aligned word and BYPASSES GUEST PAGE PROTECTIONS. Only a
149/// read strictly larger than that reaches `process_vm_readv`, which honours
150/// them. Note this is not symmetric with the write side: `write` special-cases
151/// a length of exactly eight, so splitting a write in half escapes it, while
152/// `read` special-cases eight *or fewer* and splitting only makes it worse.
153const MIN_PROTECTION_RESPECTING_READ: usize = std::mem::size_of::<u64>() + 1;
154
155/// Scan `tail_len` bytes at `base + tail_off` the way `check_zeroed_user` does.
156///
157/// Two things here are load-bearing and neither is visible from the outcome
158/// alone, only from the ORDER the outcome is reached in.
159///
160/// First, Linux scans FORWARD and stops at the first thing it finds. A non-zero
161/// byte followed later by an unreadable page is E2BIG, because the scan never
162/// reaches the page; an unreadable page reached before any non-zero byte is
163/// EFAULT. Reading the whole tail up front and judging afterwards collapses
164/// both into EFAULT and silently changes the errno a guest sees.
165///
166/// Second, every read here is kept strictly larger than eight bytes, for the
167/// reason on [`MIN_PROTECTION_RESPECTING_READ`]. Where the remainder is
168/// smaller, the window is extended BACKWARDS over bytes already scanned rather
169/// than shortened; re-reading a byte is free and only the new bytes are judged.
170fn scan_tail_is_zeroed<M: MemoryAccess>(
171    memory: &M,
172    base: AddrMut<u8>,
173    tail_off: usize,
174    tail_len: usize,
175) -> TailVerdict {
176    const CHUNK: usize = 256;
177    let mut done = 0usize;
178    let mut buf = [0u8; CHUNK];
179    while done < tail_len {
180        let remaining = tail_len - done;
181        let want = remaining.min(CHUNK);
182        // Extend backwards when the remainder alone would be a small read.
183        // The window may reach back past the start of the tail into the
184        // `sched_attr` prefix: the kernel has already read those bytes, so they
185        // are readable, and only the new bytes are judged below. Clamping this
186        // to `done` alone left a 1-byte tail with nowhere to grow into and
187        // issued exactly the small read this constant exists to avoid.
188        let back = MIN_PROTECTION_RESPECTING_READ
189            .saturating_sub(want)
190            .min(done + tail_off);
191        let read_len = want + back;
192        let start = tail_off + done - back;
193        let Some(addr) = base
194            .as_raw()
195            .checked_add(start)
196            .and_then(AddrMut::<u8>::from_raw)
197        else {
198            return TailVerdict::Faulted;
199        };
200        // A failed read means zero NEW bytes were obtained; the `got < read_len`
201        // check below is what turns that into `Faulted`. Written `unwrap_or(0)`
202        // rather than `unwrap_or_default()` so the 0 stays visible.
203        let got = memory.read(addr, &mut buf[..read_len]).unwrap_or(0);
204        // Judge only the bytes that are genuinely new AND genuinely read.
205        let new_from = back.min(got);
206        if buf[new_from..got].iter().any(|byte| *byte != 0) {
207            return TailVerdict::NotZeroed;
208        }
209        if got < read_len {
210            // The scan stopped at an unreadable byte with nothing non-zero
211            // before it, which is `check_zeroed_user`'s -EFAULT.
212            return TailVerdict::Faulted;
213        }
214        done += want;
215    }
216    TailVerdict::AllZero
217}
218
219// Scheduling policies, from include/uapi/linux/sched.h.
220const SCHED_FIFO: u32 = 1;
221const SCHED_RR: u32 = 2;
222const SCHED_DEADLINE: u32 = 6;
223const SCHED_EXT: u32 = 7;
224/// The kernel's `MAX_RT_PRIO`; valid real-time priorities are 1..=99.
225const MAX_RT_PRIO: u32 = 100;
226
227// Byte offsets of the fields this handler inspects. Taken from the UAPI struct
228// rather than from a Rust mirror, for the reason given above.
229const SCHED_ATTR_OFF_POLICY: usize = 4;
230const SCHED_ATTR_OFF_FLAGS: usize = 8;
231const SCHED_ATTR_OFF_PRIORITY: usize = 20;
232const SCHED_ATTR_OFF_RUNTIME: usize = 24;
233const SCHED_ATTR_OFF_DEADLINE: usize = 32;
234const SCHED_ATTR_OFF_PERIOD: usize = 40;
235
236// sched_attr.sched_flags bits, from include/uapi/linux/sched.h.
237const SCHED_FLAG_RESET_ON_FORK: u64 = 0x01;
238const SCHED_FLAG_RECLAIM: u64 = 0x02;
239const SCHED_FLAG_DL_OVERRUN: u64 = 0x04;
240const SCHED_FLAG_KEEP_POLICY: u64 = 0x08;
241const SCHED_FLAG_KEEP_PARAMS: u64 = 0x10;
242const SCHED_FLAG_UTIL_CLAMP_MIN: u64 = 0x20;
243const SCHED_FLAG_UTIL_CLAMP_MAX: u64 = 0x40;
244const SCHED_FLAG_UTIL_CLAMP: u64 = SCHED_FLAG_UTIL_CLAMP_MIN | SCHED_FLAG_UTIL_CLAMP_MAX;
245const SCHED_FLAG_ALL: u64 = SCHED_FLAG_RESET_ON_FORK
246    | SCHED_FLAG_RECLAIM
247    | SCHED_FLAG_DL_OVERRUN
248    | SCHED_FLAG_KEEP_POLICY
249    | SCHED_FLAG_KEEP_PARAMS
250    | SCHED_FLAG_UTIL_CLAMP;
251
252/// Whether Linux accepts `policy` as a scheduling policy for `sched_setattr`.
253/// This is the kernel's `valid_policy()`: idle, fair, rt, deadline or ext. Note
254/// the gap at 4 -- SCHED_ISO is reserved and never valid -- and that 7 is
255/// SCHED_EXT, which `valid_policy()` accepts on a kernel built with
256/// CONFIG_SCHED_CLASS_EXT.
257fn is_valid_sched_policy(policy: u32) -> bool {
258    matches!(
259        policy,
260        // SCHED_OTHER/NORMAL, FIFO, RR, BATCH
261        0 | 1 | 2 | 3
262        // SCHED_IDLE
263        | 5
264        | SCHED_DEADLINE
265        | SCHED_EXT
266    )
267}
268
269/// The kernel's `rt_policy()`: the two fixed-priority real-time policies.
270fn is_rt_policy(policy: u32) -> bool {
271    policy == SCHED_FIFO || policy == SCHED_RR
272}
273
274/// The kernel's `__checkparam_dl()`, restricted to the parts that are pure ABI.
275///
276/// The kernel's final test compares the period against
277/// `sysctl_sched_dl_period_{min,max}`, which are runtime-tunable. That bound is
278/// a property of the host's configuration rather than of the interface, so it
279/// is deliberately not reproduced here -- see the handler's doc comment for the
280/// other cases in that class.
281fn deadline_params_are_valid(runtime: u64, deadline: u64, period: u64) -> bool {
282    // deadline != 0
283    if deadline == 0 {
284        return false;
285    }
286    // The kernel truncates DL_SCALE (10) bits, so runtime must be at least that
287    // big to survive the truncation.
288    if runtime < (1u64 << 10) {
289        return false;
290    }
291    // The MSB is reserved for wrap-around and sign handling.
292    if deadline & (1u64 << 63) != 0 || period & (1u64 << 63) != 0 {
293        return false;
294    }
295    // A zero period means "same as the deadline".
296    let period = if period == 0 { deadline } else { period };
297    // runtime <= deadline <= period
298    runtime <= deadline && deadline <= period
299}
300
301/// Apply `sched_copy_attr`'s size rules to the `size` the guest declared.
302///
303/// `Ok(n)` is the effective size to copy with; `Err(())` means the request is
304/// refused with E2BIG *and* the kernel first writes its own struct size back
305/// into `uattr->size`, so the caller owes that store.
306///
307/// The zero case is not a mistake: the kernel carries an explicit ABI
308/// compatibility quirk, `if (!size) size = SCHED_ATTR_SIZE_VER0;`, so a
309/// zero-sized request is a well-formed VER0 request and succeeds.
310fn sched_attr_effective_size(declared: u32) -> Result<u32, ()> {
311    let size = if declared == 0 {
312        SCHED_ATTR_SIZE_VER0
313    } else {
314        declared
315    };
316    if !(SCHED_ATTR_SIZE_VER0..=SCHED_ATTR_MAX_SIZE).contains(&size) {
317        return Err(());
318    }
319    Ok(size)
320}
321
322/// The descriptor fields this handler inspects, decoded from the guest's bytes.
323#[derive(Clone, Copy, Debug)]
324struct SchedAttrFields {
325    policy: u32,
326    sched_flags: u64,
327    priority: u32,
328    runtime: u64,
329    deadline: u64,
330    period: u64,
331}
332
333/// The checks that run in `sched_copy_attr` and in the `sched_setattr` wrapper,
334/// i.e. everything the kernel decides *before* it looks the target pid up.
335///
336/// `size` is the effective size from [`sched_attr_effective_size`], so the
337/// util-clamp rule can be stated in the same terms the kernel uses.
338///
339/// Measured: with a pid that does not exist, both of these still report their
340/// own errno rather than ESRCH, which is what places them on this side of the
341/// lookup.
342fn validate_sched_attr_before_lookup(size: u32, attr: &SchedAttrFields) -> Result<(), Errno> {
343    // `sched_copy_attr`: util-clamp lives past the VER0 tail, so asking for it
344    // with a VER0 buffer is incoherent.
345    if attr.sched_flags & SCHED_FLAG_UTIL_CLAMP != 0 && size < SCHED_ATTR_SIZE_VER1 {
346        return Err(Errno::EINVAL);
347    }
348    // `sched_setattr`: the policy is compared as a *signed* int, and this test
349    // sits above the KEEP_POLICY substitution below, so the sign bit is refused
350    // even when the policy field is otherwise ignored.
351    if (attr.policy as i32) < 0 {
352        return Err(Errno::EINVAL);
353    }
354    Ok(())
355}
356
357/// The checks inside `__sched_setscheduler`, i.e. everything the kernel decides
358/// *after* it has resolved the target pid.
359///
360/// Measured: with a pid that does not exist, every rule here reports ESRCH
361/// instead, which is what places them on this side of the lookup.
362fn validate_sched_attr_after_lookup(attr: &SchedAttrFields) -> Result<(), Errno> {
363    // `sched_setattr` rewrites the policy to SETPARAM_POLICY (-1) when
364    // KEEP_POLICY is set, and `__sched_setscheduler` then takes its
365    // `policy < 0` branch. That branch does not skip the policy-dependent
366    // rules -- it REUSES THE TASK'S CURRENT POLICY and applies them against
367    // that. `valid_policy()` is the only thing it skips, which is why an
368    // undefined value in the ignored field still passes.
369    //
370    // Detcore's current policy is not unknown: `handle_sched_getattr` reports
371    // SCHED_OTHER, nice 0, priority 0 for every thread, unconditionally, and
372    // that is the whole of the guest-visible scheduling state this sandbox
373    // exposes. So KEEP_POLICY substitutes SCHED_OTHER here. Treating it as
374    // "no policy" and skipping the rules accepted, for instance,
375    // KEEP_POLICY with sched_priority=1, which Linux refuses because a
376    // non-real-time current policy requires priority 0.
377    //
378    // These two sites must stay in step: if `handle_sched_getattr` ever
379    // reports a different virtual policy, this substitution follows it.
380    let policy = if attr.sched_flags & SCHED_FLAG_KEEP_POLICY != 0 {
381        Some(VIRTUAL_CURRENT_POLICY)
382    } else {
383        if !is_valid_sched_policy(attr.policy) {
384            return Err(Errno::EINVAL);
385        }
386        Some(attr.policy)
387    };
388    // No undefined sched_flags bits.
389    if attr.sched_flags & !SCHED_FLAG_ALL != 0 {
390        return Err(Errno::EINVAL);
391    }
392    // Valid priorities are 1..=MAX_RT_PRIO-1 for the real-time policies and
393    // exactly 0 for every other policy, so the priority and the policy have to
394    // agree; the kernel states that as `rt_policy(policy) != (prio != 0)`.
395    if attr.priority > MAX_RT_PRIO - 1 {
396        return Err(Errno::EINVAL);
397    }
398    if let Some(policy) = policy {
399        if is_rt_policy(policy) != (attr.priority != 0) {
400            return Err(Errno::EINVAL);
401        }
402        if policy == SCHED_DEADLINE
403            && !deadline_params_are_valid(attr.runtime, attr.deadline, attr.period)
404        {
405            return Err(Errno::EINVAL);
406        }
407    }
408    Ok(())
409}
410
411// AUTONOMOUS-BOT-IMPLEMENTED
412// TODO-HUMAN-REVIEW(PR-881)
413fn virtual_ioprio(which: libc::c_int) -> Result<i64, Errno> {
414    match which {
415        IOPRIO_WHO_PROCESS => Ok(0),
416        IOPRIO_WHO_PGRP | IOPRIO_WHO_USER => Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE)),
417        _ => Err(Errno::EINVAL),
418    }
419}
420
421#[repr(C)]
422#[derive(Clone, Copy)]
423struct WaitidSigchldFields {
424    pid: libc::pid_t,
425    uid: libc::uid_t,
426    status: libc::c_int,
427    utime: libc::c_long,
428    stime: libc::c_long,
429}
430
431#[repr(C)]
432union WaitidSiginfoFields {
433    _alignment: *mut libc::c_void,
434    sigchld: WaitidSigchldFields,
435}
436
437#[repr(C)]
438struct WaitidSiginfoHead {
439    _base: [libc::c_int; 3],
440    fields: WaitidSiginfoFields,
441}
442
443fn wait_status_is_termination(status: libc::c_int) -> bool {
444    libc::WIFEXITED(status) || libc::WIFSIGNALED(status)
445}
446
447fn waitid_code_is_termination(code: libc::c_int) -> bool {
448    matches!(code, libc::CLD_EXITED | libc::CLD_KILLED | libc::CLD_DUMPED)
449}
450
451fn canonicalize_waitid_siginfo(info: &mut libc::siginfo_t) {
452    debug_assert!(
453        std::mem::size_of::<WaitidSiginfoHead>() <= std::mem::size_of::<libc::siginfo_t>()
454    );
455    // SAFETY: Linux siginfo_t starts with three c_int fields followed by a
456    // pointer-aligned union. Its SIGCHLD member is pid, uid, status, utime,
457    // and stime in that order. The local repr(C) mirror changes only the two
458    // host CPU-accounting fields and preserves the kernel-populated event.
459    let sigchld = unsafe {
460        &mut (*(info as *mut libc::siginfo_t).cast::<WaitidSiginfoHead>())
461            .fields
462            .sigchld
463    };
464    sigchld.utime = 0;
465    sigchld.stime = 0;
466}
467
468/// `child` is the task `info_value.si_pid` names (`Detcore::task_of_guest_pid`).
469fn finish_waitid_result<T, G>(
470    guest: &mut G,
471    call: syscalls::Waitid,
472    value: i64,
473    mut info_value: libc::siginfo_t,
474    child: DetPid,
475) -> Result<i64, Error>
476where
477    T: RecordOrReplay,
478    G: Guest<Detcore<T>>,
479{
480    // SAFETY: waitid writes either zeroed output or the SIGCHLD siginfo_t
481    // variant, for which libc exposes si_pid.
482    let child_pid = unsafe { info_value.si_pid() };
483    if child_pid != 0 {
484        canonicalize_waitid_siginfo(&mut info_value);
485        guest.memory().write_value(
486            call.info().expect("waitid infop checked before execution"),
487            &info_value,
488        )?;
489        if call.options() & libc::WNOWAIT == 0 && waitid_code_is_termination(info_value.si_code) {
490            guest.thread_state_mut().reap_child_process_cpu_time(child);
491        }
492        if let Some(rusage) = call.rusage() {
493            // Host CPU and scheduling counters are not deterministic.
494            let usage: libc::rusage = unsafe { std::mem::zeroed() };
495            guest.memory().write_value(rusage, &usage)?;
496        }
497    }
498    Ok(value)
499}
500
501#[derive(Debug, Eq, PartialEq)]
502enum ExactWaitPollDecision {
503    ChildReady,
504    AwaitPhysicalExit,
505    ReapAfterLogicalExit,
506    Interrupted,
507    Retry,
508}
509
510fn exact_wait_poll_decision(
511    child_ready: bool,
512    signaled: bool,
513    lifecycle: Option<ExactChildWaitState>,
514) -> ExactWaitPollDecision {
515    if child_ready {
516        ExactWaitPollDecision::ChildReady
517    } else if lifecycle == Some(ExactChildWaitState::PhysicalExitPending) {
518        ExactWaitPollDecision::AwaitPhysicalExit
519    } else if matches!(
520        lifecycle,
521        Some(ExactChildWaitState::LogicallyExited | ExactChildWaitState::PhysicallyExited)
522    ) {
523        ExactWaitPollDecision::ReapAfterLogicalExit
524    } else if signaled {
525        ExactWaitPollDecision::Interrupted
526    } else {
527        ExactWaitPollDecision::Retry
528    }
529}
530
531fn stale_any_wait_must_interrupt(signaled: bool, next_ready: Option<DetPid>) -> bool {
532    signaled && next_ready.is_none()
533}
534
535fn terminal_child_wait_spec(
536    selector: ChildWaitSelector,
537    caller: DetTid,
538    options: libc::c_int,
539) -> ChildWaitSpec {
540    let exit_class = if options & libc::__WALL != 0 {
541        ChildWaitExitClass::Any
542    } else if options & libc::__WCLONE != 0 {
543        ChildWaitExitClass::Clone
544    } else {
545        ChildWaitExitClass::Sigchld
546    };
547    ChildWaitSpec {
548        selector,
549        owner: (options & libc::__WNOTHREAD != 0).then_some(caller),
550        exit_class,
551    }
552}
553
554fn validate_wait4_arguments(pid: libc::pid_t, options: WaitPidFlag) -> Result<(), Errno> {
555    let allowed_options = WaitPidFlag::WNOHANG
556        | WaitPidFlag::WUNTRACED
557        | WaitPidFlag::WCONTINUED
558        | WaitPidFlag::__WNOTHREAD
559        | WaitPidFlag::__WCLONE
560        | WaitPidFlag::__WALL;
561
562    // Linux kernel/exit.c:kernel_wait4 rejects unknown option bits before it
563    // interprets the pid selector.
564    if options.bits() & !allowed_options.bits() != 0 {
565        return Err(Errno::EINVAL);
566    }
567    // The same function returns ESRCH for INT_MIN before looking for children,
568    // because negating that selector is not representable as a pid_t.
569    if pid == libc::pid_t::MIN {
570        return Err(Errno::ESRCH);
571    }
572    Ok(())
573}
574
575// A serial emulated child wait (today KVM) represents terminal events only, including the terminal subset
576// of WUNTRACED. `__WNOTHREAD` is enforced by the logical owner filter in
577// `terminal_child_wait_spec`, and exact-child completion strips it before
578// the backend call. Keep unsupported and unknown low-int bits on the
579// backend's prevalidation path; they must not select or consume a logical
580// child.
581pub(super) fn wait4_uses_terminal_selector(
582    options: WaitPidFlag,
583    serial_emulated_wait: bool,
584) -> bool {
585    if serial_emulated_wait {
586        options.bits() & !(libc::WNOHANG | libc::WUNTRACED | libc::__WNOTHREAD) == 0
587    } else {
588        !options.intersects(
589            WaitPidFlag::WUNTRACED
590                | WaitPidFlag::WCONTINUED
591                | WaitPidFlag::__WCLONE
592                | WaitPidFlag::__WALL,
593        )
594    }
595}
596
597/// The one completion order a backend that emulates child waits
598/// (`BackendCapabilities::emulates_child_waits`) needs for both wait4 and
599/// waitid, split around the backend's exact-child call.
600///
601/// Backend waitability precedes the child's final owner-hook CPU prefix, so
602/// the caller first waits, under its retained grant and birth-owned identity,
603/// for that publication. No new scheduler turn or user-memory identity read
604/// occurs.
605pub(super) async fn await_selected_child_cpu_publication<G, T>(
606    guest: &mut G,
607    child: DetPid,
608    call: &str,
609) -> Result<(), Error>
610where
611    G: Guest<Detcore<T>>,
612    T: RecordOrReplay,
613{
614    if guest
615        .thread_state()
616        .wait_for_child_cpu_publication(child)
617        .await
618    {
619        Ok(())
620    } else {
621        Err(Error::Tool(anyhow::anyhow!(
622            "emulated {call} selected child has no owned final CPU publication"
623        )))
624    }
625}
626
627/// After the backend's exact-child call consumed `child` (it returned the
628/// child, or EFAULT after selecting it), retire it: reap its final CPU time
629/// and consume Detcore's logical wait. Shared by wait4 and waitid.
630pub(super) async fn retire_selected_child<G, T>(
631    guest: &mut G,
632    child: DetPid,
633    call: &str,
634) -> Result<(), Error>
635where
636    G: Guest<Detcore<T>>,
637    T: RecordOrReplay,
638{
639    guest.thread_state_mut().reap_child_process_cpu_time(child);
640    if consume_child_wait(guest, child).await {
641        Ok(())
642    } else {
643        Err(Error::Tool(anyhow::anyhow!(
644            "emulated {call} selected child was not logically consumed"
645        )))
646    }
647}
648
649pub(super) async fn complete_selected_emulated_wait4<G, T>(
650    guest: &mut G,
651    call: syscalls::Wait4,
652    child: DetPid,
653) -> Result<i64, Error>
654where
655    G: Guest<Detcore<T>>,
656    T: RecordOrReplay,
657{
658    await_selected_child_cpu_publication(guest, child, "wait4").await?;
659    // Selection already applied `__WNOTHREAD` through the logical owner
660    // filter; the backend's raw wait4 accepts only WNOHANG and WUNTRACED.
661    // Keep exactly those, as the waitid exact-child completion does.
662    let exact = call
663        .with_pid(child.as_raw())
664        .with_options(WaitPidFlag::from_bits_retain(
665            call.options().bits() & (libc::WNOHANG | libc::WUNTRACED),
666        ));
667    let result = guest.inject(exact).await;
668    match result {
669        Ok(pid) if pid == i64::from(child.as_raw()) => {}
670        // The supported KVM wait4 selects/consumes before either status or
671        // rusage copyout. EFAULT therefore consumed this exact child too.
672        Err(Errno::EFAULT) => {}
673        unexpected => {
674            return Err(Error::Tool(anyhow::anyhow!(
675                "emulated wait4 selected-child invariant failed: {unexpected:?} for {child}"
676            )));
677        }
678    }
679    retire_selected_child(guest, child, "wait4").await?;
680    result.map_err(Error::from)
681}
682
683fn child_wait_can_retry_after_stale(spec: ChildWaitSpec) -> bool {
684    !matches!(spec.selector, ChildWaitSelector::Exact(_))
685}
686
687pub(super) type KernelSigset = u64;
688pub(super) const KERNEL_SIGSET_SIZE: usize = std::mem::size_of::<KernelSigset>();
689
690fn signal_is_blocked(mask: &KernelSigset, signal: SigWrapper) -> bool {
691    let raw_signal = signal.raw();
692    (1..=KernelSigset::BITS as i32).contains(&raw_signal)
693        && mask & (1_u64 << (raw_signal as u32 - 1)) != 0
694}
695
696#[repr(C)]
697#[derive(Clone, Copy)]
698pub(super) struct KernelSigaction {
699    pub(super) handler: u64,
700    pub(super) flags: u64,
701    pub(super) restorer: u64,
702    pub(super) mask: KernelSigset,
703}
704
705#[derive(Clone, Copy, Debug, Eq, PartialEq)]
706pub(super) enum WaitSignalDisposition {
707    Interrupt,
708    Restart,
709}
710
711fn signal_default_disposition_does_not_interrupt_child_wait(signal: SigWrapper) -> bool {
712    matches!(
713        signal.raw(),
714        libc::SIGCHLD | libc::SIGCONT | libc::SIGURG | libc::SIGWINCH
715    )
716}
717
718/// Whether `signal`'s default action ends the process, by terminating it or
719/// dumping core (signal(7)): every signal except those whose default is to be
720/// ignored, to stop or to continue. SIGKILL, which no handler or callback
721/// sees, is left out as well. On DBT, real-time signals do not reach
722/// Detcore's signal path today (<https://github.com/rrnewton/hermit/issues/4192>).
723fn signal_default_action_ends_the_process(signal: SigWrapper) -> bool {
724    !matches!(
725        signal.raw(),
726        libc::SIGCHLD
727            | libc::SIGCONT
728            | libc::SIGURG
729            | libc::SIGWINCH
730            | libc::SIGSTOP
731            | libc::SIGTSTP
732            | libc::SIGTTIN
733            | libc::SIGTTOU
734            | libc::SIGKILL
735    )
736}
737
738fn signal_has_uncatchable_default_disposition(signal: SigWrapper) -> bool {
739    matches!(signal.raw(), libc::SIGKILL | libc::SIGSTOP)
740}
741
742pub(super) async fn wait_signal_disposition<G, T>(
743    guest: &mut G,
744    status: ResumeStatus,
745    guest_signal_mask: &KernelSigset,
746    action_addr: AddrMut<'_, KernelSigaction>,
747    inspect_action: bool,
748) -> Result<Option<WaitSignalDisposition>, Error>
749where
750    G: Guest<Detcore<T>>,
751    T: RecordOrReplay,
752{
753    let ResumeStatus::Signaled(signals) = status else {
754        return Ok(None);
755    };
756    let Some(mut signals) = signals else {
757        return Ok(Some(WaitSignalDisposition::Interrupt));
758    };
759    signals.sort_by_key(|signal| signal.raw());
760    for signal in signals {
761        if signal_is_blocked(guest_signal_mask, signal) {
762            continue;
763        }
764        if signal_has_uncatchable_default_disposition(signal) {
765            return Ok(Some(WaitSignalDisposition::Interrupt));
766        }
767        if !inspect_action {
768            return Ok(Some(WaitSignalDisposition::Interrupt));
769        }
770        let call = syscalls::RtSigaction::new()
771            .with_signum(signal.raw())
772            .with_action(None)
773            .with_old_action(Some(action_addr.cast()))
774            .with_sigsetsize(std::mem::size_of::<u64>());
775        guest.inject_with_retry(call).await?;
776        let action: KernelSigaction = guest.memory().read_value(action_addr)?;
777        if action.handler == libc::SIG_IGN as u64
778            || action.handler == libc::SIG_DFL as u64
779                && signal_default_disposition_does_not_interrupt_child_wait(signal)
780        {
781            continue;
782        }
783        return Ok(Some(
784            if action.handler != libc::SIG_DFL as u64 && action.flags & libc::SA_RESTART as u64 != 0
785            {
786                WaitSignalDisposition::Restart
787            } else {
788                WaitSignalDisposition::Interrupt
789            },
790        ));
791    }
792    Ok(None)
793}
794
795/// The signals a precise futex wait holds in its own check after a wake:
796/// `SIGCHLD` and every signal a host-timed source can post (`host_timed`),
797/// except a signal the scheduler committed to it at the wake (`committed`)
798/// that no host-timed source can post too
799/// (https://github.com/rrnewton/hermit/issues/4005).
800pub(crate) fn futex_wait_held_after_wake(
801    host_timed: KernelSigset,
802    committed: KernelSigset,
803) -> KernelSigset {
804    (kernel_sigset_bit(libc::SIGCHLD) | host_timed) & !(committed & !host_timed)
805}
806
807/// The signals that end a precise futex wait at its own check: those pending
808/// and interrupting it (`interrupting`) that it does not hold (`held`), or,
809/// when there are none, a guest's thread-directed `SIGCHLD` in its private
810/// queue that the schedule recorded (`PrivatePending`). Such a copy may have
811/// been sent before this wait parked, and the drain that ends a parked wait for
812/// it never saw this wait, so only this check can. `/proc` cannot tell it from
813/// a copy a host-timed source posted, so its bit only prompts the question
814/// (https://github.com/rrnewton/hermit/issues/4132).
815///
816/// A pending copy Linux discarded when it was sent does not end the wait,
817/// whatever handler exists now: the scheduler's record of such copies
818/// (`DiscardedSignalControl::Bits`) is subtracted, per queue, from every
819/// signal (`without_discarded`,
820/// <https://github.com/rrnewton/hermit/issues/4293>).
821pub(crate) async fn futex_wait_pending_signals<G, T>(
822    guest: &mut G,
823    state: &KernelSignalState,
824    interrupting: KernelSigset,
825    held: KernelSigset,
826    host_timed: KernelSigset,
827    committed: KernelSigset,
828) -> KernelSigset
829where
830    G: Guest<Detcore<T>>,
831    T: RecordOrReplay,
832{
833    let pending = without_discarded(guest, state, interrupting & !held, committed).await;
834    let sigchld = kernel_sigset_bit(libc::SIGCHLD) & !host_timed;
835    if pending == 0
836        && interrupting & state.thread_pending & held & sigchld != 0
837        && matches!(
838            crate::tool_global::child_exit_sigchld(
839                guest,
840                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::PrivatePending,
841            )
842            .await,
843            crate::scheduler::child_exit_sigchld::ChildExitSigchldAnswer::Placed(true)
844        )
845    {
846        return sigchld;
847    }
848    pending
849}
850
851/// `pending`, a set of this thread's pending signals, without each one whose
852/// only pending copies Linux discarded when they were sent, as the scheduler
853/// recorded them (`scheduler::discarded_at_send`). Asks the scheduler only
854/// when such a signal could be there.
855///
856/// No signal is exempt, not even one the wake's answer names: that answer
857/// carries the drain's batch too, whose copy a sender may have flushed
858/// (`SIG_IGN`) and sent again, discarded, before this check; Linux then has
859/// no copy to deliver (the Claude re-check of the R2b-1 design, R4-1,
860/// https://github.com/rrnewton/hermit/issues/4273). A copy the scheduler
861/// itself sent kept clears its bit, so applying the record to it changes
862/// nothing. `committed` is kept for the callers' hold and is not used here.
863pub(crate) async fn without_discarded<G, T>(
864    guest: &mut G,
865    state: &KernelSignalState,
866    pending: KernelSigset,
867    committed: KernelSigset,
868) -> KernelSigset
869where
870    G: Guest<Detcore<T>>,
871    T: RecordOrReplay,
872{
873    use crate::scheduler::discarded_at_send::DiscardedSignalAnswer;
874    use crate::scheduler::discarded_at_send::DiscardedSignalControl;
875    use crate::scheduler::discarded_at_send::STANDARD_SIGNALS;
876    if pending & STANDARD_SIGNALS == 0
877        || !crate::scheduler::discarded_at_send::records(guest.config())
878    {
879        return pending;
880    }
881    let DiscardedSignalAnswer::Bits { thread, process } =
882        crate::tool_global::discarded_signal(guest, DiscardedSignalControl::Bits).await
883    else {
884        return pending;
885    };
886    with_kept_copies(state, thread, process, pending, committed)
887}
888
889/// `pending` without each signal whose only pending copies the record marks
890/// as discarded at send (`thread` for the thread's queue, `process` for the
891/// shared queue). The pure part of `without_discarded`. No signal is exempt,
892/// not even one in `committed`, the set the wake's answer names, which can
893/// hold a drain batch's copy that was flushed and sent again, discarded
894/// (R4-1 of the R2b-1 design re-checks,
895/// <https://github.com/rrnewton/hermit/issues/4273>).
896pub(crate) fn with_kept_copies(
897    state: &KernelSignalState,
898    thread: u64,
899    process: u64,
900    pending: KernelSigset,
901    committed: KernelSigset,
902) -> KernelSigset {
903    let _ = committed;
904    let kept = (state.thread_pending & !thread) | (state.shared_pending & !process);
905    pending & kept
906}
907
908/// The one-bit kernel sigset for `raw_signal` (1-based), or 0 when out of range.
909pub(crate) fn kernel_sigset_bit(raw_signal: i32) -> KernelSigset {
910    if (1..=KernelSigset::BITS as i32).contains(&raw_signal) {
911        1_u64 << (raw_signal as u32 - 1)
912    } else {
913        0
914    }
915}
916
917/// The exit signal that a child created by this clone-family call sends to
918/// the calling process when it exits, at a moment set by host timing, as a
919/// kernel sigset; 0 when there is none to hold. Linux sends a child's exit
920/// signal to the process that created it. A thread (`CLONE_THREAD`) sends
921/// none. SIGCHLD is already held in every gated wait. A `CLONE_PARENT` child
922/// sends the caller's own exit signal to the caller's parent instead, and that
923/// signal is SIGCHLD or was recorded for that parent when it created the
924/// caller's process (a reparent to another process resets it to SIGCHLD).
925pub(crate) fn clone_host_timed_signals(
926    flags: CloneFlags,
927    exit_signal: libc::c_int,
928) -> KernelSigset {
929    if flags.intersects(CloneFlags::CLONE_THREAD | CloneFlags::CLONE_PARENT)
930        || exit_signal == libc::SIGCHLD
931    {
932        0
933    } else {
934        kernel_sigset_bit(exit_signal)
935    }
936}
937
938/// One thread's signal state as the kernel reports it in
939/// `/proc/<pid>/task/<tid>/status`.
940///
941/// The kernel is the authority for a guest thread's mask, dispositions, and
942/// pending signals on backends that run the guest as real host threads. Reading
943/// the state has no effect on the guest, unlike a probe syscall around which a
944/// signal can be dequeued and held by the backend
945/// (https://github.com/rrnewton/hermit/issues/3146).
946#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
947pub(crate) struct KernelSignalState {
948    /// Signals pending for the thread or its whole thread group (`SigPnd | ShdPnd`).
949    pub(crate) pending: KernelSigset,
950    /// Signals pending on the thread's private queue (`SigPnd`).
951    pub(crate) thread_pending: KernelSigset,
952    /// Signals pending on the thread group's shared queue (`ShdPnd`).
953    pub(crate) shared_pending: KernelSigset,
954    /// The thread's current signal mask (`SigBlk`).
955    pub(crate) blocked: KernelSigset,
956    /// Signals whose disposition is `SIG_IGN` (`SigIgn`).
957    pub(crate) ignored: KernelSigset,
958    /// Signals with a handler installed (`SigCgt`).
959    pub(crate) caught: KernelSigset,
960}
961
962/// [`KernelSignalState::default_action_ends_process`] given only the
963/// thread's ignored and caught sets, from wherever they come (the kernel's
964/// `/proc` view or Detcore's copy, `signal_shadow::copied_dispositions`).
965pub(crate) fn default_action_ends_process(
966    ignored: KernelSigset,
967    caught: KernelSigset,
968    signal: i32,
969) -> bool {
970    let bit = kernel_sigset_bit(signal);
971    let stops_or_continues = [
972        libc::SIGSTOP,
973        libc::SIGTSTP,
974        libc::SIGTTIN,
975        libc::SIGTTOU,
976        libc::SIGCONT,
977    ]
978    .into_iter()
979    .fold(0, |set, signal| set | kernel_sigset_bit(signal));
980    signal == libc::SIGKILL
981        || ((ignored | caught | default_ignored_signals() | stops_or_continues) & bit) == 0
982}
983
984/// The signals a process with dispositions `ignored` and `caught` discards
985/// when they are generated and unblocked: those set to `SIG_IGN`, and the
986/// default-ignored ones with no handler (`sig_task_ignored`).
987pub(crate) fn ignored_at_generation(ignored: KernelSigset, caught: KernelSigset) -> KernelSigset {
988    ignored | (default_ignored_signals() & !caught)
989}
990
991impl KernelSignalState {
992    /// Parse the five signal lines of a `/proc/<pid>/task/<tid>/status` file.
993    pub(crate) fn parse(status: &str) -> Option<Self> {
994        let mut thread_pending = None;
995        let mut shared_pending = None;
996        let mut state = KernelSignalState::default();
997        let mut blocked = None;
998        let mut ignored = None;
999        let mut caught = None;
1000        for line in status.lines() {
1001            let Some((key, value)) = line.split_once(':') else {
1002                continue;
1003            };
1004            let slot = match key {
1005                "SigPnd" => &mut thread_pending,
1006                "ShdPnd" => &mut shared_pending,
1007                "SigBlk" => &mut blocked,
1008                "SigIgn" => &mut ignored,
1009                "SigCgt" => &mut caught,
1010                _ => continue,
1011            };
1012            *slot = Some(KernelSigset::from_str_radix(value.trim(), 16).ok()?);
1013        }
1014        state.thread_pending = thread_pending?;
1015        state.shared_pending = shared_pending?;
1016        state.pending = state.thread_pending | state.shared_pending;
1017        state.blocked = blocked?;
1018        state.ignored = ignored?;
1019        state.caught = caught?;
1020        Some(state)
1021    }
1022
1023    /// Signals whose delivery, while unblocked in `mask`, ends a blocking wait: a
1024    /// caught signal runs its handler, and a `SIG_DFL` signal terminates, dumps
1025    /// core, or stops the process. Ignored signals and the default-ignored
1026    /// `SIGCHLD`, `SIGCONT`, `SIGURG`, and `SIGWINCH` do not, and neither does the
1027    /// backend's own preemption signal.
1028    pub(crate) fn interrupting(&self, mask: KernelSigset) -> KernelSigset {
1029        let default_action = !(self.ignored | self.caught);
1030        (self.caught | (default_action & !default_ignored_signals()))
1031            & !mask
1032            & !kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32)
1033    }
1034
1035    /// Signals Linux discards when they are generated while unblocked: those
1036    /// set to `SIG_IGN`, and the default-ignored `SIGCHLD`, `SIGCONT`, `SIGURG`
1037    /// and `SIGWINCH` while they have no handler (`sig_task_ignored`). A blocked
1038    /// signal is never discarded, since its disposition may change before it is
1039    /// unblocked. Under ptrace the kernel queues even these for the tracer, so
1040    /// the pending set alone does not show the discard.
1041    pub(crate) fn discarded_at_generation(&self) -> KernelSigset {
1042        self.ignored_at_generation() & !self.blocked
1043    }
1044
1045    /// The signals [`discarded_at_generation`](Self::discarded_at_generation)
1046    /// names, before the mask: those set to `SIG_IGN`, and the default-ignored
1047    /// ones with no handler. A caller that knows a better mask than `SigBlk`
1048    /// (`scheduler::discarded_at_send`) applies its own.
1049    pub(crate) fn ignored_at_generation(&self) -> KernelSigset {
1050        ignored_at_generation(self.ignored, self.caught)
1051    }
1052
1053    /// Whether delivering `signal` now ends the process: its disposition is
1054    /// `SIG_DFL` and its default action terminates or dumps core, not ignores,
1055    /// stops or continues. `SIGKILL` always does.
1056    pub(crate) fn default_action_ends_process(&self, signal: i32) -> bool {
1057        default_action_ends_process(self.ignored, self.caught, signal)
1058    }
1059
1060    /// The job-control stop signals `SIGTSTP`, `SIGTTIN`, and `SIGTTOU` whose
1061    /// disposition is still `SIG_DFL`.
1062    ///
1063    /// Linux does not stop a process for one of these when its process group is
1064    /// orphaned: `get_signal` discards the signal (`is_current_pgrp_orphaned`),
1065    /// and a wait it reached restarts as if no signal had arrived. Whether a
1066    /// group is orphaned depends on the parents and sessions of every process in
1067    /// it, which Detcore does not track.
1068    pub(crate) fn default_job_control_stops(&self) -> KernelSigset {
1069        [libc::SIGTSTP, libc::SIGTTIN, libc::SIGTTOU]
1070            .into_iter()
1071            .fold(0, |set, signal| set | kernel_sigset_bit(signal))
1072            & !(self.ignored | self.caught)
1073    }
1074
1075    /// The signals that end a blocking wait under the guest's `mask`: those
1076    /// [`interrupting`](Self::interrupting) names, without the default job-control
1077    /// stops ([`default_job_control_stops`](Self::default_job_control_stops)) when
1078    /// `defers_default_stops` is set.
1079    ///
1080    /// A wait sets it when Linux's restart of the call keeps its deadline
1081    /// (`NonblockableSyscall::restart_keeps_deadline`): a `poll` with a positive
1082    /// timeout, and a timed futex wait. Detcore keeps that deadline for the
1083    /// kernel's restart only when the wait ends with `ERESTART_RESTARTBLOCK`, which
1084    /// a stop signal the backend holds does not (`held_signal_restart_errno`), so
1085    /// ending such a wait for a default stop that Linux discards in an orphaned
1086    /// process group could restart it with a fresh timeout, and it would return
1087    /// late. Left alone, the wait keeps its deadline, as on hermit main, and a stop
1088    /// that Linux does not discard takes effect when the call returns rather than
1089    /// when the signal arrives (https://github.com/rrnewton/hermit/issues/3358).
1090    /// `SIGSTOP`, a caught stop signal, and a fatal one still end the wait.
1091    pub(crate) fn interrupting_wait(
1092        &self,
1093        mask: KernelSigset,
1094        defers_default_stops: bool,
1095    ) -> KernelSigset {
1096        let interrupting = self.interrupting(mask);
1097        if defers_default_stops {
1098            interrupting & !self.default_job_control_stops()
1099        } else {
1100            interrupting
1101        }
1102    }
1103
1104    /// Pending signals that would end a blocking wait under the guest's `mask`
1105    /// (see [`interrupting_wait`](Self::interrupting_wait)).
1106    pub(crate) fn pending_interrupting(
1107        &self,
1108        mask: KernelSigset,
1109        defers_default_stops: bool,
1110    ) -> KernelSigset {
1111        self.pending & self.interrupting_wait(mask, defers_default_stops)
1112    }
1113
1114    /// The signal the kernel dequeues next for this thread while `mask` is
1115    /// blocked, and the queue it comes from, or `None` if no unblocked signal is
1116    /// pending.
1117    ///
1118    /// As in `dequeue_signal` and `next_signal` (`kernel/signal.c`), the thread's
1119    /// private queue goes before the thread group's shared queue, and within a
1120    /// queue a synchronous signal (`SIGSEGV`, `SIGBUS`, `SIGILL`, `SIGTRAP`,
1121    /// `SIGFPE`, `SIGSYS`) goes before the lowest-numbered other one.
1122    pub(crate) fn next_dequeued(&self, mask: KernelSigset) -> Option<(i32, SignalQueue)> {
1123        let synchronous = SYNCHRONOUS_SIGNALS
1124            .into_iter()
1125            .fold(0, |set, signal| set | kernel_sigset_bit(signal));
1126        let first = |queued: KernelSigset| {
1127            let deliverable = queued & !mask;
1128            let preferred = if deliverable & synchronous != 0 {
1129                deliverable & synchronous
1130            } else {
1131                deliverable
1132            };
1133            (preferred != 0).then(|| preferred.trailing_zeros() as i32 + 1)
1134        };
1135        first(self.thread_pending)
1136            .map(|signal| (signal, SignalQueue::Thread))
1137            .or_else(|| first(self.shared_pending).map(|signal| (signal, SignalQueue::Shared)))
1138    }
1139
1140    /// The signals pending on `queue`.
1141    pub(crate) fn queued(&self, queue: SignalQueue) -> KernelSigset {
1142        match queue {
1143            SignalQueue::Thread => self.thread_pending,
1144            SignalQueue::Shared => self.shared_pending,
1145        }
1146    }
1147}
1148
1149/// The signals whose default action ignores them.
1150fn default_ignored_signals() -> KernelSigset {
1151    [libc::SIGCHLD, libc::SIGCONT, libc::SIGURG, libc::SIGWINCH]
1152        .into_iter()
1153        .fold(0, |set, signal| set | kernel_sigset_bit(signal))
1154}
1155
1156/// The signals an instruction raises, which the kernel dequeues before any other
1157/// signal on the same queue (`SYNCHRONOUS_MASK` in `kernel/signal.c`).
1158const SYNCHRONOUS_SIGNALS: [i32; 6] = [
1159    libc::SIGSEGV,
1160    libc::SIGBUS,
1161    libc::SIGILL,
1162    libc::SIGTRAP,
1163    libc::SIGFPE,
1164    libc::SIGSYS,
1165];
1166
1167/// One of a thread's two queues of pending signals.
1168#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1169pub(crate) enum SignalQueue {
1170    /// The thread's private queue (`SigPnd`).
1171    Thread,
1172    /// The thread group's shared queue (`ShdPnd`).
1173    Shared,
1174}
1175
1176/// Set once per Hermit process, by [`refuse_host_signal_state_reads`], when
1177/// the backend's guest thread IDs do not name host tasks (KVM): a host
1178/// `/proc/<pid>/task/<tid>/status` would then describe an unrelated host task,
1179/// if any, chosen by host thread-ID allocation, so its signal state must never
1180/// decide a guest-visible outcome. Every read that exists today is gated off on
1181/// such a backend by a capability (`models_signal_targets`,
1182/// `supports_blocked_wait_signal_interruption` or one of its named readings in
1183/// `detcore_model::bundled_signal_facts`, `reports_child_exit_publication`, a
1184/// nested PID namespace, or the guard in
1185/// `restartable_internal_io_interrupting_signals`); this latch is the backstop
1186/// for a future path that misses its gate.
1187#[cfg(not(test))]
1188static HOST_SIGNAL_STATE_READS_REFUSED: std::sync::atomic::AtomicBool =
1189    std::sync::atomic::AtomicBool::new(false);
1190
1191#[cfg(test)]
1192thread_local! {
1193    /// The latch for unit tests, per test thread, so that tests reading their
1194    /// own real `/proc` state run beside one that sets it.
1195    static HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST: std::cell::Cell<bool> =
1196        const { std::cell::Cell::new(false) };
1197}
1198
1199/// Whether a backend with `backend`'s capabilities forbids host `/proc` signal
1200/// state reads for its guest threads: exactly when its guest thread IDs do not
1201/// name host tasks (`procfs_inode::guest_tids_name_host_tasks`).
1202pub(crate) fn refuses_host_signal_state_reads(backend: &BackendCapabilities) -> bool {
1203    !crate::procfs_inode::guest_tids_name_host_tasks(backend, None)
1204}
1205
1206/// Latch the refusal for this process when `backend` forbids host `/proc`
1207/// signal state reads ([`refuses_host_signal_state_reads`]). Called once, when
1208/// Detcore's global state is created for a run.
1209pub(crate) fn refuse_host_signal_state_reads(backend: &BackendCapabilities) {
1210    if !refuses_host_signal_state_reads(backend) {
1211        return;
1212    }
1213    #[cfg(not(test))]
1214    HOST_SIGNAL_STATE_READS_REFUSED.store(true, std::sync::atomic::Ordering::Relaxed);
1215    #[cfg(test)]
1216    HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST.with(|refused| refused.set(true));
1217}
1218
1219/// Whether host `/proc` signal state reads are refused in this process
1220/// ([`refuse_host_signal_state_reads`]).
1221pub(crate) fn host_signal_state_reads_refused() -> bool {
1222    #[cfg(not(test))]
1223    {
1224        HOST_SIGNAL_STATE_READS_REFUSED.load(std::sync::atomic::Ordering::Relaxed)
1225    }
1226    #[cfg(test)]
1227    {
1228        HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST.with(|refused| refused.get())
1229    }
1230}
1231
1232/// Read `tid`'s signal state from the kernel.
1233///
1234/// On a backend whose guest thread IDs do not name host tasks
1235/// ([`host_signal_state_reads_refused`]) the read is refused with `ENOSYS`
1236/// before it reaches `/proc`: a caller that needs the state ends the run by
1237/// name (`BlockedWaitSignalError::StateUnreadable`), and one that treats an
1238/// unreadable state as unknown keeps its documented fallback. Either way no
1239/// unrelated host task's state reaches a decision.
1240pub(crate) fn read_kernel_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Errno> {
1241    #[cfg(test)]
1242    if let Some(result) = signal_state_read_seam::scripted(pid, tid) {
1243        return result;
1244    }
1245    if host_signal_state_reads_refused() {
1246        static REPORTED: std::sync::Once = std::sync::Once::new();
1247        REPORTED.call_once(|| {
1248            error!(
1249                "refused a host /proc signal state read of guest thread {} (process {}): this \
1250                 backend's guest thread IDs do not name host tasks",
1251                tid.as_raw(),
1252                pid.as_raw()
1253            );
1254        });
1255        return Err(Errno::ENOSYS);
1256    }
1257    let path = format!("/proc/{}/task/{}/status", pid.as_raw(), tid.as_raw());
1258    let status = std::fs::read_to_string(path).map_err(|_| Errno::ESRCH)?;
1259    KernelSignalState::parse(&status).ok_or(Errno::EIO)
1260}
1261
1262/// Why a blocked wait ended the run instead of returning to the guest
1263/// (https://github.com/rrnewton/hermit/issues/3146). A wait call cannot return
1264/// the underlying error natively, and resuming the guest after the second
1265/// failure would leave every blockable signal blocked in it.
1266#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1267pub(crate) enum BlockedWaitSignalError {
1268    /// The thread still exists, but its signal state could not be read from
1269    /// `/proc` (`errno` is `ESRCH` for an unreadable file, `EIO` for one that
1270    /// does not parse).
1271    StateUnreadable { pid: Pid, tid: Pid, errno: Errno },
1272    /// The guest's own signal mask could not be put back after the wait blocked
1273    /// every signal. `last_error` is the last injected call's error.
1274    MaskNotRestored {
1275        pid: Pid,
1276        tid: Pid,
1277        attempts: usize,
1278        last_error: Option<Errno>,
1279    },
1280}
1281
1282impl std::fmt::Display for BlockedWaitSignalError {
1283    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1284        match self {
1285            Self::StateUnreadable { pid, tid, errno } => write!(
1286                f,
1287                "cannot read the signal state of guest thread {tid} (process {pid}) from \
1288                 /proc while it waits: {errno}"
1289            ),
1290            Self::MaskNotRestored {
1291                pid,
1292                tid,
1293                attempts,
1294                last_error,
1295            } => {
1296                write!(
1297                    f,
1298                    "cannot restore the signal mask of guest thread {tid} (process {pid}) \
1299                     after a blocked wait ({attempts} attempts"
1300                )?;
1301                if let Some(errno) = last_error {
1302                    write!(f, ", last error {errno}")?;
1303                }
1304                f.write_str("); it would resume with every signal blocked")
1305            }
1306        }
1307    }
1308}
1309
1310impl std::error::Error for BlockedWaitSignalError {}
1311
1312/// Whether thread `tid` of process `pid` no longer exists.
1313pub(crate) fn guest_thread_is_gone(pid: Pid, tid: Pid) -> bool {
1314    // SAFETY: signal 0 only checks that the thread exists and may be signalled.
1315    let result = unsafe { libc::syscall(libc::SYS_tgkill, pid.as_raw(), tid.as_raw(), 0) };
1316    result == -1 && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH)
1317}
1318
1319/// Read `tid`'s signal state when `pid` may not be its thread group.
1320///
1321/// Reverie can report the creating process's pid for a process that a raw
1322/// `clone` without `CLONE_THREAD` created, so `/proc/<pid>/task/<tid>` does not
1323/// exist although the thread does. `/proc/<tid>/task/<tid>` names any live
1324/// thread, its own thread group's leader or not, so it is read before the
1325/// thread is taken to be gone (https://github.com/rrnewton/hermit/issues/3982).
1326pub(crate) fn read_thread_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Errno> {
1327    read_kernel_signal_state(pid, tid).or_else(|error| {
1328        if pid == tid {
1329            Err(error)
1330        } else {
1331            read_kernel_signal_state(tid, tid)
1332        }
1333    })
1334}
1335
1336/// Whether thread `tid` no longer exists, when `pid` may not be its thread
1337/// group ([`read_thread_signal_state`]). `tkill` names the thread without a
1338/// thread group, so a live thread under a wrong `pid` is not taken to be gone.
1339pub(crate) fn thread_is_gone(pid: Pid, tid: Pid) -> bool {
1340    if !guest_thread_is_gone(pid, tid) {
1341        return false;
1342    }
1343    // SAFETY: signal 0 only checks that the thread exists and may be signalled.
1344    let result = unsafe { libc::syscall(libc::SYS_tkill, tid.as_raw(), 0) };
1345    result == -1 && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH)
1346}
1347
1348/// [`read_wait_signal_state`] for a thread whose reported `pid` may not be its
1349/// thread group ([`read_thread_signal_state`]).
1350pub(crate) fn read_thread_wait_signal_state(
1351    pid: Pid,
1352    tid: Pid,
1353) -> Result<KernelSignalState, Error> {
1354    match read_thread_signal_state(pid, tid) {
1355        Ok(state) => Ok(state),
1356        Err(_) if thread_is_gone(pid, tid) => Err(Errno::ERESTARTNOINTR.into()),
1357        Err(errno) => Err(Error::Tool(anyhow::Error::new(
1358            BlockedWaitSignalError::StateUnreadable { pid, tid, errno },
1359        ))),
1360    }
1361}
1362
1363/// Read the signal state of `tid`, which is stopped inside a blocked wait.
1364///
1365/// The read's own error never reaches the guest, because no wait call returns
1366/// `ESRCH` or `EIO` for it. If the thread no longer exists (it was killed while
1367/// it waited), the call ends with `ERESTARTNOINTR`, which no thread observes.
1368/// Otherwise the run ends with [`BlockedWaitSignalError::StateUnreadable`].
1369pub(crate) fn read_wait_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Error> {
1370    match read_kernel_signal_state(pid, tid) {
1371        Ok(state) => Ok(state),
1372        Err(_) if guest_thread_is_gone(pid, tid) => Err(Errno::ERESTARTNOINTR.into()),
1373        Err(errno) => Err(Error::Tool(anyhow::Error::new(
1374            BlockedWaitSignalError::StateUnreadable { pid, tid, errno },
1375        ))),
1376    }
1377}
1378
1379/// A test seam in front of the `/proc` read in [`read_kernel_signal_state`].
1380#[cfg(test)]
1381pub(crate) mod signal_state_read_seam {
1382    use std::cell::RefCell;
1383
1384    use reverie::Pid;
1385    use reverie::syscalls::Errno;
1386
1387    use super::KernelSignalState;
1388
1389    type Script = Box<dyn FnMut(Pid, Pid) -> Option<Result<KernelSignalState, Errno>>>;
1390
1391    thread_local! {
1392        static SCRIPT: RefCell<Option<Script>> = const { RefCell::new(None) };
1393    }
1394
1395    /// Removes the installed script when dropped.
1396    pub(crate) struct Installed(());
1397
1398    impl Drop for Installed {
1399        fn drop(&mut self) {
1400            SCRIPT.with(|script| script.borrow_mut().take());
1401        }
1402    }
1403
1404    /// Answer this thread's reads with `script`; `None` falls through to `/proc`.
1405    pub(crate) fn install(
1406        script: impl FnMut(Pid, Pid) -> Option<Result<KernelSignalState, Errno>> + 'static,
1407    ) -> Installed {
1408        SCRIPT.with(|slot| *slot.borrow_mut() = Some(Box::new(script)));
1409        Installed(())
1410    }
1411
1412    pub(super) fn scripted(pid: Pid, tid: Pid) -> Option<Result<KernelSignalState, Errno>> {
1413        SCRIPT.with(|slot| {
1414            slot.borrow_mut()
1415                .as_mut()
1416                .and_then(|script| script(pid, tid))
1417        })
1418    }
1419}
1420
1421pub(super) fn blocked_signal_mask() -> KernelSigset {
1422    // Preserve libc's definition of the blockable set (notably its reserved
1423    // NPTL signals) while converting the result to the kernel's one-word ABI.
1424    let mut libc_mask: libc::sigset_t = unsafe { std::mem::zeroed() };
1425    unsafe {
1426        libc::sigfillset(&mut libc_mask);
1427        libc::sigdelset(&mut libc_mask, reverie::PERF_EVENT_SIGNAL as i32);
1428    }
1429    (1..=KernelSigset::BITS as i32).fold(0, |mask, raw_signal| {
1430        if unsafe { libc::sigismember(&libc_mask, raw_signal) } == 1 {
1431            mask | (1_u64 << (raw_signal as u32 - 1))
1432        } else {
1433            mask
1434        }
1435    })
1436}
1437
1438pub(super) async fn block_signals_for_disposition<G, T>(
1439    guest: &mut G,
1440    blocked_mask_addr: Addr<'_, KernelSigset>,
1441    old_mask_addr: AddrMut<'_, KernelSigset>,
1442) -> Result<KernelSigset, Error>
1443where
1444    G: Guest<Detcore<T>>,
1445    T: RecordOrReplay,
1446{
1447    let block_signals = syscalls::RtSigprocmask::new()
1448        .with_how(libc::SIG_SETMASK)
1449        .with_set(
1450            (!guest
1451                .config()
1452                .backend
1453                .requires_thread_directed_process_signals)
1454                .then_some(blocked_mask_addr.cast()),
1455        )
1456        .with_oldset(Some(old_mask_addr.cast()))
1457        .with_sigsetsize(KERNEL_SIGSET_SIZE);
1458    guest.inject_with_retry(block_signals).await?;
1459    let guest_mask: KernelSigset = guest.memory().read_value(old_mask_addr)?;
1460    if guest.config().backend.reports_child_exit_publication
1461        || crate::scheduler::discarded_at_send::records(guest.config())
1462    {
1463        // While the private mask is installed, the kernel reports Detcore's
1464        // mask for this thread; the scheduler's child-exit classification and
1465        // its record of copies Linux discarded at send must read the guest's
1466        // own (the Claude re-check of the R2b-1 design, R4-3).
1467        crate::tool_global::set_saved_guest_sigmask(guest, Some(guest_mask)).await;
1468    }
1469    Ok(guest_mask)
1470}
1471
1472pub(super) async fn restore_signals_after_disposition<G, T>(
1473    guest: &mut G,
1474    old_mask_addr: AddrMut<'_, KernelSigset>,
1475) -> Result<(), Error>
1476where
1477    G: Guest<Detcore<T>>,
1478    T: RecordOrReplay,
1479{
1480    if !guest
1481        .config()
1482        .backend
1483        .requires_thread_directed_process_signals
1484    {
1485        let old_mask: Addr<'_, KernelSigset> = old_mask_addr.into();
1486        let restore_signals = syscalls::RtSigprocmask::new()
1487            .with_how(libc::SIG_SETMASK)
1488            .with_set(Some(old_mask.cast()))
1489            .with_oldset(None)
1490            .with_sigsetsize(KERNEL_SIGSET_SIZE);
1491        guest.inject_with_retry(restore_signals).await?;
1492    }
1493    if guest.config().backend.reports_child_exit_publication
1494        || crate::scheduler::discarded_at_send::records(guest.config())
1495    {
1496        crate::tool_global::set_saved_guest_sigmask(guest, None).await;
1497    }
1498    Ok(())
1499}
1500
1501async fn interrupted_child_wait_result<G, T, S>(
1502    guest: &mut G,
1503    call: S,
1504    disposition: WaitSignalDisposition,
1505) -> Result<i64, Error>
1506where
1507    G: Guest<Detcore<T>>,
1508    T: RecordOrReplay,
1509    S: SyscallInfo,
1510{
1511    if !guest
1512        .config()
1513        .backend
1514        .requires_thread_directed_process_signals
1515    {
1516        return Err(Errno::ERESTARTSYS.into());
1517    }
1518    if disposition == WaitSignalDisposition::Interrupt {
1519        return Err(Errno::EINTR.into());
1520    }
1521
1522    guest.tail_inject(call).await
1523}
1524
1525fn snapshot_process_group(pid: Pid) -> Result<libc::pid_t, Errno> {
1526    let pgrp = Process::new(pid.as_raw())
1527        .and_then(|process| process.stat())
1528        .map(|stat| stat.pgrp)
1529        .map_err(|_| Errno::ESRCH)?;
1530    if pgrp == 0 {
1531        Err(Errno::EOPNOTSUPP)
1532    } else {
1533        Ok(pgrp)
1534    }
1535}
1536
1537fn guest_fd_status_flags(pid: Pid, fd: libc::c_int) -> Result<libc::c_int, Errno> {
1538    let path = format!("/proc/{}/fdinfo/{}", pid.as_raw(), fd);
1539    let contents = std::fs::read_to_string(path).map_err(|_| Errno::EBADF)?;
1540    let flags = contents
1541        .lines()
1542        .find_map(|line| line.strip_prefix("flags:"))
1543        .map(str::trim)
1544        .ok_or(Errno::EINVAL)?;
1545    libc::c_int::from_str_radix(flags, 8).map_err(|_| Errno::EINVAL)
1546}
1547
1548#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1549enum FutexTimeout {
1550    Relative(u64),
1551    Absolute(LogicalTime),
1552}
1553
1554/// Linux's `timespec64_valid`, which `futex_init_timeout` applies: a negative
1555/// second count or a nanosecond count outside `0..1e9` is EINVAL. Any other
1556/// value is valid, however large.
1557fn futex_timespec_is_valid(timeout: Timespec) -> bool {
1558    timeout.tv_sec >= 0 && (0..1_000_000_000).contains(&timeout.tv_nsec)
1559}
1560
1561/// The largest futex timeout in nanoseconds: `timespec64_to_ktime` clamps a
1562/// valid timespec beyond it to `KTIME_MAX` rather than refusing it.
1563const FUTEX_KTIME_MAX_NANOS: u64 = i64::MAX as u64;
1564
1565fn parse_futex_timeout(futex_op: i32, timeout: Timespec) -> Result<FutexTimeout, Errno> {
1566    if !futex_timespec_is_valid(timeout) {
1567        return Err(Errno::EINVAL);
1568    }
1569    let seconds = timeout.tv_sec as u64;
1570    let nanoseconds = timeout.tv_nsec as u64;
1571    // `timespec64_to_ktime`: KTIME_MAX from KTIME_SEC_MAX seconds on.
1572    let timeout_nanos = if seconds >= FUTEX_KTIME_MAX_NANOS / 1_000_000_000 {
1573        FUTEX_KTIME_MAX_NANOS
1574    } else {
1575        seconds * 1_000_000_000 + nanoseconds
1576    };
1577    // Mask off FUTEX_PRIVATE_FLAG / FUTEX_CLOCK_REALTIME before matching the
1578    // command: FUTEX_WAIT_BITSET measures its timeout as an *absolute* deadline,
1579    // whereas plain FUTEX_WAIT uses a *relative* one. A private-flagged
1580    // FUTEX_WAIT_BITSET (e.g. 0x89) must still be recognized as the BITSET
1581    // command; comparing the raw op would misclassify it as relative and add
1582    // the absolute deadline to the current time (leaking the epoch).
1583    if futex_op & libc::FUTEX_CMD_MASK == libc::FUTEX_WAIT_BITSET {
1584        Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
1585            timeout_nanos,
1586        )))
1587    } else {
1588        Ok(FutexTimeout::Relative(timeout_nanos))
1589    }
1590}
1591
1592fn rebase_absolute_timeout(
1593    deadline: LogicalTime,
1594    clock_now: LogicalTime,
1595    logical_now: LogicalTime,
1596) -> LogicalTime {
1597    logical_now + Duration::from_nanos(deadline.as_nanos().saturating_sub(clock_now.as_nanos()))
1598}
1599
1600fn absolute_timeout_uses_host_clock(
1601    deadline: LogicalTime,
1602    host_clock_now: LogicalTime,
1603    logical_now: LogicalTime,
1604) -> bool {
1605    deadline.as_nanos().abs_diff(host_clock_now.as_nanos())
1606        < deadline.as_nanos().abs_diff(logical_now.as_nanos())
1607}
1608
1609/// Where a futex wait takes its deadline from.
1610#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1611pub(crate) enum FutexDeadline {
1612    /// The call's own timeout.
1613    FromCall,
1614    /// The deadline an interrupted timed futex wait kept for the kernel's restart
1615    /// (`RestartBlock`).
1616    Restart(Option<LogicalTime>),
1617}
1618
1619/// How a sequentialized `sched_yield` yields to the scheduler
1620/// ([`sched_yield_route`]).
1621#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1622enum SchedYieldRoute {
1623    /// A recorded chaos priority change point with a fresh random priority.
1624    ChaosReprioritize,
1625    /// A one-turn `SchedYield`, with the timeslice statistics reset.
1626    ReplayStrongYield,
1627    /// A `SchedYield` that the scheduler turns into a yield epoch.
1628    ChaosYieldEpoch,
1629    /// A `SleepUntil(0)` yield, granted at once.
1630    WeakYield,
1631    /// The end of the caller's timeslice, as at a timer expiry.
1632    EndTimeslice,
1633}
1634
1635/// Choose how a sequentialized `sched_yield` yields; it reads only the
1636/// configuration, so a record and its replay choose alike.
1637///
1638/// - In chaos mode, thread-interleaving diversity (and thus fairness) comes
1639///   from re-randomizing thread priorities at preemption-timer expirations.
1640///   When timer preemption is disabled (`--max-timeslice disabled`),
1641///   priorities are fixed at thread creation and never change, so a thread
1642///   that spins on sched_yield while holding the numerically-lowest priority
1643///   would starve every thread it waits on (GH #81). There sched_yield is an
1644///   explicit chaos reprioritization point, recorded for chaos replay.
1645/// - With the timer on, chaos still redraws a priority only when a slice
1646///   expires, which a sched_yield loop may never reach
1647///   (https://github.com/rrnewton/hermit/issues/4068). There sched_yield is a
1648///   `SchedYield`, which the scheduler turns into a yield epoch
1649///   (`Scheduler::requeue_after`): the caller keeps its band, and once it has
1650///   passed another runnable thread over more than
1651///   `PLAIN_YIELDS_BEFORE_EPOCH` times it is not selected again until a thread
1652///   that did not yield has had a turn. It changes no
1653///   priority, draws nothing from the chaos PRNG and consumes no recorded
1654///   preemption point, so a preemption replay under `--chaos` makes the same
1655///   decision. A schedule replay keeps the weak yield it always had, and so
1656///   does a backend that does not deliver the preemption timer
1657///   (`BackendCapabilities::delivers_preemption_timer_events`): there a thread handed the
1658///   turn that never makes a syscall would never give it back.
1659/// - `--sched-heuristic=random` also keeps the weak yield. It draws a uniform
1660///   pick among the queued threads at every turn, so a yielder cannot hold
1661///   the CPU from the thread it waits on, and an epoch would only force the
1662///   yielders into near-equal shares: on the fp-reduction chaos cell
1663///   (https://github.com/rrnewton/hermit/issues/4150) it cut the outcomes
1664///   over 32 seeds to fewer than the 7 of 8 classes the cell requires.
1665///   `StickyRandom` keeps its pick across turns, so it keeps the epoch.
1666fn sched_yield_route(cfg: &Config) -> SchedYieldRoute {
1667    if cfg.chaos && cfg.max_timeslice.is_none() {
1668        SchedYieldRoute::ChaosReprioritize
1669    } else if !cfg.chaos && cfg.replay_preemptions_from.is_some() {
1670        SchedYieldRoute::ReplayStrongYield
1671    } else if cfg.chaos
1672        && cfg.replay_schedule_from.is_none()
1673        && cfg.backend.delivers_preemption_timer_events
1674        && cfg.sched_heuristic != SchedHeuristic::Random
1675    {
1676        SchedYieldRoute::ChaosYieldEpoch
1677    } else if cfg.chaos || cfg.replay_schedule_from.is_some() {
1678        SchedYieldRoute::WeakYield
1679    } else {
1680        SchedYieldRoute::EndTimeslice
1681    }
1682}
1683
1684impl<T: RecordOrReplay> Detcore<T> {
1685    async fn futex_timeout_deadline<G: Guest<Self>>(
1686        &self,
1687        guest: &mut G,
1688        futex_flags: i32,
1689        timeout: Option<Addr<'_, Timespec>>,
1690    ) -> Result<Option<LogicalTime>, Error> {
1691        let Some(timeout) = timeout else {
1692            return Ok(None);
1693        };
1694        let timeout = parse_futex_timeout(futex_flags, guest.memory().read_value(timeout)?)?;
1695        match timeout {
1696            FutexTimeout::Relative(nanos) => {
1697                let now = thread_observe_time(guest).await;
1698                Ok(Some(now + Duration::from_nanos(nanos)))
1699            }
1700            FutexTimeout::Absolute(deadline)
1701                if self.cfg.virtualize_time
1702                    && !self.cfg.backend.guest_clock_reads_bypass_backend =>
1703            {
1704                Ok(Some(deadline))
1705            }
1706            FutexTimeout::Absolute(deadline) => {
1707                let clockid = if futex_flags & libc::FUTEX_CLOCK_REALTIME != 0 {
1708                    syscalls::ClockId::CLOCK_REALTIME
1709                } else {
1710                    syscalls::ClockId::CLOCK_MONOTONIC
1711                };
1712
1713                let mut stack = guest.stack().await;
1714                let clock_output = syscalls::TimespecMutPtr(stack.reserve());
1715                let _stack_guard = stack.commit()?;
1716                let clock_call = syscalls::ClockGettime::new()
1717                    .with_clockid(clockid)
1718                    .with_tp(Some(clock_output));
1719                if self.cfg.virtualize_time && self.cfg.backend.guest_clock_reads_bypass_backend {
1720                    // Read the same live host clock as a direct guest vDSO call. Replaying a
1721                    // recorded value here would compare this run's host-domain deadline with the
1722                    // previous run's clock and turn a short timeout into an arbitrary long one.
1723                    guest.inject(Syscall::from(clock_call)).await?;
1724                } else {
1725                    self.record_or_replay(guest, clock_call).await?;
1726                }
1727                let clock_now = match parse_futex_timeout(
1728                    libc::FUTEX_WAIT_BITSET,
1729                    guest.memory().read_value(clock_output.0)?,
1730                )? {
1731                    FutexTimeout::Absolute(time) => time,
1732                    FutexTimeout::Relative(_) => unreachable!(),
1733                };
1734                let logical_now = thread_observe_time(guest).await;
1735                if self.cfg.virtualize_time
1736                    && !absolute_timeout_uses_host_clock(deadline, clock_now, logical_now)
1737                {
1738                    return Ok(Some(deadline));
1739                }
1740                Ok(Some(rebase_absolute_timeout(
1741                    deadline,
1742                    clock_now,
1743                    logical_now,
1744                )))
1745            }
1746        }
1747    }
1748
1749    /// The deadline of a futex wait, from the call's timeout or from the record an
1750    /// interrupted wait kept for its restart (`FutexDeadline`).
1751    async fn futex_deadline<G: Guest<Self>>(
1752        &self,
1753        guest: &mut G,
1754        call: syscalls::Futex,
1755        deadline: FutexDeadline,
1756    ) -> Result<Option<LogicalTime>, Error> {
1757        match deadline {
1758            FutexDeadline::FromCall => {
1759                self.futex_timeout_deadline(guest, call.futex_op(), call.timeout())
1760                    .await
1761            }
1762            FutexDeadline::Restart(deadline) => Ok(deadline),
1763        }
1764    }
1765
1766    /// Promotes the open file descriptions whose model must stay one copy
1767    /// (random devices and timerfds, `ThreadState::promote_shared_open_files`)
1768    /// before this handler's native fork, process-copying clone or exec, on a
1769    /// backend whose tool runs inside the guest and whose runtime routes those
1770    /// operations through this handler (in-guest LiteInst). DBT runs them
1771    /// natively and its runtime promotes there; ptrace and KVM keep the one
1772    /// copy outside the guest. It runs inside the caller's turn, before the
1773    /// operation can expose a child or a new image
1774    /// (<https://github.com/rrnewton/hermit/issues/4381>).
1775    fn promote_before_native_lifecycle<G: Guest<Self>>(&self, guest: &G) {
1776        let backend = &guest.config().backend;
1777        if self.cfg.sequentialize_threads
1778            && backend.promotes_open_files_before_native_lifecycle
1779            && !crate::syscalls::timerfd::detcore_runs_outside_the_guest(backend)
1780        {
1781            guest.thread_state().promote_shared_open_files().expect(
1782                "could not publish shared open file descriptions before a native fork or exec",
1783            );
1784        }
1785    }
1786
1787    /// Clone, clone3, fork, vfork system calls
1788    pub async fn handle_clone_family<G: Guest<Self>>(
1789        &self,
1790        guest: &mut G,
1791        clone_family: syscalls::family::CloneFamily,
1792    ) -> Result<i64, Error> {
1793        if let syscalls::family::CloneFamily::Clone3(clone) = &clone_family
1794            && let Some(refusal) = self.clone3_set_tid_refusal(guest, clone).await
1795        {
1796            return refusal;
1797        }
1798        // clone3's `struct clone_args` is read field by field
1799        // (`clone3_field`): Reverie's whole-struct read fails for a valid
1800        // 64-byte one at the end of a mapping, which lost its flags, exit
1801        // signal and child tid address.
1802        let (flags, exit_signal, child_tid) = match &clone_family {
1803            syscalls::family::CloneFamily::Clone3(clone) => {
1804                let memory = guest.memory();
1805                (
1806                    clone3_field(&memory, clone, 0)
1807                        .map_or_else(CloneFlags::empty, CloneFlags::from_bits_truncate),
1808                    clone3_field(&memory, clone, 32).map_or(0, |signal| signal as libc::c_int),
1809                    clone3_field(&memory, clone, 16).map_or(0, |address| address as usize),
1810                )
1811            }
1812            syscalls::family::CloneFamily::Clone(clone) => (
1813                clone_family.flags(&guest.memory()),
1814                (clone.flags().bits() & 0xff) as libc::c_int,
1815                clone_family.child_tid(&guest.memory()),
1816            ),
1817            #[cfg(not(target_arch = "aarch64"))]
1818            _ => (
1819                clone_family.flags(&guest.memory()),
1820                libc::SIGCHLD,
1821                clone_family.child_tid(&guest.memory()),
1822            ),
1823        };
1824        let ctid = child_tid_clear_address(flags, child_tid);
1825        // Without sequentialized threads a sibling can run while this call
1826        // does, and rewrite the clone's arguments after they are read here or
1827        // the pidfd word before it is read back, so no pidfd is tracked then.
1828        let pidfd_address = guest
1829            .config()
1830            .sequentialize_threads
1831            .then(|| clone_pidfd_address(&clone_family, &guest.memory(), flags))
1832            .flatten();
1833        // Only a CLONE_VFORK parent waits for its child. Every backend runs a
1834        // forked process child concurrently with its parent and dispatches a
1835        // cloned thread's syscalls through this tool.
1836        let is_vfork = flags.contains(CloneFlags::CLONE_VFORK);
1837
1838        let ts = guest.thread_state_mut();
1839        assert_eq!(ts.clone_flags, None);
1840        assert!(ts.pending_vfork.is_none());
1841        ts.clone_flags = Some(flags);
1842
1843        let parent_dettid = ts.dettid;
1844        let child_priority_entropy = if is_vfork
1845            && self.cfg.chaos
1846            && self.cfg.replay_preemptions_from.is_none()
1847            && self.cfg.replay_schedule_from.is_none()
1848        {
1849            let mut parent_chaos_prng = ts.chaos_prng.clone();
1850            Some(parent_chaos_prng.next_u64())
1851        } else {
1852            None
1853        };
1854        if is_vfork {
1855            ts.pending_vfork = Some(PendingVfork {
1856                parent_dettid,
1857                parent_detpid: ts.detpid.expect("detpid unset"),
1858                child_tid_addr: ctid,
1859                flags,
1860                exit_signal,
1861                child_priority_entropy,
1862            });
1863        }
1864
1865        // A child's exit signal other than SIGCHLD reaches this process when
1866        // the child exits, at a moment set by host timing. Record it in this
1867        // turn, before the child exists, for every thread of the caller's
1868        // process, and never forget it (`Scheduler::record_host_timed_signals`).
1869        let exit_signals = clone_host_timed_signals(flags, exit_signal);
1870        if exit_signals != 0
1871            && bundled_signal_facts::host_timed_signal_sources_are_physical(&guest.config().backend)
1872        {
1873            record_host_timed_signals(guest, HostTimedSignalScope::Caller, exit_signals).await;
1874        }
1875
1876        if !flags.contains(CloneFlags::CLONE_THREAD) {
1877            self.promote_before_native_lifecycle(guest);
1878        }
1879
1880        // Actions shared with a new process are withdrawn from the
1881        // scheduler before the child exists.
1882        super::signal_shadow::before_clone(guest, flags.bits()).await;
1883
1884        trace!("[detcore, dtid {}] parent invoking clone.", parent_dettid);
1885        let blocking_child_op_id =
1886            ExternalOpId::new(parent_dettid, guest.thread_state().stats.syscall_count);
1887
1888        // A CLONE_VFORK parent cannot resume until the child execs or exits.
1889        // Relinquish the parent's scheduler turn before entering that
1890        // blocking operation.
1891        if is_vfork && self.cfg.sequentialize_threads {
1892            let mut resources = Resources::new(parent_dettid);
1893            resources.insert(
1894                ResourceID::BlockingVfork(blocking_child_op_id),
1895                Permission::RW,
1896            );
1897            resources.fyi("clone_vfork");
1898            resource_request(guest, resources).await;
1899        }
1900
1901        let call = Syscall::from(clone_family);
1902        let sysno = call.number();
1903        let maybe_res = guest.inject(call).await;
1904        // Ask before anything else is injected: the next injection replaces
1905        // the backend's record.
1906        let refusal = if maybe_res.is_err() {
1907            guest.take_unsupported_refusal()
1908        } else {
1909            None
1910        };
1911
1912        if is_vfork && self.cfg.sequentialize_threads {
1913            let mut resources = Resources::new(parent_dettid);
1914            if maybe_res.is_err() {
1915                // TODO-HUMAN-REVIEW(PR-1152): Review failed deferred-vfork cancellation.
1916                // A deferred-spawn backend cannot infer failure from the absence of a registered
1917                // child: a successful child also registers after this continuation. Report the
1918                // known injected-syscall outcome explicitly so the scheduler can cancel the
1919                // barrier and re-admit this parent before we propagate the original error below.
1920                resources.insert(
1921                    ResourceID::VforkFailed(blocking_child_op_id),
1922                    Permission::RW,
1923                );
1924                resources.fyi("clone_vfork_failed");
1925            } else {
1926                resources.insert(
1927                    ResourceID::BlockedExternalContinue(blocking_child_op_id),
1928                    Permission::RW,
1929                );
1930                resources.fyi("clone_vfork");
1931            }
1932            resource_request(guest, resources).await;
1933        }
1934
1935        let ts = guest.thread_state_mut();
1936        ts.clone_flags = None; // Unset, now that it has been read by the child.
1937        ts.pending_vfork = None;
1938
1939        // A backend that cannot create the child says so with a typed refusal
1940        // (an in-guest backend runs one thread of the guest). Answering the
1941        // guest with the refusal's errno would be an error Linux never gives
1942        // a valid clone, so the run is refused instead, as for an exec the
1943        // backend cannot perform.
1944        if let (Some(refusal), Err(errno)) = (refusal, &maybe_res) {
1945            tracing::error!(
1946                "[detcore, dtid {parent_dettid}] {}; no child was created",
1947                refusal.diagnostic
1948            );
1949            if !self.cfg.panic_on_unsupported_syscalls {
1950                crate::tool_global::report_unsupported_syscall(guest, sysno).await;
1951            }
1952            return self
1953                .refuse_unserviceable_operation_because(guest, sysno, *errno, refusal.diagnostic)
1954                .await;
1955        }
1956
1957        let res = maybe_res?;
1958
1959        if !flags.contains(CloneFlags::CLONE_THREAD) {
1960            // Only a successful process clone can let another process mutate
1961            // inherited open file descriptions. Failed clone-family calls leave
1962            // the previously observed flock state authoritative.
1963            guest.thread_state().forget_flock_modes();
1964        }
1965
1966        // Match ordinary clone: the parent consumes the priority entropy after
1967        // the child has inherited the parent state.
1968        if is_vfork
1969            && self.cfg.chaos
1970            && self.cfg.replay_preemptions_from.is_none()
1971            && self.cfg.replay_schedule_from.is_none()
1972        {
1973            let _ = guest
1974                .thread_state_mut()
1975                .chaos_prng_next_u64("child_priority");
1976        }
1977
1978        let child_tid = Pid::from_raw(res as i32);
1979        let child_dettid = DetTid::from_raw(child_tid.into()); // TODO(T78538674), virtualized tid/pid
1980        trace!(
1981            "[detcore] dtid {} cloned, continuing parent + register new thread.",
1982            child_dettid
1983        );
1984
1985        if !is_vfork {
1986            create_child_thread(guest, child_dettid, ctid, Some(flags), exit_signal, None).await;
1987        }
1988
1989        if let Some(address) = pidfd_address {
1990            self.register_clone_pidfd(guest, address, child_dettid)
1991                .await;
1992        }
1993
1994        {
1995            // The child will have updated their pedigree, we update ours before continuing.
1996            let parent_pedigree = &mut guest.thread_state_mut().pedigree;
1997            let child_pedigree = parent_pedigree.fork_mut();
1998            debug!(
1999                "[dtid {}] after creating child thread (tid {}, pedigree {}) parents pedigree becomes {}",
2000                parent_dettid, child_dettid, child_pedigree, parent_pedigree,
2001            );
2002        }
2003
2004        // A nested creator sees its child's pid in its own PID namespace, as
2005        // the kernel returned it; Reverie reports the container's
2006        // (https://github.com/rrnewton/hermit/issues/4090).
2007        if guest.thread_state().nested_pid_namespace {
2008            let refusal = match crate::tool_global::local_pid(guest, child_dettid).await {
2009                Ok(Some(local)) => return Ok(local as i64),
2010                Ok(None) => {
2011                    format!("child {child_dettid} has no pid recorded in its creator's namespace")
2012                }
2013                Err(reason) => reason,
2014            };
2015            tracing::error!(
2016                "[detcore, dtid {}] the pid a clone in a nested PID namespace returns cannot be translated: {} (https://github.com/rrnewton/hermit/issues/4090)",
2017                parent_dettid,
2018                refusal,
2019            );
2020            return self
2021                .refuse_unserviceable_operation(
2022                    guest,
2023                    reverie::syscalls::Sysno::clone,
2024                    Errno::ENOSYS,
2025                )
2026                .await;
2027        }
2028        Ok(child_dettid.as_raw() as i64)
2029    }
2030
2031    // TODO-HUMAN-REVIEW(PR-2985): Review scheduler tracking of set_tid_address.
2032    /// `set_tid_address` system call.
2033    ///
2034    /// Linux owns the guest-visible registration and return value. Detcore
2035    /// mirrors the accepted address into the scheduler so its modeled
2036    /// CHILD_CLEARTID wake targets the same word as the backend.
2037    pub async fn handle_set_tid_address<G: Guest<Self>>(
2038        &self,
2039        guest: &mut G,
2040        call: syscalls::SetTidAddress,
2041    ) -> Result<i64, Error> {
2042        let address = call.tidptr().map_or(0, |pointer| pointer.as_raw());
2043        let result = self
2044            .record_or_replay(guest, Syscall::SetTidAddress(call))
2045            .await?;
2046        if guest.config().sequentialize_threads {
2047            set_child_tid_address(guest, address).await;
2048        }
2049        trace!(
2050            "[detcore, dtid {}] child TID clear address registered: {address:#x}",
2051            guest.thread_state().dettid,
2052        );
2053        Ok(result)
2054    }
2055
2056    /// `set_robust_list` system call.
2057    ///
2058    /// Still a pass-through: Linux owns the registration and supplies the
2059    /// result, and Detcore only records the head address so it can replay
2060    /// `exit_robust_list()` when the thread dies (see
2061    /// `Self::run_robust_list_owner_death`). Recording happens only after the
2062    /// kernel accepts the call, so a rejected length or address never becomes
2063    /// Detcore state.
2064    ///
2065    /// The call goes through `record_or_replay`, like every other pass-through.
2066    /// Using `Guest::inject` directly would keep the classification but drop the
2067    /// behavior it implies: the syscall would vanish from a `hermit record`
2068    /// trace, and a log recorded by a build that did record it would no longer
2069    /// replay.
2070    // AUTONOMOUS-BOT-IMPLEMENTED
2071    pub async fn handle_set_robust_list<G: Guest<Self>>(
2072        &self,
2073        guest: &mut G,
2074        call: syscalls::SetRobustList,
2075    ) -> Result<i64, Error> {
2076        let head = call.head().map(AddrMut::as_raw);
2077        let len = call.len();
2078        let res = self
2079            .record_or_replay(guest, Syscall::SetRobustList(call))
2080            .await?;
2081        // TODO-HUMAN-REVIEW(PR-2223): Review robust-list
2082        // head tracking used to drive owner-death wakeups.
2083        let recorded = match head {
2084            // `set_robust_list(NULL, ...)` unregisters the list.
2085            None => None,
2086            // Fail closed, and not dead code: `len` is the guest's own argument,
2087            // so a 32-bit guest (or a bug) can present the 12-byte
2088            // `compat_robust_list_head`, whose fields sit at different offsets.
2089            // The 64-bit walk would misread it, so refuse to record it at all
2090            // rather than walk a layout we cannot parse.
2091            Some(_) if len != robust_list::ROBUST_LIST_HEAD_LEN => None,
2092            Some(addr) => Some(addr),
2093        };
2094        guest.thread_state_mut().record_robust_list_head(recorded);
2095        trace!(
2096            "[detcore, dtid {}] robust-list head registered: {:?}",
2097            guest.thread_state().dettid,
2098            recorded,
2099        );
2100        Ok(res)
2101    }
2102
2103    /// Replay Linux's `exit_robust_list()` for the calling thread.
2104    ///
2105    /// Linux runs this from `mm_release()` while a task dies. Detcore performs
2106    /// the same walk and issues the wake against its own modeled waiter pool,
2107    /// which is where precise-mode futex waiters actually live. Ptrace leaves
2108    /// the atomic word transition to Linux on every backend that enters this
2109    /// path ([`OwnerDeathPath`]), and the wake reaches a waiter only after
2110    /// Linux has made it. The algorithm is in
2111    /// [`crate::syscalls::robust_list`]; this function only supplies guest
2112    /// memory and the scheduler wake.
2113    ///
2114    /// Only the precise futex model needs this. Polling and external modes park
2115    /// waiters in the host kernel, which performs its own robust-list cleanup;
2116    /// and without thread sequentialization Detcore does not model futexes at
2117    /// all.
2118    // AUTONOMOUS-BOT-IMPLEMENTED
2119    // TODO-HUMAN-REVIEW(PR-2223): Review owner-death wakeup
2120    // emulation, which changes how a dying thread's peers are scheduled.
2121    async fn run_robust_list_owner_death<G: Guest<Self>>(&self, guest: &mut G) {
2122        let Some(path) = self.robust_owner_death_path() else {
2123            return;
2124        };
2125        let Some(head) = guest.thread_state().robust_list_head else {
2126            return;
2127        };
2128        let dettid = guest.thread_state().dettid;
2129        // Which TID goes in the comparison? Not one Detcore hands out: `gettid`
2130        // is a reviewed pass-through, and glibc puts the value the kernel
2131        // supplied through `CLONE_PARENT_SETTID` into the lock word, not a
2132        // `gettid` result. The comparison is valid for a narrower reason —
2133        // `DetTid` currently *is* the raw namespaced `Tid`. `init_thread_state`
2134        // builds every one with `DetPid::from_raw(tid.into())` (detcore/src/lib.rs,
2135        // `lib.rs:1257` at this commit), four lines under
2136        // `// TODO(T78538674): virtualize tid, extend tid<=>dettid mapping here.`
2137        // Completing that TODO breaks this comparison, which would then have to
2138        // map back to the guest-visible TID.
2139        // `hermit-cli/tests/robust_futex_owner_death.rs` is the tripwire: it
2140        // fails the moment the two diverge.
2141        let owner_tid = dettid.as_raw() as u32;
2142
2143        let mut marked = HashMap::new();
2144        let mut effects = GuestRobustEffects::<'_, G, T> {
2145            guest,
2146            dettid,
2147            staged_wakes: None,
2148            marked: &mut marked,
2149            tool: PhantomData,
2150        };
2151        let outcome = robust_list::exit_robust_list(&mut effects, head, owner_tid).await;
2152        if path == OwnerDeathPath::Barrier {
2153            guest.thread_state().mark_robust_list_walked_by_tool();
2154        }
2155        if outcome.head_unreadable {
2156            trace!(
2157                "[detcore, dtid {}] unreadable robust-list head at {:#x}; no owner-death wakeups",
2158                dettid, head,
2159            );
2160        } else if outcome.aborted || outcome.next_faulted || outcome.truncated {
2161            trace!(
2162                "[detcore, dtid {}] robust-list walk stopped early after {} entr(ies): {:?}",
2163                dettid, outcome.entries_visited, outcome,
2164            );
2165        }
2166    }
2167
2168    /// Read every registered robust list in the current thread group while
2169    /// its address space still exists, but hold its modeled wakes until the
2170    /// corresponding exit callback. On ptrace that callback confirms Linux has
2171    /// completed the atomic owner-word update.
2172    ///
2173    /// On [`OwnerDeathPath::Barrier`] nothing is staged. An exit_group walks
2174    /// the words and wakes their waiters at once instead
2175    /// (`Self::handle_exit_group`), and no waiter runs before the kernel has
2176    /// ended the group. A delivered signal
2177    /// may still be caught or ignored: Detcore must not mark a live owner's
2178    /// word, and that backend's native exit callback cannot tell which signal
2179    /// ended the thread group.
2180    pub(crate) async fn stage_thread_group_robust_list_wakes<G: Guest<Self>>(
2181        &self,
2182        guest: &mut G,
2183        reason: RobustListExit,
2184    ) {
2185        match self.robust_owner_death_path() {
2186            None | Some(OwnerDeathPath::Barrier) => {}
2187            Some(OwnerDeathPath::Kernel) => {
2188                let staged = self
2189                    .read_thread_group_robust_list_wakes(guest, OwnerDeath::Exit)
2190                    .await;
2191                guest.thread_state().stage_robust_list_wakes(reason, staged);
2192            }
2193        }
2194    }
2195
2196    /// Replay Linux's `exit_robust_list()` for each `(owner, head)` of the
2197    /// current thread group, in owner order, as that owner's list, waking at
2198    /// once ([`OwnerDeathPath::Barrier`]). The threads the grant killed have not made
2199    /// their native exits (`ThreadState::wait_for_exit_group_robust_walk`), so
2200    /// every word reads as the guest left it.
2201    async fn run_thread_group_robust_list_owner_death<G: Guest<Self>>(
2202        &self,
2203        guest: &mut G,
2204        heads: Vec<RobustListOwner>,
2205    ) {
2206        // One group exit: a word Linux marks under one owner reads as marked
2207        // under every later one.
2208        let mut marked = HashMap::new();
2209        for RobustListOwner {
2210            dettid: owner,
2211            head,
2212        } in heads
2213        {
2214            let mut effects = GuestRobustEffects::<'_, G, T> {
2215                guest,
2216                dettid: owner,
2217                staged_wakes: None,
2218                marked: &mut marked,
2219                tool: PhantomData,
2220            };
2221            let outcome =
2222                robust_list::exit_robust_list(&mut effects, head, owner.as_raw() as u32).await;
2223            if outcome.head_unreadable || outcome.aborted {
2224                trace!(
2225                    "[detcore, dtid {}] robust-list owner death stopped early: {:?}",
2226                    owner, outcome,
2227                );
2228            }
2229        }
2230    }
2231
2232    /// How this backend orders owner-death wakes after Linux's walk, or `None`
2233    /// where Detcore does not model robust-futex owner death.
2234    ///
2235    /// Only the precise futex model needs owner death modeled. Polling and
2236    /// external modes park waiters in the host kernel, which performs its own
2237    /// robust-list cleanup; and without thread sequentialization Detcore does
2238    /// not model futexes at all.
2239    fn robust_owner_death_path(&self) -> Option<OwnerDeathPath> {
2240        owner_death_path(&self.cfg)
2241    }
2242
2243    /// The owner-death wakes a successful execve makes Linux deliver, in
2244    /// delivery order, for a backend that runs the native execve outside
2245    /// Detcore's handler and so cannot stage them in this thread's state (DBT,
2246    /// whose new image starts a fresh runtime). Read while the old image is
2247    /// mapped, before the native exec; none where Detcore does not model
2248    /// owner death (<https://github.com/rrnewton/hermit/issues/4268>).
2249    pub async fn exec_robust_list_wakes<G: Guest<Self>>(
2250        &self,
2251        guest: &mut G,
2252    ) -> Vec<(DetTid, FutexID)> {
2253        if self.robust_owner_death_path().is_none() {
2254            return Vec::new();
2255        }
2256        let wakes = self
2257            .read_thread_group_robust_list_wakes(guest, OwnerDeath::Exec)
2258            .await;
2259        crate::tool_local::flatten_exec_robust_list_wakes(wakes)
2260            .into_iter()
2261            .map(|(owner, wake)| (owner, wake.futex))
2262            .collect()
2263    }
2264
2265    /// The owner-death wakes Linux's `exit_robust_list` would make for every
2266    /// registered robust list in the current thread group, read without
2267    /// changing guest memory: Linux makes the owner-word transitions. Callers
2268    /// decide whether Detcore models owner death at all
2269    /// ([`Self::robust_owner_death_path`]).
2270    ///
2271    /// Each list is walked as its owner's, with that owner's TID, except the
2272    /// caller's own list in an exec by a thread that is not the group leader.
2273    /// `de_thread` gives that caller the leader's TID (`exchange_tids`) before
2274    /// `exec_mm_release` walks its list, so `handle_futex_death` compares the
2275    /// owner words with the thread group ID and leaves a word the caller owns
2276    /// under its old TID alone (fs/exec.c, kernel/futex/core.c).
2277    async fn read_thread_group_robust_list_wakes<G: Guest<Self>>(
2278        &self,
2279        guest: &mut G,
2280        death: OwnerDeath,
2281    ) -> Vec<(DetTid, Vec<RobustListWake>)> {
2282        let caller = guest.thread_state().dettid;
2283        let tgid = guest.thread_state().detpid.expect("detpid unset");
2284        // A thread whose own exit Detcore already walked (its head stays
2285        // registered while an exit_group is filed) is left out, as an
2286        // exit_group's walk leaves it out, so no list is walked twice (Claude
2287        // review of https://github.com/rrnewton/hermit/pull/4352, F4).
2288        let mut heads: Vec<(DetTid, usize)> = guest
2289            .thread_state()
2290            .robust_list_owners_for_exit_group()
2291            .into_iter()
2292            .map(|owner| (owner.dettid, owner.head))
2293            .collect();
2294        if death == OwnerDeath::Exec {
2295            // de_thread waits until every other thread has exited, each walking
2296            // its own list, before exec_mm_release walks the caller's; with
2297            // marks carried across lists, the caller's must come last (Claude
2298            // review of https://github.com/rrnewton/hermit/pull/4277 at
2299            // 65138a17, N5).
2300            heads.sort_by_key(|(owner, _)| *owner == caller);
2301        }
2302        let mut staged = Vec::with_capacity(heads.len());
2303        let mut marked = HashMap::new();
2304        for (owner, head) in heads {
2305            let walked_as = if death == OwnerDeath::Exec && owner == caller {
2306                tgid.as_raw()
2307            } else {
2308                owner.as_raw()
2309            };
2310            let mut wakes = Vec::new();
2311            let mut effects = GuestRobustEffects::<'_, G, T> {
2312                guest,
2313                dettid: owner,
2314                staged_wakes: Some(&mut wakes),
2315                marked: &mut marked,
2316                tool: PhantomData,
2317            };
2318            let outcome = robust_list::exit_robust_list(&mut effects, head, walked_as as u32).await;
2319            if outcome.head_unreadable || outcome.aborted {
2320                trace!(
2321                    "[detcore, dtid {}] could not stage complete robust-list owner-death effects: {:?}",
2322                    owner, outcome,
2323                );
2324            }
2325            staged.push((owner, wakes));
2326        }
2327        staged
2328    }
2329
2330    /// Exit system call
2331    pub async fn handle_exit<G: Guest<Self>>(
2332        &self,
2333        guest: &mut G,
2334        call: syscalls::Exit,
2335    ) -> Result<i64, Error> {
2336        // This thread may be its process's last (`crate::guest_log`).
2337        crate::guest_log::flush_unsent();
2338        // A raw `exit` of a process's last thread ends the process as an
2339        // `exit_group` does, and the scheduler then sends the parent's SIGCHLD
2340        // with Linux's siginfo, as for `handle_exit_group`. Only the exit grant
2341        // knows whether this thread is the last, so every raw exit reports its
2342        // status, kept for this thread alone until that grant settles it.
2343        if self.cfg.backend.reports_kernel_child_exit_signals {
2344            let uid = real_uid(guest.tid().as_raw()).unwrap_or_else(|| unsafe { libc::getuid() });
2345            crate::tool_global::child_exit_sigchld(
2346                guest,
2347                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::RawExitStatus {
2348                    code: libc::CLD_EXITED,
2349                    status: call.status() & 0xff,
2350                    uid,
2351                },
2352            )
2353            .await;
2354        }
2355        let request = guest.thread_state().mk_request(
2356            ResourceID::Exit {
2357                group: false,
2358                process: guest.thread_state().detpid.expect("detpid unset"),
2359                mm: guest.thread_state().mm_id,
2360            },
2361            Permission::RW,
2362        );
2363        resource_request(guest, request).await;
2364        self.run_robust_list_owner_death(guest).await;
2365        // A leader whose group lives on is a zombie from here until its last
2366        // sibling leaves, and its backend reports its exit only then: it
2367        // leaves the scheduler now, after its last request
2368        // (https://github.com/rrnewton/hermit/issues/4100).
2369        let state = guest.thread_state();
2370        if self.cfg.sequentialize_threads
2371            && state
2372                .detpid
2373                .is_some_and(|pid| pid.as_raw() == state.dettid.as_raw())
2374            && crate::tool_global::retire_exited_leader(guest).await
2375            && self.cfg.replay_data.is_some()
2376        {
2377            // The recorder reads the process's descriptor table through its
2378            // leader, which is a zombie from here, so it would record the
2379            // group's later output as ordinary writes that replay drops
2380            // (https://github.com/rrnewton/hermit/issues/4244).
2381            let message = format!(
2382                "hermit: thread-group leader {} exited while its threads run on, which record \
2383                 and replay cannot yet capture, so the run is refused \
2384                 (https://github.com/rrnewton/hermit/issues/4244)",
2385                guest.thread_state().dettid
2386            );
2387            tracing::error!("{message}");
2388            let _ = std::io::Write::write_fmt(
2389                &mut crate::util::RetryingStderr,
2390                format_args!("{message}\n"),
2391            );
2392            crate::tool_global::unrecoverable_shutdown(
2393                guest,
2394                detcore_model::HERMIT_POLICY_REFUSAL_EXIT,
2395            )
2396            .await;
2397        }
2398        // It's ok here that we skip running the posthook:
2399        guest.tail_inject(call).await
2400    }
2401
2402    /// Exit_group system call
2403    pub async fn handle_exit_group<G: Guest<Self>>(
2404        &self,
2405        guest: &mut G,
2406        call: syscalls::ExitGroup,
2407    ) -> Result<i64, Error> {
2408        // One of the last points where this process's unsent warnings can
2409        // still be reported (`crate::guest_log`).
2410        crate::guest_log::flush_unsent();
2411        // Where the kernel also notifies the parent, the scheduler sends the
2412        // parent's SIGCHLD itself and gives it the siginfo Linux would
2413        // (`scheduler::child_exit_sigchld`): CLD_EXITED and the exit code.
2414        if self.cfg.backend.reports_kernel_child_exit_signals {
2415            let uid = real_uid(guest.tid().as_raw()).unwrap_or_else(|| unsafe { libc::getuid() });
2416            crate::tool_global::child_exit_sigchld(
2417                guest,
2418                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::ExitStatus {
2419                    code: libc::CLD_EXITED,
2420                    status: call.status() & 0xff,
2421                    uid,
2422                },
2423            )
2424            .await;
2425        }
2426        // On [`OwnerDeathPath::Barrier`] the walk follows the grant and wakes
2427        // at once, as an exit does (`Self::run_robust_list_owner_death`):
2428        // nothing can call the exit_group off, the grant logically kills the
2429        // group's other threads, so none of them runs guest code again, and
2430        // the scheduler commits no turn until the kernel has ended every
2431        // thread of the group, so no waiter runs before Linux has marked its
2432        // word. Holding the wakes for the exit callbacks would lose them on
2433        // DBT, which answers a logically killed thread's callback
2434        // `ThreadExited`. Read the registrations at the grant, as Linux's
2435        // walks use the ones current when each thread dies. Filing first keeps
2436        // an exiting thread's head registered until then and holds the killed
2437        // threads' native exits until the walk is done
2438        // (`ThreadState::file_exit_group_for_robust_lists`,
2439        // `ThreadState::wait_for_exit_group_robust_walk`): a killed thread's
2440        // native exit would otherwise let Linux mark and clear its words before
2441        // the walk reads them. The lists stay mapped until the native
2442        // exit_group.
2443        let barrier = self.robust_owner_death_path() == Some(OwnerDeathPath::Barrier);
2444        if barrier {
2445            guest.thread_state().file_exit_group_for_robust_lists();
2446        }
2447        let request = guest.thread_state().mk_request(
2448            ResourceID::Exit {
2449                group: true,
2450                process: guest.thread_state().detpid.expect("detpid unset"),
2451                mm: guest.thread_state().mm_id,
2452            },
2453            Permission::RW,
2454        );
2455        resource_request(guest, request).await;
2456        if barrier {
2457            guest.thread_state().begin_exit_group_robust_walk();
2458            let owners = guest.thread_state().robust_list_owners_for_exit_group();
2459            self.run_thread_group_robust_list_owner_death(guest, owners)
2460                .await;
2461            guest.thread_state().finish_exit_group_robust_walk();
2462        } else {
2463            self.stage_thread_group_robust_list_wakes(guest, RobustListExit::ExitGroup)
2464                .await
2465        }
2466        // It's ok here that we skip running the posthook:
2467        guest.tail_inject(call).await
2468    }
2469
2470    /// On DBT, end the thread group in the schedule before a signal that
2471    /// ends it by default is delivered natively
2472    /// (<https://github.com/rrnewton/hermit/issues/4278>). DynamoRIO carries
2473    /// out such a default action itself, and before the process exits it
2474    /// synchronizes with every other thread of it. A thread waiting for its
2475    /// turn is blocked in the client's call to the coordinator, inside a
2476    /// DynamoRIO event callback, where DynamoRIO cannot suspend it, so the
2477    /// dying thread waited for it forever. The `Exit` grant of an exit_group
2478    /// logically kills the group's other threads and cancels their pending
2479    /// requests, so each returns from its callback and can be synchronized;
2480    /// the robust lists are walked as an exit_group's are. Returns whether it
2481    /// ended the group.
2482    ///
2483    /// The decision is the action read in this thread's `InboundSignal` turn.
2484    /// Linux commits it under the signal lock: for an unblocked signal,
2485    /// `complete_signal` sets `SIGNAL_GROUP_EXIT` and queues SIGKILL to every
2486    /// other thread of the group, so no sibling runs another user instruction
2487    /// after the decision. Filing the `Exit` request ends this thread's turn,
2488    /// so the thread first asks that the request be granted at the very next
2489    /// turn (`Scheduler::hold_turn_for_group_exit`). No sibling takes a turn
2490    /// between the decision and the grant, which logically kills the siblings,
2491    /// so none runs guest code before the native delivery (Claude re-check of
2492    /// https://github.com/rrnewton/hermit/pull/4387).
2493    ///
2494    /// One path can still run a sibling first: an exit parked behind a
2495    /// sibling's signal-delivery permit (`Scheduler::exit_awaits_sibling_permit`).
2496    /// DynamoRIO reads the action again when it delivers, so after the grant
2497    /// the action is read again and, if a sibling changed it, set back to
2498    /// `SIG_DFL` in this dying process, and the delivery carries out the
2499    /// committed decision (Codex review of
2500    /// https://github.com/rrnewton/hermit/pull/4387, P1).
2501    ///
2502    /// The gate is this backend's: DynamoRIO carries out a default action in
2503    /// the process and synchronizes every thread before it exits. Today only
2504    /// DBT sends process signals to a named thread
2505    /// (`requires_thread_directed_process_signals`), so that flag selects it.
2506    pub(crate) async fn end_thread_group_before_fatal_delivery<G: Guest<Self>>(
2507        &self,
2508        guest: &mut G,
2509        signal: SigWrapper,
2510    ) -> bool {
2511        if !(self.cfg.sequentialize_threads
2512            && self.cfg.backend.requires_thread_directed_process_signals)
2513            || !signal_default_action_ends_the_process(signal)
2514        {
2515            return false;
2516        }
2517        match self.signal_is_left_at_default(guest, signal).await {
2518            Ok(true) => {}
2519            Ok(false) => return false,
2520            Err(error) => {
2521                tracing::warn!(
2522                    "[detcore, dtid {}] cannot read the disposition of {}: {}",
2523                    guest.thread_state().dettid,
2524                    signal,
2525                    error
2526                );
2527                return false;
2528            }
2529        }
2530        info!(
2531            "[detcore, dtid {}] {} ends its thread group by default",
2532            guest.thread_state().dettid,
2533            signal
2534        );
2535        let barrier = self.robust_owner_death_path() == Some(OwnerDeathPath::Barrier);
2536        if barrier {
2537            guest.thread_state().file_exit_group_for_robust_lists();
2538        }
2539        let dettid = guest.thread_state().dettid;
2540        if !hold_turn_for_group_exit(guest, dettid).await {
2541            tracing::warn!(
2542                "[detcore, dtid {}] the scheduler did not hold the turn for the group exit of {}",
2543                dettid,
2544                signal
2545            );
2546        }
2547        let request = guest.thread_state().mk_request(
2548            ResourceID::Exit {
2549                group: true,
2550                process: guest.thread_state().detpid.expect("detpid unset"),
2551                mm: guest.thread_state().mm_id,
2552            },
2553            Permission::RW,
2554        );
2555        resource_request(guest, request).await;
2556        match self.signal_is_left_at_default(guest, signal).await {
2557            Ok(true) => {}
2558            changed => {
2559                info!(
2560                    "[detcore, dtid {}] the action for {} changed after the delivery decision \
2561                     ({:?}); restoring SIG_DFL in the dying process",
2562                    guest.thread_state().dettid,
2563                    signal,
2564                    changed.map(|default| !default)
2565                );
2566                if let Err(error) = self.restore_default_action(guest, signal).await {
2567                    tracing::warn!(
2568                        "[detcore, dtid {}] cannot restore SIG_DFL for {}: {}",
2569                        guest.thread_state().dettid,
2570                        signal,
2571                        error
2572                    );
2573                }
2574            }
2575        }
2576        if barrier {
2577            guest.thread_state().begin_exit_group_robust_walk();
2578            let owners = guest.thread_state().robust_list_owners_for_exit_group();
2579            self.run_thread_group_robust_list_owner_death(guest, owners)
2580                .await;
2581            guest.thread_state().finish_exit_group_robust_walk();
2582        }
2583        true
2584    }
2585
2586    /// Set the guest's action for `signal` to `SIG_DFL`.
2587    async fn restore_default_action<G: Guest<Self>>(
2588        &self,
2589        guest: &mut G,
2590        signal: SigWrapper,
2591    ) -> Result<(), Error> {
2592        let default = KernelSigaction {
2593            handler: libc::SIG_DFL as u64,
2594            flags: 0,
2595            restorer: 0,
2596            mask: 0,
2597        };
2598        let mut stack = guest.stack().await;
2599        let action_addr = stack.push(default);
2600        let _guard = stack.commit()?;
2601        let call = syscalls::RtSigaction::new()
2602            .with_signum(signal.raw())
2603            .with_action(Some(action_addr.cast()))
2604            .with_old_action(None)
2605            .with_sigsetsize(std::mem::size_of::<u64>());
2606        guest.inject_with_retry(call).await?;
2607        // Detcore's own change, which the signal-state copy does not record:
2608        // the copy, and the actions it shares, are unknown now.
2609        super::signal_shadow::give_up(
2610            guest,
2611            "Detcore reset an action to the default before a fatal delivery",
2612        );
2613        Ok(())
2614    }
2615
2616    /// Whether the guest's action for `signal` is the default (`SIG_DFL`),
2617    /// as the backend reports it to the guest.
2618    async fn signal_is_left_at_default<G: Guest<Self>>(
2619        &self,
2620        guest: &mut G,
2621        signal: SigWrapper,
2622    ) -> Result<bool, Error> {
2623        let mut stack = guest.stack().await;
2624        let action_addr = stack.reserve::<KernelSigaction>();
2625        let _guard = stack.commit()?;
2626        let call = syscalls::RtSigaction::new()
2627            .with_signum(signal.raw())
2628            .with_action(None)
2629            .with_old_action(Some(action_addr.cast()))
2630            .with_sigsetsize(std::mem::size_of::<u64>());
2631        guest.inject_with_retry(call).await?;
2632        let action: KernelSigaction = guest.memory().read_value(action_addr)?;
2633        Ok(action.handler == libc::SIG_DFL as u64)
2634    }
2635
2636    /// Futex system call, which can block.
2637    pub async fn handle_futex<G: Guest<Self>>(
2638        &self,
2639        guest: &mut G,
2640        call: syscalls::Futex,
2641    ) -> Result<i64, Error> {
2642        self.handle_futex_from(guest, call, FutexDeadline::FromCall)
2643            .await
2644    }
2645
2646    /// `handle_futex`, taking a wait's deadline from `deadline`. A `restart_syscall`
2647    /// resumes an interrupted timed futex wait here with the deadline it kept,
2648    /// and the value is compared again, as in Linux's `futex_wait_restart`
2649    /// (`Detcore::handle_restart_syscall`).
2650    pub(crate) async fn handle_futex_from<G: Guest<Self>>(
2651        &self,
2652        guest: &mut G,
2653        call: syscalls::Futex,
2654        deadline: FutexDeadline,
2655    ) -> Result<i64, Error> {
2656        let dettid = guest.thread_state().dettid;
2657        // Detcore emulates the futex commands below, so it also answers, as Linux's
2658        // `do_futex` (kernel/futex/syscalls.c) does, for the ones it does not serve:
2659        // before the futex address is even looked at.
2660        if self.cfg.sequentialize_threads
2661            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
2662        {
2663            match classify_futex_command(call.futex_op()) {
2664                FutexCommand::Served => {}
2665                FutexCommand::NoSys => return Err(Error::Errno(Errno::ENOSYS)),
2666                FutexCommand::PriorityInheritance(name) => {
2667                    return self
2668                        .refuse_futex_command(
2669                            guest,
2670                            name,
2671                            "Detcore does not emulate priority-inheritance futexes",
2672                        )
2673                        .await;
2674                }
2675            }
2676        }
2677        // FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and FUTEX_WAKE_OP key their words
2678        // without reading `uaddr` (only CMP_REQUEUE compares it), and NULL is a
2679        // valid private key for them, so they take their own path before the
2680        // NULL passthrough and the read below.
2681        if self.cfg.sequentialize_threads
2682            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
2683        {
2684            let command = call.futex_op() & libc::FUTEX_CMD_MASK;
2685            // FUTEX_WAKE and FUTEX_WAKE_BITSET only key their word too, and a
2686            // requeue can leave a modeled waiter on any admitted private key,
2687            // NULL or unmapped included, which a wake must still reach.
2688            if matches!(command, libc::FUTEX_WAKE | libc::FUTEX_WAKE_BITSET)
2689                && matches!(self.cfg.debug_futex_mode, BlockingMode::Precise)
2690            {
2691                return self.handle_futex_wake(guest, call, command).await;
2692            }
2693            let name = match command {
2694                libc::FUTEX_REQUEUE => Some("FUTEX_REQUEUE"),
2695                libc::FUTEX_CMP_REQUEUE => Some("FUTEX_CMP_REQUEUE"),
2696                libc::FUTEX_WAKE_OP => Some("FUTEX_WAKE_OP"),
2697                _ => None,
2698            };
2699            if let Some(name) = name {
2700                // Polling waiters are not on a waiter list that a requeue or a
2701                // WAKE_OP's second wake could act on.
2702                if matches!(self.cfg.debug_futex_mode, BlockingMode::Polling) {
2703                    return self
2704                        .refuse_futex_command(guest, name, POLLING_REFUSAL)
2705                        .await;
2706                }
2707                return if command == libc::FUTEX_WAKE_OP {
2708                    // AUTONOMOUS-BOT-IMPLEMENTED
2709                    self.handle_futex_wake_op(guest, call).await
2710                } else {
2711                    // AUTONOMOUS-BOT-IMPLEMENTED
2712                    self.handle_futex_requeue(guest, call, command).await
2713                };
2714            }
2715        }
2716        let ptr = match call.uaddr() {
2717            None => {
2718                // null pointer error:
2719                return Ok(guest.inject(call).await?);
2720            }
2721            Some(x) => x,
2722        };
2723        if self.cfg.sequentialize_threads
2724            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
2725            && !AddrMut::as_raw(ptr).is_multiple_of(std::mem::size_of::<u32>())
2726        {
2727            // `get_futex_key` refuses a misaligned futex word before any access.
2728            return Err(Error::Errno(Errno::EINVAL));
2729        }
2730        if !self.cfg.sequentialize_threads {
2731            return Ok(guest.inject(call).await?);
2732        }
2733        let polling = match self.cfg.debug_futex_mode {
2734            BlockingMode::External => {
2735                return self.record_or_replay_blocking(guest, call.into()).await;
2736            }
2737            BlockingMode::Precise => false,
2738            BlockingMode::Polling => true,
2739        };
2740        // Only the waits compare the word, and they read it as Linux's
2741        // `futex_wait_setup` does, with user-mode permissions: EFAULT for an
2742        // unmapped, PROT_NONE or otherwise unreadable word
2743        // (https://github.com/rrnewton/hermit/issues/4030). A wake left to the
2744        // polling mode reads nothing, as Linux's `futex_wake` reads nothing.
2745        //
2746        // Linux checks a wait's other arguments first, without touching the
2747        // word: `sys_futex` (kernel/futex/syscalls.c) copies and validates the
2748        // timeout (EFAULT, EINVAL), then `__futex_wait` refuses a zero bitset
2749        // (EINVAL). A restarted wait keeps its validated deadline.
2750        let init_val = match call.futex_op() & libc::FUTEX_CMD_MASK {
2751            command @ (libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET) => {
2752                if matches!(deadline, FutexDeadline::FromCall)
2753                    && let Some(timeout) = call.timeout()
2754                {
2755                    let timeout = read_user_timespec(guest, timeout.as_raw())?;
2756                    if !futex_timespec_is_valid(timeout) {
2757                        return Err(Error::Errno(Errno::EINVAL));
2758                    }
2759                }
2760                if command == libc::FUTEX_WAIT_BITSET && call.val3() == 0 {
2761                    return Err(Error::Errno(Errno::EINVAL));
2762                }
2763                read_futex_word(guest, AddrMut::as_raw(ptr))?
2764            }
2765            _ => 0,
2766        };
2767        trace!(
2768            "[detcore, dtid {}] futex op with memory address containing value {}",
2769            &dettid, init_val
2770        );
2771        if polling {
2772            self.handle_futex_polling(guest, call, init_val, deadline)
2773                .await
2774        } else {
2775            self.handle_futex_blocking(guest, call, init_val, deadline)
2776                .await
2777        }
2778    }
2779
2780    /// Blocking (precise) Futex implementation.
2781    /// Here we use a two-phase request to the scheduler: before and after the futex wait/wake
2782    /// side effects. We EMULATE futex calls and NEVER run them inside the kernel.
2783    pub(crate) async fn handle_futex_blocking<G: Guest<Self>>(
2784        &self,
2785        guest: &mut G,
2786        call: syscalls::Futex,
2787        init_val: i32,
2788        deadline: FutexDeadline,
2789    ) -> Result<i64, Error> {
2790        let ptr = call.uaddr().unwrap();
2791        let futexid = guest.thread_state().futex_id(
2792            AddrMut::as_raw(ptr),
2793            call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0,
2794        );
2795        let futex_op = call.futex_op() & libc::FUTEX_CMD_MASK;
2796        let bitset = match futex_op {
2797            libc::FUTEX_WAKE_BITSET | libc::FUTEX_WAIT_BITSET => call.val3() as u32,
2798            _ => u32::MAX,
2799        };
2800        if bitset == 0 {
2801            return Err(Error::Errno(Errno::EINVAL));
2802        }
2803        let dettid = guest.thread_state().dettid;
2804        match futex_op {
2805            libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET => {
2806                if init_val != call.val() {
2807                    info!(
2808                        "[detcore, dtid {}] Futex wait running immediately because it will fizzle ({} != {}).",
2809                        &dettid,
2810                        init_val,
2811                        call.val()
2812                    );
2813                    Err(Error::Errno(Errno::EAGAIN))
2814                } else {
2815                    let maybe_timeout_lt = self.futex_deadline(guest, call, deadline).await?;
2816                    let signal_interruption = guest
2817                        .config()
2818                        .backend
2819                        .supports_blocked_wait_signal_interruption;
2820                    // Whether this wait was woken for a signal and is checking again.
2821                    let mut rewait = false;
2822                    // The signals the scheduler committed to this waiter at that wake
2823                    // (`SchedValue::Signaled`), which this turn's check counts although
2824                    // the wait holds them (https://github.com/rrnewton/hermit/issues/4005).
2825                    let mut committed_wake: KernelSigset = 0;
2826                    // Whether a wait request reached the scheduler. A wait that
2827                    // ends before its first one, on a pending signal or a failed
2828                    // read, sends no `WaitFinished`, as before.
2829                    let mut requested = false;
2830                    let res = loop {
2831                        // On a backend whose kernel reports the guest's signal state,
2832                        // a blocked, ignored, or default-ignored signal leaves the wait
2833                        // parked until its wakeup or its original deadline. As in
2834                        // Linux, one already pending when the value matches ends the
2835                        // wait at once with the futex's restart errno. A `SIGCHLD`
2836                        // ends it only when the scheduler committed it to this
2837                        // waiter at its wake, sent at a commit point (a child's
2838                        // child-exit timer, or a POSIX timer: `committed_wake`,
2839                        // https://github.com/rrnewton/hermit/issues/4005), or when it
2840                        // is a guest's thread-directed copy in this thread's private
2841                        // queue that the schedule recorded (`futex_wait_pending_signals`,
2842                        // https://github.com/rrnewton/hermit/issues/4132); any other
2843                        // stays pending until the call returns, because the kernel
2844                        // also posts one for a child event at a moment set by host
2845                        // timing (https://github.com/rrnewton/hermit/issues/3146). Nor does
2846                        // a signal that a host-timed source armed by a guest can
2847                        // post to this process, such as a parent-death signal
2848                        // (`host_timed_signals`, read here in this thread's turn).
2849                        //
2850                        // The same check decides a wait the scheduler woke for a
2851                        // signal. The scheduler commits such a wake without this
2852                        // thread running, and queues the thread to run next so that it
2853                        // is the thread that dequeues the signal. Checking again here,
2854                        // in the thread's own turn, keeps the restart errno for a
2855                        // signal the kernel will deliver to this thread as the call
2856                        // returns. If another thread took the signal first (a chaos
2857                        // schedule can run one ahead) or it became ignored, the wait
2858                        // parks again with its original absolute deadline, as
2859                        // `__futex_wait` retries a wait woken with no signal pending:
2860                        // an expired deadline ends it at the scheduler's next timed pop
2861                        // with ETIMEDOUT. Before parking again it reads the word, as
2862                        // `futex_wait_setup` does on that retry (see the re-check below).
2863                        // Returning the restart errno with nothing to deliver would
2864                        // instead have leaked it to the guest, or restarted the call
2865                        // with a fresh timeout.
2866                        //
2867                        // The scheduler is given only the mask, which only this thread
2868                        // can change and so cannot change while it is parked. A sibling
2869                        // can change the dispositions at any time, so the scheduler
2870                        // reads them when it commits a wake, not here
2871                        // (https://github.com/rrnewton/hermit/issues/3146).
2872                        let signal_watch = if signal_interruption {
2873                            // A failed read is never the call's errno
2874                            // (`read_wait_signal_state`).
2875                            let state = match read_wait_signal_state(guest.pid(), guest.tid()) {
2876                                Ok(state) => state,
2877                                Err(error) => break Err(error),
2878                            };
2879                            // A timed futex wait lets a default job-control stop
2880                            // wait for its deadline (`KernelSignalState::interrupting_wait`).
2881                            let defers_default_stops = call.restart_keeps_deadline();
2882                            let host_timed = host_timed_signals(guest).await;
2883                            let committed = std::mem::take(&mut committed_wake);
2884                            let held = futex_wait_held_after_wake(host_timed, committed);
2885                            let pending = futex_wait_pending_signals(
2886                                guest,
2887                                &state,
2888                                state.pending_interrupting(state.blocked, defers_default_stops),
2889                                held,
2890                                host_timed,
2891                                committed,
2892                            )
2893                            .await;
2894                            if pending != 0 {
2895                                let errno = call.kernel_restart_errno();
2896                                trace!(
2897                                    "[detcore, dtid {}] futex wait interrupted by pending signals {:#x}: {:?}",
2898                                    &dettid, pending, errno
2899                                );
2900                                break Err(Error::Errno(errno));
2901                            }
2902                            Some(FutexSignalWatch {
2903                                unblocked: !state.blocked
2904                                    & !kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32),
2905                                defers_default_stops,
2906                                pid: guest.pid().as_raw(),
2907                                tid: guest.tid().as_raw(),
2908                            })
2909                        } else {
2910                            None
2911                        };
2912                        if rewait {
2913                            // No signal is pending for this thread, so Linux's
2914                            // `__futex_wait` retries `futex_wait_setup`, which reads the
2915                            // word again with user-mode permissions: EFAULT if it cannot,
2916                            // EAGAIN if it changed, and otherwise the wait parks again
2917                            // (https://github.com/rrnewton/hermit/issues/4033). While the
2918                            // wait was off the waiter list a `FUTEX_WAKE` could not reach
2919                            // it, and a waker that saw no waiter is consistent with
2920                            // exactly this retry window.
2921                            let observed = match read_futex_word(guest, AddrMut::as_raw(ptr)) {
2922                                Ok(observed) => observed,
2923                                Err(error) => break Err(error),
2924                            };
2925                            if observed != call.val() {
2926                                trace!(
2927                                    "[detcore, dtid {}] futex value changed while its wait was woken for a signal ({} != {}); EAGAIN",
2928                                    &dettid,
2929                                    observed,
2930                                    call.val()
2931                                );
2932                                break Err(Error::Errno(Errno::EAGAIN));
2933                            }
2934                            debug!(
2935                                "[detcore, dtid {}] futex wait woken for a signal that is not pending for it; waiting again until {:?}",
2936                                &dettid, maybe_timeout_lt
2937                            );
2938                        }
2939                        requested = true;
2940                        let ans = futex_action(
2941                            guest,
2942                            FutexAction::WaitRequest(maybe_timeout_lt, signal_watch),
2943                            &futexid,
2944                            init_val,
2945                            bitset,
2946                        )
2947                        .await;
2948                        if signal_interruption && let Some(SchedValue::Signaled(committed)) = ans {
2949                            committed_wake = committed;
2950                            // The scheduler ended the wait for a signal that
2951                            // interrupted it under the dispositions the kernel held
2952                            // when the wake was committed. The check at the top of the
2953                            // loop decides, in this thread's turn, whether it is still
2954                            // pending here.
2955                            rewait = true;
2956                            continue;
2957                        }
2958                        break if ans != Some(SchedValue::TimeOut) {
2959                            let expected = call.val();
2960                            // AUTONOMOUS-BOT-IMPLEMENTED
2961                            // TODO-HUMAN-REVIEW(#845): Review exited-thread futex diagnostics.
2962                            match guest.memory().read_value(ptr) {
2963                                Ok(observed) => {
2964                                    trace!(
2965                                        "[detcore, dtid {}] after (emulated) futex wait, memory value is {}, expected {}",
2966                                        &dettid, observed, expected,
2967                                    );
2968                                    if expected == observed {
2969                                        debug!(
2970                                            "WARNING: fishy that the futex value did not change before wakeup. Weird application-level protocol.\n"
2971                                        );
2972                                    }
2973                                }
2974                                Err(error) => trace!(
2975                                    "[detcore, dtid {}] skipped post-wait futex memory diagnostic: {}",
2976                                    &dettid, error,
2977                                ),
2978                            }
2979                            Ok(0)
2980                        } else {
2981                            trace!("[detcore, dtid {}] futex wait timed out", &dettid);
2982                            Err(Error::Errno(Errno::ETIMEDOUT))
2983                        };
2984                    };
2985                    if requested {
2986                        futex_action(guest, FutexAction::WaitFinished, &futexid, init_val, bitset)
2987                            .await;
2988                    }
2989                    keep_restart_block(guest, &res, RestartCall::Futex(call), maybe_timeout_lt)
2990                        .await;
2991                    res
2992                }
2993            }
2994            // `classify_futex_command` already answered every other command.
2995            _ => Err(Error::Errno(Errno::ENOSYS)),
2996        }
2997    }
2998
2999    /// FUTEX_WAKE and FUTEX_WAKE_BITSET, as Linux's `futex_wake`
3000    /// (kernel/futex/waitwake.c): `-EINVAL` for a zero bitset, then the word is
3001    /// keyed for reading (`futex_key`) and never read, and up to `val` modeled
3002    /// waiters whose bitset matches are woken (a count of 0 or below wakes one).
3003    async fn handle_futex_wake<G: Guest<Self>>(
3004        &self,
3005        guest: &mut G,
3006        call: syscalls::Futex,
3007        command: i32,
3008    ) -> Result<i64, Error> {
3009        let bitset = if command == libc::FUTEX_WAKE_BITSET {
3010            call.val3() as u32
3011        } else {
3012            u32::MAX
3013        };
3014        if bitset == 0 {
3015            return Err(Error::Errno(Errno::EINVAL));
3016        }
3017        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
3018        let futexid = futex_key(guest, futex_uaddr(&call), private, KeyAccess::Read).await?;
3019        let num = match futex_action(
3020            guest,
3021            FutexAction::WakeRequest(call.val()),
3022            &futexid,
3023            0,
3024            bitset,
3025        )
3026        .await
3027        .expect("futex wake must return value")
3028        {
3029            SchedValue::Value(num) => num,
3030            other => panic!("impossible answer to a futex wake: {:?}", other),
3031        };
3032        let _ = futex_action(guest, FutexAction::WakeFinished(0), &futexid, 0, bitset).await;
3033        if self.cfg.yields_after_futex_wake(num) {
3034            guest.thread_state_mut().yield_after_futex_wake = true;
3035        }
3036        Ok(num as i64)
3037    }
3038
3039    /// FUTEX_REQUEUE and FUTEX_CMP_REQUEUE on plain futexes, as Linux's
3040    /// `futex_requeue` (kernel/futex/requeue.c) with `requeue_pi == 0`, in its
3041    /// order:
3042    /// - `-EINVAL` if `nr_wake` (`val`) or `nr_requeue` (`val2`, passed in the
3043    ///   timeout slot) is negative as an `int`, before any address is looked at;
3044    /// - both words keyed (`futex_key`): `-EINVAL` if misaligned, `-EFAULT` if
3045    ///   outside the user address range or, for a shared key, unmapped;
3046    /// - for FUTEX_CMP_REQUEUE only, the `uaddr` word read with the guest's own
3047    ///   permissions (`-EFAULT`), then `-EAGAIN` if it differs from `val3`.
3048    ///   Plain FUTEX_REQUEUE never reads either word;
3049    /// - wake the first `nr_wake` waiters, move up to `nr_requeue` more onto
3050    ///   `uaddr2` (`Scheduler::requeue_futex_waiters`), and return how many were
3051    ///   woken plus moved.
3052    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/pull/4020): Review the
3053    // emulated futex requeue and its waiter ordering.
3054    async fn handle_futex_requeue<G: Guest<Self>>(
3055        &self,
3056        guest: &mut G,
3057        call: syscalls::Futex,
3058        command: i32,
3059    ) -> Result<i64, Error> {
3060        let nr_wake = call.val();
3061        let nr_requeue = futex_val2(&call) as i32;
3062        if nr_wake < 0 || nr_requeue < 0 {
3063            return Err(Error::Errno(Errno::EINVAL));
3064        }
3065        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
3066        let uaddr = futex_uaddr(&call);
3067        let futexid = futex_key(guest, uaddr, private, KeyAccess::Read).await?;
3068        let futexid2 = futex_key(guest, futex_uaddr2(&call), private, KeyAccess::Read).await?;
3069        let mut current = 0;
3070        if command == libc::FUTEX_CMP_REQUEUE {
3071            current = read_futex_word(guest, uaddr)?;
3072            if current != call.val3() {
3073                return Err(Error::Errno(Errno::EAGAIN));
3074            }
3075        }
3076        let woken_and_moved = match futex_action(
3077            guest,
3078            FutexAction::RequeueRequest(futexid2, nr_wake as u32, nr_requeue as u32),
3079            &futexid,
3080            current,
3081            u32::MAX,
3082        )
3083        .await
3084        {
3085            Some(SchedValue::Requeued { woken, moved }) => {
3086                if self.cfg.yields_after_futex_wake(woken) {
3087                    guest.thread_state_mut().yield_after_futex_wake = true;
3088                }
3089                woken + moved
3090            }
3091            // A logically killed or replaced caller is answered with a plain value, as
3092            // its wakes are; it never returns to the guest.
3093            Some(SchedValue::Value(num)) => num,
3094            other => panic!("impossible answer to a futex requeue: {:?}", other),
3095        };
3096        let _ = futex_action(
3097            guest,
3098            FutexAction::WakeFinished(0),
3099            &futexid,
3100            current,
3101            u32::MAX,
3102        )
3103        .await;
3104        Ok(woken_and_moved as i64)
3105    }
3106
3107    /// FUTEX_WAKE_OP, as Linux's `futex_wake_op` (kernel/futex/waitwake.c), in
3108    /// its order: key both words (`futex_key`; the `uaddr` word is never read);
3109    /// apply the operation encoded in `val3` to the word at `uaddr2`
3110    /// (`futex_atomic_op_inuser`); wake up to `nr_wake` (`val`) waiters on
3111    /// `uaddr` and, if the encoded comparison of the old value holds, up to
3112    /// `nr_wake2` (`val2`, in the timeout slot) waiters on `uaddr2`. Returns the
3113    /// total woken.
3114    /// - An unknown operation is `-ENOSYS` before the word is touched; an
3115    ///   unknown comparison is `-ENOSYS` after it was written, and nobody is
3116    ///   woken. So a private NULL `uaddr2` (a valid key) with an unknown
3117    ///   operation is `-ENOSYS`.
3118    /// - The word is read and written as exactly four bytes with the guest's own
3119    ///   permissions, so an unreadable or unwritable word is `-EFAULT` and a word
3120    ///   at the end of a page next to a hole is fine.
3121    ///
3122    /// Both wakes count a waiter before comparing, so a count of 0 or below wakes
3123    /// one, and neither looks at the waiters' bitsets, as `futex_wake_op` does not.
3124    /// The read-modify-write is atomic with respect to the guest because Detcore
3125    /// runs one guest thread at a time and this one holds the turn, and only
3126    /// guest threads can reach a private or anonymous shared word. A word in a
3127    /// file-backed shared mapping can also be written by a process outside
3128    /// Hermit, which Linux's locked instruction would not lose, so that case is
3129    /// refused by name before any side effect.
3130    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/pull/4020): Review the
3131    // emulated FUTEX_WAKE_OP and its read-modify-write of the guest word.
3132    async fn handle_futex_wake_op<G: Guest<Self>>(
3133        &self,
3134        guest: &mut G,
3135        call: syscalls::Futex,
3136    ) -> Result<i64, Error> {
3137        let nr_wake = call.val();
3138        let nr_wake2 = futex_val2(&call) as i32;
3139        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
3140        let uaddr2 = futex_uaddr2(&call);
3141        let futexid = futex_key(guest, futex_uaddr(&call), private, KeyAccess::Read).await?;
3142        let futexid2 = futex_key(guest, uaddr2, private, KeyAccess::Write).await?;
3143        let op = FutexWakeOp::decode(call.val3() as u32);
3144        if !op.has_known_operation() {
3145            return Err(Error::Errno(Errno::ENOSYS));
3146        }
3147        if matches!(
3148            guest.thread_state().futex_id(uaddr2, false),
3149            FutexID::Shared {
3150                object: SharedMemoryObjectId::File { .. } | SharedMemoryObjectId::OpenFile { .. },
3151                ..
3152            }
3153        ) {
3154            return self
3155                .refuse_futex_command(
3156                    guest,
3157                    "FUTEX_WAKE_OP",
3158                    "its word is in a file-backed shared mapping that a process outside Hermit \
3159                     could update concurrently, and Detcore cannot apply the operation atomically",
3160                )
3161                .await;
3162        }
3163        let old = read_futex_word(guest, uaddr2)?;
3164        let new = op.apply(old).expect("operation was checked to be known");
3165        let word2 = AddrMut::<libc::c_int>::from_raw(uaddr2).ok_or(Errno::EFAULT)?;
3166        guest
3167            .memory()
3168            .write_value(word2, &new)
3169            .map_err(|_| Error::Errno(Errno::EFAULT))?;
3170        let Some(wake2) = op.compare(old) else {
3171            return Err(Error::Errno(Errno::ENOSYS));
3172        };
3173        let mut woken = 0;
3174        for (futex, count, wake) in [(futexid, nr_wake, true), (futexid2, nr_wake2, wake2)] {
3175            if !wake {
3176                continue;
3177            }
3178            woken += match futex_action(guest, FutexAction::WakeRequest(count), &futex, 0, u32::MAX)
3179                .await
3180            {
3181                Some(SchedValue::Value(num)) => num,
3182                other => panic!("impossible answer to a futex wake: {:?}", other),
3183            };
3184            let _ = futex_action(guest, FutexAction::WakeFinished(0), &futex, 0, u32::MAX).await;
3185        }
3186        if self.cfg.yields_after_futex_wake(woken) {
3187            guest.thread_state_mut().yield_after_futex_wake = true;
3188        }
3189        Ok(woken as i64)
3190    }
3191
3192    /// Refuse a futex command Detcore cannot serve deterministically, naming it,
3193    /// through the unsupported-syscall policy (`refuse_unserviceable_operation`).
3194    /// A run that is not fail-closed gets `-ENOSYS`, which is what Linux returns
3195    /// for every priority-inheritance command when built without CONFIG_FUTEX_PI
3196    /// (kernel/futex/pi.c, kernel/futex/requeue.c).
3197    async fn refuse_futex_command<G: Guest<Self>>(
3198        &self,
3199        guest: &mut G,
3200        name: &'static str,
3201        reason: &'static str,
3202    ) -> Result<i64, Error> {
3203        tracing::error!(
3204            "[detcore, dtid {}] futex command {} is not supported: {}",
3205            guest.thread_state().dettid,
3206            name,
3207            reason,
3208        );
3209        self.refuse_unserviceable_operation(guest, reverie::syscalls::Sysno::futex, Errno::ENOSYS)
3210            .await
3211    }
3212
3213    /// Futex system call, alternative implemenattion where we treat futexes as InternalIOPolling
3214    /// operations.
3215    pub(crate) async fn handle_futex_polling<G: Guest<Self>>(
3216        &self,
3217        guest: &mut G,
3218        call: syscalls::Futex,
3219        init_val: i32,
3220        deadline: FutexDeadline,
3221    ) -> Result<i64, Error> {
3222        fn make_futex_wake_request(dettid: DetTid) -> Resources {
3223            let mut rsrc = Resources::new(dettid);
3224            rsrc.fyi("futex_wake");
3225            rsrc
3226        }
3227
3228        fn make_futex_wait_request(dettid: DetTid) -> Resources {
3229            let mut rsrc = Resources::new(dettid);
3230            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
3231            rsrc.fyi("futex_wait");
3232            rsrc
3233        }
3234
3235        let dettid = guest.thread_state().dettid;
3236        let futex_op = call.futex_op() & libc::FUTEX_CMD_MASK;
3237        match futex_op {
3238            libc::FUTEX_WAKE | libc::FUTEX_WAKE_BITSET => {
3239                let rsrc = make_futex_wake_request(dettid);
3240                resource_request(guest, rsrc.clone()).await; // Linearize this operation as a separate COMMIT.
3241                let res = guest.inject(call).await;
3242                // FIXME: With the non-blocking version of futex_wait, `res` will always be 0.  It
3243                // is quite difficult to tell how many polling waiters we unblocked with a given
3244                // wake, without going back to modeling futexes like `handle_futex_blocking` does.
3245                Ok(res?)
3246            }
3247            libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET => {
3248                if init_val != call.val() {
3249                    info!(
3250                        "[detcore, dtid {}] Futex wait running immediately because it will fizzle ({} != {}).",
3251                        dettid,
3252                        init_val,
3253                        call.val()
3254                    );
3255                    let res = guest.inject(call).await;
3256                    Ok(res?)
3257                } else {
3258                    let rsrc = make_futex_wait_request(dettid);
3259                    let deadline = self.futex_deadline(guest, call, deadline).await?;
3260                    let res =
3261                        retry_nonblocking_syscall_with_timeout(guest, call, rsrc, deadline).await;
3262                    keep_restart_block(guest, &res, RestartCall::Futex(call), deadline).await;
3263                    let res = res?;
3264                    trace!(
3265                        "[detcore, dtid {}] after futex wait, memory value is {}",
3266                        &dettid,
3267                        guest.memory().read_value(call.uaddr().unwrap()).unwrap()
3268                    );
3269                    Ok(res)
3270                }
3271            }
3272            // `classify_futex_command` already answered every other command.
3273            _ => Err(Error::Errno(Errno::ENOSYS)),
3274        }
3275    }
3276
3277    /// The image `call` runs if it succeeds
3278    /// ([`crate::exec_record::ExecRecord::resolve`]), looked up as the kernel
3279    /// will look it up: through the calling thread's root and working
3280    /// directory, or the directory descriptor, or with `AT_EMPTY_PATH` the
3281    /// descriptor itself. `None` where Detcore cannot see the thread's
3282    /// filesystem ([`Self::guest_task_directory`]) or the kernel would
3283    /// refuse the exec; the new image's `/proc/<pid>/exe` link is then the
3284    /// kernel's.
3285    fn exec_image<G: Guest<Self>>(
3286        &self,
3287        guest: &G,
3288        call: &syscalls::Execveat,
3289    ) -> Option<crate::exec_record::ExecRecord> {
3290        let path: std::path::PathBuf = call.path()?.read(&guest.memory()).ok()?;
3291        self.exec_image_at(guest, call.dirfd(), &path)
3292    }
3293
3294    /// The image this one's exec ran, from the pathname the exec was given
3295    /// (`AT_EXECFN`), resolved as [`Self::exec_image`] resolves an `execve`'s
3296    /// from the working directory, which an exec keeps. For an exec Detcore
3297    /// did not prepare: a backend's copied vfork child runs its `execve`
3298    /// without Detcore. `None` where the auxiliary vector has no such entry
3299    /// or its string cannot be read.
3300    pub(crate) fn exec_image_from_execfn<G: Guest<Self>>(
3301        &self,
3302        guest: &G,
3303    ) -> Option<crate::exec_record::ExecRecord> {
3304        use reverie::syscalls::FromToRaw;
3305        let address = guest.auxv().at_execfn()?.as_raw();
3306        let path: std::path::PathBuf = Option::<syscalls::PathPtr>::from_raw(address)?
3307            .read(&guest.memory())
3308            .ok()?;
3309        self.exec_image_at(guest, libc::AT_FDCWD, &path)
3310    }
3311
3312    /// `Self::exec_image` for a `path` the caller already read from the
3313    /// guest: public for a backend that runs the native `execve` outside
3314    /// Detcore's handler, prepares the exec itself (`crate::prepare_exec`)
3315    /// and reads guest memory its own way.
3316    pub fn exec_image_at<G: Guest<Self>>(
3317        &self,
3318        guest: &G,
3319        dirfd: i32,
3320        path: &std::path::Path,
3321    ) -> Option<crate::exec_record::ExecRecord> {
3322        let task = self.guest_task_directory(guest)?;
3323        let root = std::fs::read_link(task.join("root")).ok()?;
3324        let inside = |link: std::path::PathBuf| {
3325            Some(std::path::Path::new("/").join(link.strip_prefix(&root).ok()?))
3326        };
3327        let cwd = inside(std::fs::read_link(task.join("cwd")).ok()?)?;
3328        let spelled = if path.is_absolute() || dirfd == libc::AT_FDCWD {
3329            cwd.join(path)
3330        } else {
3331            let descriptor = task.join("fd").join(dirfd.to_string());
3332            let directory = inside(std::fs::read_link(descriptor).ok()?)?;
3333            // An empty path names the descriptor itself; without
3334            // `AT_EMPTY_PATH` the exec fails, and the record with it.
3335            if path.as_os_str().is_empty() {
3336                directory
3337            } else {
3338                directory.join(path)
3339            }
3340        };
3341        // An exec of the caller's own `exe` link runs the image it executes,
3342        // which the link names, also where the kernel's link names the
3343        // guest's launcher (SaBRe's loader).
3344        match self.resolve_exe_subject(guest, &spelled, true) {
3345            Some(crate::syscalls::namespace::ExeLinkSubject::Own) => {
3346                return guest.thread_state().exe.as_deref().cloned();
3347            }
3348            // Another process's image, which only the coordinator records.
3349            Some(crate::syscalls::namespace::ExeLinkSubject::Other(_)) => return None,
3350            None => {}
3351        }
3352        crate::exec_record::ExecRecord::resolve(&root, &cwd, &spelled)
3353    }
3354
3355    /// Execveat system call.  Doesn't return if successful.
3356    pub async fn handle_execveat<G: Guest<Self>>(
3357        &self,
3358        guest: &mut G,
3359        call: syscalls::Execveat,
3360    ) -> Result<i64, Error> {
3361        self.promote_before_native_lifecycle(guest);
3362        let (old_metadata, old_memory_metadata, table_is_shared, dettid, detpid, old_mm_id) = {
3363            let thread_state = guest.thread_state();
3364            (
3365                Arc::clone(&thread_state.file_metadata),
3366                Arc::clone(&thread_state.memory_metadata),
3367                Arc::strong_count(&thread_state.file_metadata) > 1,
3368                thread_state.dettid,
3369                thread_state.detpid.expect("detpid unset"),
3370                thread_state.mm_id,
3371            )
3372        };
3373        let (new_metadata, closed_open_files, exec_fd_blocking) = {
3374            let metadata = old_metadata.lock().unwrap();
3375            let new_metadata = metadata.for_exec(dettid);
3376            (
3377                new_metadata.clone(),
3378                metadata.open_files_closed_on_exec(table_is_shared),
3379                new_metadata.exec_blocking_overrides(),
3380            )
3381        };
3382        let preserve_exec_fd_status = guest.config().backend.rediscovers_descriptors_after_exec;
3383        let exe = self.exec_image(guest, &call);
3384
3385        prepare_exec(
3386            guest,
3387            old_mm_id,
3388            if preserve_exec_fd_status {
3389                exec_fd_blocking
3390            } else {
3391                Default::default()
3392            },
3393            // This handler stages the exec's owner-death wakes itself, below.
3394            Vec::new(),
3395            exe,
3396        )
3397        .await;
3398
3399        let mut released_ports = Vec::new();
3400        for open_file_id in closed_open_files {
3401            if let Some(port) = self.release_port_for_open_file(guest, open_file_id).await {
3402                released_ports.push((open_file_id, port));
3403            }
3404        }
3405
3406        // A successful execve walks every robust list in the thread group
3407        // before it replaces the address space (see
3408        // `ThreadState::stage_robust_list_wakes_for_exec`), then clears
3409        // `task->robust_list`; the new image re-registers its own. Read the
3410        // lists while the old image is still mapped.
3411        // Linux marks the owner words itself at a successful exec, and a failed
3412        // exec must leave them alone, so Detcore only reads them here. Only
3413        // where Linux's exec runs under this handler ([`OwnerDeathPath::Kernel`]):
3414        // on DBT Detcore never sees the execve, and a word the native client
3415        // does not rewrite to a TID Linux knows is never marked
3416        // (https://github.com/rrnewton/hermit/issues/4268).
3417        let exec_robust_wakes = match self.robust_owner_death_path() {
3418            Some(OwnerDeathPath::Kernel) => Some(
3419                self.read_thread_group_robust_list_wakes(guest, OwnerDeath::Exec)
3420                    .await,
3421            ),
3422            Some(OwnerDeathPath::Barrier) | None => None,
3423        };
3424        let old_robust_list_head;
3425        // The exec'ing thread leads its process after a successful exec, so
3426        // the table exec gives it is the process's (`process_files`), also
3427        // for a thread that did not lead it before.
3428        let old_process_files = guest.thread_state().process_files;
3429
3430        {
3431            let thread_state = guest.thread_state_mut();
3432            thread_state.file_metadata = Arc::new(Mutex::new(new_metadata));
3433            thread_state.adopt_process_files();
3434            thread_state.memory_metadata = Arc::new(Mutex::new(MemoryMetadata::new()));
3435            thread_state.mm_id = old_mm_id.for_exec(detpid);
3436            old_robust_list_head = thread_state.take_robust_list_for_exec();
3437            if let Some(wakes) = exec_robust_wakes {
3438                thread_state.stage_robust_list_wakes_for_exec(wakes);
3439            }
3440        }
3441
3442        // execve(2) doesn't return upon success.
3443        let errno = self.record_or_replay(guest, call).await.unwrap_err();
3444        // Ask before anything else is injected: the next injection replaces
3445        // the backend's record.
3446        let refusal = guest.take_unsupported_refusal();
3447
3448        {
3449            let thread_state = guest.thread_state_mut();
3450            thread_state.file_metadata = old_metadata;
3451            thread_state.process_files = old_process_files;
3452            thread_state.memory_metadata = old_memory_metadata;
3453            thread_state.mm_id = old_mm_id;
3454            thread_state.restore_robust_list_after_failed_exec(old_robust_list_head);
3455            // The old image runs on, and so do its robust-mutex owners.
3456            thread_state.take_robust_list_wakes_for_exec();
3457        }
3458
3459        cancel_exec(guest).await;
3460        for (open_file_id, port) in released_ports {
3461            self.restore_port_for_open_file(guest, open_file_id, port)
3462                .await;
3463        }
3464
3465        // A backend that cannot perform this exec says so with a typed
3466        // refusal: for example one that cannot promote a worker thread to
3467        // group leader, which refuses after validating the replacement image,
3468        // and also when a host syscall its exec preflight makes (such as the
3469        // KVM backend's faccessat2 permission check) fails with ENOSYS.
3470        // Diagnose it only after normal failed-exec rollback. Any other
3471        // failure, including an ENOSYS the backend did not report as a
3472        // refusal, is the guest's ordinary exec error.
3473        if let Some(refusal) = refusal {
3474            tracing::error!(
3475                "[detcore, dtid {dettid}] {}; the replacement image did not run",
3476                refusal.diagnostic
3477            );
3478            if !self.cfg.panic_on_unsupported_syscalls {
3479                crate::tool_global::report_unsupported_syscall(guest, call.number()).await;
3480            }
3481            return self
3482                .refuse_unserviceable_operation_because(
3483                    guest,
3484                    call.number(),
3485                    errno,
3486                    refusal.diagnostic,
3487                )
3488                .await;
3489        }
3490
3491        Err(errno.into())
3492    }
3493
3494    // AUTONOMOUS-BOT-IMPLEMENTED
3495    // TODO-HUMAN-REVIEW(#258): Confirm one-turn exclusion semantics across scheduler modes.
3496    /// End the current logical timeslice for a sequentialized sched_yield.
3497    pub async fn handle_sched_yield<G: Guest<Self>>(
3498        &self,
3499        guest: &mut G,
3500        call: syscalls::SchedYield,
3501    ) -> Result<i64, Error> {
3502        if self.cfg.sequentialize_threads {
3503            match sched_yield_route(&self.cfg) {
3504                SchedYieldRoute::ChaosReprioritize => {
3505                    let change_time = guest.thread_state().thread_logical_time.as_nanos();
3506                    let request = Self::random_priority_changepoint_request(guest, change_time);
3507                    resource_request(guest, request).await;
3508                }
3509                SchedYieldRoute::ReplayStrongYield => {
3510                    if self.cfg.max_timeslice.is_some() {
3511                        guest
3512                            .thread_state_mut()
3513                            .reset_timeslice_for_explicit_yield();
3514                    }
3515                    let request = Self::sched_yield_request(guest);
3516                    resource_request(guest, request).await;
3517                }
3518                SchedYieldRoute::ChaosYieldEpoch => {
3519                    let request = Self::sched_yield_request(guest);
3520                    resource_request(guest, request).await;
3521                }
3522                SchedYieldRoute::WeakYield => {
3523                    let request = Self::yield_request(guest);
3524                    resource_request(guest, request).await;
3525                }
3526                SchedYieldRoute::EndTimeslice => self.end_timeslice_for_sched_yield(guest).await,
3527            }
3528            trace!("sched_yield yielded to the scheduler; NOT performing actual syscall");
3529            Ok(0)
3530        } else {
3531            Ok(self.record_or_replay(guest, call).await?)
3532        }
3533    }
3534
3535    /// `child`'s pid as the calling thread names it: its DetTid at depth 0,
3536    /// its pid in the caller's namespace below that
3537    /// (https://github.com/rrnewton/hermit/issues/4090). Detcore picks the
3538    /// child of a wait itself and injects the exact wait, which the kernel
3539    /// reads in the caller's namespace.
3540    async fn guest_visible_pid<G: Guest<Self>>(
3541        &self,
3542        guest: &mut G,
3543        sysno: reverie::syscalls::Sysno,
3544        child: DetPid,
3545    ) -> Result<i32, Error> {
3546        if !guest.thread_state().nested_pid_namespace {
3547            return Ok(child.as_raw());
3548        }
3549        let refusal = match crate::tool_global::local_pid(guest, child).await {
3550            Ok(Some(local)) => return Ok(local),
3551            Ok(None) => format!("child {child} is not visible in the caller's namespace"),
3552            Err(reason) => reason,
3553        };
3554        Err(self.refuse_nested_pid(guest, sysno, &refusal).await)
3555    }
3556
3557    /// The task a pid the kernel answered the calling thread with names: the
3558    /// pid itself at depth 0, translated from the caller's namespace below
3559    /// that, before it enters Detcore's bookkeeping
3560    /// (https://github.com/rrnewton/hermit/issues/4090).
3561    async fn task_of_guest_pid<G: Guest<Self>>(
3562        &self,
3563        guest: &mut G,
3564        sysno: reverie::syscalls::Sysno,
3565        pid: i32,
3566    ) -> Result<DetPid, Error> {
3567        if !guest.thread_state().nested_pid_namespace || pid <= 0 {
3568            return Ok(DetPid::from_raw(pid));
3569        }
3570        let refusal = match crate::tool_global::guest_pid(guest, pid).await {
3571            GuestPidAnswer::Task { task, .. } => return Ok(task),
3572            GuestPidAnswer::NoSuchPid => {
3573                format!("the kernel answered pid {pid}, which no recorded task has")
3574            }
3575            GuestPidAnswer::Untranslatable(reason) => reason,
3576        };
3577        Err(self.refuse_nested_pid(guest, sysno, &refusal).await)
3578    }
3579
3580    /// Track the pidfd a `CLONE_PIDFD` clone wrote at `address` as
3581    /// `pidfd_open`'s is tracked: a close-on-exec pidfd naming the new
3582    /// process, `child`, so that `pidfd_send_signal`, `waitid(P_PIDFD)` and
3583    /// the descriptor calls know it. Before, Detcore did not know the
3584    /// descriptor, and `pidfd_send_signal` on it failed with EBADF
3585    /// (https://github.com/rrnewton/hermit/issues/4430). The kernel installs it
3586    /// in the caller's descriptor table after copying that table for the
3587    /// child, so the child does not have it; the child's Detcore table was
3588    /// copied while the clone ran, so the same holds there.
3589    ///
3590    /// Only a child that shares neither the caller's memory nor its
3591    /// descriptor table, and is no vfork child, gets here
3592    /// (`clone_pidfd_address`), and only with sequentialized threads: no other
3593    /// task can then run between the kernel's clone and this, in the caller's
3594    /// own turn, so neither the clone's arguments nor the word nor the
3595    /// descriptor can change in between. The clone has
3596    /// succeeded whatever happens here, so nothing here fails it: a pidfd
3597    /// that cannot be tracked stays open and unknown to Detcore (EBADF through
3598    /// it, as before), and the reason is logged.
3599    async fn register_clone_pidfd<G: Guest<Self>>(
3600        &self,
3601        guest: &mut G,
3602        address: usize,
3603        child: DetTid,
3604    ) {
3605        let dettid = guest.thread_state().dettid;
3606        let skip = |reason: String| {
3607            tracing::error!(
3608                "[detcore, dtid {}] the pidfd of CLONE_PIDFD child {} is not tracked: {}; pidfd \
3609                 calls through it answer EBADF (https://github.com/rrnewton/hermit/issues/4430)",
3610                dettid,
3611                child,
3612                reason,
3613            );
3614        };
3615        let fd: libc::c_int = match Addr::<libc::c_int>::from_raw(address)
3616            .map(|address| guest.memory().read_value(address))
3617        {
3618            Some(Ok(fd)) => fd,
3619            // The kernel wrote it, or the clone would have failed with EFAULT;
3620            // a task sharing the memory may have unmapped it since.
3621            _ => return skip(format!("its word at {address:#x} cannot be read back")),
3622        };
3623        // The kernel has just allocated it, so a number Detcore already
3624        // tracks means another thread of the caller rewrote the word.
3625        if guest.thread_state().with_detfd(fd, |_| ()).is_ok() {
3626            return skip(format!(
3627                "its word names descriptor {fd}, which Detcore already tracks"
3628            ));
3629        }
3630        if let Err(errno) = self
3631            .track_held_fd(
3632                guest,
3633                fd,
3634                nix::fcntl::OFlag::O_CLOEXEC,
3635                crate::fd::FdType::Pidfd,
3636            )
3637            .await
3638        {
3639            return skip(format!("tracking descriptor {fd} failed with {errno}"));
3640        }
3641        if let Err(error) = guest.thread_state().with_detfd(fd, |detfd| {
3642            detfd.set_pidfd_target(DetPid::from_raw(child.as_raw()))
3643        }) {
3644            skip(format!("descriptor {fd} has no Detcore entry: {error}"));
3645        }
3646    }
3647
3648    /// Refuse, by name and through the unsupported-operation policy, a
3649    /// `clone3` whose `set_tid` asks for an id that a task of this run had
3650    /// (`thread_id_refused`): a reaped child's pid or an exited thread's tid,
3651    /// which Linux would give out again, or a live task's id, whose release
3652    /// can race the call (https://github.com/rrnewton/hermit/issues/4370).
3653    /// Detcore keeps per-task state by that id (the task's clock, its
3654    /// recorded schedule and preemptions, its priority), and a new task given
3655    /// it took over the old one's: the run crashed with "thread time should
3656    /// never go down", or recorded two tasks as one. `None` lets the call go
3657    /// ahead, and the kernel's own answer stands, whenever the call cannot
3658    /// reuse such an id or the kernel would fail it first: no `set_tid`; a
3659    /// `clone_args` size, exit signal or `set_tid` array the kernel rejects
3660    /// (E2BIG, EINVAL, EFAULT); a caller without the capability to choose a
3661    /// pid (EPERM); an id never used; or the pid of a zombie child of the
3662    /// caller's process (EEXIST).
3663    ///
3664    /// The entry that names Detcore's id is `set_tid[0]`, or `set_tid[1]`
3665    /// with `CLONE_NEWPID`, whose `set_tid[0]` is the pid inside the new
3666    /// namespace; any later entries name pids in the namespaces holding
3667    /// Hermit's container. Where those would make Linux fail the call, with
3668    /// EINVAL for more levels than exist or EPERM for a level the caller has
3669    /// no capability over, the refusal is given instead: the conservative
3670    /// side, since the id is not handed out either way. So is a nonzero tail
3671    /// past the fields this code knows, which a kernel that does not know
3672    /// them answers with E2BIG. From a nested PID namespace, whose pids
3673    /// Detcore does not translate for this, any `set_tid` the checks above
3674    /// let through is refused (issue 4155).
3675    async fn clone3_set_tid_refusal<G: Guest<Self>>(
3676        &self,
3677        guest: &mut G,
3678        clone: &syscalls::Clone3,
3679    ) -> Option<Result<i64, Error>> {
3680        // Refuse only a call the kernel would accept as far as `set_tid` goes:
3681        // any other shape goes to the kernel, whose own error stands, so a
3682        // refusal never replaces an E2BIG, EINVAL, EFAULT or EPERM Linux
3683        // would give for these arguments. `struct clone_args` gained `set_tid`
3684        // (offset 64) and `set_tid_size` (offset 72) with its second version,
3685        // 80 bytes.
3686        const CLONE_ARGS_SIZE_VER1: usize = 80;
3687        // The kernel's limit on PID namespace nesting (MAX_PID_NS_LEVEL).
3688        const MAX_SET_TID: u64 = 32;
3689        let size = clone.size();
3690        let page = usize::try_from(unsafe { libc::sysconf(libc::_SC_PAGESIZE) }).ok()?;
3691        if size < CLONE_ARGS_SIZE_VER1 || size > page {
3692            return None;
3693        }
3694        // The kernel copies all `size` bytes first: a fault there is its
3695        // EFAULT. A nonzero tail beyond the fields this code knows is not
3696        // read as a reason to let the call through, since a newer kernel may
3697        // accept it.
3698        let mut raw = vec![0u8; size];
3699        let memory = guest.memory();
3700        memory
3701            .read_exact(Addr::<u8>::from_raw(clone.args()?.as_raw())?, &mut raw)
3702            .ok()?;
3703        let field = |offset: usize| u64::from_ne_bytes(raw[offset..offset + 8].try_into().unwrap());
3704        let flags = field(0);
3705        let exit_signal = field(32);
3706        let set_tid = field(64);
3707        let set_tid_size = field(72);
3708        // An exit signal must be a signal number, with nothing in CSIGNAL.
3709        if exit_signal > 64 || flags & 0xff != 0 {
3710            return None;
3711        }
3712        if set_tid_size == 0 || set_tid_size > MAX_SET_TID {
3713            return None;
3714        }
3715        // The kernel copies the whole array next (EFAULT) and takes no entry
3716        // below 1 (EINVAL).
3717        let mut tids = vec![0 as libc::pid_t; set_tid_size as usize];
3718        memory
3719            .read_values(Addr::<libc::pid_t>::from_raw(set_tid as usize)?, &mut tids)
3720            .ok()?;
3721        // With CLONE_NEWPID the first entry is the pid in the new namespace,
3722        // which must be 1 since that namespace has no init yet (EINVAL).
3723        let newpid = flags & libc::CLONE_NEWPID as u64 != 0;
3724        if tids.iter().any(|tid| *tid < 1) || (newpid && tids[0] != 1) {
3725            return None;
3726        }
3727        // Choosing a pid takes CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE over
3728        // the namespace, and a caller with neither in its effective set gets
3729        // EPERM. A set that cannot be read counts as privileged, so the
3730        // refusal below still guards Detcore's state.
3731        const CAP_SYS_ADMIN: u32 = 21;
3732        const CAP_CHECKPOINT_RESTORE: u32 = 40;
3733        let thread = guest.thread_state();
3734        let status = format!(
3735            "/proc/{}/task/{}/status",
3736            thread.detpid.expect("detpid unset"),
3737            thread.dettid
3738        );
3739        let capabilities = std::fs::read_to_string(status).ok().and_then(|status| {
3740            status
3741                .lines()
3742                .find_map(|line| line.strip_prefix("CapEff:"))
3743                .and_then(|mask| u64::from_str_radix(mask.trim(), 16).ok())
3744        });
3745        let pid_capabilities = (1u64 << CAP_SYS_ADMIN) | (1u64 << CAP_CHECKPOINT_RESTORE);
3746        if capabilities.is_some_and(|mask| mask & pid_capabilities == 0) {
3747            return None;
3748        }
3749        // From a nested PID namespace the array names pids at several levels,
3750        // which Detcore does not translate for this: refuse any such call.
3751        if guest.thread_state().nested_pid_namespace {
3752            return Some(Err(self
3753                .refuse_nested_pid(
3754                    guest,
3755                    reverie::syscalls::Sysno::clone3,
3756                    "clone3 set_tid names pids in a namespace Detcore does not translate",
3757                )
3758                .await));
3759        }
3760        // The array runs from the new task's namespace outwards, so the
3761        // caller's (the container's) pid is entry 0, or entry 1 with
3762        // CLONE_NEWPID. Entries after it name pids in the namespaces holding
3763        // Hermit's container, which Detcore does not track.
3764        if set_tid_size <= u64::from(newpid) {
3765            return None;
3766        }
3767        let tid = tids[usize::from(newpid)];
3768        if !crate::tool_global::thread_id_refused(guest, DetTid::from_raw(tid)).await {
3769            return None;
3770        }
3771        let message = format!(
3772            "hermit: clone3 set_tid asks for id {tid}, which an earlier task of this run had; \
3773             Detcore keeps per-task state by that id and cannot give it to a new task \
3774             (https://github.com/rrnewton/hermit/issues/4370)"
3775        );
3776        tracing::error!(
3777            "[detcore, dtid {}] {}",
3778            guest.thread_state().dettid,
3779            message
3780        );
3781        if guest.config().panic_on_unsupported_syscalls {
3782            use std::io::Write as _;
3783            let _ = writeln!(crate::util::RetryingStderr, "{message}");
3784        }
3785        Some(
3786            self.refuse_unserviceable_operation(
3787                guest,
3788                reverie::syscalls::Sysno::clone3,
3789                Errno::EEXIST,
3790            )
3791            .await,
3792        )
3793    }
3794
3795    /// Refuse by name a call from a nested PID namespace whose pids Detcore
3796    /// cannot translate (https://github.com/rrnewton/hermit/issues/4155).
3797    async fn refuse_nested_pid<G: Guest<Self>>(
3798        &self,
3799        guest: &mut G,
3800        sysno: reverie::syscalls::Sysno,
3801        reason: &str,
3802    ) -> Error {
3803        tracing::error!(
3804            "[detcore, dtid {}] {} from a nested PID namespace is not supported: {} (https://github.com/rrnewton/hermit/issues/4155)",
3805            guest.thread_state().dettid,
3806            sysno,
3807            reason,
3808        );
3809        match self
3810            .refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
3811            .await
3812        {
3813            Err(error) => error,
3814            Ok(_) => Errno::ENOSYS.into(),
3815        }
3816    }
3817
3818    /// wait4 system call
3819    /// This is handled by the scheduler and not passed to the record/replay layer.
3820    // TODO-HUMAN-REVIEW(PR-587): Confirm wait4 rusage canonicalization boundaries.
3821    pub async fn handle_wait4<G: Guest<Self>>(
3822        &self,
3823        guest: &mut G,
3824        call: syscalls::Wait4,
3825    ) -> Result<i64, Error> {
3826        let serial_emulated_wait =
3827            guest.config().backend.emulates_child_waits && guest.config().sequentialize_threads;
3828        let mut emulated_wait_consumed = false;
3829        let dettid = guest.thread_state().dettid;
3830        let mut rsrc = Resources::new(dettid);
3831        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
3832        rsrc.fyi("wait4");
3833
3834        validate_wait4_arguments(call.pid(), call.options())?;
3835
3836        let parent = guest.thread_state().detpid.expect("detpid unset");
3837        // A nested caller names its children by its own namespace's pids
3838        // (https://github.com/rrnewton/hermit/issues/4090). Its process-group
3839        // ids are not translated yet, nor are emulated waits.
3840        let nested = guest.thread_state().nested_pid_namespace;
3841        if nested && (call.pid() == 0 || call.pid() < -1 || serial_emulated_wait) {
3842            return Err(self
3843                .refuse_nested_pid(
3844                    guest,
3845                    reverie::syscalls::Sysno::wait4,
3846                    "a process-group wait, or a wait on a backend that emulates child waits",
3847                )
3848                .await);
3849        }
3850        let named_child = if call.pid() > 0 && nested {
3851            match crate::tool_global::guest_pid(guest, call.pid()).await {
3852                GuestPidAnswer::Task { task, .. } => task,
3853                // No task of the caller's namespace has that pid, so it is
3854                // not a child: Linux answers ECHILD.
3855                GuestPidAnswer::NoSuchPid => return Err(Errno::ECHILD.into()),
3856                GuestPidAnswer::Untranslatable(reason) => {
3857                    return Err(self
3858                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::wait4, &reason)
3859                        .await);
3860                }
3861            }
3862        } else {
3863            DetPid::from_raw(call.pid())
3864        };
3865        // Stop/continue events need a backend waitability callback. Non-SIGCHLD
3866        // process clones also remain legacy until backends distinguish
3867        // PTRACE_EVENT_CLONE from CLONE_THREAD. The common matcher already
3868        // carries those filters so activation does not require another model.
3869        let selector = if !wait4_uses_terminal_selector(call.options(), serial_emulated_wait) {
3870            None
3871        } else {
3872            match call.pid() {
3873                pid if pid > 0 => Some(ChildWaitSelector::Exact(named_child)),
3874                -1 => Some(ChildWaitSelector::Any),
3875                0 => process_group(guest, parent)
3876                    .await
3877                    .map(ChildWaitSelector::ProcessGroup),
3878                pid if pid < -1 => Some(ChildWaitSelector::ProcessGroup(DetPid::from_raw(-pid))),
3879                _ => unreachable!(),
3880            }
3881        };
3882        let spec = selector
3883            .map(|selector| terminal_child_wait_spec(selector, dettid, call.options().bits()));
3884        let complete_lineage = guest.config().backend.tracks_process_children;
3885        let managed_spec = if let Some(spec) = spec {
3886            let (_, has_child) = ready_child_wait(guest, spec).await;
3887            (has_child || complete_lineage).then_some(spec)
3888        } else {
3889            None
3890        };
3891
3892        let value = if call.options().contains(WaitPidFlag::WNOHANG) {
3893            resource_request(guest, rsrc.clone()).await;
3894            info!(
3895                "[dtid {}] Executing non-blocking wait4 in one shot.",
3896                dettid
3897            );
3898            if let Some(spec) = spec {
3899                'select_child: loop {
3900                    let (ready, has_child) = ready_child_wait(guest, spec).await;
3901                    let Some(child) = ready else {
3902                        break if has_child {
3903                            0
3904                        } else if complete_lineage {
3905                            return Err(Errno::ECHILD.into());
3906                        } else {
3907                            guest.inject_with_retry(call).await?
3908                        };
3909                    };
3910                    let _ = await_exact_child_physical_exit(guest, child).await;
3911                    let exact_call = call.with_pid(
3912                        self.guest_visible_pid(guest, reverie::syscalls::Sysno::wait4, child)
3913                            .await?,
3914                    );
3915                    loop {
3916                        let result = if serial_emulated_wait {
3917                            complete_selected_emulated_wait4(guest, exact_call, child).await
3918                        } else {
3919                            guest
3920                                .inject_with_retry(exact_call)
3921                                .await
3922                                .map_err(Error::from)
3923                        };
3924                        emulated_wait_consumed =
3925                            serial_emulated_wait && matches!(result, Ok(value) if value > 0);
3926                        match result {
3927                            Ok(value) if value != 0 => break 'select_child value,
3928                            Ok(_) => yield_once().await,
3929                            Err(Error::Errno(Errno::ECHILD)) => {
3930                                let _ = consume_child_wait(guest, child).await;
3931                                if child_wait_can_retry_after_stale(spec) {
3932                                    continue 'select_child;
3933                                }
3934                                return Err(Errno::ECHILD.into());
3935                            }
3936                            Err(error) => return Err(error),
3937                        }
3938                    }
3939                }
3940            } else {
3941                guest.inject_with_retry(call).await?
3942            }
3943        } else if let Some(spec) = managed_spec {
3944            {
3945                // The ptrace backend must block ordinary signals until child
3946                // readiness is resolved. DBT already delays application signal
3947                // delivery while this callback is active, and replacing its
3948                // application mask here also hides those signals from
3949                // rt_sigpending. Read that mask without changing it instead.
3950                let blocked_mask = blocked_signal_mask();
3951                let mut stack = guest.stack().await;
3952                let blocked_mask_addr = stack.push(blocked_mask);
3953                let old_mask_addr = stack.reserve::<KernelSigset>();
3954                let action_addr = stack.reserve::<KernelSigaction>();
3955                let _mask_guard = stack.commit()?;
3956                let guest_signal_mask =
3957                    block_signals_for_disposition(guest, blocked_mask_addr, old_mask_addr).await?;
3958                let inspect_signal_action = guest
3959                    .config()
3960                    .backend
3961                    .requires_thread_directed_process_signals;
3962
3963                let poll_call = call.with_options(call.options() | WaitPidFlag::WNOHANG);
3964                let mut pending_signal = None;
3965                let result: Result<i64, Error> = loop {
3966                    let status = wait_for_child_lifecycle(guest, spec).await;
3967                    if pending_signal.is_none() {
3968                        pending_signal = wait_signal_disposition(
3969                            guest,
3970                            status,
3971                            &guest_signal_mask,
3972                            action_addr,
3973                            inspect_signal_action,
3974                        )
3975                        .await?;
3976                    }
3977                    let (ready, has_child) = ready_child_wait(guest, spec).await;
3978                    if let Some(child) = ready {
3979                        let _ = await_exact_child_physical_exit(guest, child).await;
3980                        let result = if serial_emulated_wait {
3981                            complete_selected_emulated_wait4(guest, call, child).await
3982                        } else {
3983                            match self
3984                                .guest_visible_pid(guest, reverie::syscalls::Sysno::wait4, child)
3985                                .await
3986                            {
3987                                Ok(pid) => guest
3988                                    .inject_with_retry(call.with_pid(pid))
3989                                    .await
3990                                    .map_err(Error::from),
3991                                Err(error) => Err(error),
3992                            }
3993                        };
3994                        emulated_wait_consumed =
3995                            serial_emulated_wait && matches!(result, Ok(value) if value > 0);
3996                        match result {
3997                            Ok(value) => break Ok(value),
3998                            Err(Error::Errno(Errno::ECHILD)) => {
3999                                let _ = consume_child_wait(guest, child).await;
4000                                if child_wait_can_retry_after_stale(spec) {
4001                                    let (next_ready, _) = ready_child_wait(guest, spec).await;
4002                                    if stale_any_wait_must_interrupt(
4003                                        pending_signal.is_some(),
4004                                        next_ready,
4005                                    ) {
4006                                        break interrupted_child_wait_result(
4007                                            guest,
4008                                            call,
4009                                            pending_signal.expect("signal checked above"),
4010                                        )
4011                                        .await;
4012                                    }
4013                                    continue;
4014                                }
4015                                break Err(Errno::ECHILD.into());
4016                            }
4017                            Err(error) => break Err(error),
4018                        }
4019                    }
4020                    if !has_child {
4021                        break Err(Errno::ECHILD.into());
4022                    }
4023                    if serial_emulated_wait {
4024                        // A broad backend poll can become consuming while the
4025                        // owner callback is still publishing logical/CPU state.
4026                        // Only a selected exact identity may cross that boundary.
4027                        if let Some(disposition) = pending_signal {
4028                            break interrupted_child_wait_result(guest, call, disposition).await;
4029                        }
4030                        continue;
4031                    }
4032                    match guest.inject(poll_call).await {
4033                        Ok(value) => {
4034                            if value > 0 {
4035                                break Ok(value);
4036                            }
4037                            if let Some(disposition) = pending_signal {
4038                                break interrupted_child_wait_result(guest, call, disposition)
4039                                    .await;
4040                            }
4041                        }
4042                        Err(errno) => break Err(errno.into()),
4043                    }
4044                };
4045
4046                restore_signals_after_disposition(guest, old_mask_addr).await?;
4047                result?
4048            }
4049        } else {
4050            // wait4 is a scheduler poll, not a record/replay data read (see doc above),
4051            // so it is not routed through the record/replay subtool.
4052            retry_nonblocking_syscall(guest, call, rsrc, None).await?
4053        };
4054        // The kernel answered in the caller's namespace; the guest gets that
4055        // pid, and Detcore's bookkeeping the task it names.
4056        let reaped = if value > 0 {
4057            self.task_of_guest_pid(guest, reverie::syscalls::Sysno::wait4, value as i32)
4058                .await?
4059        } else {
4060            DetPid::from_raw(value as i32)
4061        };
4062        let consumed_termination = if emulated_wait_consumed || value <= 0 {
4063            false
4064        } else if let Some(status) = call.wstatus() {
4065            wait_status_is_termination(guest.memory().read_value(status)?)
4066        } else if !call
4067            .options()
4068            .intersects(WaitPidFlag::WUNTRACED | WaitPidFlag::WCONTINUED)
4069        {
4070            // Without them, wait4 reports only a child that terminated. (The
4071            // exited child's CPU time is recorded where its own Tool runs,
4072            // which on the in-guest backends is not the parent's, so it
4073            // cannot tell; https://github.com/rrnewton/hermit/issues/4266.)
4074            true
4075        } else {
4076            // A stop or continue report leaves the child running; once it
4077            // has exited, the report was its termination.
4078            guest
4079                .thread_state()
4080                .has_exited_child_process_cpu_time(reaped)
4081                || matches!(
4082                    crate::tool_global::exact_child_wait_state(guest, reaped).await,
4083                    ExactChildWaitState::LogicallyExited
4084                        | ExactChildWaitState::PhysicalExitPending
4085                        | ExactChildWaitState::PhysicallyExited
4086                )
4087        };
4088        if consumed_termination {
4089            guest.thread_state_mut().reap_child_process_cpu_time(reaped);
4090            let _ = consume_child_wait(guest, reaped).await;
4091        }
4092        if value > 0
4093            && let Some(rusage) = call.rusage()
4094        {
4095            // Host CPU and scheduling counters are not deterministic.
4096            let usage: libc::rusage = unsafe { std::mem::zeroed() };
4097            guest.memory().write_value(rusage, &usage)?;
4098        }
4099        Ok(value)
4100    }
4101
4102    // AUTONOMOUS-BOT-IMPLEMENTED
4103    // TODO-HUMAN-REVIEW(#274): Review waitid polling and compatibility boundaries.
4104    // TODO-HUMAN-REVIEW(#2246): Review waitid progress and child-ready signal precedence.
4105    /// waitid system call
4106    /// This is handled by the scheduler and not passed to the record/replay layer.
4107    pub async fn handle_waitid<G: Guest<Self>>(
4108        &self,
4109        guest: &mut G,
4110        mut call: syscalls::Waitid,
4111    ) -> Result<i64, Error> {
4112        // A backend that emulates child waits (today KVM) can delegate ordered
4113        // user copyout to itself on the serial path. Enter before the legacy
4114        // NULL rejection and whole-siginfo writes; ptrace, DBT and
4115        // nonsequential execution retain their existing path.
4116        if guest.config().backend.emulates_child_waits && guest.config().sequentialize_threads {
4117            // Its selector reads the guest's pid as a DetPid
4118            // (`emulated_waitid::handle`), so a nested caller is refused by name
4119            // (https://github.com/rrnewton/hermit/issues/4155).
4120            if guest.thread_state().nested_pid_namespace {
4121                return Err(self
4122                    .refuse_nested_pid(
4123                        guest,
4124                        reverie::syscalls::Sysno::waitid,
4125                        "a wait on a backend that emulates child waits",
4126                    )
4127                    .await);
4128            }
4129            return emulated_waitid::handle(guest, call).await;
4130        }
4131        // A nested caller names its children by its own namespace's pids
4132        // (https://github.com/rrnewton/hermit/issues/4090); its process-group
4133        // ids are not translated yet.
4134        let nested = guest.thread_state().nested_pid_namespace;
4135        if nested && call.which() == libc::P_PGID as i32 {
4136            return Err(self
4137                .refuse_nested_pid(
4138                    guest,
4139                    reverie::syscalls::Sysno::waitid,
4140                    "a process-group wait",
4141                )
4142                .await);
4143        }
4144        let named_child = if nested && call.which() == libc::P_PID as i32 && call.pid() > 0 {
4145            match crate::tool_global::guest_pid(guest, call.pid()).await {
4146                GuestPidAnswer::Task { task, .. } => task,
4147                GuestPidAnswer::NoSuchPid => return Err(Errno::ECHILD.into()),
4148                GuestPidAnswer::Untranslatable(reason) => {
4149                    return Err(self
4150                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::waitid, &reason)
4151                        .await);
4152                }
4153            }
4154        } else {
4155            DetPid::from_raw(call.pid())
4156        };
4157        let dettid = guest.thread_state().dettid;
4158        let mut rsrc = Resources::new(dettid);
4159        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
4160        rsrc.fyi("waitid");
4161
4162        let event_options = libc::WEXITED | libc::WSTOPPED | libc::WCONTINUED;
4163        let allowed_options = event_options
4164            | libc::WNOHANG
4165            | libc::WNOWAIT
4166            | libc::__WNOTHREAD
4167            | libc::__WALL
4168            | libc::__WCLONE;
4169        if call.options() & event_options == 0 || call.options() & !allowed_options != 0 {
4170            return Err(Errno::EINVAL.into());
4171        }
4172
4173        // POSIX requires non-null infop. Linux accepts null, but that form can
4174        // expose host rusage and requires backend-neutral scratch memory for
4175        // deterministic polling. Reject it uniformly instead of diverging or
4176        // panicking on DBT's unsupported scratch stack.
4177        if call.info().is_none() {
4178            return Err(Errno::EFAULT.into());
4179        }
4180
4181        // Keep clone-class waits on the legacy path until ptrace and KVM both
4182        // register non-SIGCHLD clone children as processes rather than threads.
4183        let terminal_events_only = call.options() & libc::WEXITED != 0
4184            && call.options() & (libc::WSTOPPED | libc::WCONTINUED | libc::__WCLONE | libc::__WALL)
4185                == 0;
4186
4187        // The parked nonterminal path still uses kernel polling. Preserve its
4188        // P_PGID(0) entry snapshot until backend lifecycle events replace it.
4189        if !terminal_events_only && call.which() == libc::P_PGID as i32 && call.pid() == 0 {
4190            call = call.with_pid(snapshot_process_group(guest.pid())?);
4191        }
4192
4193        // A blocking waitid on an O_NONBLOCK pidfd must return EAGAIN rather
4194        // than being converted to WNOHANG. Acquire the scheduler resource first,
4195        // then snapshot fdinfo and issue the one-shot wait without another yield.
4196        let pidfd_nonblocking =
4197            if call.which() == libc::P_PIDFD as i32 && call.options() & libc::WNOHANG == 0 {
4198                resource_request(guest, rsrc.clone()).await;
4199                guest_fd_status_flags(guest.pid(), call.pid())? & libc::O_NONBLOCK != 0
4200            } else {
4201                false
4202            };
4203        if call.which() == libc::P_PIDFD as i32
4204            && call.options() & libc::WNOHANG == 0
4205            && !pidfd_nonblocking
4206        {
4207            // Polling a numeric pidfd cannot preserve Linux's held file
4208            // reference if another thread closes and reuses the descriptor.
4209            // Reject the blocking form until Detcore can retain that identity.
4210            return Err(Errno::EOPNOTSUPP.into());
4211        }
4212        let info = call.info().expect("waitid infop checked above");
4213
4214        // Unlike wait4, waitid returns zero both when it reports a child event and
4215        // when WNOHANG finds nothing. Polling must inspect si_pid to distinguish
4216        // those cases.
4217        // Known limitation: without backend-neutral scratch memory, an invalid
4218        // non-null infop faults on the first physical poll rather than after a
4219        // child becomes waitable.
4220        // siginfo_t has no portable initializer. An all-zero value is the
4221        // waitid WNOHANG sentinel defined by POSIX and Linux.
4222        let empty_info: libc::siginfo_t = unsafe { std::mem::zeroed() };
4223
4224        // The lifecycle scheduler currently models terminal child events for
4225        // exact and any-child selectors. Group membership and stop/continue
4226        // state remain on the legacy kernel-polling path.
4227        let terminal_spec = if terminal_events_only {
4228            let selector = match call.which() {
4229                which if which == libc::P_PID as i32 => Some(ChildWaitSelector::Exact(named_child)),
4230                which if which == libc::P_ALL as i32 => Some(ChildWaitSelector::Any),
4231                which if which == libc::P_PGID as i32 => {
4232                    let group = if call.pid() == 0 {
4233                        process_group(guest, guest.thread_state().detpid.expect("detpid unset"))
4234                            .await
4235                    } else {
4236                        Some(DetPid::from_raw(call.pid()))
4237                    };
4238                    group.map(ChildWaitSelector::ProcessGroup)
4239                }
4240                _ => None,
4241            };
4242            selector.map(|selector| terminal_child_wait_spec(selector, dettid, call.options()))
4243        } else {
4244            None
4245        };
4246        let complete_lineage = guest.config().backend.tracks_process_children;
4247        let managed_terminal_spec = if let Some(spec) = terminal_spec {
4248            let (_, has_child) = ready_child_wait(guest, spec).await;
4249            (has_child || complete_lineage).then_some(spec)
4250        } else {
4251            None
4252        };
4253
4254        if call.options() & libc::WNOHANG != 0 || pidfd_nonblocking {
4255            if !pidfd_nonblocking {
4256                resource_request(guest, rsrc).await;
4257            }
4258            info!(
4259                "[dtid {}] Executing non-blocking waitid in one shot.",
4260                dettid
4261            );
4262            'select_child: loop {
4263                let selected = if let Some(spec) = terminal_spec {
4264                    let (ready, has_child) = ready_child_wait(guest, spec).await;
4265                    if ready.is_none() && has_child {
4266                        guest.memory().write_value(info, &empty_info)?;
4267                        return Ok(0);
4268                    }
4269                    if ready.is_none() && complete_lineage {
4270                        return Err(Errno::ECHILD.into());
4271                    }
4272                    ready
4273                } else {
4274                    None
4275                };
4276                if let Some(child) = selected {
4277                    let _ = await_exact_child_physical_exit(guest, child).await;
4278                }
4279                let effective_call = match selected {
4280                    Some(child) => call.with_which(libc::P_PID as i32).with_pid(
4281                        self.guest_visible_pid(guest, reverie::syscalls::Sysno::waitid, child)
4282                            .await?,
4283                    ),
4284                    None => call,
4285                };
4286                loop {
4287                    guest.memory().write_value(info, &empty_info)?;
4288                    let value = match guest.inject_with_retry(effective_call).await {
4289                        Ok(value) => value,
4290                        Err(Errno::ECHILD) if selected.is_some() => {
4291                            let child = selected.expect("selected child checked above");
4292                            let _ = consume_child_wait(guest, child).await;
4293                            if terminal_spec.is_some_and(child_wait_can_retry_after_stale) {
4294                                continue 'select_child;
4295                            }
4296                            return Err(Errno::ECHILD.into());
4297                        }
4298                        Err(errno) => return Err(errno.into()),
4299                    };
4300                    let info_value: libc::siginfo_t = guest.memory().read_value(info)?;
4301                    let child_pid = unsafe { info_value.si_pid() };
4302                    if child_pid == 0 && selected.is_some() {
4303                        yield_once().await;
4304                        continue;
4305                    }
4306                    let consumed = child_pid != 0
4307                        && call.options() & libc::WNOWAIT == 0
4308                        && waitid_code_is_termination(info_value.si_code);
4309                    let child = self
4310                        .task_of_guest_pid(guest, reverie::syscalls::Sysno::waitid, child_pid)
4311                        .await?;
4312                    let result = finish_waitid_result(guest, call, value, info_value, child)?;
4313                    if consumed {
4314                        let _ = consume_child_wait(guest, child).await;
4315                    }
4316                    return Ok(result);
4317                }
4318            }
4319        }
4320
4321        {
4322            // A signal can arrive after the scheduler wakes this logical wait but
4323            // before the zero-timeout kernel probe that resolves Linux's
4324            // child-ready-versus-interrupt precedence. The ptrace backend blocks
4325            // ordinary signals across that probe, then restores the guest's exact
4326            // mask before returning. DBT reads the mask without replacing it because
4327            // DynamoRIO already delays application delivery while this callback runs.
4328            // The tracer's private preemption signal must remain unblocked.
4329            let blocked_mask = blocked_signal_mask();
4330            let mut stack = guest.stack().await;
4331            let blocked_mask_addr = stack.push(blocked_mask);
4332            let old_mask_addr = stack.reserve::<KernelSigset>();
4333            let action_addr = stack.reserve::<KernelSigaction>();
4334            let _mask_guard = stack.commit()?;
4335            let guest_signal_mask =
4336                block_signals_for_disposition(guest, blocked_mask_addr, old_mask_addr).await?;
4337            let inspect_signal_action = guest
4338                .config()
4339                .backend
4340                .requires_thread_directed_process_signals;
4341
4342            let poll_call = call.with_options(call.options() | libc::WNOHANG);
4343            let mut pending_signal = None;
4344            let result: Result<i64, Error> = loop {
4345                // Match the polling protocol used by wait4: the first request with
4346                // poll_attempt zero establishes an ordinary runnable turn, while later
4347                // nonzero attempts receive the scheduler's poller backoff. Omitting the
4348                // first request starts directly as a poller and can keep the run queue
4349                // nonempty forever, preventing logical time from reaching a pending
4350                // signal's deadline.
4351                //
4352                // Do not return on Signaled yet. Linux lets an already-waitable child
4353                // status win over an interrupt, so the zero-timeout kernel probe below
4354                // remains authoritative when readiness and a signal coincide.
4355                let managed_spec = managed_terminal_spec;
4356                // Both ways of parking inside waitid -- the scheduler-managed child
4357                // wait and the legacy kernel-polling loop -- can now be resumed with
4358                // the signals that woke the thread, so both consult the guest mask.
4359                let status = if let Some(spec) = managed_spec {
4360                    wait_for_child_lifecycle(guest, spec).await
4361                } else {
4362                    resource_request(guest, rsrc.clone()).await
4363                };
4364                if pending_signal.is_none() {
4365                    pending_signal = wait_signal_disposition(
4366                        guest,
4367                        status,
4368                        &guest_signal_mask,
4369                        action_addr,
4370                        inspect_signal_action,
4371                    )
4372                    .await?;
4373                }
4374                let (ready, has_child) = if let Some(spec) = managed_spec {
4375                    ready_child_wait(guest, spec).await
4376                } else {
4377                    (None, true)
4378                };
4379                if let Some(child) = ready {
4380                    let _ = await_exact_child_physical_exit(guest, child).await;
4381                    if let Err(error) = guest.memory().write_value(info, &empty_info) {
4382                        break Err(error.into());
4383                    }
4384                    let pid = match self
4385                        .guest_visible_pid(guest, reverie::syscalls::Sysno::waitid, child)
4386                        .await
4387                    {
4388                        Ok(pid) => pid,
4389                        Err(error) => break Err(error),
4390                    };
4391                    let exact_call = call.with_which(libc::P_PID as i32).with_pid(pid);
4392                    match guest.inject_with_retry(exact_call).await {
4393                        Ok(value) => {
4394                            let info_value: libc::siginfo_t = match guest.memory().read_value(info)
4395                            {
4396                                Ok(value) => value,
4397                                Err(error) => break Err(error.into()),
4398                            };
4399                            let reported = match self
4400                                .task_of_guest_pid(
4401                                    guest,
4402                                    reverie::syscalls::Sysno::waitid,
4403                                    unsafe { info_value.si_pid() },
4404                                )
4405                                .await
4406                            {
4407                                Ok(task) => task,
4408                                Err(error) => break Err(error),
4409                            };
4410                            break finish_waitid_result(guest, call, value, info_value, reported);
4411                        }
4412                        Err(Errno::ECHILD) => {
4413                            let _ = consume_child_wait(guest, child).await;
4414                            if managed_spec.is_some_and(child_wait_can_retry_after_stale) {
4415                                let (next_ready, _) =
4416                                    ready_child_wait(guest, managed_spec.expect("managed spec"))
4417                                        .await;
4418                                if stale_any_wait_must_interrupt(
4419                                    pending_signal.is_some(),
4420                                    next_ready,
4421                                ) {
4422                                    break interrupted_child_wait_result(
4423                                        guest,
4424                                        call,
4425                                        pending_signal.expect("signal checked above"),
4426                                    )
4427                                    .await;
4428                                }
4429                                continue;
4430                            }
4431                            break Err(Errno::ECHILD.into());
4432                        }
4433                        Err(errno) => break Err(errno.into()),
4434                    }
4435                }
4436                if managed_spec.is_some() && !has_child {
4437                    break Err(Errno::ECHILD.into());
4438                }
4439
4440                if let Err(error) = guest.memory().write_value(info, &empty_info) {
4441                    break Err(error.into());
4442                }
4443                let result = guest.inject(poll_call).await;
4444                match result {
4445                    Ok(value) => {
4446                        let info_value: libc::siginfo_t = match guest.memory().read_value(info) {
4447                            Ok(value) => value,
4448                            Err(error) => break Err(error.into()),
4449                        };
4450                        // waitid writes the SIGCHLD variant of siginfo_t. A zeroed
4451                        // structure is used only for the no-event WNOHANG result.
4452                        let child_pid = unsafe { info_value.si_pid() };
4453                        match exact_wait_poll_decision(
4454                            child_pid != 0,
4455                            pending_signal.is_some(),
4456                            None,
4457                        ) {
4458                            ExactWaitPollDecision::ChildReady => {
4459                                let reported = match self
4460                                    .task_of_guest_pid(
4461                                        guest,
4462                                        reverie::syscalls::Sysno::waitid,
4463                                        child_pid,
4464                                    )
4465                                    .await
4466                                {
4467                                    Ok(task) => task,
4468                                    Err(error) => break Err(error),
4469                                };
4470                                break finish_waitid_result(
4471                                    guest, call, value, info_value, reported,
4472                                );
4473                            }
4474                            ExactWaitPollDecision::Interrupted => {
4475                                break interrupted_child_wait_result(
4476                                    guest,
4477                                    call,
4478                                    pending_signal.expect("signal checked above"),
4479                                )
4480                                .await;
4481                            }
4482                            ExactWaitPollDecision::Retry => {}
4483                            ExactWaitPollDecision::AwaitPhysicalExit
4484                            | ExactWaitPollDecision::ReapAfterLogicalExit => unreachable!(),
4485                        }
4486                        if managed_spec.is_some() {
4487                            if !has_child {
4488                                break Ok(value);
4489                            }
4490                            continue;
4491                        }
4492                        rsrc.poll_attempt += 1;
4493                        trace!(
4494                            "Retry #{} for waitid because no child state is ready",
4495                            rsrc.poll_attempt
4496                        );
4497                        record_retry_event(guest, poll_call).await;
4498                    }
4499                    Err(Errno::ERESTARTSYS) if pending_signal.is_some() => {
4500                        break Err(Errno::EINTR.into());
4501                    }
4502                    Err(errno) => break Err(errno.into()),
4503                }
4504            };
4505
4506            restore_signals_after_disposition(guest, old_mask_addr).await?;
4507            if result.is_ok() && call.options() & libc::WNOWAIT == 0 {
4508                let info_value: libc::siginfo_t = guest.memory().read_value(info)?;
4509                let child_pid = unsafe { info_value.si_pid() };
4510                if child_pid != 0 && waitid_code_is_termination(info_value.si_code) {
4511                    let child = self
4512                        .task_of_guest_pid(guest, reverie::syscalls::Sysno::waitid, child_pid)
4513                        .await?;
4514                    let _ = consume_child_wait(guest, child).await;
4515                }
4516            }
4517            result
4518        }
4519    }
4520
4521    // AUTONOMOUS-BOT-IMPLEMENTED
4522    // TODO-HUMAN-REVIEW(#546)
4523    /// Accept valid affinity masks without changing the host scheduler.
4524    pub async fn handle_sched_setaffinity<G: Guest<Self>>(
4525        &self,
4526        guest: &mut G,
4527        call: syscalls::SchedSetaffinity,
4528    ) -> Result<i64, Error> {
4529        let size_bytes = call.len() as usize;
4530        if size_bytes == 0 {
4531            return Err(Errno::EINVAL.into());
4532        }
4533
4534        let mask = call.mask().ok_or(Errno::EFAULT)?;
4535        let mask: Addr<u8> = mask.cast();
4536        let mut requested = [0u8; VIRTUAL_CPUSET_BYTES];
4537        let bytes_to_read = size_bytes.min(VIRTUAL_CPUSET_BYTES);
4538        guest
4539            .memory()
4540            .read_exact(mask, &mut requested[..bytes_to_read])?;
4541        info!(
4542            "Suppressing sched_setaffinity mask {:?}; affinity remains virtual CPU 0",
4543            requested
4544        );
4545        Ok(0)
4546    }
4547
4548    // AUTONOMOUS-BOT-IMPLEMENTED
4549    // TODO-HUMAN-REVIEW(#546)
4550    /// Report that we are on cpu 0, irrespective of what physical CPU we are on.
4551    ///
4552    /// Linux's `sched_getaffinity` accepts any length whose bits cover
4553    /// `nr_cpu_ids` (one, for Hermit's single virtual CPU) and that is a
4554    /// multiple of `sizeof(long)`, copies `min(len, cpumask_size())` bytes and
4555    /// returns that count. Detcore's mask is `VIRTUAL_CPUSET_BYTES` long
4556    /// (`kernel_max` 127), so an 8-byte set, which `CPU_ALLOC` gives for the
4557    /// one CPU that `sysconf(_SC_NPROCESSORS_CONF)` reports, receives its
4558    /// first 8 bytes (<https://github.com/rrnewton/hermit/issues/4160>).
4559    pub async fn handle_sched_getaffinity<G: Guest<Self>>(
4560        &self,
4561        guest: &mut G,
4562        call: syscalls::SchedGetaffinity,
4563    ) -> Result<i64, Error> {
4564        let size_bytes: usize = call.len() as usize;
4565        if size_bytes == 0 || !size_bytes.is_multiple_of(std::mem::size_of::<libc::c_ulong>()) {
4566            return Err(Errno::EINVAL.into());
4567        }
4568        let copied = size_bytes.min(VIRTUAL_CPUSET_BYTES);
4569
4570        // N.B. we can't use an opaque, type-safe representation such as
4571        // nix::sched::CpuSet currently.  The problem is that the
4572        // SchedGetAffinity syscall treats this field as a u64.
4573        let mut cpu_set = [0u8; VIRTUAL_CPUSET_BYTES];
4574        cpu_set[0] = 1;
4575
4576        info!(
4577            "Suppressing sched_getaffinity and returning {}-byte virtualized result, {:?}",
4578            copied,
4579            &cpu_set[..copied]
4580        );
4581        if let Some(mask) = call.mask() {
4582            let mask: AddrMut<u8> = mask.cast();
4583            guest.memory().write_exact(mask, &cpu_set[..copied])?;
4584            // From the man page:
4585            // > On success, the raw sched_getaffinity() system call returns the size (in bytes) of
4586            // > the cpumask_t data type that is used internally by the kernel to represent the CPU
4587            // > set bit mask.
4588            // Linux returns the bytes it copied, the smaller of that size and the caller's.
4589            Ok(copied as i64)
4590        } else {
4591            Err(Error::Errno(Errno::EFAULT))
4592        }
4593    }
4594
4595    /// sched_getparam under Hermit. Detcore replaces the Linux scheduler with its
4596    /// own deterministic one, so a thread's Linux scheduling parameters are
4597    /// inert. Report a fixed SCHED_OTHER priority of 0. The value is emulated
4598    /// (never injected), so it is identical across --verify runs and
4599    /// record/replay.
4600    // AUTONOMOUS-BOT-IMPLEMENTED
4601    // TODO-HUMAN-REVIEW(#720)
4602    pub async fn handle_sched_getparam<G: Guest<Self>>(
4603        &self,
4604        guest: &mut G,
4605        call: syscalls::SchedGetparam,
4606    ) -> Result<i64, Error> {
4607        if let Some(param) = call.param() {
4608            let p = libc::sched_param { sched_priority: 0 };
4609            guest.memory().write_value(param, &p)?;
4610        }
4611        Ok(0)
4612    }
4613
4614    /// sched_rr_get_interval under Hermit. The round-robin quantum is a property
4615    /// of the Linux scheduler, which Detcore does not use, so report a fixed zero
4616    /// interval. Being a constant, it is deterministic across --verify and
4617    /// record/replay.
4618    // AUTONOMOUS-BOT-IMPLEMENTED
4619    // TODO-HUMAN-REVIEW(#720)
4620    pub async fn handle_sched_rr_get_interval<G: Guest<Self>>(
4621        &self,
4622        guest: &mut G,
4623        call: syscalls::SchedRrGetInterval,
4624    ) -> Result<i64, Error> {
4625        if let Some(tp) = call.tp() {
4626            let t = Timespec {
4627                tv_sec: 0,
4628                tv_nsec: 0,
4629            };
4630            guest.memory().write_value(tp, &t)?;
4631        }
4632        Ok(0)
4633    }
4634
4635    /// sched_getattr under Hermit. Detcore replaces the Linux scheduler with its
4636    /// own deterministic one, so a thread's Linux scheduling attributes are inert.
4637    /// Report a fixed SCHED_OTHER policy with zeroed nice/priority/flags. The
4638    /// value is emulated (never injected), so it is identical across --verify runs
4639    /// and record/replay. Re-enables `chrt` under --strict.
4640    // AUTONOMOUS-BOT-IMPLEMENTED
4641    // TODO-HUMAN-REVIEW(#791)
4642    pub async fn handle_sched_getattr<G: Guest<Self>>(
4643        &self,
4644        guest: &mut G,
4645        call: syscalls::SchedGetattr,
4646    ) -> Result<i64, Error> {
4647        // `flags` is reserved and must be zero; the kernel rejects anything else.
4648        if call.flags() != 0 {
4649            return Err(Errno::EINVAL.into());
4650        }
4651        // The caller must provide room for at least the base sched_attr (VER0).
4652        let attr_size = std::mem::size_of::<libc::sched_attr>();
4653        if (call.size() as usize) < attr_size {
4654            return Err(Errno::EINVAL.into());
4655        }
4656        let attr = call.attr().ok_or(Errno::EINVAL)?;
4657        // SAFETY: sched_attr is a plain-old-data struct; an all-zero bit pattern is
4658        // a valid SCHED_OTHER descriptor (nice/priority/flags/runtime/... all 0).
4659        let mut sa: libc::sched_attr = unsafe { std::mem::zeroed() };
4660        sa.size = attr_size as u32;
4661        sa.sched_policy = libc::SCHED_OTHER as u32;
4662        // SAFETY: reinterpret the POD struct as its raw bytes to copy it into the
4663        // guest's buffer.
4664        let bytes = unsafe {
4665            std::slice::from_raw_parts(&sa as *const libc::sched_attr as *const u8, attr_size)
4666        };
4667        let dst: AddrMut<u8> = attr.cast();
4668        guest.memory().write_exact(dst, bytes)?;
4669        info!(
4670            "Emulating sched_getattr(pid={}): fixed SCHED_OTHER, nice 0, priority 0",
4671            call.pid()
4672        );
4673        Ok(0)
4674    }
4675
4676    // AUTONOMOUS-BOT-IMPLEMENTED
4677    // TODO-HUMAN-REVIEW(PR-841): Review virtual sched_setattr no-op policy.
4678    /// Linux scheduler attributes cannot affect Detcore's replacement
4679    /// scheduler, so a *well-formed* request is accepted as a deterministic
4680    /// no-op, matching the existing sched_setscheduler and sched_setparam
4681    /// policy.
4682    ///
4683    /// Suppressing the effect is not the same as accepting arguments Linux
4684    /// refuses, nor as refusing arguments Linux accepts. Both directions are
4685    /// guest-visible: a probe that expects EINVAL and sees success takes the
4686    /// wrong branch, and so does one that expects success and sees E2BIG.
4687    ///
4688    /// The order below is the kernel's, and it is guest-visible when two
4689    /// arguments are wrong at once, because the kernel returns the *first*
4690    /// applicable error. `sched_setattr()` screens `uattr`, `pid` and `flags`
4691    /// together; `sched_copy_attr()` then handles the size, the trailing bytes
4692    /// and the util-clamp size rule; the signed-policy test follows; the target
4693    /// pid is resolved *there*, in the middle; and only then does
4694    /// `__sched_setscheduler()` judge the policy, the flags, the priority and
4695    /// the deadline parameters. Putting any of that last group before the pid
4696    /// lookup makes a request against a nonexistent pid report EINVAL where
4697    /// Linux reports ESRCH.
4698    ///
4699    /// # Determinism
4700    ///
4701    /// Every check is a pure function of the guest's own arguments. The one
4702    /// piece of state consulted is the pid lookup, which asks the scheduler's
4703    /// own task table via `thread_is_live` -- Detcore state, replayed
4704    /// identically -- rather than the host's process table, which would leak
4705    /// unrelated host processes into a guest-visible answer.
4706    ///
4707    /// Specifically NOT `tool_global::resolve_kill_targets`, which
4708    /// models `kill(2)` and so recognises only thread-group leaders; asking it
4709    /// this question reports ESRCH for a live non-leader thread.
4710    ///
4711    /// # Deliberately not emulated
4712    ///
4713    /// Three behaviours are excluded, under one rule: **an answer that depends
4714    /// on the host's kernel configuration or the caller's privileges is not
4715    /// reproduced, because a deterministic sandbox must not vary with the
4716    /// machine underneath it.** Each was measured natively and would differ on
4717    /// a differently-built or differently-privileged host:
4718    ///
4719    /// * EPERM for a real-time priority, a SCHED_DEADLINE admission, or a
4720    ///   negative nice, which depends on `CAP_SYS_NICE` and `RLIMIT_RTPRIO`.
4721    /// * EOPNOTSUPP for util-clamp on a VER1 buffer, which depends on
4722    ///   `CONFIG_UCLAMP_TASK`.
4723    /// * The `sysctl_sched_dl_period_{min,max}` bound on SCHED_DEADLINE
4724    ///   periods, which is runtime-tunable.
4725    ///
4726    /// In all three Hermit accepts the request as the same no-op as any other
4727    /// well-formed one. The same rule is why SCHED_EXT (policy 7) is accepted
4728    /// unconditionally even though `valid_policy()` admits it only with
4729    /// `CONFIG_SCHED_CLASS_EXT`: picking one answer keeps the sandbox stable
4730    /// across hosts, and accepting is the choice consistent with suppressing
4731    /// the effect rather than refusing the request.
4732    ///
4733    /// The bracketed regression test in `hermit-cli/tests/sched_setattr_abi.rs`
4734    /// compares Hermit against the running kernel case by case, and therefore
4735    /// deliberately omits exactly these cases -- including them would make its
4736    /// verdict depend on the host it runs on.
4737    pub async fn handle_sched_setattr<G: Guest<Self>>(
4738        &self,
4739        guest: &mut G,
4740        call: syscalls::SchedSetattr,
4741    ) -> Result<i64, Error> {
4742        // `if (!uattr || pid < 0 || flags)` -- one clause in the kernel, so all
4743        // three are EINVAL and none of them is ordered against the others. A
4744        // null pointer is EINVAL rather than EFAULT because it is refused
4745        // before any access is attempted.
4746        if call.flags() != 0 || call.pid() < 0 {
4747            return Err(Errno::EINVAL.into());
4748        }
4749        let attr = call.attr().ok_or(Errno::EINVAL)?;
4750
4751        // `get_user(size, &uattr->size)` -- the declared size is read before
4752        // anything else, and a fault here is EFAULT with no store back.
4753        // `AddrMut` is not `Copy` and `cast` consumes it, so each access below
4754        // re-derives the address from the syscall argument.
4755        // A fault reading guest memory is EFAULT for this syscall. The
4756        // backend's memory layer reports a failed peek as EIO, which is not an
4757        // errno `sched_setattr` can return, so it is mapped here; measured
4758        // native, an unmapped `uattr` gives EFAULT.
4759        let declared: u32 = guest
4760            .memory()
4761            .read_value(attr.cast())
4762            .map_err(|_| Errno::EFAULT)?;
4763
4764        // Both E2BIG exits below run the kernel's `err_size` path, which stores
4765        // the kernel's own struct size into `uattr->size` before returning. A
4766        // guest that reads the field back learns the size it should have sent,
4767        // which is the entire point of the store; the kernel ignores whether it
4768        // succeeds, and so do we.
4769        fn refuse_too_big<S: MemoryAccess>(mut memory: S, attr: AddrMut<libc::c_void>) -> Error {
4770            let _ = memory.write_value(attr.cast::<u32>(), &SCHED_ATTR_KERNEL_SIZE);
4771            Errno::E2BIG.into()
4772        }
4773
4774        let size = match sched_attr_effective_size(declared) {
4775            Ok(size) => size,
4776            Err(()) => {
4777                let back = call.attr().ok_or(Errno::EINVAL)?;
4778                return Err(refuse_too_big(guest.memory(), back));
4779            }
4780        };
4781
4782        // `copy_struct_from_user` with a user size past the kernel's struct:
4783        // every trailing byte must be zero, or the guest is sending a field
4784        // this kernel does not know and must not silently drop. A fault while
4785        // scanning is EFAULT and skips the store back -- only the not-all-zero
4786        // verdict is E2BIG.
4787        if size > SCHED_ATTR_KERNEL_SIZE {
4788            let base: AddrMut<u8> = call.attr().ok_or(Errno::EINVAL)?.cast();
4789            match scan_tail_is_zeroed(
4790                &guest.memory(),
4791                base,
4792                SCHED_ATTR_KERNEL_SIZE as usize,
4793                (size - SCHED_ATTR_KERNEL_SIZE) as usize,
4794            ) {
4795                TailVerdict::AllZero => {}
4796                TailVerdict::NotZeroed => {
4797                    let back = call.attr().ok_or(Errno::EINVAL)?;
4798                    return Err(refuse_too_big(guest.memory(), back));
4799                }
4800                TailVerdict::Faulted => return Err(Errno::EFAULT.into()),
4801            }
4802        }
4803
4804        // Copy the interoperable prefix, zero-filling anything the guest's
4805        // buffer is too short to carry, exactly as `copy_struct_from_user`
4806        // does for a short read.
4807        let copied = std::cmp::min(size, SCHED_ATTR_KERNEL_SIZE) as usize;
4808        let mut raw = [0u8; SCHED_ATTR_KERNEL_SIZE as usize];
4809        let base: AddrMut<u8> = call.attr().ok_or(Errno::EINVAL)?.cast();
4810        guest
4811            .memory()
4812            .read_exact(base, &mut raw[..copied])
4813            .map_err(|_| Errno::EFAULT)?;
4814        let field32 = |offset: usize| -> u32 {
4815            u32::from_ne_bytes(raw[offset..offset + 4].try_into().expect("4 bytes"))
4816        };
4817        let field64 = |offset: usize| -> u64 {
4818            u64::from_ne_bytes(raw[offset..offset + 8].try_into().expect("8 bytes"))
4819        };
4820        let fields = SchedAttrFields {
4821            policy: field32(SCHED_ATTR_OFF_POLICY),
4822            sched_flags: field64(SCHED_ATTR_OFF_FLAGS),
4823            priority: field32(SCHED_ATTR_OFF_PRIORITY),
4824            runtime: field64(SCHED_ATTR_OFF_RUNTIME),
4825            deadline: field64(SCHED_ATTR_OFF_DEADLINE),
4826            period: field64(SCHED_ATTR_OFF_PERIOD),
4827        };
4828
4829        // Everything the kernel decides before it resolves the pid.
4830        validate_sched_attr_before_lookup(size, &fields)?;
4831
4832        // `find_process_by_pid()` sits here, between the two groups of checks,
4833        // and the position is guest-visible: a request that is malformed only
4834        // in a way judged below reports ESRCH rather than EINVAL when the pid
4835        // does not exist. pid 0 means the calling thread, which always exists;
4836        // otherwise ask the scheduler's own task table, so the answer comes
4837        // from Detcore's state rather than from the host's process table.
4838        // `find_task_by_vpid` resolves ANY LIVE TASK, not just a thread-group
4839        // leader. The kill-target resolver is the wrong question here: it
4840        // models `kill(2)`, whose first act is to refuse anything that is not a
4841        // leader, so a perfectly live non-leader thread's tid reported ESRCH.
4842        // A nested caller names the thread by its own namespace's tid
4843        // (https://github.com/rrnewton/hermit/issues/4155).
4844        let named = if call.pid() > 0 && guest.thread_state().nested_pid_namespace {
4845            match crate::tool_global::guest_pid(guest, call.pid()).await {
4846                GuestPidAnswer::Task { task, .. } => Some(task),
4847                GuestPidAnswer::NoSuchPid => None,
4848                GuestPidAnswer::Untranslatable(reason) => {
4849                    return Err(self
4850                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::sched_setattr, &reason)
4851                        .await);
4852                }
4853            }
4854        } else {
4855            Some(DetTid::from_raw(call.pid()))
4856        };
4857        if call.pid() != 0 {
4858            match named {
4859                Some(task) if thread_is_live(guest, task).await => {}
4860                _ => return Err(Errno::ESRCH.into()),
4861            }
4862        }
4863
4864        // And everything `__sched_setscheduler` decides after it.
4865        validate_sched_attr_after_lookup(&fields)?;
4866
4867        info!(
4868            "Suppressing sched_setattr(pid={}, flags={}); Linux scheduler attributes are virtual",
4869            call.pid(),
4870            call.flags()
4871        );
4872        Ok(0)
4873    }
4874
4875    /// ioprio_set under Hermit. Detcore serializes guest threads onto one virtual
4876    /// CPU, so the block-layer I/O scheduling class and priority cannot change
4877    /// guest-visible computation. Accept and suppress the request as a
4878    /// deterministic no-op success, mirroring how sched_setaffinity is handled.
4879    /// Re-enables `ionice` under --strict.
4880    // AUTONOMOUS-BOT-IMPLEMENTED
4881    // TODO-HUMAN-REVIEW(#791)
4882    pub async fn handle_ioprio_set<G: Guest<Self>>(
4883        &self,
4884        _guest: &mut G,
4885        call: syscalls::IoprioSet,
4886    ) -> Result<i64, Error> {
4887        info!(
4888            "Suppressing ioprio_set(which={}, who={}, priority={}); I/O priority is virtual",
4889            call.which(),
4890            call.who(),
4891            call.priority()
4892        );
4893        Ok(0)
4894    }
4895
4896    /// ioprio_get under Hermit. I/O priority is inert under Detcore's serialized
4897    /// scheduler, so process queries observe the fixed raw IOPRIO_CLASS_NONE
4898    /// value while group/user queries observe the effective SCHED_OTHER default
4899    /// of IOPRIO_CLASS_BE/4, without consulting host block-scheduler state.
4900    // AUTONOMOUS-BOT-IMPLEMENTED
4901    // TODO-HUMAN-REVIEW(PR-881)
4902    pub async fn handle_ioprio_get<G: Guest<Self>>(
4903        &self,
4904        _guest: &mut G,
4905        call: syscalls::IoprioGet,
4906    ) -> Result<i64, Error> {
4907        let priority = virtual_ioprio(call.which())?;
4908
4909        info!(
4910            "Emulating ioprio_get(which={}, who={}): fixed priority {}",
4911            call.which(),
4912            call.who(),
4913            priority
4914        );
4915        Ok(priority)
4916    }
4917}
4918
4919/// The one real implementation of [`robust_list::RobustDeathEffects`]: guest
4920/// memory plus a wake against Detcore's modeled futex waiter pool.
4921///
4922/// It exists so the walk itself never mentions `Guest`, and can therefore be
4923/// unit-tested against fake memory.
4924struct GuestRobustEffects<'a, G, T> {
4925    guest: &'a mut G,
4926    dettid: DetTid,
4927    staged_wakes: Option<&'a mut Vec<RobustListWake>>,
4928    /// The words this exit's walks found owned by their dying owner, keyed as
4929    /// futexes (so two mappings of one shared page are one word), with the
4930    /// value Linux's walk stores there. Detcore does not store it, so a later
4931    /// read of the same word, through another entry or another owner's list
4932    /// in the same group exit, sees this value, as it would after Linux's
4933    /// store.
4934    marked: &'a mut HashMap<FutexID, u32>,
4935    tool: PhantomData<T>,
4936}
4937
4938impl<G, T> robust_list::RobustDeathEffects for GuestRobustEffects<'_, G, T>
4939where
4940    G: Guest<Detcore<T>>,
4941    T: RecordOrReplay,
4942{
4943    fn read_u64(&mut self, address: usize) -> Option<u64> {
4944        let at = Addr::<u64>::from_raw(address)?;
4945        self.guest.memory().read_value::<_, u64>(at).ok()
4946    }
4947
4948    fn read_u32(&mut self, address: usize) -> Option<u32> {
4949        let at = Addr::<u32>::from_raw(address)?;
4950        let value = self.guest.memory().read_value::<_, u32>(at).ok()?;
4951        let futexid = self.guest.thread_state().futex_id(address, false);
4952        Some(self.marked.get(&futexid).copied().unwrap_or(value))
4953    }
4954
4955    fn compare_and_swap(
4956        &mut self,
4957        address: usize,
4958        expected: u32,
4959        desired: u32,
4960    ) -> robust_list::FutexCasOutcome {
4961        use robust_list::FutexCasOutcome;
4962
4963        let Some(read_at) = Addr::<u32>::from_raw(address) else {
4964            return FutexCasOutcome::Faulted;
4965        };
4966        // Detcore never stores the owner word itself. It re-reads the word to
4967        // decide whether the kernel's retry loop would take another pass, then
4968        // leaves the replacement to the native task exit, which every
4969        // [`OwnerDeathPath`] completes before another modeled thread runs.
4970        let observed = match self.guest.memory().read_value::<_, u32>(read_at) {
4971            Ok(value) => value,
4972            Err(_) => return FutexCasOutcome::Faulted,
4973        };
4974        let futexid = self.guest.thread_state().futex_id(address, false);
4975        let observed = self.marked.get(&futexid).copied().unwrap_or(observed);
4976        if observed != expected {
4977            return FutexCasOutcome::Changed(observed);
4978        }
4979        self.marked.insert(futexid, desired);
4980        // No other scheduler turn runs until Linux has repeated the owner
4981        // check and changed the word atomically. Do not perform a separate
4982        // write here: a process outside Hermit's scheduler can share the
4983        // mapping and acquire the mutex between this read and that write.
4984        // Deliberately DEBUG, not INFO: this line carries a raw guest address,
4985        // and INFO is the surface `--verify-strict` compares.
4986        debug!(
4987            "[detcore, dtid {}] robust-list owner death: leaving futex word {:#x} for backend exit cleanup",
4988            self.dettid, address,
4989        );
4990        FutexCasOutcome::Matched
4991    }
4992
4993    async fn wake_one(&mut self, address: usize, observed: u32) {
4994        // glibc always issues robust-mutex futex operations with the shared
4995        // flag, and so does the kernel's owner-death wake; resolve the same key.
4996        let futexid = self.guest.thread_state().futex_id(address, false);
4997        if let Some(wakes) = self.staged_wakes.as_mut() {
4998            wakes.push(RobustListWake { futex: futexid });
4999            debug!(
5000                "[detcore, dtid {}] staged robust-list owner-death wake until physical exit",
5001                self.dettid,
5002            );
5003            return;
5004        }
5005        let woken = match futex_action(
5006            self.guest,
5007            FutexAction::WakeRequest(1),
5008            &futexid,
5009            observed as i32,
5010            u32::MAX,
5011        )
5012        .await
5013        {
5014            Some(SchedValue::Value(count)) => count,
5015            // A wake never carries a timeout, and a cancelled RPC wakes nobody.
5016            Some(SchedValue::TimeOut)
5017            | Some(SchedValue::Signaled(_))
5018            | Some(SchedValue::Requeued { .. })
5019            | None => 0,
5020        };
5021        // Guest-level identities only: dettid, the modeled futex key, and a
5022        // count. No host pointers and no iteration order leak into this line,
5023        // which is compared exactly under `--verify-strict`.
5024        info!(
5025            "[detcore, dtid {}] robust-list owner death woke {} waiter(s) on futex {:?}",
5026            self.dettid, woken, futexid,
5027        );
5028        let _ = futex_action(
5029            self.guest,
5030            FutexAction::WakeFinished(0),
5031            &futexid,
5032            observed as i32,
5033            u32::MAX,
5034        )
5035        .await;
5036    }
5037}
5038
5039/// How a thread group's robust-mutex owners die, for
5040/// `Detcore::read_thread_group_robust_list_wakes`.
5041#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5042enum OwnerDeath {
5043    /// exit_group or a fatal signal: every thread exits with its own TID.
5044    Exit,
5045    /// A successful execve: the other threads exit with their own TIDs, and the
5046    /// caller's list is walked under the TID it holds after `de_thread`.
5047    Exec,
5048}
5049
5050/// `Detcore::robust_owner_death_path` for `cfg`.
5051///
5052/// The Barrier path needs three properties of a backend: an exit callback that
5053/// runs before the native exit, a native exit that runs Linux's own robust
5054/// walk, and a registered host pidfd for every thread, which the scheduler's
5055/// exited-thread hold polls. `requires_thread_directed_process_signals` is
5056/// the flag that makes Detcore refuse a thread without host IDs, so it implies
5057/// the third; today only DBT sets it, and DBT has the other two.
5058/// `owner_death_path_is_tied_to_the_backends_that_have_its_properties` fails
5059/// if another backend starts to set it (Claude review of
5060/// https://github.com/rrnewton/hermit/pull/4277 at 65138a17, N4).
5061fn owner_death_path(cfg: &Config) -> Option<OwnerDeathPath> {
5062    if !cfg.sequentialize_threads || cfg.debug_futex_mode != BlockingMode::Precise {
5063        return None;
5064    }
5065    if cfg.backend.runs_exit_robust_list {
5066        Some(OwnerDeathPath::Kernel)
5067    } else if cfg.backend.requires_thread_directed_process_signals {
5068        Some(OwnerDeathPath::Barrier)
5069    } else {
5070        None
5071    }
5072}
5073
5074/// How Detcore orders its modeled owner-death wakes after Linux's own walk.
5075/// In both, Linux changes each owner word to `FUTEX_OWNER_DIED` in the native
5076/// exit, and Detcore only reads the words.
5077#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5078enum OwnerDeathPath {
5079    /// The backend's exit callback comes after the native exit
5080    /// (`BackendCapabilities::runs_exit_robust_list`, ptrace). Wakes for a
5081    /// whole group's death wait for the owners' exit callbacks.
5082    Kernel,
5083    /// The backend reports a thread's exit before the native exit runs, and
5084    /// registers a pidfd for every host thread
5085    /// (`BackendCapabilities::requires_thread_directed_process_signals`, DBT).
5086    /// The scheduler then commits no turn until the kernel has ended a thread
5087    /// that exited by its own grant, or any thread of a group whose exit_group
5088    /// was granted (`Scheduler::exited_thread_barriers`). An exit_group's
5089    /// killed threads also hold their native exits until the group's walk is
5090    /// done (`ThreadState::wait_for_exit_group_robust_walk`), so that walk reads
5091    /// every word as the guest left it.
5092    Barrier,
5093}
5094
5095/// How precise and polling futex modes answer a futex command, decided as
5096/// Linux's `do_futex` (kernel/futex/syscalls.c) decides it, before the futex
5097/// address is looked at.
5098#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5099pub(crate) enum FutexCommand {
5100    /// Emulated: FUTEX_WAIT, FUTEX_WAIT_BITSET, FUTEX_WAKE, FUTEX_WAKE_BITSET,
5101    /// FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and FUTEX_WAKE_OP.
5102    Served,
5103    /// `-ENOSYS`, exactly as Linux: FUTEX_CLOCK_REALTIME with any command but
5104    /// FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI or FUTEX_LOCK_PI2; the removed
5105    /// FUTEX_FD; and any unknown command.
5106    NoSys,
5107    /// A priority-inheritance command, which Detcore does not emulate; refused
5108    /// by name (`Detcore::refuse_futex_command`).
5109    PriorityInheritance(&'static str),
5110}
5111
5112/// [`FutexCommand`] for a raw `futex_op`.
5113// AUTONOMOUS-BOT-IMPLEMENTED
5114pub(crate) fn classify_futex_command(futex_op: i32) -> FutexCommand {
5115    let cmd = futex_op & libc::FUTEX_CMD_MASK;
5116    if futex_op & libc::FUTEX_CLOCK_REALTIME != 0
5117        && !matches!(
5118            cmd,
5119            libc::FUTEX_WAIT_BITSET | libc::FUTEX_WAIT_REQUEUE_PI | libc::FUTEX_LOCK_PI2
5120        )
5121    {
5122        return FutexCommand::NoSys;
5123    }
5124    match cmd {
5125        libc::FUTEX_WAIT
5126        | libc::FUTEX_WAIT_BITSET
5127        | libc::FUTEX_WAKE
5128        | libc::FUTEX_WAKE_BITSET
5129        | libc::FUTEX_REQUEUE
5130        | libc::FUTEX_CMP_REQUEUE
5131        | libc::FUTEX_WAKE_OP => FutexCommand::Served,
5132        libc::FUTEX_LOCK_PI => FutexCommand::PriorityInheritance("FUTEX_LOCK_PI"),
5133        libc::FUTEX_LOCK_PI2 => FutexCommand::PriorityInheritance("FUTEX_LOCK_PI2"),
5134        libc::FUTEX_UNLOCK_PI => FutexCommand::PriorityInheritance("FUTEX_UNLOCK_PI"),
5135        libc::FUTEX_TRYLOCK_PI => FutexCommand::PriorityInheritance("FUTEX_TRYLOCK_PI"),
5136        libc::FUTEX_WAIT_REQUEUE_PI => FutexCommand::PriorityInheritance("FUTEX_WAIT_REQUEUE_PI"),
5137        libc::FUTEX_CMP_REQUEUE_PI => FutexCommand::PriorityInheritance("FUTEX_CMP_REQUEUE_PI"),
5138        _ => FutexCommand::NoSys,
5139    }
5140}
5141
5142/// Why `--debug-futex-mode polling` refuses FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and
5143/// FUTEX_WAKE_OP.
5144const POLLING_REFUSAL: &str = "--debug-futex-mode polling does not model futex waiter lists";
5145
5146/// The `val2` of FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and FUTEX_WAKE_OP, which the
5147/// syscall passes in the timeout argument: `sys_futex` hands
5148/// `(unsigned long)utime` to `do_futex` as a `u32`, and the commands read it as
5149/// an `int`.
5150fn futex_val2(call: &syscalls::Futex) -> u32 {
5151    call.timeout().map_or(0, Addr::as_raw) as u32
5152}
5153
5154/// The raw `uaddr2` argument; NULL is address 0, as Linux keys it.
5155fn futex_uaddr2(call: &syscalls::Futex) -> usize {
5156    call.uaddr2().map_or(0, AddrMut::as_raw)
5157}
5158
5159/// The raw `uaddr` of a futex call; NULL is a valid private key for the
5160/// commands that only key their words.
5161fn futex_uaddr(call: &syscalls::Futex) -> usize {
5162    call.uaddr().map_or(0, AddrMut::as_raw)
5163}
5164
5165/// How a command acquires a futex key: Linux's `enum futex_access`.
5166#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5167enum KeyAccess {
5168    /// `FUTEX_READ`: the word is only compared or woken.
5169    Read,
5170    /// `FUTEX_WRITE`: the word is changed (WAKE_OP's second word).
5171    Write,
5172}
5173
5174/// The highest address `access_ok` accepts for a futex word on this host,
5175/// `USER_PTR_MAX` (arch/x86/include/asm/uaccess_64.h). It depends on the
5176/// paging mode the kernel booted with, so it is measured once from the host
5177/// kernel, which is also the guest's kernel: a private FUTEX_WAKE with count 0
5178/// keys the word without touching it and fails with EFAULT exactly when
5179/// `access_ok` refuses it.
5180fn user_ptr_max() -> usize {
5181    static MAX: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
5182    *MAX.get_or_init(|| {
5183        let accepted = |address: usize| {
5184            // SAFETY: a private FUTEX_WAKE with count 0 never accesses `address`.
5185            let ret = unsafe {
5186                libc::syscall(
5187                    libc::SYS_futex,
5188                    address,
5189                    libc::FUTEX_WAKE | libc::FUTEX_PRIVATE_FLAG,
5190                    0,
5191                    0,
5192                    0,
5193                    0,
5194                )
5195            };
5196            ret >= 0
5197        };
5198        // Binary search over 4-aligned addresses: 0 is accepted, and an address
5199        // with the top bit set never is.
5200        let (mut ok, mut bad) = (0usize, 1usize << 63);
5201        while bad - ok > 4 {
5202            let mid = (ok + (bad - ok) / 2) & !3;
5203            if accepted(mid) { ok = mid } else { bad = mid }
5204        }
5205        ok
5206    })
5207}
5208
5209/// The futex key of a word that a command keys, as Linux's `get_futex_key`
5210/// (kernel/futex/core.c) admits it, without reading the word:
5211/// - `-EINVAL` if it is not 4-aligned;
5212/// - `-EFAULT` if `access_ok` refuses it (`user_ptr_max`);
5213/// - a private key needs nothing more, so NULL is a valid one;
5214/// - a shared key needs its backing page, acquired for reading or writing.
5215///   Which pages the kernel can acquire (a copy-on-write page made read-only, a
5216///   page past the end of a truncated file, a read-only anonymous page) is not
5217///   visible in `/proc` metadata, so the kernel is asked with an effect-free
5218///   probe on the guest's own address (`probe_shared_futex_key`).
5219async fn futex_key<G: Guest<Detcore<T>>, T: RecordOrReplay>(
5220    guest: &mut G,
5221    address: usize,
5222    private: bool,
5223    access: KeyAccess,
5224) -> Result<FutexID, Error> {
5225    if !address.is_multiple_of(std::mem::size_of::<u32>()) {
5226        return Err(Error::Errno(Errno::EINVAL));
5227    }
5228    if address > user_ptr_max() {
5229        return Err(Error::Errno(Errno::EFAULT));
5230    }
5231    if !private {
5232        probe_shared_futex_key(guest, address, access).await?;
5233    }
5234    Ok(guest.thread_state().futex_id(address, private))
5235}
5236
5237/// Whether the kernel admits `address` as a shared futex key with `access`,
5238/// asked with a futex call injected into the guest that runs `get_futex_key`
5239/// and has no other effect, even on a waiter outside Hermit:
5240/// - a READ key: a non-private FUTEX_REQUEUE from the word to itself with both
5241///   counts 0. `futex_requeue` acquires both keys for reading, and its loop
5242///   then stops before the first waiter (`task_count - nr_wake >= nr_requeue`).
5243///   A FUTEX_WAKE with count 0 would not do: it still wakes one waiter;
5244/// - a WRITE key: a non-private FUTEX_WAKE_OP from the word to itself with an
5245///   unknown operation. `futex_wake_op` acquires the first key for reading and
5246///   the second for writing, then `futex_atomic_op_inuser` returns -ENOSYS for
5247///   the unknown operation before it touches the word or wakes anyone.
5248///
5249/// Linux's refusal (-EFAULT, or -EINVAL) is returned as is.
5250async fn probe_shared_futex_key<G: Guest<Detcore<T>>, T: RecordOrReplay>(
5251    guest: &mut G,
5252    address: usize,
5253    access: KeyAccess,
5254) -> Result<(), Error> {
5255    let probe = shared_futex_key_probe(address, access);
5256    match run_shared_futex_key_probe(guest, probe, access, |guest, probe| guest.inject(probe)).await
5257    {
5258        SharedKeyProbe::Admitted => Ok(()),
5259        SharedKeyProbe::Refused(errno) => Err(Error::Errno(errno)),
5260        SharedKeyProbe::Interrupted(errno) => {
5261            refuse_interrupted_shared_key_probe(guest, address, errno).await
5262        }
5263    }
5264}
5265
5266/// The effect-free futex call that asks the kernel whether `address` is a
5267/// shared key with `access` (see `probe_shared_futex_key`).
5268fn shared_futex_key_probe(address: usize, access: KeyAccess) -> syscalls::Futex {
5269    let word = AddrMut::<libc::c_int>::from_raw(address);
5270    match access {
5271        KeyAccess::Read => syscalls::Futex::new()
5272            .with_uaddr(word)
5273            .with_futex_op(libc::FUTEX_REQUEUE)
5274            .with_val(0)
5275            .with_uaddr2(word),
5276        KeyAccess::Write => syscalls::Futex::new()
5277            .with_uaddr(word)
5278            .with_futex_op(libc::FUTEX_WAKE_OP)
5279            .with_val(0)
5280            .with_uaddr2(word)
5281            .with_val3((7 << 28) | (1 << 12)),
5282    }
5283}
5284
5285/// The pending answer to one injected shared-key probe.
5286type KeyProbeAnswer<'a> =
5287    std::pin::Pin<Box<dyn std::future::Future<Output = Result<i64, Errno>> + Send + 'a>>;
5288
5289/// What one injected shared-key probe answered.
5290#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5291enum SharedKeyProbe {
5292    /// The kernel admitted the key: 0, or ENOSYS for a WRITE key (the unknown
5293    /// WAKE_OP operation is rejected only after both keys are acquired).
5294    Admitted,
5295    /// The kernel refused the key with this errno, which is the guest's.
5296    Refused(Errno),
5297    /// A signal stopped the probe's instruction before it ran (Reverie's
5298    /// `Guest::inject` returns ERESTARTSYS; EINTR is never a key answer either,
5299    /// since neither probe sleeps). The kernel answered nothing.
5300    Interrupted(Errno),
5301}
5302
5303/// Inject a shared-key `probe` once with `inject` and classify the answer.
5304///
5305/// The probe is never injected again: Reverie holds the signal that stopped
5306/// it in a single slot, and a second interrupted injection would replace that
5307/// signal, losing one the kernel already dequeued (Codex re-check #4 of
5308/// https://github.com/rrnewton/hermit/pull/4020). An interruption is returned
5309/// as such, never as an admission or as the guest's errno.
5310async fn run_shared_futex_key_probe<C>(
5311    context: &mut C,
5312    probe: syscalls::Futex,
5313    access: KeyAccess,
5314    inject: for<'a> fn(&'a mut C, syscalls::Futex) -> KeyProbeAnswer<'a>,
5315) -> SharedKeyProbe {
5316    match inject(context, probe).await {
5317        Ok(_) => SharedKeyProbe::Admitted,
5318        Err(errno @ (Errno::ERESTARTSYS | Errno::EINTR)) => SharedKeyProbe::Interrupted(errno),
5319        Err(Errno::ENOSYS) if access == KeyAccess::Write => SharedKeyProbe::Admitted,
5320        Err(errno) => SharedKeyProbe::Refused(errno),
5321    }
5322}
5323
5324/// Stop the run by name because a signal interrupted the shared-key probe for
5325/// the futex word at `address`.
5326///
5327/// The original call has no answer to return: the interruption token is not a
5328/// Linux result for it, retrying could lose the held signal
5329/// (`run_shared_futex_key_probe`), and admitting the key unchecked could be a
5330/// silent wrong answer. The run ends with the policy-refusal status whatever
5331/// the unsupported-operation policy, since `--allow-unsupported-syscalls` has
5332/// no errno to offer here either. A signal must arrive at exactly that
5333/// instruction, which is rare.
5334async fn refuse_interrupted_shared_key_probe<G: Guest<Detcore<T>>, T: RecordOrReplay>(
5335    guest: &mut G,
5336    address: usize,
5337    errno: Errno,
5338) -> ! {
5339    {
5340        use std::io::Write;
5341        let _ = writeln!(
5342            crate::util::RetryingStderr,
5343            "hermit: a signal interrupted Detcore's shared futex key check for word {:#x} in thread {} ({}); \
5344             refusing the run rather than retrying it, which could lose that signal \
5345             (https://github.com/rrnewton/hermit/pull/4020)",
5346            address,
5347            guest.thread_state().dettid,
5348            errno,
5349        );
5350    }
5351    crate::tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
5352        .await
5353}
5354
5355/// A futex word's value as a user-mode access reads it, which is what Linux's
5356/// `futex_get_value_locked`/`get_user` and `futex_atomic_op_inuser` do:
5357/// `-EFAULT` if the word cannot be read.
5358///
5359/// The word is read as exactly four bytes with the guest's own permissions. On
5360/// x86 a writable page is also readable from user mode, but that read refuses a
5361/// mapping without `PROT_READ`, so for a writable one the 8-byte-aligned word
5362/// containing it is read instead. That cannot cross into the next page, unlike a
5363/// debugger read at the word's own address. A debugger read alone would also
5364/// ignore `PROT_NONE`.
5365fn read_futex_word<G: Guest<Detcore<T>>, T: RecordOrReplay>(
5366    guest: &mut G,
5367    address: usize,
5368) -> Result<i32, Error> {
5369    let word = Addr::<u8>::from_raw(address).ok_or(Errno::EFAULT)?;
5370    let mut bytes = [0u8; 4];
5371    if guest
5372        .memory()
5373        .read_exact_with_user_access(word, &mut bytes)
5374        .is_ok()
5375    {
5376        return Ok(i32::from_ne_bytes(bytes));
5377    }
5378    // Only a backend that runs the guest as real host threads has a host
5379    // `/proc/<pid>/maps` describing the guest; elsewhere (KVM's guest pid is
5380    // virtual) the user-access read above is the backend's whole answer.
5381    if !bundled_signal_facts::host_task_reads_enabled(&guest.config().backend)
5382        || !mapping_is_writable(guest.pid().as_raw(), address)
5383    {
5384        return Err(Error::Errno(Errno::EFAULT));
5385    }
5386    let aligned = address & !(std::mem::size_of::<u64>() - 1);
5387    let pair: u64 = guest
5388        .memory()
5389        .read_value(Addr::<u64>::from_raw(aligned).ok_or(Errno::EFAULT)?)
5390        .map_err(|_| Error::Errno(Errno::EFAULT))?;
5391    let offset = address - aligned;
5392    let pair = pair.to_ne_bytes();
5393    bytes.copy_from_slice(&pair[offset..offset + 4]);
5394    Ok(i32::from_ne_bytes(bytes))
5395}
5396
5397/// Whether the guest mapping containing `address` is writable, from
5398/// `/proc/<pid>/maps`. False if no mapping contains it or the file cannot be
5399/// read.
5400fn mapping_is_writable(pid: i32, address: usize) -> bool {
5401    mapping_permissions(pid, address).is_some_and(|perms| perms[1] == b'w')
5402}
5403
5404/// The `rwxp` permissions of the guest mapping containing `address`, from
5405/// `/proc/<pid>/maps`, or `None` if no mapping contains it or the file cannot be
5406/// read.
5407fn mapping_permissions(pid: i32, address: usize) -> Option<[u8; 4]> {
5408    let maps = std::fs::read_to_string(format!("/proc/{pid}/maps")).ok()?;
5409    maps.lines().find_map(|line| {
5410        let mut fields = line.split_whitespace();
5411        let (Some(range), Some(perms)) = (fields.next(), fields.next()) else {
5412            return None;
5413        };
5414        let (start, end) = range.split_once('-')?;
5415        let (Ok(start), Ok(end)) = (
5416            usize::from_str_radix(start, 16),
5417            usize::from_str_radix(end, 16),
5418        ) else {
5419            return None;
5420        };
5421        if !(start..end).contains(&address) {
5422            return None;
5423        }
5424        perms.as_bytes().get(..4)?.try_into().ok()
5425    })
5426}
5427
5428/// A `struct timespec` copied from the guest as Linux's `get_timespec64`
5429/// (`copy_from_user`) copies it: every byte must lie in a mapping user mode can
5430/// read, which on x86 includes a write-only one, or the copy is EFAULT, with no
5431/// partial result. On a backend whose guest is real host threads, the guest's
5432/// host `/proc/<pid>/maps` decides; elsewhere the backend's user-access read. The bytes are then read through the tracer, which is only
5433/// safe because every page they span was checked first: the tracer's own read
5434/// would force its way through a PROT_NONE page.
5435fn read_user_timespec<G: Guest<Detcore<T>>, T: RecordOrReplay>(
5436    guest: &mut G,
5437    address: usize,
5438) -> Result<Timespec, Error> {
5439    let size = std::mem::size_of::<Timespec>();
5440    let last = address.checked_add(size - 1).ok_or(Errno::EFAULT)?;
5441    if last > user_ptr_max() {
5442        return Err(Error::Errno(Errno::EFAULT));
5443    }
5444    if !bundled_signal_facts::host_task_reads_enabled(&guest.config().backend) {
5445        // No host `/proc` describes this guest (KVM's guest pid is virtual), so
5446        // the backend's own user-access read decides, all or nothing.
5447        let mut bytes = [0u8; std::mem::size_of::<Timespec>()];
5448        guest
5449            .memory()
5450            .read_exact_with_user_access(
5451                Addr::<u8>::from_raw(address).ok_or(Errno::EFAULT)?,
5452                &mut bytes,
5453            )
5454            .map_err(|_| Error::Errno(Errno::EFAULT))?;
5455        let field = |at: usize| -> i64 {
5456            let mut raw = [0u8; 8];
5457            raw.copy_from_slice(&bytes[at..at + 8]);
5458            i64::from_ne_bytes(raw)
5459        };
5460        return Ok(Timespec {
5461            tv_sec: field(0) as libc::time_t,
5462            tv_nsec: field(8) as libc::c_long,
5463        });
5464    }
5465    // 4096 divides every page size, so probing each 4 KiB step checks every page.
5466    let page = 4096;
5467    let pid = guest.pid().as_raw();
5468    let mut cursor = address & !(page - 1);
5469    while cursor <= last {
5470        let probe = cursor.max(address);
5471        let readable = mapping_permissions(pid, probe)
5472            .is_some_and(|perms| perms[0] == b'r' || perms[1] == b'w');
5473        if !readable {
5474            return Err(Error::Errno(Errno::EFAULT));
5475        }
5476        cursor += page;
5477    }
5478    // Read the bytes as aligned 8-byte words, which the tracer reads one at a
5479    // time even from a write-only page; a larger read goes through
5480    // `process_vm_readv`, which needs the page to be readable.
5481    let start = address & !7;
5482    let mut bytes = Vec::with_capacity(last + 1 - start);
5483    let mut word = start;
5484    while word <= last {
5485        let value: u64 = guest
5486            .memory()
5487            .read_value(Addr::<u64>::from_raw(word).ok_or(Errno::EFAULT)?)
5488            .map_err(|_| Error::Errno(Errno::EFAULT))?;
5489        bytes.extend_from_slice(&value.to_ne_bytes());
5490        word += 8;
5491    }
5492    let field = |at: usize| -> i64 {
5493        let mut raw = [0u8; 8];
5494        raw.copy_from_slice(&bytes[address - start + at..address - start + at + 8]);
5495        i64::from_ne_bytes(raw)
5496    };
5497    Ok(Timespec {
5498        tv_sec: field(0) as libc::time_t,
5499        tv_nsec: field(8) as libc::c_long,
5500    })
5501}
5502
5503// FUTEX_WAKE_OP operations and comparisons (include/uapi/linux/futex.h).
5504const FUTEX_OP_SET: u32 = 0;
5505const FUTEX_OP_ADD: u32 = 1;
5506const FUTEX_OP_OR: u32 = 2;
5507const FUTEX_OP_ANDN: u32 = 3;
5508const FUTEX_OP_XOR: u32 = 4;
5509const FUTEX_OP_OPARG_SHIFT: u32 = 8;
5510const FUTEX_OP_CMP_EQ: u32 = 0;
5511const FUTEX_OP_CMP_NE: u32 = 1;
5512const FUTEX_OP_CMP_LT: u32 = 2;
5513const FUTEX_OP_CMP_GE: u32 = 3;
5514const FUTEX_OP_CMP_LE: u32 = 4;
5515const FUTEX_OP_CMP_GT: u32 = 5;
5516
5517/// FUTEX_WAKE_OP's encoded operation, decoded as Linux's
5518/// `futex_atomic_op_inuser` (kernel/futex/waitwake.c) decodes it.
5519#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5520pub(crate) struct FutexWakeOp {
5521    op: u32,
5522    cmp: u32,
5523    oparg: i32,
5524    cmparg: i32,
5525}
5526
5527impl FutexWakeOp {
5528    pub(crate) fn decode(encoded: u32) -> Self {
5529        let sign_extend_12 = |v: u32| ((v << 20) as i32) >> 20;
5530        let op = (encoded & 0x7000_0000) >> 28;
5531        let cmp = (encoded & 0x0f00_0000) >> 24;
5532        let mut oparg = sign_extend_12((encoded & 0x00ff_f000) >> 12);
5533        let cmparg = sign_extend_12(encoded & 0x0000_0fff);
5534        if encoded & (FUTEX_OP_OPARG_SHIFT << 28) != 0 {
5535            // Linux masks an out-of-range shift (and logs "fix this program").
5536            if !(0..=31).contains(&oparg) {
5537                oparg &= 31;
5538            }
5539            oparg = 1i32.wrapping_shl(oparg as u32);
5540        }
5541        FutexWakeOp {
5542            op,
5543            cmp,
5544            oparg,
5545            cmparg,
5546        }
5547    }
5548
5549    /// Whether the operation is one x86's `arch_futex_atomic_op_inuser` knows;
5550    /// it returns `-ENOSYS` for any other before touching the word.
5551    pub(crate) fn has_known_operation(&self) -> bool {
5552        self.apply(0).is_some()
5553    }
5554
5555    /// The new value of the word, from its old value.
5556    pub(crate) fn apply(&self, old: i32) -> Option<i32> {
5557        Some(match self.op {
5558            FUTEX_OP_SET => self.oparg,
5559            FUTEX_OP_ADD => old.wrapping_add(self.oparg),
5560            FUTEX_OP_OR => old | self.oparg,
5561            FUTEX_OP_ANDN => old & !self.oparg,
5562            FUTEX_OP_XOR => old ^ self.oparg,
5563            _ => return None,
5564        })
5565    }
5566
5567    /// Whether to wake on `uaddr2`, from the word's old value; `None` (`-ENOSYS`)
5568    /// for an unknown comparison.
5569    pub(crate) fn compare(&self, old: i32) -> Option<bool> {
5570        Some(match self.cmp {
5571            FUTEX_OP_CMP_EQ => old == self.cmparg,
5572            FUTEX_OP_CMP_NE => old != self.cmparg,
5573            FUTEX_OP_CMP_LT => old < self.cmparg,
5574            FUTEX_OP_CMP_GE => old >= self.cmparg,
5575            FUTEX_OP_CMP_LE => old <= self.cmparg,
5576            FUTEX_OP_CMP_GT => old > self.cmparg,
5577            _ => return None,
5578        })
5579    }
5580}
5581
5582#[cfg(test)]
5583mod tests {
5584
5585    /// A copy the record marks as discarded at send is left out even when the
5586    /// wake's answer names its signal (`committed`), as for a drain batch's
5587    /// copy that was flushed and sent again, discarded (R4-1 of the R2b-1
5588    /// design re-checks, https://github.com/rrnewton/hermit/issues/4273; arm
5589    /// A9). A kept copy in either queue stays.
5590    #[test]
5591    fn a_discarded_copy_is_left_out_even_when_committed() {
5592        let chld = kernel_sigset_bit(libc::SIGCHLD);
5593        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
5594        let state = KernelSignalState {
5595            pending: chld | usr1,
5596            thread_pending: chld,
5597            shared_pending: usr1,
5598            ..Default::default()
5599        };
5600        assert_eq!(with_kept_copies(&state, chld, 0, chld | usr1, chld), usr1);
5601        assert_eq!(with_kept_copies(&state, 0, usr1, chld | usr1, usr1), chld);
5602        assert_eq!(with_kept_copies(&state, 0, 0, chld | usr1, 0), chld | usr1);
5603    }
5604    use std::io::Read;
5605    use std::io::Seek;
5606    use std::os::fd::AsRawFd;
5607
5608    use reverie::GlobalRPC;
5609    use reverie::GlobalTool;
5610    use reverie::Tid;
5611    use reverie::Tool;
5612
5613    use super::*;
5614
5615    /// The Kernel path is ptrace's, and the Barrier path is DBT's alone: a
5616    /// backend gets the Barrier path only by setting a flag whose other
5617    /// properties it must then have (`owner_death_path`).
5618    #[test]
5619    fn owner_death_path_is_tied_to_the_backends_that_have_its_properties() {
5620        let path = |backend: reverie::BackendCapabilities| {
5621            let mut cfg = Config::default().with_backend(|capabilities| *capabilities = backend);
5622            cfg.sequentialize_threads = true;
5623            cfg.debug_futex_mode = BlockingMode::Precise;
5624            owner_death_path(&cfg)
5625        };
5626        assert_eq!(
5627            path(reverie::BackendCapabilities::PTRACE),
5628            Some(OwnerDeathPath::Kernel)
5629        );
5630        assert_eq!(
5631            path(reverie::BackendCapabilities::DBT),
5632            Some(OwnerDeathPath::Barrier)
5633        );
5634        for backend in [
5635            reverie::BackendCapabilities::KVM,
5636            reverie::BackendCapabilities::SABRE,
5637            reverie::BackendCapabilities::LITEINST_IN_GUEST,
5638        ] {
5639            assert_eq!(path(backend), None, "{backend:?}");
5640        }
5641    }
5642
5643    /// Each configuration takes its own `sched_yield` route; only chaos with
5644    /// the timer on and delivered, no schedule replay, and a heuristic other
5645    /// than `Random` takes the yield epoch, and an ordinary run still ends its
5646    /// timeslice (https://github.com/rrnewton/hermit/issues/4068,
5647    /// https://github.com/rrnewton/hermit/issues/4150).
5648    #[test]
5649    fn each_configuration_takes_its_sched_yield_route() {
5650        let path = || Some(std::path::PathBuf::from("record.json"));
5651        let cases = [
5652            (Config::default(), SchedYieldRoute::EndTimeslice),
5653            // The ordinary ptrace run: timers delivered, no chaos.
5654            (
5655                Config {
5656                    ..Config::default()
5657                }
5658                .with_backend(|backend| {
5659                    backend.delivers_preemption_timer_events = true;
5660                    backend.runs_guest_code_between_injections = false;
5661                }),
5662                SchedYieldRoute::EndTimeslice,
5663            ),
5664            (
5665                Config {
5666                    chaos: true,
5667                    replay_schedule_from: path(),
5668                    ..Config::default()
5669                }
5670                .with_backend(|backend| {
5671                    backend.delivers_preemption_timer_events = true;
5672                    backend.runs_guest_code_between_injections = false;
5673                }),
5674                SchedYieldRoute::WeakYield,
5675            ),
5676            (
5677                Config {
5678                    chaos: true,
5679                    ..Config::default()
5680                }
5681                .with_backend(|backend| {
5682                    backend.delivers_preemption_timer_events = true;
5683                    backend.runs_guest_code_between_injections = false;
5684                }),
5685                SchedYieldRoute::ChaosYieldEpoch,
5686            ),
5687            (
5688                Config {
5689                    chaos: true,
5690                    sched_heuristic: SchedHeuristic::Random,
5691                    ..Config::default()
5692                }
5693                .with_backend(|backend| {
5694                    backend.delivers_preemption_timer_events = true;
5695                    backend.runs_guest_code_between_injections = false;
5696                }),
5697                SchedYieldRoute::WeakYield,
5698            ),
5699            (
5700                Config {
5701                    chaos: true,
5702                    sched_heuristic: SchedHeuristic::StickyRandom,
5703                    ..Config::default()
5704                }
5705                .with_backend(|backend| {
5706                    backend.delivers_preemption_timer_events = true;
5707                    backend.runs_guest_code_between_injections = false;
5708                }),
5709                SchedYieldRoute::ChaosYieldEpoch,
5710            ),
5711            (
5712                Config {
5713                    chaos: true,
5714                    sched_heuristic: SchedHeuristic::ConnectBind,
5715                    ..Config::default()
5716                }
5717                .with_backend(|backend| {
5718                    backend.delivers_preemption_timer_events = true;
5719                    backend.runs_guest_code_between_injections = false;
5720                }),
5721                SchedYieldRoute::ChaosYieldEpoch,
5722            ),
5723            (
5724                Config {
5725                    chaos: true,
5726                    max_timeslice: None,
5727                    sched_heuristic: SchedHeuristic::Random,
5728                    ..Config::default()
5729                },
5730                SchedYieldRoute::ChaosReprioritize,
5731            ),
5732            // A backend that delivers no preemption timer events.
5733            (
5734                Config {
5735                    chaos: true,
5736                    ..Config::default()
5737                }
5738                .with_backend(|backend| backend.delivers_preemption_timer_events = false),
5739                SchedYieldRoute::WeakYield,
5740            ),
5741            (
5742                Config {
5743                    chaos: true,
5744                    max_timeslice: None,
5745                    ..Config::default()
5746                },
5747                SchedYieldRoute::ChaosReprioritize,
5748            ),
5749            (
5750                Config {
5751                    chaos: true,
5752                    replay_preemptions_from: path(),
5753                    ..Config::default()
5754                }
5755                .with_backend(|backend| {
5756                    backend.delivers_preemption_timer_events = true;
5757                    backend.runs_guest_code_between_injections = false;
5758                }),
5759                SchedYieldRoute::ChaosYieldEpoch,
5760            ),
5761            (
5762                Config {
5763                    chaos: true,
5764                    replay_schedule_from: path(),
5765                    ..Config::default()
5766                },
5767                SchedYieldRoute::WeakYield,
5768            ),
5769            (
5770                Config {
5771                    replay_schedule_from: path(),
5772                    ..Config::default()
5773                },
5774                SchedYieldRoute::WeakYield,
5775            ),
5776            (
5777                Config {
5778                    replay_preemptions_from: path(),
5779                    ..Config::default()
5780                },
5781                SchedYieldRoute::ReplayStrongYield,
5782            ),
5783        ];
5784        for (cfg, route) in cases {
5785            assert_eq!(
5786                sched_yield_route(&cfg),
5787                route,
5788                "chaos={} timer delivered={} heuristic={:?} max_timeslice={:?} preemptions={:?} schedule={:?}",
5789                cfg.chaos,
5790                cfg.backend.delivers_preemption_timer_events,
5791                cfg.sched_heuristic,
5792                cfg.max_timeslice,
5793                cfg.replay_preemptions_from,
5794                cfg.replay_schedule_from
5795            );
5796        }
5797    }
5798
5799    /// A thread whose reported pid is not its thread group, as Reverie
5800    /// reports for a process that a raw `clone` without `CLONE_THREAD` made,
5801    /// still has a readable signal state and is not taken to be gone
5802    /// (https://github.com/rrnewton/hermit/issues/3982). The test's own thread
5803    /// stands in for it, with this process's parent as the wrong pid.
5804    #[test]
5805    fn a_thread_reported_under_another_pid_is_read_and_alive() {
5806        let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
5807        let wrong = Pid::from_raw(unsafe { libc::getppid() });
5808        assert_ne!(wrong, tid);
5809        assert!(read_kernel_signal_state(wrong, tid).is_err());
5810        assert!(read_thread_signal_state(wrong, tid).is_ok());
5811        assert!(!thread_is_gone(wrong, tid));
5812        assert!(read_thread_wait_signal_state(wrong, tid).is_ok());
5813    }
5814
5815    /// Host `/proc` signal state reads are forbidden exactly where guest
5816    /// thread IDs do not name host tasks: KVM, and no other backend today.
5817    #[test]
5818    fn host_signal_state_reads_are_refused_only_where_guest_tids_are_not_host_tasks() {
5819        assert!(refuses_host_signal_state_reads(&BackendCapabilities::KVM));
5820        for backend in [
5821            BackendCapabilities::PTRACE,
5822            BackendCapabilities::E9PATCH,
5823            BackendCapabilities::SABRE,
5824            BackendCapabilities::DBT,
5825            BackendCapabilities::LITEINST_IN_GUEST,
5826        ] {
5827            assert!(!refuses_host_signal_state_reads(&backend));
5828        }
5829    }
5830
5831    /// Once the refusal is latched for a backend whose guest thread IDs are
5832    /// not host tasks, a signal state read never reaches `/proc`: the test's
5833    /// own live thread, whose state is readable before, is refused after.
5834    #[test]
5835    fn a_latched_refusal_never_reads_a_host_task_signal_state() {
5836        let pid = Pid::from_raw(unsafe { libc::getpid() });
5837        let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
5838        refuse_host_signal_state_reads(&BackendCapabilities::PTRACE);
5839        assert!(!host_signal_state_reads_refused());
5840        assert!(read_kernel_signal_state(pid, tid).is_ok());
5841        refuse_host_signal_state_reads(&BackendCapabilities::KVM);
5842        assert!(host_signal_state_reads_refused());
5843        assert_eq!(read_kernel_signal_state(pid, tid), Err(Errno::ENOSYS));
5844        assert_eq!(read_thread_signal_state(pid, tid), Err(Errno::ENOSYS));
5845    }
5846    use crate::config::Config;
5847    use crate::tool_global::GlobalRequest;
5848    use crate::tool_global::GlobalState;
5849    use crate::types::MmId;
5850
5851    /// A new process whose exit signal is not SIGCHLD makes its creator hold
5852    /// that signal; a thread, a `CLONE_PARENT` child, a SIGCHLD child, and an
5853    /// out-of-range signal add nothing
5854    /// (https://github.com/rrnewton/hermit/issues/3146).
5855    #[test]
5856    fn a_child_exit_signal_other_than_sigchld_is_host_timed_for_its_creator() {
5857        let usr1 = 1_u64 << (libc::SIGUSR1 - 1);
5858        let none = CloneFlags::empty();
5859        assert_eq!(clone_host_timed_signals(none, libc::SIGUSR1), usr1);
5860        assert_eq!(
5861            clone_host_timed_signals(CloneFlags::CLONE_VFORK, libc::SIGUSR1),
5862            usr1
5863        );
5864        assert_eq!(clone_host_timed_signals(none, libc::SIGCHLD), 0);
5865        assert_eq!(clone_host_timed_signals(none, 0), 0);
5866        assert_eq!(clone_host_timed_signals(none, 65), 0);
5867        let thread = CloneFlags::CLONE_THREAD | CloneFlags::CLONE_SIGHAND | CloneFlags::CLONE_VM;
5868        assert_eq!(clone_host_timed_signals(thread, libc::SIGUSR1), 0);
5869        assert_eq!(
5870            clone_host_timed_signals(CloneFlags::CLONE_PARENT, libc::SIGUSR1),
5871            0
5872        );
5873    }
5874
5875    struct FailedExecStack;
5876    struct FailedExecStackGuard;
5877
5878    impl Drop for FailedExecStackGuard {
5879        fn drop(&mut self) {}
5880    }
5881
5882    impl reverie::Stack for FailedExecStack {
5883        type StackGuard = FailedExecStackGuard;
5884
5885        fn size(&self) -> usize {
5886            panic!("failed exec must not use the guest stack")
5887        }
5888        fn capacity(&self) -> usize {
5889            panic!("failed exec must not use the guest stack")
5890        }
5891        fn push<'stack, T>(&mut self, _: T) -> Addr<'stack, T> {
5892            panic!("failed exec must not use the guest stack")
5893        }
5894        fn reserve<'stack, T>(&mut self) -> AddrMut<'stack, T> {
5895            panic!("failed exec must not use the guest stack")
5896        }
5897        fn commit(self) -> Result<Self::StackGuard, Errno> {
5898            panic!("failed exec must not use the guest stack")
5899        }
5900    }
5901
5902    // Inject only the backend's errno and, when the backend refuses the exec
5903    // as unsupported, its typed refusal. Preparation, rollback, cancellation,
5904    // unsupported reporting and the configured refusal policy are real code.
5905    struct FailedExecGuest<'a> {
5906        config: &'a Config,
5907        global: &'a GlobalState,
5908        thread: crate::ThreadState<()>,
5909        sender: Tid,
5910        process: Tid,
5911        old_mm: MmId,
5912        errno: Errno,
5913        backend_refuses: bool,
5914        refusal: Option<reverie::UnsupportedRefusal>,
5915        refusal_takes: usize,
5916        injections: usize,
5917        requests: Mutex<Vec<GlobalRequest>>,
5918    }
5919
5920    #[reverie::tool]
5921    impl GlobalRPC<GlobalState> for FailedExecGuest<'_> {
5922        async fn send_rpc(
5923            &self,
5924            message: <GlobalState as GlobalTool>::Request,
5925        ) -> <GlobalState as GlobalTool>::Response {
5926            assert_eq!(message.1, self.old_mm, "RPC follows restored exec identity");
5927            self.requests.lock().unwrap().push(message.2.clone());
5928            self.global.receive_rpc(self.sender, message).await
5929        }
5930        fn config(&self) -> &Config {
5931            self.config
5932        }
5933    }
5934
5935    #[reverie::tool]
5936    impl Guest<Detcore> for FailedExecGuest<'_> {
5937        type Memory = reverie::syscalls::LocalMemory;
5938        type Stack = FailedExecStack;
5939
5940        fn tid(&self) -> Tid {
5941            self.sender
5942        }
5943        fn pid(&self) -> Tid {
5944            self.process
5945        }
5946        fn ppid(&self) -> Option<Tid> {
5947            None
5948        }
5949        fn memory(&self) -> Self::Memory {
5950            panic!("failed exec rollback must not read guest memory")
5951        }
5952        fn thread_state(&self) -> &crate::ThreadState<()> {
5953            &self.thread
5954        }
5955        fn thread_state_mut(&mut self) -> &mut crate::ThreadState<()> {
5956            &mut self.thread
5957        }
5958        async fn regs(&mut self) -> libc::user_regs_struct {
5959            panic!("failed exec rollback must not read registers")
5960        }
5961        async fn stack(&mut self) -> Self::Stack {
5962            panic!("failed exec rollback must not use a guest stack")
5963        }
5964        async fn daemonize(&mut self) {
5965            panic!("failed exec rollback must not daemonize")
5966        }
5967        async fn inject<S: SyscallInfo>(&mut self, call: S) -> Result<i64, Errno> {
5968            assert_eq!(call.number(), syscalls::Sysno::execveat);
5969            assert_eq!(
5970                self.thread.mm_id,
5971                self.old_mm.for_exec(self.thread.detpid.unwrap())
5972            );
5973            assert_eq!(self.thread.robust_list_head, None);
5974            self.injections += 1;
5975            // As reverie-kvm does, every injection replaces the record.
5976            self.refusal = self.backend_refuses.then(|| {
5977                reverie::UnsupportedRefusal::new(
5978                    reverie::UnsupportedOperation::NonLeaderExec,
5979                    self.errno,
5980                    "KVM nonleader exec is unsupported",
5981                )
5982            });
5983            Err(self.errno)
5984        }
5985        fn take_unsupported_refusal(&mut self) -> Option<reverie::UnsupportedRefusal> {
5986            assert_eq!(
5987                self.thread.mm_id,
5988                self.old_mm.for_exec(self.thread.detpid.unwrap()),
5989                "the refusal is taken before the failed exec is rolled back"
5990            );
5991            self.refusal_takes += 1;
5992            self.refusal.take()
5993        }
5994        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
5995            panic!("failed exec must not retire a live guest")
5996        }
5997        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
5998            panic!("failed exec rollback must not replace the timer")
5999        }
6000        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
6001            panic!("failed exec rollback must not replace the timer")
6002        }
6003        fn read_clock(&mut self) -> Result<u64, Error> {
6004            panic!("failed exec rollback must not sample the clock")
6005        }
6006    }
6007
6008    #[tokio::test]
6009    async fn backend_exec_refusal_preserves_failed_exec_rollback_and_policy() {
6010        let process = DetPid::from_raw(17);
6011        let worker = DetTid::from_raw(18);
6012        // `backend_refuses` is whether the backend reports a typed refusal for
6013        // the exec. reverie-kvm reports one for every worker exec that returns
6014        // ENOSYS, whether its own refusal after preflight or an ENOSYS from a
6015        // host syscall the preflight makes: the first two rows. The last row
6016        // is a worker ENOSYS for which a backend with KVM's other behaviours
6017        // reports no refusal (as KvmGuest::inject's early admission refusals
6018        // do); Detcore must not infer a refusal from the errno, so it is an
6019        // ordinary exec failure.
6020        for (kvm_behaviours, caller, errno, backend_refuses, fail_closed, refused, reported) in [
6021            (true, worker, Errno::ENOSYS, true, true, true, false),
6022            (true, worker, Errno::ENOSYS, true, false, false, true),
6023            (true, worker, Errno::ENOENT, false, true, false, false),
6024            (true, worker, Errno::ENOEXEC, false, true, false, false),
6025            (true, worker, Errno::EFAULT, false, true, false, false),
6026            (true, worker, Errno::EACCES, false, true, false, false),
6027            (true, worker, Errno::EOPNOTSUPP, false, true, false, false),
6028            (true, process, Errno::ENOSYS, false, true, false, false),
6029            (false, worker, Errno::ENOSYS, false, true, false, false),
6030            (true, worker, Errno::ENOSYS, false, true, false, false),
6031        ] {
6032            let mut report = tempfile::tempfile().unwrap();
6033            let config = Config {
6034                sequentialize_threads: false,
6035                panic_on_unsupported_syscalls: fail_closed,
6036                exit_on_unsupported_syscall: true,
6037                shutdown_on_unsupported_syscall: false,
6038                unsupported_syscall_report_fd: Some(report.as_raw_fd()),
6039                ..Config::default().with_backend(|backend| {
6040                    if kvm_behaviours {
6041                        // The behaviours the old `backend_is_kvm` identity flag
6042                        // selected, other than the exec refusal, which the
6043                        // backend now reports per exec (`backend_refuses`), and
6044                        // the user address limit, which it reports per guest.
6045                        backend.provides_process_signal_control = true;
6046                        backend.emulates_child_waits = true;
6047                    }
6048                })
6049            };
6050            let global = GlobalState::init_global_state(&config).await;
6051            let tool = Detcore::new(Tid::from_raw(process.as_raw()), &config);
6052            let mut thread = crate::ThreadState::new(caller, &config, ());
6053            thread.detpid = Some(process);
6054            thread.mm_id = MmId::initial(process);
6055            thread.record_robust_list_head(Some(0x12340));
6056            thread.thread_logical_time.add_syscall_with_cost(123);
6057            let old_time = thread.thread_logical_time.as_nanos();
6058            let old_files = Arc::clone(&thread.file_metadata);
6059            let old_memory = Arc::clone(&thread.memory_metadata);
6060            let old_mm = thread.mm_id;
6061            let mut guest = FailedExecGuest {
6062                config: &config,
6063                global: &global,
6064                thread,
6065                sender: Tid::from_raw(caller.as_raw()),
6066                process: Tid::from_raw(process.as_raw()),
6067                old_mm,
6068                errno,
6069                backend_refuses,
6070                refusal: None,
6071                refusal_takes: 0,
6072                injections: 0,
6073                requests: Mutex::new(Vec::new()),
6074            };
6075            let result = tool
6076                .handle_execveat(&mut guest, syscalls::Execveat::new())
6077                .await;
6078            match result {
6079                Err(Error::Tool(error)) if refused => assert_eq!(
6080                    error
6081                        .downcast_ref::<crate::UnsupportedSyscallError>()
6082                        .unwrap()
6083                        .0,
6084                    syscalls::Sysno::execveat
6085                ),
6086                Err(Error::Errno(actual)) if !refused => assert_eq!(actual, errno),
6087                result => panic!("wrong failed-exec policy: {result:?}"),
6088            }
6089            assert_eq!(guest.injections, 1, "backend preflight must run first");
6090            assert_eq!(guest.refusal_takes, 1, "the refusal must be asked for once");
6091            assert_eq!(guest.refusal, None, "a reported refusal must be taken");
6092            assert_eq!(guest.thread.dettid, caller);
6093            assert_eq!(guest.thread.detpid, Some(process));
6094            assert_eq!(guest.thread.mm_id, old_mm);
6095            assert_eq!(guest.thread.robust_list_head, Some(0x12340));
6096            assert_eq!(guest.thread.thread_logical_time.as_nanos(), old_time);
6097            assert!(Arc::ptr_eq(&guest.thread.file_metadata, &old_files));
6098            assert!(Arc::ptr_eq(&guest.thread.memory_metadata, &old_memory));
6099            let requests = guest.requests.lock().unwrap();
6100            assert!(matches!(requests[0], GlobalRequest::PrepareExec(..)));
6101            assert!(matches!(requests[1], GlobalRequest::CancelExec(..)));
6102            assert_eq!(requests.len(), if reported { 3 } else { 2 });
6103            if reported {
6104                assert!(
6105                    matches!(&requests[2], GlobalRequest::ReportUnsupportedSyscall(name) if name == "execveat")
6106                );
6107            }
6108            report.rewind().unwrap();
6109            let mut aggregate = String::new();
6110            report.read_to_string(&mut aggregate).unwrap();
6111            assert_eq!(aggregate, if reported { "execveat\n" } else { "" });
6112        }
6113    }
6114
6115    /// A guest whose backend fails every clone with `errno`, recording a typed
6116    /// refusal when `backend_refuses`, as an in-guest backend does for a
6117    /// thread it cannot create.
6118    struct FailedCloneGuest<'a> {
6119        config: &'a Config,
6120        global: &'a GlobalState,
6121        thread: crate::ThreadState<()>,
6122        sender: Tid,
6123        errno: Errno,
6124        backend_refuses: bool,
6125        refusal: Option<reverie::UnsupportedRefusal>,
6126        refusal_takes: usize,
6127        injections: usize,
6128        requests: Mutex<Vec<GlobalRequest>>,
6129    }
6130
6131    #[reverie::tool]
6132    impl GlobalRPC<GlobalState> for FailedCloneGuest<'_> {
6133        async fn send_rpc(
6134            &self,
6135            message: <GlobalState as GlobalTool>::Request,
6136        ) -> <GlobalState as GlobalTool>::Response {
6137            self.requests.lock().unwrap().push(message.2.clone());
6138            self.global.receive_rpc(self.sender, message).await
6139        }
6140        fn config(&self) -> &Config {
6141            self.config
6142        }
6143    }
6144
6145    #[reverie::tool]
6146    impl Guest<Detcore> for FailedCloneGuest<'_> {
6147        type Memory = reverie::syscalls::LocalMemory;
6148        type Stack = FailedExecStack;
6149
6150        fn tid(&self) -> Tid {
6151            self.sender
6152        }
6153        fn pid(&self) -> Tid {
6154            self.sender
6155        }
6156        fn ppid(&self) -> Option<Tid> {
6157            None
6158        }
6159        fn memory(&self) -> Self::Memory {
6160            reverie::syscalls::LocalMemory::new()
6161        }
6162        fn thread_state(&self) -> &crate::ThreadState<()> {
6163            &self.thread
6164        }
6165        fn thread_state_mut(&mut self) -> &mut crate::ThreadState<()> {
6166            &mut self.thread
6167        }
6168        async fn regs(&mut self) -> libc::user_regs_struct {
6169            panic!("a failed clone must not read registers")
6170        }
6171        async fn stack(&mut self) -> Self::Stack {
6172            panic!("a failed clone must not use a guest stack")
6173        }
6174        async fn daemonize(&mut self) {
6175            panic!("a failed clone must not daemonize")
6176        }
6177        async fn inject<S: SyscallInfo>(&mut self, call: S) -> Result<i64, Errno> {
6178            assert_eq!(call.number(), syscalls::Sysno::clone);
6179            self.injections += 1;
6180            self.refusal = self.backend_refuses.then(|| {
6181                reverie::UnsupportedRefusal::new(
6182                    reverie::UnsupportedOperation::NativeExec,
6183                    self.errno,
6184                    "this backend cannot create a thread",
6185                )
6186            });
6187            Err(self.errno)
6188        }
6189        fn take_unsupported_refusal(&mut self) -> Option<reverie::UnsupportedRefusal> {
6190            self.refusal_takes += 1;
6191            self.refusal.take()
6192        }
6193        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
6194            panic!("a failed clone must not retire a live guest")
6195        }
6196        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
6197            panic!("a failed clone must not replace the timer")
6198        }
6199        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
6200            panic!("a failed clone must not replace the timer")
6201        }
6202        fn read_clock(&mut self) -> Result<u64, Error> {
6203            panic!("a failed clone must not sample the clock")
6204        }
6205    }
6206
6207    /// A clone the backend refuses with a typed refusal is refused by the
6208    /// unsupported-operation policy, never answered with the refusal's errno in
6209    /// a fail-closed run; a clone that merely fails keeps its errno.
6210    #[tokio::test]
6211    async fn backend_clone_refusal_follows_the_unsupported_operation_policy() {
6212        let process = DetPid::from_raw(23);
6213        for (errno, backend_refuses, fail_closed, refused, reported) in [
6214            (Errno::EOPNOTSUPP, true, true, true, false),
6215            (Errno::EOPNOTSUPP, true, false, false, true),
6216            (Errno::EAGAIN, false, true, false, false),
6217            (Errno::EOPNOTSUPP, false, true, false, false),
6218        ] {
6219            let mut report = tempfile::tempfile().unwrap();
6220            let config = Config {
6221                sequentialize_threads: false,
6222                panic_on_unsupported_syscalls: fail_closed,
6223                exit_on_unsupported_syscall: true,
6224                shutdown_on_unsupported_syscall: false,
6225                unsupported_syscall_report_fd: Some(report.as_raw_fd()),
6226                ..Config::default()
6227            };
6228            let global = GlobalState::init_global_state(&config).await;
6229            let tool = Detcore::new(Tid::from_raw(process.as_raw()), &config);
6230            let mut thread = crate::ThreadState::new(process, &config, ());
6231            thread.detpid = Some(process);
6232            let mut guest = FailedCloneGuest {
6233                config: &config,
6234                global: &global,
6235                thread,
6236                sender: Tid::from_raw(process.as_raw()),
6237                errno,
6238                backend_refuses,
6239                refusal: None,
6240                refusal_takes: 0,
6241                injections: 0,
6242                requests: Mutex::new(Vec::new()),
6243            };
6244            let flags = (libc::CLONE_VM
6245                | libc::CLONE_FS
6246                | libc::CLONE_FILES
6247                | libc::CLONE_SIGHAND
6248                | libc::CLONE_THREAD
6249                | libc::CLONE_SYSVSEM) as u64;
6250            let clone = syscalls::Clone::new()
6251                .with_flags(nix::sched::CloneFlags::from_bits_truncate(flags as _));
6252            let result = tool
6253                .handle_clone_family(&mut guest, syscalls::family::CloneFamily::Clone(clone))
6254                .await;
6255            match result {
6256                Err(Error::Tool(error)) if refused => assert_eq!(
6257                    error
6258                        .downcast_ref::<crate::UnsupportedSyscallError>()
6259                        .unwrap()
6260                        .0,
6261                    syscalls::Sysno::clone
6262                ),
6263                Err(Error::Errno(actual)) if !refused => assert_eq!(actual, errno),
6264                result => panic!("wrong failed-clone policy: {result:?}"),
6265            }
6266            assert_eq!(guest.injections, 1);
6267            assert_eq!(guest.refusal_takes, 1, "the refusal must be asked for once");
6268            assert_eq!(guest.refusal, None, "a reported refusal must be taken");
6269            assert_eq!(guest.thread.clone_flags, None);
6270            let requests = guest.requests.lock().unwrap();
6271            assert_eq!(
6272                requests
6273                    .iter()
6274                    .filter(|request| matches!(request, GlobalRequest::ReportUnsupportedSyscall(name) if name == "clone"))
6275                    .count(),
6276                usize::from(reported)
6277            );
6278            report.rewind().unwrap();
6279            let mut aggregate = String::new();
6280            report.read_to_string(&mut aggregate).unwrap();
6281            assert_eq!(aggregate, if reported { "clone\n" } else { "" });
6282        }
6283    }
6284
6285    fn bits(signals: &[i32]) -> KernelSigset {
6286        signals
6287            .iter()
6288            .fold(0, |set, &signal| set | kernel_sigset_bit(signal))
6289    }
6290
6291    #[test]
6292    fn a_precise_futex_wait_holds_a_committed_signal_only_if_a_host_timed_source_can_post_it() {
6293        let chld = kernel_sigset_bit(libc::SIGCHLD);
6294        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6295        // Nothing committed: SIGCHLD and the host-timed signals are held.
6296        assert_eq!(futex_wait_held_after_wake(0, 0), chld);
6297        assert_eq!(futex_wait_held_after_wake(usr1, 0), chld | usr1);
6298        // A committed SIGCHLD is not held (https://github.com/rrnewton/hermit/issues/4005).
6299        assert_eq!(futex_wait_held_after_wake(0, chld), 0);
6300        assert_eq!(futex_wait_held_after_wake(usr1, chld), usr1);
6301        // Unless a host-timed source can post it too, and a committed
6302        // host-timed signal stays held.
6303        assert_eq!(futex_wait_held_after_wake(chld, chld), chld);
6304        assert_eq!(futex_wait_held_after_wake(usr1, usr1 | chld), usr1);
6305    }
6306
6307    #[test]
6308    fn kernel_signal_state_parses_proc_status() {
6309        let status = "Name:\tguest\nSigQ:\t1/1024\nSigPnd:\t0000000000000200\n\
6310                      ShdPnd:\t0000000000000400\nSigBlk:\t0000000000000800\n\
6311                      SigIgn:\t0000000000001000\nSigCgt:\t0000000000000400\n";
6312        assert_eq!(
6313            KernelSignalState::parse(status),
6314            Some(KernelSignalState {
6315                pending: bits(&[libc::SIGUSR1, libc::SIGSEGV]),
6316                thread_pending: bits(&[libc::SIGUSR1]),
6317                shared_pending: bits(&[libc::SIGSEGV]),
6318                blocked: bits(&[libc::SIGUSR2]),
6319                ignored: bits(&[libc::SIGPIPE]),
6320                caught: bits(&[libc::SIGSEGV]),
6321            })
6322        );
6323        // Every line is required: a missing one is not an empty set.
6324        assert_eq!(
6325            KernelSignalState::parse("SigPnd:\t0\nShdPnd:\t0\nSigBlk:\t0\nSigIgn:\t0\n"),
6326            None
6327        );
6328        assert_eq!(
6329            KernelSignalState::parse(
6330                "SigPnd:\tzz\nShdPnd:\t0\nSigBlk:\t0\nSigIgn:\t0\nSigCgt:\t0\n"
6331            ),
6332            None
6333        );
6334    }
6335
6336    #[test]
6337    fn only_unblocked_caught_or_fatal_signals_interrupt_a_wait() {
6338        let state = KernelSignalState {
6339            pending: bits(&[
6340                libc::SIGUSR1,
6341                libc::SIGUSR2,
6342                libc::SIGPIPE,
6343                libc::SIGTERM,
6344                libc::SIGCHLD,
6345                libc::SIGWINCH,
6346                libc::SIGURG,
6347                libc::SIGCONT,
6348            ]),
6349            blocked: bits(&[libc::SIGUSR2]),
6350            ignored: bits(&[libc::SIGPIPE]),
6351            caught: bits(&[libc::SIGUSR1, libc::SIGUSR2, libc::SIGWINCH]),
6352            ..Default::default()
6353        };
6354        // Caught and unblocked (SIGUSR1, SIGWINCH) and default-fatal (SIGTERM) end the
6355        // wait; blocked (SIGUSR2), ignored (SIGPIPE), and default-ignored ones do not.
6356        assert_eq!(
6357            state.pending_interrupting(state.blocked, false),
6358            bits(&[libc::SIGUSR1, libc::SIGWINCH, libc::SIGTERM])
6359        );
6360        // The mask the guest had when the wait began decides, not the current one.
6361        assert_eq!(
6362            state.pending_interrupting(0, false),
6363            bits(&[libc::SIGUSR1, libc::SIGUSR2, libc::SIGWINCH, libc::SIGTERM])
6364        );
6365        let interrupting = state.interrupting(state.blocked);
6366        assert_ne!(interrupting & kernel_sigset_bit(libc::SIGKILL), 0);
6367        assert_ne!(interrupting & kernel_sigset_bit(libc::SIGSTOP), 0);
6368        assert_eq!(
6369            interrupting & kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32),
6370            0
6371        );
6372        assert_eq!(kernel_sigset_bit(0), 0);
6373        assert_eq!(kernel_sigset_bit(65), 0);
6374    }
6375
6376    /// A wait whose restart starts its relative timeout again does not end for a
6377    /// default `SIGTSTP`, `SIGTTIN`, or `SIGTTOU`, which Linux discards in an
6378    /// orphaned process group; every other wait still does. `SIGSTOP`, a caught
6379    /// stop signal, and a fatal signal end both kinds, and an ignored stop signal
6380    /// ends neither (review of https://github.com/rrnewton/hermit/pull/3361 at
6381    /// `cbb36408`, finding 4).
6382    #[test]
6383    fn a_rearming_wait_is_not_ended_by_a_default_job_control_stop() {
6384        let stops = bits(&[libc::SIGTSTP, libc::SIGTTIN, libc::SIGTTOU]);
6385        let state = KernelSignalState {
6386            pending: stops | bits(&[libc::SIGSTOP, libc::SIGTERM]),
6387            ..Default::default()
6388        };
6389        assert_eq!(state.default_job_control_stops(), stops);
6390        assert_eq!(state.pending_interrupting(0, false), state.pending);
6391        assert_eq!(
6392            state.pending_interrupting(0, true),
6393            bits(&[libc::SIGSTOP, libc::SIGTERM])
6394        );
6395        let rearming = state.interrupting_wait(0, true);
6396        assert_eq!(rearming & stops, 0);
6397        assert_eq!(rearming, state.interrupting(0) & !stops);
6398
6399        // A handler makes SIGTSTP an ordinary caught signal, and SIG_IGN takes
6400        // SIGTTIN out of every wait; SIGTTOU keeps its default action.
6401        let state = KernelSignalState {
6402            pending: stops,
6403            caught: bits(&[libc::SIGTSTP]),
6404            ignored: bits(&[libc::SIGTTIN]),
6405            ..Default::default()
6406        };
6407        assert_eq!(state.default_job_control_stops(), bits(&[libc::SIGTTOU]));
6408        assert_eq!(state.pending_interrupting(0, true), bits(&[libc::SIGTSTP]));
6409        assert_eq!(
6410            state.pending_interrupting(0, false),
6411            bits(&[libc::SIGTSTP, libc::SIGTTOU])
6412        );
6413        // The mask still decides first.
6414        assert_eq!(state.pending_interrupting(bits(&[libc::SIGTSTP]), true), 0);
6415    }
6416
6417    #[test]
6418    fn kernel_blocked_mask_preserves_libc_signal_membership() {
6419        let mask = blocked_signal_mask();
6420        let mut libc_mask: libc::sigset_t = unsafe { std::mem::zeroed() };
6421        unsafe {
6422            libc::sigfillset(&mut libc_mask);
6423            libc::sigdelset(&mut libc_mask, reverie::PERF_EVENT_SIGNAL as i32);
6424        }
6425        for raw_signal in 1..=KernelSigset::BITS as i32 {
6426            assert_eq!(
6427                signal_is_blocked(&mask, SigWrapper(raw_signal)),
6428                unsafe { libc::sigismember(&libc_mask, raw_signal) == 1 },
6429                "signal {raw_signal} membership changed while converting to the kernel ABI"
6430            );
6431        }
6432    }
6433
6434    #[test]
6435    fn clone_without_child_cleartid_does_not_register_the_pointer() {
6436        assert_eq!(
6437            child_tid_clear_address(CloneFlags::CLONE_CHILD_SETTID, 0x1234),
6438            0
6439        );
6440    }
6441
6442    #[test]
6443    fn clone_with_child_cleartid_registers_the_pointer() {
6444        assert_eq!(
6445            child_tid_clear_address(CloneFlags::CLONE_CHILD_CLEARTID, 0x1234),
6446            0x1234
6447        );
6448    }
6449
6450    #[test]
6451    fn linux_default_dispositions_that_do_not_interrupt_child_waits() {
6452        for signal in [libc::SIGCHLD, libc::SIGCONT, libc::SIGURG, libc::SIGWINCH] {
6453            assert!(signal_default_disposition_does_not_interrupt_child_wait(
6454                SigWrapper(signal)
6455            ));
6456        }
6457        for signal in [libc::SIGALRM, libc::SIGSTOP, libc::SIGUSR1] {
6458            assert!(!signal_default_disposition_does_not_interrupt_child_wait(
6459                SigWrapper(signal)
6460            ));
6461        }
6462    }
6463
6464    /// signal(7): the signals whose default action is to terminate or dump
6465    /// core end the process; those ignored, stopping or continuing by
6466    /// default do not, and SIGKILL never reaches a delivery callback
6467    /// (https://github.com/rrnewton/hermit/issues/4278).
6468    #[test]
6469    fn default_actions_that_end_the_process() {
6470        for signal in [
6471            libc::SIGTERM,
6472            libc::SIGINT,
6473            libc::SIGHUP,
6474            libc::SIGQUIT,
6475            libc::SIGABRT,
6476            libc::SIGSEGV,
6477            libc::SIGBUS,
6478            libc::SIGFPE,
6479            libc::SIGILL,
6480            libc::SIGPIPE,
6481            libc::SIGALRM,
6482            libc::SIGUSR1,
6483            libc::SIGUSR2,
6484            libc::SIGRTMIN(),
6485            libc::SIGRTMAX(),
6486        ] {
6487            assert!(
6488                signal_default_action_ends_the_process(SigWrapper(signal)),
6489                "{signal}"
6490            );
6491        }
6492        for signal in [
6493            libc::SIGCHLD,
6494            libc::SIGCONT,
6495            libc::SIGURG,
6496            libc::SIGWINCH,
6497            libc::SIGSTOP,
6498            libc::SIGTSTP,
6499            libc::SIGTTIN,
6500            libc::SIGTTOU,
6501            libc::SIGKILL,
6502        ] {
6503            assert!(
6504                !signal_default_action_ends_the_process(SigWrapper(signal)),
6505                "{signal}"
6506            );
6507        }
6508    }
6509
6510    #[test]
6511    fn uncatchable_signals_do_not_require_a_sigaction_query() {
6512        assert!(signal_has_uncatchable_default_disposition(SigWrapper(
6513            libc::SIGKILL
6514        )));
6515        assert!(signal_has_uncatchable_default_disposition(SigWrapper(
6516            libc::SIGSTOP
6517        )));
6518        assert!(!signal_has_uncatchable_default_disposition(SigWrapper(
6519            libc::SIGUSR1
6520        )));
6521    }
6522
6523    #[test]
6524    fn waitid_ready_child_wins_when_scheduler_also_reports_a_signal() {
6525        assert_eq!(
6526            exact_wait_poll_decision(true, true, Some(ExactChildWaitState::Running)),
6527            ExactWaitPollDecision::ChildReady
6528        );
6529        assert_eq!(
6530            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::LogicallyExited)),
6531            ExactWaitPollDecision::ReapAfterLogicalExit
6532        );
6533        assert_eq!(
6534            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::PhysicalExitPending)),
6535            ExactWaitPollDecision::AwaitPhysicalExit
6536        );
6537        assert_eq!(
6538            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::Running)),
6539            ExactWaitPollDecision::Interrupted
6540        );
6541        assert_eq!(
6542            exact_wait_poll_decision(false, false, Some(ExactChildWaitState::Running)),
6543            ExactWaitPollDecision::Retry
6544        );
6545    }
6546
6547    #[test]
6548    fn wait4_argument_validation_follows_linux_precedence() {
6549        let valid_bits = [0, 1, 3, 29, 30, 31];
6550        for bit in valid_bits {
6551            let options = WaitPidFlag::from_bits_retain((1_u32 << bit) as libc::c_int);
6552            assert_eq!(validate_wait4_arguments(-1, options), Ok(()), "bit {bit}");
6553        }
6554
6555        for bit in (0..u32::BITS).filter(|bit| !valid_bits.contains(bit)) {
6556            let options = WaitPidFlag::from_bits_retain((1_u32 << bit) as libc::c_int);
6557            assert_eq!(
6558                validate_wait4_arguments(-1, options),
6559                Err(Errno::EINVAL),
6560                "bit {bit}"
6561            );
6562        }
6563
6564        // Only INT_MIN is refused: every other pid, including the nearest
6565        // process-group selector, must still reach the wait.
6566        for pid in [libc::pid_t::MIN + 1, -2, 0, 1, libc::pid_t::MAX] {
6567            assert_eq!(
6568                validate_wait4_arguments(pid, WaitPidFlag::empty()),
6569                Ok(()),
6570                "pid {pid}"
6571            );
6572        }
6573        assert_eq!(
6574            validate_wait4_arguments(libc::pid_t::MIN, WaitPidFlag::empty()),
6575            Err(Errno::ESRCH)
6576        );
6577        assert_eq!(
6578            validate_wait4_arguments(libc::pid_t::MIN, WaitPidFlag::from_bits_retain(0x10)),
6579            Err(Errno::EINVAL),
6580            "invalid options must win over the INT_MIN selector"
6581        );
6582    }
6583
6584    #[test]
6585    fn stale_any_child_preserves_interrupt_until_no_ready_child_remains() {
6586        let next_child = DetPid::from_raw(200);
6587
6588        assert!(
6589            !stale_any_wait_must_interrupt(true, Some(next_child)),
6590            "another ready child must retain child-ready precedence"
6591        );
6592        assert!(
6593            stale_any_wait_must_interrupt(true, None),
6594            "a pending signal must interrupt before the wait parks again"
6595        );
6596        assert!(!stale_any_wait_must_interrupt(false, None));
6597    }
6598
6599    #[test]
6600    fn ioprio_query_reports_fixed_raw_and_effective_defaults() {
6601        assert_eq!(virtual_ioprio(IOPRIO_WHO_PROCESS), Ok(0));
6602        assert_eq!(
6603            virtual_ioprio(IOPRIO_WHO_PGRP),
6604            Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE))
6605        );
6606        assert_eq!(
6607            virtual_ioprio(IOPRIO_WHO_USER),
6608            Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE))
6609        );
6610        assert_eq!(virtual_ioprio(0), Err(Errno::EINVAL));
6611        assert_eq!(virtual_ioprio(4), Err(Errno::EINVAL));
6612    }
6613
6614    #[test]
6615    fn waitid_siginfo_canonicalization_clears_only_cpu_accounting() {
6616        let mut info: libc::siginfo_t = unsafe { std::mem::zeroed() };
6617        info.si_signo = libc::SIGCHLD;
6618        info.si_code = libc::CLD_EXITED;
6619        // SAFETY: This uses the same Linux SIGCHLD layout mirror validated by
6620        // canonicalize_waitid_siginfo.
6621        let fields = unsafe {
6622            &mut (*(std::ptr::addr_of_mut!(info)).cast::<WaitidSiginfoHead>())
6623                .fields
6624                .sigchld
6625        };
6626        fields.pid = 123;
6627        fields.uid = 456;
6628        fields.status = 7;
6629        fields.utime = 8;
6630        fields.stime = 9;
6631
6632        canonicalize_waitid_siginfo(&mut info);
6633
6634        assert_eq!(info.si_signo, libc::SIGCHLD);
6635        assert_eq!(info.si_code, libc::CLD_EXITED);
6636        assert_eq!(unsafe { info.si_pid() }, 123);
6637        assert_eq!(unsafe { info.si_uid() }, 456);
6638        assert_eq!(unsafe { info.si_status() }, 7);
6639        assert_eq!(unsafe { info.si_utime() }, 0);
6640        assert_eq!(unsafe { info.si_stime() }, 0);
6641    }
6642
6643    #[test]
6644    fn wait_status_rollup_only_accepts_process_termination() {
6645        assert!(wait_status_is_termination(0));
6646        assert!(wait_status_is_termination(libc::SIGTERM));
6647        assert!(!wait_status_is_termination((libc::SIGSTOP << 8) | 0x7f));
6648        assert!(!wait_status_is_termination(0xffff));
6649
6650        assert!(waitid_code_is_termination(libc::CLD_EXITED));
6651        assert!(waitid_code_is_termination(libc::CLD_KILLED));
6652        assert!(waitid_code_is_termination(libc::CLD_DUMPED));
6653        assert!(!waitid_code_is_termination(libc::CLD_STOPPED));
6654        assert!(!waitid_code_is_termination(libc::CLD_CONTINUED));
6655        assert!(!waitid_code_is_termination(libc::CLD_TRAPPED));
6656    }
6657
6658    /// `do_futex` (kernel/futex/syscalls.c): FUTEX_CLOCK_REALTIME only with
6659    /// FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI or FUTEX_LOCK_PI2, else -ENOSYS;
6660    /// the removed FUTEX_FD and unknown commands are -ENOSYS; the PI commands are
6661    /// refused by name; the rest are emulated
6662    /// (https://github.com/rrnewton/hermit/issues/3958).
6663    #[test]
6664    fn futex_commands_are_classified_as_linux_dispatches_them() {
6665        use FutexCommand::*;
6666        let private = libc::FUTEX_PRIVATE_FLAG;
6667        let realtime = libc::FUTEX_CLOCK_REALTIME;
6668        for cmd in [
6669            libc::FUTEX_WAIT,
6670            libc::FUTEX_WAIT_BITSET,
6671            libc::FUTEX_WAKE,
6672            libc::FUTEX_WAKE_BITSET,
6673            libc::FUTEX_REQUEUE,
6674            libc::FUTEX_CMP_REQUEUE,
6675            libc::FUTEX_WAKE_OP,
6676        ] {
6677            assert_eq!(classify_futex_command(cmd), Served, "cmd {cmd}");
6678            assert_eq!(classify_futex_command(cmd | private), Served, "cmd {cmd}");
6679        }
6680        assert_eq!(
6681            classify_futex_command(libc::FUTEX_WAIT_BITSET | realtime),
6682            Served
6683        );
6684        for cmd in [
6685            libc::FUTEX_WAIT,
6686            libc::FUTEX_WAKE,
6687            libc::FUTEX_REQUEUE,
6688            libc::FUTEX_WAKE_OP,
6689        ] {
6690            assert_eq!(classify_futex_command(cmd | realtime), NoSys, "cmd {cmd}");
6691        }
6692        for cmd in [libc::FUTEX_FD, 14, 99, libc::FUTEX_CMD_MASK] {
6693            assert_eq!(classify_futex_command(cmd), NoSys, "cmd {cmd}");
6694        }
6695        assert_eq!(
6696            classify_futex_command(libc::FUTEX_LOCK_PI | private),
6697            PriorityInheritance("FUTEX_LOCK_PI")
6698        );
6699        assert_eq!(
6700            classify_futex_command(libc::FUTEX_LOCK_PI2 | realtime),
6701            PriorityInheritance("FUTEX_LOCK_PI2")
6702        );
6703        assert_eq!(
6704            classify_futex_command(libc::FUTEX_LOCK_PI | realtime),
6705            NoSys
6706        );
6707        for (cmd, name) in [
6708            (libc::FUTEX_UNLOCK_PI, "FUTEX_UNLOCK_PI"),
6709            (libc::FUTEX_TRYLOCK_PI, "FUTEX_TRYLOCK_PI"),
6710            (libc::FUTEX_WAIT_REQUEUE_PI, "FUTEX_WAIT_REQUEUE_PI"),
6711            (libc::FUTEX_CMP_REQUEUE_PI, "FUTEX_CMP_REQUEUE_PI"),
6712        ] {
6713            assert_eq!(classify_futex_command(cmd), PriorityInheritance(name));
6714        }
6715    }
6716
6717    /// FUTEX_WAKE_OP's encoding, as `futex_atomic_op_inuser` decodes it: 12-bit
6718    /// signed arguments, the shift flag (with an out-of-range shift masked to
6719    /// 0..31), and -ENOSYS for an unknown operation or comparison.
6720    /// An injected probe's futex op, uaddr, uaddr2, val and val3.
6721    type ProbeArgs = (i32, usize, usize, i32, i32);
6722
6723    /// A guest standing in for the kernel: each injected probe is recorded and
6724    /// answered with the next scripted result.
6725    struct ScriptedProbes {
6726        answers: std::collections::VecDeque<Result<i64, Errno>>,
6727        probes: Vec<ProbeArgs>,
6728    }
6729
6730    impl ScriptedProbes {
6731        fn inject(&mut self, probe: syscalls::Futex) -> KeyProbeAnswer<'_> {
6732            self.probes.push((
6733                probe.futex_op(),
6734                probe.uaddr().map_or(0, AddrMut::as_raw),
6735                probe.uaddr2().map_or(0, AddrMut::as_raw),
6736                probe.val(),
6737                probe.val3(),
6738            ));
6739            let answer = self
6740                .answers
6741                .pop_front()
6742                .expect("the probe was injected more often than scripted");
6743            Box::pin(async move { answer })
6744        }
6745    }
6746
6747    fn run_scripted(
6748        access: KeyAccess,
6749        answer: Result<i64, Errno>,
6750    ) -> (SharedKeyProbe, Vec<ProbeArgs>) {
6751        let mut guest = ScriptedProbes {
6752            answers: [answer].into_iter().collect(),
6753            probes: Vec::new(),
6754        };
6755        let result = futures::executor::block_on(run_shared_futex_key_probe(
6756            &mut guest,
6757            shared_futex_key_probe(0x1000, access),
6758            access,
6759            |guest, probe| guest.inject(probe),
6760        ));
6761        (result, guest.probes)
6762    }
6763
6764    /// The shared-key admission probe is injected exactly once
6765    /// (https://github.com/rrnewton/hermit/pull/4020). When a signal stops it
6766    /// before it runs (`Guest::inject` returns ERESTARTSYS, or EINTR), it is not
6767    /// injected again, because Reverie holds that signal in a single slot that a
6768    /// second interruption would overwrite, and the interruption is reported as
6769    /// such: never as an admitted key and never as the guest's errno. The
6770    /// caller stops the run by name on it. The kernel's own answers keep their
6771    /// meaning: 0 admits, ENOSYS admits only a WRITE key, EFAULT is the
6772    /// guest's.
6773    #[test]
6774    fn an_interrupted_shared_key_probe_is_never_retried_or_taken_as_an_answer() {
6775        let read = (libc::FUTEX_REQUEUE, 0x1000, 0x1000, 0, 0);
6776        let write = (
6777            libc::FUTEX_WAKE_OP,
6778            0x1000,
6779            0x1000,
6780            0,
6781            (7 << 28) | (1 << 12),
6782        );
6783        for (access, args) in [(KeyAccess::Read, read), (KeyAccess::Write, write)] {
6784            for errno in [Errno::ERESTARTSYS, Errno::EINTR] {
6785                assert_eq!(
6786                    run_scripted(access, Err(errno)),
6787                    (SharedKeyProbe::Interrupted(errno), vec![args]),
6788                    "{access:?} {errno}"
6789                );
6790            }
6791            assert_eq!(
6792                run_scripted(access, Ok(0)),
6793                (SharedKeyProbe::Admitted, vec![args])
6794            );
6795            assert_eq!(
6796                run_scripted(access, Err(Errno::EFAULT)),
6797                (SharedKeyProbe::Refused(Errno::EFAULT), vec![args])
6798            );
6799        }
6800        assert_eq!(
6801            run_scripted(KeyAccess::Read, Err(Errno::ENOSYS)),
6802            (SharedKeyProbe::Refused(Errno::ENOSYS), vec![read])
6803        );
6804        assert_eq!(
6805            run_scripted(KeyAccess::Write, Err(Errno::ENOSYS)),
6806            (SharedKeyProbe::Admitted, vec![write])
6807        );
6808    }
6809
6810    #[test]
6811    fn futex_wake_op_decodes_and_applies_as_linux() {
6812        let encode = |op: u32, cmp: u32, oparg: u32, cmparg: u32| {
6813            ((op & 0xf) << 28) | ((cmp & 0xf) << 24) | ((oparg & 0xfff) << 12) | (cmparg & 0xfff)
6814        };
6815        let set5_eq0 = FutexWakeOp::decode(encode(FUTEX_OP_SET, FUTEX_OP_CMP_EQ, 5, 0));
6816        assert_eq!(set5_eq0.apply(0), Some(5));
6817        assert_eq!(set5_eq0.compare(0), Some(true));
6818        assert_eq!(set5_eq0.compare(1), Some(false));
6819        let add_minus1 = FutexWakeOp::decode(encode(FUTEX_OP_ADD, FUTEX_OP_CMP_LT, 0xfff, 0x800));
6820        assert_eq!(add_minus1.apply(10), Some(9));
6821        assert_eq!(add_minus1.apply(i32::MIN), Some(i32::MAX));
6822        assert_eq!(add_minus1.compare(-2048), Some(false));
6823        assert_eq!(add_minus1.compare(-2049), Some(true));
6824        let or = FutexWakeOp::decode(encode(FUTEX_OP_OR, FUTEX_OP_CMP_NE, 0b100, 7));
6825        assert_eq!(or.apply(0b011), Some(0b111));
6826        assert_eq!(or.compare(7), Some(false));
6827        let andn = FutexWakeOp::decode(encode(FUTEX_OP_ANDN, FUTEX_OP_CMP_GE, 0b110, 3));
6828        assert_eq!(andn.apply(0b111), Some(0b001));
6829        assert_eq!(andn.compare(3), Some(true));
6830        let xor = FutexWakeOp::decode(encode(FUTEX_OP_XOR, FUTEX_OP_CMP_LE, 0xff, 0));
6831        assert_eq!(xor.apply(0x0f), Some(0xf0));
6832        assert_eq!(xor.compare(1), Some(false));
6833        let shift = FutexWakeOp::decode(encode(
6834            FUTEX_OP_OPARG_SHIFT | FUTEX_OP_OR,
6835            FUTEX_OP_CMP_GT,
6836            3,
6837            0,
6838        ));
6839        assert_eq!(shift.apply(0), Some(8));
6840        assert_eq!(shift.compare(1), Some(true));
6841        // A shift of -1 (0xfff) is masked to 31, as Linux does.
6842        let masked = FutexWakeOp::decode(encode(FUTEX_OP_OPARG_SHIFT | FUTEX_OP_SET, 0, 0xfff, 0));
6843        assert_eq!(masked.apply(0), Some(i32::MIN));
6844        let unknown_op = FutexWakeOp::decode(encode(7, FUTEX_OP_CMP_EQ, 1, 0));
6845        assert!(!unknown_op.has_known_operation());
6846        assert_eq!(unknown_op.apply(0), None);
6847        let unknown_cmp = FutexWakeOp::decode(encode(FUTEX_OP_SET, 6, 1, 0));
6848        assert!(unknown_cmp.has_known_operation());
6849        assert_eq!(unknown_cmp.compare(0), None);
6850    }
6851
6852    #[test]
6853    fn futex_timeout_units_and_modes_match_linux() {
6854        let timeout = Timespec {
6855            tv_sec: 2,
6856            tv_nsec: 3,
6857        };
6858        assert_eq!(
6859            parse_futex_timeout(libc::FUTEX_WAIT, timeout),
6860            Ok(FutexTimeout::Relative(2_000_000_003))
6861        );
6862        assert_eq!(
6863            parse_futex_timeout(libc::FUTEX_WAIT_BITSET, timeout),
6864            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
6865                2_000_000_003
6866            )))
6867        );
6868        // The command bits must be matched after masking off FUTEX_PRIVATE_FLAG
6869        // (and FUTEX_CLOCK_REALTIME): a private FUTEX_WAIT_BITSET still uses an
6870        // absolute deadline, and a private FUTEX_WAIT still uses a relative one.
6871        assert_eq!(
6872            parse_futex_timeout(libc::FUTEX_WAIT_BITSET | libc::FUTEX_PRIVATE_FLAG, timeout),
6873            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
6874                2_000_000_003
6875            )))
6876        );
6877        assert_eq!(
6878            parse_futex_timeout(libc::FUTEX_WAIT | libc::FUTEX_PRIVATE_FLAG, timeout),
6879            Ok(FutexTimeout::Relative(2_000_000_003))
6880        );
6881    }
6882
6883    #[test]
6884    fn absolute_futex_timeout_is_rebased_to_logical_time() {
6885        let logical_now = LogicalTime::from_secs(100);
6886        let clock_now = LogicalTime::from_secs(5_000);
6887        let deadline = clock_now + Duration::from_millis(100);
6888        assert_eq!(
6889            rebase_absolute_timeout(deadline, clock_now, logical_now),
6890            logical_now + Duration::from_millis(100)
6891        );
6892        assert_eq!(
6893            rebase_absolute_timeout(
6894                clock_now - LogicalTime::from_nanos(1),
6895                clock_now,
6896                logical_now
6897            ),
6898            logical_now
6899        );
6900    }
6901
6902    #[test]
6903    fn absolute_futex_timeout_detects_host_and_logical_clock_domains() {
6904        let host_monotonic_now = LogicalTime::from_secs(374_766);
6905        let logical_now = LogicalTime::from_secs(1_640_995_199);
6906        let delta = Duration::from_millis(100);
6907
6908        assert!(absolute_timeout_uses_host_clock(
6909            host_monotonic_now + delta,
6910            host_monotonic_now,
6911            logical_now
6912        ));
6913        assert!(!absolute_timeout_uses_host_clock(
6914            logical_now + delta,
6915            host_monotonic_now,
6916            logical_now
6917        ));
6918
6919        let host_realtime_now = LogicalTime::from_secs(1_785_142_800);
6920        assert!(absolute_timeout_uses_host_clock(
6921            host_realtime_now + delta,
6922            host_realtime_now,
6923            logical_now
6924        ));
6925    }
6926
6927    /// Linux's `futex_init_timeout` refuses only an invalid timespec, and
6928    /// `timespec64_to_ktime` clamps a valid one beyond `KTIME_MAX` instead of
6929    /// refusing it (Codex re-check of https://github.com/rrnewton/hermit/pull/4061).
6930    #[test]
6931    fn futex_timeout_clamps_a_huge_valid_timespec_like_ktime() {
6932        let huge = Timespec {
6933            tv_sec: libc::time_t::MAX,
6934            tv_nsec: 0,
6935        };
6936        assert!(futex_timespec_is_valid(huge));
6937        assert_eq!(
6938            parse_futex_timeout(libc::FUTEX_WAIT, huge),
6939            Ok(FutexTimeout::Relative(FUTEX_KTIME_MAX_NANOS))
6940        );
6941        assert_eq!(
6942            parse_futex_timeout(libc::FUTEX_WAIT_BITSET, huge),
6943            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
6944                FUTEX_KTIME_MAX_NANOS
6945            )))
6946        );
6947        let at_ktime_sec_max = Timespec {
6948            tv_sec: (FUTEX_KTIME_MAX_NANOS / 1_000_000_000) as libc::time_t,
6949            tv_nsec: 0,
6950        };
6951        assert_eq!(
6952            parse_futex_timeout(libc::FUTEX_WAIT, at_ktime_sec_max),
6953            Ok(FutexTimeout::Relative(FUTEX_KTIME_MAX_NANOS))
6954        );
6955        let just_below = Timespec {
6956            tv_sec: (FUTEX_KTIME_MAX_NANOS / 1_000_000_000 - 1) as libc::time_t,
6957            tv_nsec: 999_999_999,
6958        };
6959        assert_eq!(
6960            parse_futex_timeout(libc::FUTEX_WAIT, just_below),
6961            Ok(FutexTimeout::Relative(
6962                (FUTEX_KTIME_MAX_NANOS / 1_000_000_000) * 1_000_000_000 - 1
6963            ))
6964        );
6965        for invalid in [(-1, 0), (0, -1), (0, 1_000_000_000)] {
6966            assert!(!futex_timespec_is_valid(Timespec {
6967                tv_sec: invalid.0,
6968                tv_nsec: invalid.1,
6969            }));
6970        }
6971    }
6972
6973    #[test]
6974    fn futex_timeout_rejects_invalid_timespecs() {
6975        assert_eq!(
6976            parse_futex_timeout(
6977                libc::FUTEX_WAIT,
6978                Timespec {
6979                    tv_sec: -1,
6980                    tv_nsec: 0,
6981                },
6982            ),
6983            Err(Errno::EINVAL)
6984        );
6985        assert_eq!(
6986            parse_futex_timeout(
6987                libc::FUTEX_WAIT_BITSET,
6988                Timespec {
6989                    tv_sec: 0,
6990                    tv_nsec: 1_000_000_000,
6991                },
6992            ),
6993            Err(Errno::EINVAL)
6994        );
6995    }
6996
6997    // The expectations below are not guesses at the kernel's behaviour: each is
6998    // a row measured natively on this host (Linux 6.19, x86-64) with a raw
6999    // `sched_setattr` probe. Where a row differs from what the handler used to
7000    // do, the difference is called out.
7001
7002    /// A well-formed VER0 SCHED_OTHER descriptor, as the decoded fields.
7003    fn plain_attr() -> SchedAttrFields {
7004        SchedAttrFields {
7005            policy: 0,
7006            sched_flags: 0,
7007            priority: 0,
7008            runtime: 0,
7009            deadline: 0,
7010            period: 0,
7011        }
7012    }
7013
7014    #[test]
7015    fn size_zero_is_a_well_formed_ver0_request() {
7016        // ABI compatibility quirk: `if (!size) size = SCHED_ATTR_SIZE_VER0;`.
7017        // Measured native: ret 0. PR #2288 returned E2BIG.
7018        assert_eq!(sched_attr_effective_size(0), Ok(SCHED_ATTR_SIZE_VER0));
7019    }
7020
7021    #[test]
7022    fn size_below_ver0_or_past_a_page_is_too_big() {
7023        // Measured native: size 1, 47 and 4097 all give E2BIG.
7024        assert_eq!(sched_attr_effective_size(1), Err(()));
7025        assert_eq!(sched_attr_effective_size(SCHED_ATTR_SIZE_VER0 - 1), Err(()));
7026        assert_eq!(sched_attr_effective_size(SCHED_ATTR_MAX_SIZE + 1), Err(()));
7027    }
7028
7029    #[test]
7030    fn size_from_ver0_through_one_page_is_accepted_unchanged() {
7031        // Measured native: 48, 56, 57 and 4096 all give ret 0.
7032        for size in [
7033            SCHED_ATTR_SIZE_VER0,
7034            SCHED_ATTR_SIZE_VER1,
7035            SCHED_ATTR_SIZE_VER1 + 1,
7036            SCHED_ATTR_MAX_SIZE,
7037        ] {
7038            assert_eq!(sched_attr_effective_size(size), Ok(size), "size {}", size);
7039        }
7040    }
7041
7042    #[test]
7043    fn sched_ext_is_a_valid_policy_and_sched_iso_is_not() {
7044        // Measured native: policy 7 gives ret 0; policy 4 gives EINVAL. PR
7045        // #2288 refused 7.
7046        assert!(is_valid_sched_policy(SCHED_EXT), "SCHED_EXT is accepted");
7047        assert!(!is_valid_sched_policy(4), "SCHED_ISO is reserved");
7048        for policy in [0, 1, 2, 3, 5, 6] {
7049            assert!(is_valid_sched_policy(policy), "policy {}", policy);
7050        }
7051        // Measured native: policy 8 and 99 both give EINVAL.
7052        for policy in [8, 99] {
7053            assert!(!is_valid_sched_policy(policy), "policy {}", policy);
7054        }
7055    }
7056
7057    // ---- which side of the pid lookup each rule falls on --------------------
7058    // The kernel resolves the pid between `sched_setattr()` and
7059    // `__sched_setscheduler()`, so a request naming a nonexistent pid reports
7060    // ESRCH for every rule on the far side and its own errno for every rule on
7061    // the near side. Measured natively with pid 0x3fffffff:
7062    //     bad sched_flags    -> ESRCH    (far side)
7063    //     bad priority       -> ESRCH    (far side)
7064    //     negative policy    -> EINVAL   (near side)
7065    //     util-clamp size 48 -> EINVAL   (near side)
7066    // The split between the two functions below is exactly that boundary.
7067
7068    #[test]
7069    fn util_clamp_size_rule_is_decided_before_the_pid_lookup() {
7070        // Measured native: EINVAL even with a nonexistent pid.
7071        let mut attr = plain_attr();
7072        attr.sched_flags = SCHED_FLAG_UTIL_CLAMP_MIN;
7073        assert_eq!(
7074            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
7075            Err(Errno::EINVAL)
7076        );
7077        assert_eq!(
7078            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER1, &attr),
7079            Ok(())
7080        );
7081        // ...and it is not re-decided on the far side.
7082        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
7083    }
7084
7085    #[test]
7086    fn a_negative_policy_is_decided_before_the_pid_lookup() {
7087        // Measured native: EINVAL even with a nonexistent pid, and EINVAL with
7088        // KEEP_POLICY too -- the signed test sits above the substitution.
7089        let mut attr = plain_attr();
7090        attr.policy = 0x8000_0000;
7091        assert_eq!(
7092            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
7093            Err(Errno::EINVAL)
7094        );
7095        attr.sched_flags = SCHED_FLAG_KEEP_POLICY;
7096        assert_eq!(
7097            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
7098            Err(Errno::EINVAL),
7099            "KEEP_POLICY must not hide a negative policy"
7100        );
7101    }
7102
7103    #[test]
7104    fn policy_and_flag_rules_are_decided_after_the_pid_lookup() {
7105        // Measured native: with a nonexistent pid both of these report ESRCH,
7106        // so neither may be decided on the near side.
7107        let mut bad_policy = plain_attr();
7108        bad_policy.policy = 99;
7109        assert_eq!(
7110            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &bad_policy),
7111            Ok(()),
7112            "an undefined policy must survive the near side so ESRCH can win"
7113        );
7114        assert_eq!(
7115            validate_sched_attr_after_lookup(&bad_policy),
7116            Err(Errno::EINVAL)
7117        );
7118
7119        let mut bad_flag = plain_attr();
7120        bad_flag.sched_flags = 0x80;
7121        assert_eq!(
7122            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &bad_flag),
7123            Ok(()),
7124            "an undefined sched_flags bit must survive the near side"
7125        );
7126        assert_eq!(
7127            validate_sched_attr_after_lookup(&bad_flag),
7128            Err(Errno::EINVAL)
7129        );
7130    }
7131
7132    #[test]
7133    fn keep_policy_makes_the_policy_field_irrelevant() {
7134        // Measured native: policy 99 alone is EINVAL, but policy 99 with
7135        // SCHED_FLAG_KEEP_POLICY is ret 0 -- the kernel overwrites the field
7136        // with SETPARAM_POLICY and never runs valid_policy(). PR #2288 refused
7137        // it.
7138        let mut attr = plain_attr();
7139        attr.policy = 99;
7140        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
7141        attr.sched_flags = SCHED_FLAG_KEEP_POLICY;
7142        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
7143    }
7144
7145    #[test]
7146    fn defined_sched_flags_bits_are_accepted_and_undefined_ones_are_not() {
7147        // Measured native: sched_flags 0x80 gives EINVAL; RESET_ON_FORK,
7148        // KEEP_PARAMS, KEEP_ALL, RECLAIM and DL_OVERRUN are all ret 0 at
7149        // size 48. PR #2288 ignored sched_flags entirely.
7150        let mut attr = plain_attr();
7151        attr.sched_flags = 0x80;
7152        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
7153        for flag in [
7154            SCHED_FLAG_RESET_ON_FORK,
7155            SCHED_FLAG_RECLAIM,
7156            SCHED_FLAG_DL_OVERRUN,
7157            SCHED_FLAG_KEEP_PARAMS,
7158            SCHED_FLAG_KEEP_POLICY,
7159        ] {
7160            let mut ok = plain_attr();
7161            ok.sched_flags = flag;
7162            assert_eq!(
7163                validate_sched_attr_after_lookup(&ok),
7164                Ok(()),
7165                "flag {:#x}",
7166                flag
7167            );
7168        }
7169        // The whole mask at once is refused on the NEAR side, and for the
7170        // util-clamp size reason rather than the flag-validity one: measured
7171        // native EINVAL at size 48.
7172        let mut all = plain_attr();
7173        all.sched_flags = SCHED_FLAG_ALL;
7174        assert_eq!(
7175            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &all),
7176            Err(Errno::EINVAL)
7177        );
7178        assert_eq!(
7179            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER1, &all),
7180            Ok(())
7181        );
7182        assert_eq!(validate_sched_attr_after_lookup(&all), Ok(()));
7183    }
7184
7185    #[test]
7186    fn priority_must_agree_with_the_policy() {
7187        // The kernel states this as `rt_policy(policy) != (prio != 0)`.
7188        // Measured native, all EINVAL: OTHER/BATCH/IDLE with priority 1, and
7189        // FIFO/RR with priority 0. PR #2288 accepted every one of them.
7190        for policy in [0u32, 3, 5] {
7191            let mut attr = plain_attr();
7192            attr.policy = policy;
7193            attr.priority = 1;
7194            assert_eq!(
7195                validate_sched_attr_after_lookup(&attr),
7196                Err(Errno::EINVAL),
7197                "policy {} with priority 1",
7198                policy
7199            );
7200            attr.priority = 0;
7201            assert_eq!(
7202                validate_sched_attr_after_lookup(&attr),
7203                Ok(()),
7204                "policy {} with priority 0",
7205                policy
7206            );
7207        }
7208        for policy in [SCHED_FIFO, SCHED_RR] {
7209            let mut attr = plain_attr();
7210            attr.policy = policy;
7211            attr.priority = 0;
7212            assert_eq!(
7213                validate_sched_attr_after_lookup(&attr),
7214                Err(Errno::EINVAL),
7215                "rt policy {} with priority 0",
7216                policy
7217            );
7218            // A real-time priority is accepted here; whether the *caller* may
7219            // ask for it is EPERM, which depends on privilege and is not
7220            // emulated.
7221            attr.priority = 1;
7222            assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
7223        }
7224    }
7225
7226    #[test]
7227    fn a_priority_past_max_rt_prio_is_refused() {
7228        // Measured native: FIFO with priority 100 is EINVAL rather than the
7229        // EPERM that priorities 1..=99 give, so the range test runs first.
7230        let mut attr = plain_attr();
7231        attr.policy = SCHED_FIFO;
7232        attr.priority = MAX_RT_PRIO;
7233        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
7234        attr.priority = MAX_RT_PRIO - 1;
7235        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
7236    }
7237
7238    #[test]
7239    fn deadline_parameters_are_checked() {
7240        // Measured native: SCHED_DEADLINE with all-zero parameters is EINVAL,
7241        // and with runtime > deadline is EINVAL. PR #2288 accepted both.
7242        let mut zeroed = plain_attr();
7243        zeroed.policy = SCHED_DEADLINE;
7244        assert_eq!(
7245            validate_sched_attr_after_lookup(&zeroed),
7246            Err(Errno::EINVAL),
7247            "all-zero deadline parameters"
7248        );
7249
7250        let mut inverted = plain_attr();
7251        inverted.policy = SCHED_DEADLINE;
7252        inverted.runtime = 90_000_000;
7253        inverted.deadline = 30_000_000;
7254        inverted.period = 30_000_000;
7255        assert_eq!(
7256            validate_sched_attr_after_lookup(&inverted),
7257            Err(Errno::EINVAL),
7258            "runtime > deadline"
7259        );
7260
7261        // Sane parameters pass the ABI rules. Natively this host answers EPERM,
7262        // which is a privilege question rather than an ABI one.
7263        let mut sane = plain_attr();
7264        sane.policy = SCHED_DEADLINE;
7265        sane.runtime = 10_000_000;
7266        sane.deadline = 30_000_000;
7267        sane.period = 30_000_000;
7268        assert_eq!(validate_sched_attr_after_lookup(&sane), Ok(()));
7269    }
7270
7271    #[test]
7272    fn deadline_parameter_edges_follow_checkparam_dl() {
7273        // deadline == 0 is refused whatever else is set.
7274        assert!(!deadline_params_are_valid(1 << 20, 0, 0));
7275        // runtime below the DL_SCALE truncation floor (1 << 10) is refused.
7276        assert!(!deadline_params_are_valid((1 << 10) - 1, 1 << 20, 1 << 20));
7277        assert!(deadline_params_are_valid(1 << 10, 1 << 20, 1 << 20));
7278        // The MSB is reserved on both deadline and period.
7279        assert!(!deadline_params_are_valid(1 << 20, 1 << 63, 0));
7280        assert!(!deadline_params_are_valid(1 << 20, 1 << 20, 1 << 63));
7281        // A zero period means "same as the deadline", so this is runtime <=
7282        // deadline <= deadline and is accepted.
7283        assert!(deadline_params_are_valid(1 << 20, 1 << 21, 0));
7284        // deadline > period is refused.
7285        assert!(!deadline_params_are_valid(1 << 20, 1 << 22, 1 << 21));
7286    }
7287
7288    #[test]
7289    fn the_size_written_back_on_refusal_is_the_kernel_struct_not_the_libc_mirror() {
7290        // Measured native: every E2BIG row leaves uattr->size holding 56, not
7291        // 48. Deriving that from the libc crate's `sched_attr` would report 48
7292        // and tell the guest to retry with a size the kernel already accepted.
7293        assert_eq!(SCHED_ATTR_KERNEL_SIZE, 56);
7294        assert_eq!(std::mem::size_of::<libc::sched_attr>(), 48);
7295        assert_ne!(
7296            SCHED_ATTR_KERNEL_SIZE as usize,
7297            std::mem::size_of::<libc::sched_attr>()
7298        );
7299    }
7300
7301    /// A `MemoryAccess` whose readable region ends at `readable_len`, recording
7302    /// every read length it is asked for.
7303    struct BoundedMemory {
7304        bytes: Vec<u8>,
7305        readable_len: usize,
7306        reads: std::cell::RefCell<Vec<usize>>,
7307    }
7308
7309    impl reverie::syscalls::MemoryAccess for BoundedMemory {
7310        fn read_vectored(
7311            &self,
7312            read_from: &[std::io::IoSlice<'_>],
7313            write_to: &mut [std::io::IoSliceMut<'_>],
7314        ) -> Result<usize, Errno> {
7315            let start = read_from[0].as_ptr() as usize;
7316            let want = read_from.iter().map(|slice| slice.len()).sum::<usize>();
7317            self.reads.borrow_mut().push(want);
7318            if start >= self.readable_len {
7319                return Err(Errno::EFAULT);
7320            }
7321            let avail = (self.readable_len - start).min(want);
7322            let mut copied = 0;
7323            for out in write_to.iter_mut() {
7324                if copied == avail {
7325                    break;
7326                }
7327                let take = out.len().min(avail - copied);
7328                out[..take].copy_from_slice(&self.bytes[start + copied..start + copied + take]);
7329                copied += take;
7330            }
7331            Ok(copied)
7332        }
7333
7334        fn write_vectored(
7335            &mut self,
7336            _read_from: &[std::io::IoSlice<'_>],
7337            _write_to: &mut [std::io::IoSliceMut<'_>],
7338        ) -> Result<usize, Errno> {
7339            unimplemented!("this fixture never writes")
7340        }
7341    }
7342
7343    fn bounded(bytes: Vec<u8>, readable_len: usize) -> BoundedMemory {
7344        BoundedMemory {
7345            bytes,
7346            readable_len,
7347            reads: std::cell::RefCell::new(Vec::new()),
7348        }
7349    }
7350
7351    fn tail_base() -> AddrMut<'static, u8> {
7352        AddrMut::<u8>::from_raw(1).expect("nonzero base")
7353    }
7354
7355    /// ITEM 2 REGRESSION, ORDERING HALF: a non-zero byte BEFORE an unreadable
7356    /// page is E2BIG, not EFAULT.
7357    ///
7358    /// `check_zeroed_user` scans forward and stops at the first thing it finds,
7359    /// so it never reaches the fault. Reading the whole tail up front and
7360    /// judging afterwards turns this into EFAULT and changes the errno the
7361    /// guest sees.
7362    #[test]
7363    fn a_nonzero_byte_before_a_fault_is_e2big_not_efault() {
7364        let off = SCHED_ATTR_KERNEL_SIZE as usize;
7365        let mut bytes = vec![0u8; off + 4096];
7366        bytes[off + 1] = 0xAA; // non-zero, well before the boundary
7367        let readable = off + 512; // everything past this faults
7368        let memory = bounded(bytes, readable);
7369        assert_eq!(
7370            scan_tail_is_zeroed(&memory, tail_base(), off, 4096),
7371            TailVerdict::NotZeroed,
7372            "a non-zero byte the scan reaches first must win over a later fault"
7373        );
7374    }
7375
7376    /// ITEM 2 REGRESSION, the other side of the same order: a fault with
7377    /// nothing non-zero before it is EFAULT.
7378    #[test]
7379    fn a_fault_before_any_nonzero_byte_is_efault() {
7380        let off = SCHED_ATTR_KERNEL_SIZE as usize;
7381        let bytes = vec![0u8; off + 4096];
7382        let memory = bounded(bytes, off + 512);
7383        assert_eq!(
7384            scan_tail_is_zeroed(&memory, tail_base(), off, 4096),
7385            TailVerdict::Faulted,
7386            "an unreadable byte reached before anything non-zero must be EFAULT"
7387        );
7388    }
7389
7390    /// ITEM 2 REGRESSION, PROTECTION HALF: never issue a read of eight bytes or
7391    /// fewer.
7392    ///
7393    /// safeptrace serves those through `PTRACE_PEEKDATA`, which reads a whole
7394    /// aligned word and bypasses guest page protections, so a small tail would
7395    /// be readable under Hermit where Linux reports EFAULT. The assertion is on
7396    /// the READ LENGTHS ASKED FOR, because that is the mechanism; the returned
7397    /// verdict cannot show it.
7398    #[test]
7399    fn tail_reads_are_never_small_enough_to_bypass_guest_protection() {
7400        let off = SCHED_ATTR_KERNEL_SIZE as usize;
7401        for tail_len in 1..=16usize {
7402            let bytes = vec![0u8; off + tail_len + 64];
7403            let memory = bounded(bytes, off + tail_len + 64);
7404            assert_eq!(
7405                scan_tail_is_zeroed(&memory, tail_base(), off, tail_len),
7406                TailVerdict::AllZero
7407            );
7408            let reads = memory.reads.borrow().clone();
7409            assert!(!reads.is_empty(), "tail_len {tail_len} issued no read");
7410            for length in reads {
7411                assert!(
7412                    length > std::mem::size_of::<u64>(),
7413                    "tail_len {tail_len} issued a {length}-byte read, which safeptrace \
7414                     serves with PTRACE_PEEKDATA and which therefore bypasses guest \
7415                     page protections"
7416                );
7417            }
7418        }
7419    }
7420
7421    /// ITEM 3 REGRESSION: KEEP_POLICY reuses the CURRENT policy; it does not
7422    /// switch the policy-dependent rules off.
7423    ///
7424    /// Detcore's current policy is the one `handle_sched_getattr` reports for
7425    /// every thread, SCHED_OTHER, and a non-real-time policy requires priority
7426    /// 0. Skipping the rules accepted this.
7427    #[test]
7428    fn keep_policy_validates_against_the_virtual_current_policy() {
7429        let attr = SchedAttrFields {
7430            policy: 99, // ignored under KEEP_POLICY, and deliberately invalid
7431            sched_flags: SCHED_FLAG_KEEP_POLICY,
7432            priority: 1,
7433            runtime: 0,
7434            deadline: 0,
7435            period: 0,
7436        };
7437        assert_eq!(
7438            validate_sched_attr_after_lookup(&attr),
7439            Err(Errno::EINVAL),
7440            "priority 1 under the virtual SCHED_OTHER current policy must be refused"
7441        );
7442
7443        // The companion that must keep passing: the ignored policy field really
7444        // is ignored, so the same request at priority 0 is accepted.
7445        let ok = SchedAttrFields {
7446            priority: 0,
7447            ..attr
7448        };
7449        assert_eq!(
7450            validate_sched_attr_after_lookup(&ok),
7451            Ok(()),
7452            "KEEP_POLICY must still ignore the policy field itself"
7453        );
7454    }
7455
7456    /// ITEM 3 COHERENCE: the substituted policy is the one the guest can
7457    /// actually observe, so the two sites cannot drift apart silently.
7458    #[test]
7459    fn the_virtual_current_policy_is_what_sched_getattr_reports() {
7460        assert_eq!(
7461            VIRTUAL_CURRENT_POLICY,
7462            libc::SCHED_OTHER as u32,
7463            "handle_sched_getattr writes SCHED_OTHER into sched_policy for every thread; \
7464             KEEP_POLICY must substitute that same value"
7465        );
7466    }
7467}
7468
7469/// The real uid of thread `tid`, from `/proc/<tid>/status`.
7470pub(crate) fn real_uid(tid: i32) -> Option<u32> {
7471    let status = std::fs::read_to_string(format!("/proc/{tid}/status")).ok()?;
7472    status
7473        .lines()
7474        .find_map(|line| line.strip_prefix("Uid:"))?
7475        .split_whitespace()
7476        .next()?
7477        .parse()
7478        .ok()
7479}
7480
7481/// The 8-byte field at `offset` of a clone3 call's `struct clone_args`,
7482/// which may be any size the kernel accepts from 64 bytes (its first
7483/// version) up: read alone, so that a shorter struct at the end of a mapping
7484/// is read as the kernel reads it. `None` for a size below 64, a field past
7485/// the size, or an unreadable field.
7486fn clone3_field<M: MemoryAccess>(
7487    memory: &M,
7488    clone: &syscalls::Clone3,
7489    offset: usize,
7490) -> Option<u64> {
7491    const CLONE_ARGS_SIZE_VER0: usize = 64;
7492    if clone.size() < CLONE_ARGS_SIZE_VER0 || offset + 8 > clone.size() {
7493        return None;
7494    }
7495    let base = clone.args()?.as_raw();
7496    memory
7497        .read_value(Addr::<u64>::from_raw(base + offset)?)
7498        .ok()
7499}
7500
7501/// Where a `CLONE_PIDFD` clone writes the new process's pidfd (`clone`'s
7502/// `parent_tid` argument, or `clone3`'s `pidfd` field), for a child Detcore
7503/// tracks the pidfd of (`Detcore::register_clone_pidfd`): one that shares
7504/// neither the caller's memory nor its descriptor table and is no vfork
7505/// child. Such a child could rewrite the word, or close or replace the
7506/// descriptor, before the caller tracks it, and a vfork parent resumes, and
7507/// tracks it, only after its child is done, while a sibling may already
7508/// use the pidfd; Detcore leaves those pidfds untracked, as before
7509/// https://github.com/rrnewton/hermit/issues/4430
7510/// (https://github.com/rrnewton/hermit/issues/4443).
7511fn clone_pidfd_address<M: MemoryAccess>(
7512    clone_family: &syscalls::family::CloneFamily,
7513    memory: &M,
7514    flags: CloneFlags,
7515) -> Option<usize> {
7516    let (flags, address) = match clone_family {
7517        syscalls::family::CloneFamily::Clone(clone) => {
7518            (flags, clone.ptid().map(|ptid| ptid.as_raw()))
7519        }
7520        syscalls::family::CloneFamily::Clone3(clone) => (
7521            flags,
7522            Some(usize::try_from(clone3_field(memory, clone, 8)?).ok()?),
7523        ),
7524        #[cfg(not(target_arch = "aarch64"))]
7525        _ => return None,
7526    };
7527    if !flags.contains(CloneFlags::CLONE_PIDFD)
7528        || flags
7529            .intersects(CloneFlags::CLONE_VM | CloneFlags::CLONE_FILES | CloneFlags::CLONE_VFORK)
7530    {
7531        return None;
7532    }
7533    address
7534}