Skip to main content

detcore/syscalls/
helpers.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
9use std::num::NonZeroUsize;
10use std::time::Duration;
11
12use async_trait::async_trait;
13use reverie::Errno;
14use reverie::Error;
15use reverie::Guest;
16use reverie::MaskChangeRefused;
17use reverie::Stack;
18use reverie::syscalls;
19use reverie::syscalls::Addr;
20use reverie::syscalls::AddrMut;
21use reverie::syscalls::Displayable;
22use reverie::syscalls::MapFlags;
23use reverie::syscalls::MemoryAccess;
24use reverie::syscalls::ProtFlags;
25use reverie::syscalls::Syscall;
26use reverie::syscalls::SyscallInfo;
27use reverie::syscalls::Sysno;
28use reverie::syscalls::Timespec;
29use reverie::syscalls::WaitPidFlag;
30
31use crate::fd::FdType;
32use crate::record_or_replay::RecordOrReplay;
33use crate::resources::ExternalOpId;
34use crate::resources::Permission;
35use crate::resources::ResourceID;
36use crate::resources::Resources;
37use crate::syscalls::threads::BlockedWaitSignalError;
38use crate::syscalls::threads::KERNEL_SIGSET_SIZE;
39use crate::syscalls::threads::KernelSigaction;
40use crate::syscalls::threads::KernelSignalState;
41use crate::syscalls::threads::KernelSigset;
42use crate::syscalls::threads::SignalQueue;
43use crate::syscalls::threads::WaitSignalDisposition;
44use crate::syscalls::threads::block_signals_for_disposition;
45use crate::syscalls::threads::blocked_signal_mask;
46use crate::syscalls::threads::kernel_sigset_bit;
47use crate::syscalls::threads::read_thread_wait_signal_state;
48use crate::syscalls::threads::read_wait_signal_state;
49use crate::syscalls::threads::restore_signals_after_disposition;
50use crate::syscalls::threads::wait_signal_disposition;
51use crate::tool_global::ResumeStatus;
52use crate::tool_global::host_timed_signals;
53use crate::tool_global::resource_request;
54use crate::tool_global::thread_observe_time;
55use crate::tool_global::trace_schedevent;
56use crate::tool_local::Detcore;
57use crate::tool_local::finish_partial_record_or_replay_write;
58use crate::types::DetTid;
59use crate::types::LogicalTime;
60use crate::types::OpenFileId;
61use crate::types::SchedEvent;
62use crate::types::SyscallPhase;
63
64impl<T: RecordOrReplay> Detcore<T> {
65    // AUTONOMOUS-BOT-IMPLEMENTED
66    // TODO-HUMAN-REVIEW(#2373)
67    /// Apply the established unsupported-syscall refusal policy to a *supported*
68    /// syscall whose particular operation Detcore cannot serve deterministically.
69    ///
70    /// This exists so such a refusal cannot invent its own policy. Three separate
71    /// config knobs govern how a fail-closed run dies -- `shutdown_on_unsupported_syscall`
72    /// (hard `exit(1)` through `unrecoverable_shutdown`), `exit_on_unsupported_syscall`
73    /// (a typed `UnsupportedSyscallError` the backend terminates on without
74    /// unwinding), and the `panic!` fallback -- and `Detcore::handle_unsupported_syscall`
75    /// consults all three in that order. The normal `hermit run` CLI happens to set
76    /// `shutdown_on_unsupported_syscall = panic_on_unsupported_syscalls`, so reading
77    /// only the latter looks equivalent, but that coupling is a CLI default, not an
78    /// invariant: an embedder that sets just `exit_on_unsupported_syscall` would get a
79    /// process-wide `exit(1)` from a bespoke call site where the standard path returns
80    /// a catchable error.
81    ///
82    /// When the run is *not* fail-closed, the caller's `fallback` errno is returned,
83    /// because the operation itself is legal and the guest is entitled to a normal
84    /// failure code (`handle_unsupported_syscall` passes the call through instead,
85    /// which is not available here -- passing through is precisely the thing the
86    /// caller has determined it cannot do).
87    pub(crate) async fn refuse_unserviceable_operation<G: Guest<Self>>(
88        &self,
89        guest: &mut G,
90        sysno: reverie::syscalls::Sysno,
91        fallback: Errno,
92    ) -> Result<i64, Error> {
93        refuse_unserviceable_operation_with(
94            guest,
95            self.cfg.panic_on_unsupported_syscalls,
96            sysno,
97            fallback,
98            None,
99        )
100        .await
101    }
102
103    /// [`Self::refuse_unserviceable_operation`], with the backend's own
104    /// description of why it cannot perform the operation, which a
105    /// fail-closed refusal reports as its reason.
106    pub(crate) async fn refuse_unserviceable_operation_because<G: Guest<Self>>(
107        &self,
108        guest: &mut G,
109        sysno: reverie::syscalls::Sysno,
110        fallback: Errno,
111        reason: &str,
112    ) -> Result<i64, Error> {
113        refuse_unserviceable_operation_with(
114            guest,
115            self.cfg.panic_on_unsupported_syscalls,
116            sysno,
117            fallback,
118            Some(reason),
119        )
120        .await
121    }
122
123    /// Record or replay a BLOCKING syscall without stalling the current thread (and thus
124    /// deadlocking).  This uses a protocol of an extra resource request before/after the
125    /// syscall to inform the scheduler that the thread is leaving/rejoining the runnable
126    /// threads pool.
127    ///
128    /// This is only valid to use (1) in hermit record/replay modes, or (2)
129    /// when we're in "hermit run", but we're NOT sequentializing threads, because in
130    /// that case it's ok to use the blocking versions of system calls.
131    pub async fn record_or_replay_blocking<G: Guest<Self>>(
132        &self,
133        guest: &mut G,
134        call: Syscall,
135    ) -> Result<i64, Error> {
136        self.record_or_replay_blocking_with_mask(guest, call, None)
137            .await
138    }
139
140    /// `record_or_replay_blocking` for a call that sleeps under its own
141    /// temporary signal mask (`ppoll`, `pselect6`, or an `rt_sigsuspend` that
142    /// finds a signal already pending): `blocked_signal_mask` is the mask the
143    /// kernel installs for the call, read in this thread's turn
144    /// (`Resources::blocked_signal_mask`). `None` means the call sleeps under
145    /// the thread's own mask.
146    pub async fn record_or_replay_blocking_with_mask<G: Guest<Self>>(
147        &self,
148        guest: &mut G,
149        call: Syscall,
150        blocked_signal_mask: Option<u64>,
151    ) -> Result<i64, Error> {
152        let dettid = guest.thread_state().dettid;
153        let op_id = ExternalOpId::new(dettid, guest.thread_state().stats.syscall_count);
154        self.record_or_replay_blocking_resource(
155            guest,
156            call,
157            ResourceID::BlockingExternalIO(op_id),
158            blocked_signal_mask,
159            false,
160        )
161        .await
162    }
163
164    /// `record_or_replay_blocking` for a call that sleeps under a temporary
165    /// mask its turn cannot vouch for (`Resources::blocked_signal_mask_unknown`):
166    /// the scheduler records no sleeping mask for it.
167    pub async fn record_or_replay_blocking_with_unknown_mask<G: Guest<Self>>(
168        &self,
169        guest: &mut G,
170        call: Syscall,
171    ) -> Result<i64, Error> {
172        self.record_or_replay_blocking_with_unknown_mask_then(guest, call, |_| {})
173            .await
174    }
175
176    /// `record_or_replay_blocking_with_unknown_mask`, running `after_grant` once
177    /// the scheduler has granted the call and before it runs: after any
178    /// sibling that ran while the request waited. In replay nothing else runs
179    /// until the served call finishes; in recording a sibling turn may still
180    /// run before the call enters the kernel.
181    pub async fn record_or_replay_blocking_with_unknown_mask_then<G: Guest<Self>>(
182        &self,
183        guest: &mut G,
184        call: Syscall,
185        after_grant: impl FnOnce(&mut G),
186    ) -> Result<i64, Error> {
187        let dettid = guest.thread_state().dettid;
188        let op_id = ExternalOpId::new(dettid, guest.thread_state().stats.syscall_count);
189        self.record_or_replay_blocking_resource_then(
190            guest,
191            call,
192            ResourceID::BlockingExternalIO(op_id),
193            None,
194            true,
195            after_grant,
196        )
197        .await
198    }
199
200    /// Execute the real `rt_sigsuspend` outside the runnable set while preserving
201    /// its signal-only completion condition for the scheduler. `temporary_mask`
202    /// is the mask the call sleeps under, as `Resources::blocked_signal_mask`
203    /// describes.
204    pub async fn record_or_replay_rt_sigsuspend<G: Guest<Self>>(
205        &self,
206        guest: &mut G,
207        call: syscalls::RtSigsuspend,
208        temporary_mask: u64,
209    ) -> Result<i64, Error> {
210        let dettid = guest.thread_state().dettid;
211        let op_id = ExternalOpId::new(dettid, guest.thread_state().stats.syscall_count);
212        let result = self
213            .record_or_replay_blocking_resource(
214                guest,
215                call.into(),
216                ResourceID::BlockingRtSigsuspend(op_id),
217                Some(temporary_mask),
218                false,
219            )
220            .await;
221        // Linux's rt_sigsuspend ends only with ERESTARTNOHAND, which a handler
222        // turns into EINTR and never restarts. The host call reports
223        // ERESTARTSYS instead when the signal reached the thread before the
224        // call ran, which depends on host timing; under SA_RESTART the guest
225        // then slept again where Linux returns
226        // (https://github.com/rrnewton/hermit/issues/4320). This fixes the
227        // result and the restart only: in that case the call never ran, so
228        // the kernel never installed its temporary mask, and the handler runs
229        // under the thread's pre-call mask, still a host-timed difference when
230        // the two masks differ (https://github.com/rrnewton/hermit/issues/4338).
231        match result {
232            Err(Error::Errno(Errno::ERESTARTSYS)) => Err(Errno::ERESTARTNOHAND.into()),
233            other => other,
234        }
235    }
236
237    async fn record_or_replay_blocking_resource<G: Guest<Self>>(
238        &self,
239        guest: &mut G,
240        call: Syscall,
241        blocking_resource: ResourceID,
242        blocked_signal_mask: Option<u64>,
243        blocked_signal_mask_unknown: bool,
244    ) -> Result<i64, Error> {
245        self.record_or_replay_blocking_resource_then(
246            guest,
247            call,
248            blocking_resource,
249            blocked_signal_mask,
250            blocked_signal_mask_unknown,
251            |_| {},
252        )
253        .await
254    }
255
256    /// `record_or_replay_blocking_resource`, running `after_grant` between the
257    /// grant and the call.
258    async fn record_or_replay_blocking_resource_then<G: Guest<Self>>(
259        &self,
260        guest: &mut G,
261        call: Syscall,
262        blocking_resource: ResourceID,
263        blocked_signal_mask: Option<u64>,
264        blocked_signal_mask_unknown: bool,
265        after_grant: impl FnOnce(&mut G),
266    ) -> Result<i64, Error> {
267        // A host wait on descriptors that may include a timerfd on virtual
268        // time would never see it readable (`crate::syscalls::timerfd`).
269        crate::syscalls::timerfd::refuse_host_wait_for(guest, call);
270        let dettid = guest.thread_state().dettid;
271        let op_id = match &blocking_resource {
272            ResourceID::BlockingExternalIO(op_id) | ResourceID::BlockingRtSigsuspend(op_id) => {
273                *op_id
274            }
275            _ => unreachable!("blocking syscall helper requires a blocking resource"),
276        };
277        // Replay serves some of these calls from the recording, so they cannot block.
278        // They still run in the background, as they did during recording, so that the
279        // schedule matches the recording's. The flag makes the scheduler commit no
280        // other turn until they finish. Otherwise a stand-in descriptor that replay
281        // creates for an accepted connection could take its slot before or after
282        // another thread's open or close, and which of these calls had finished, and
283        // so the order in which they rejoin, would depend on host timing
284        // (https://github.com/rrnewton/hermit/pull/3871).
285        let replay_served_from_log = self.cfg.replaying
286            && (replay_serves_blocking_call_from_log(call)
287                || replay_serves_socket_call_from_log(guest, call));
288        // Internal-vs-external fd classification happens at the call sites that hold the
289        // typed, nonblockize-able syscall (see execute_nonblockable_fd_syscall):
290        // container-internal pipes are routed to the InternalIOPolling nonblockize-retry
291        // path and must NOT reach this external-blocking protocol. BlockingExternalIO
292        // deschedules the thread to run in the background and rejoin nondeterministically,
293        // which is unsafe for a pipe whose reader and writer are interdependent -- doing
294        // so is the root cause of the record/replay pipe deadlock. The remaining callers
295        // (external poll, wait4) are external by construction (their fd is not a single
296        // extractable internal pipe). Guard the invariant in debug builds while the
297        // deterministic scheduler is active. With thread sequentialization disabled,
298        // resource requests are no-ops and internal pipes intentionally use a blocking
299        // host syscall, as documented by this method.
300        debug_assert!(
301            !self.cfg.sequentialize_threads || !syscall_targets_internal_fd(guest, call),
302            "record_or_replay_blocking (BlockingExternalIO) reached for an internal fd \
303             (pipe or socketpair endpoint) on syscall {}; internal fds must use the \
304             InternalIOPolling path",
305            call.name()
306        );
307        {
308            let mut rsrcs = Resources::new(dettid);
309            // With sequentialization enabled, only truly EXTERNAL endpoints reach here.
310            // Without it, resource_request is a no-op and internal fds may block directly.
311            rsrcs.reads_signalfd = matches!(blocking_resource, ResourceID::BlockingExternalIO(_))
312                && call_reads_signalfd(guest, call);
313            if matches!(blocking_resource, ResourceID::BlockingExternalIO(_)) {
314                rsrcs.read_fd =
315                    read_family_fd(call).map(|fd| (guest.thread_state().files_id(), fd));
316            }
317            rsrcs.insert(blocking_resource, Permission::RW);
318            rsrcs.fyi(call.name());
319            rsrcs.blocked_signal_mask = blocked_signal_mask;
320            rsrcs.blocked_signal_mask_unknown = blocked_signal_mask_unknown;
321            rsrcs.replay_served_from_log = replay_served_from_log;
322            resource_request(guest, rsrcs).await;
323        }
324        after_grant(guest);
325        // Race probes (docs/RACE_PROBES.md) may delay the call or its rejoin;
326        // both are host timing this protocol already treats as nondeterministic.
327        crate::race_probe::delay(crate::race_probe::BG_PRE_CALL).await;
328        tracing::trace!(
329            "Guest proceeding to execute potentially blocking call {}...",
330            call.name()
331        );
332        let res = self
333            .record_or_replay_preserving_tool_errors(guest, call)
334            .await;
335        crate::race_probe::delay(crate::race_probe::BG_POST_CALL).await;
336        // N.B. BlockingExternalIO is a "oneshot" resource, so no need to release
337        // explicitly here:
338        {
339            let mut rsrcs = Resources::new(dettid);
340            rsrcs.insert(ResourceID::BlockedExternalContinue(op_id), Permission::RW);
341            rsrcs.fyi(call.name());
342            // The mask the thread is stopped under here, as the scheduler may
343            // decide from it before this turn (`BlockedPool::continuation_masks`).
344            match continuation_mask(call, &res) {
345                ContinuationMask::Temporary => {
346                    rsrcs.blocked_signal_mask = blocked_signal_mask;
347                    rsrcs.blocked_signal_mask_unknown = blocked_signal_mask_unknown;
348                }
349                ContinuationMask::Unknown => rsrcs.blocked_signal_mask_unknown = true,
350                ContinuationMask::Restored => {}
351            }
352            resource_request(guest, rsrcs).await;
353        }
354        res
355    }
356
357    /// Executes a nonblockable syscall according to the following strategy:
358    /// - Record mode: Execute possibly blocking syscall
359    /// - Run mode: Transform the syscall to nonblocking if required before executing
360    ///
361    /// These are fd-oriented syscalls in the sense that whether they block or not depends
362    /// on whether NONBLOCK was set on the corresponding file descriptor.
363    pub async fn execute_nonblockable_fd_syscall<
364        G: Guest<Self>,
365        C: SyscallInfo + NonblockableSyscall + Into<Syscall>,
366    >(
367        &self,
368        guest: &mut G,
369        call: C,
370    ) -> Result<i64, Error> {
371        let wrapped: Syscall = call.into();
372
373        let action = match ioaction_based_on_fd_status(guest, call) {
374            Ok(action) => action,
375            Err(errno) => {
376                // Descriptor metadata is advisory for choosing an execution strategy. If the
377                // descriptor is invalid or cannot be classified, execute through the
378                // scheduler-safe blocking path and let the kernel provide the syscall errno.
379                // Returning the metadata error (or panicking on it) can change Linux error
380                // precedence, for example connect(-1, invalid_sockaddr, ...).
381                tracing::trace!(
382                    "NonblockableSyscall: fd classification failed with {}; executing kernel-authoritatively: {}",
383                    errno,
384                    call.name()
385                );
386                return self.record_or_replay_blocking(guest, wrapped).await;
387            }
388        };
389
390        // Is this operation on a container-INTERNAL fd (a pipe or a socketpair
391        // endpoint)? Internal fds are made physically nonblocking even in
392        // record/replay (see handle_pipe2 and handle_socketpair), so they can take the
393        // deterministic InternalIOPolling nonblockize-and-retry path. They must NOT be
394        // forced onto the BlockingExternalIO path in R/R: a reader and its paired
395        // writer are not independent, so descheduling the reader as "external
396        // blocking IO" deadlocks the sequentialized scheduler (the documented R/R pipe
397        // hang), and a one-shot read on the physically nonblocking fd returns EAGAIN.
398        // Truly external endpoints (host fds, network sockets) still use
399        // BlockingExternalIO. Other sockets are left external for now: there is no
400        // internal-vs-external socket detection yet (see the handle_accept4 comment).
401        let internal_fd = syscall_targets_internal_fd(guest, wrapped);
402
403        if !self.cfg.sequentialize_threads
404            || (self.cfg.recordreplay_modes && !internal_fd)
405            || action == IOAction::Blocking
406        {
407            tracing::trace!(
408                "NonblockableSyscall: executing in blocking mode after all: {}",
409                call.name()
410            );
411            // We let these have nondeterminstic timing in record mode:
412            Ok(self.record_or_replay_blocking(guest, wrapped).await?)
413            // If in the future we want to record EXTERNAL network traffic only, we have a
414            // challenge to overcome.  We don't know if we need to record until after the
415            // accept completes, so we need an API for *post-facto* recording.
416        } else if action == IOAction::NonblockizeRetry {
417            tracing::trace!(
418                "NonblockableSyscall: converting to nonblocking syscall (internal polling): {}",
419                call.name()
420            );
421            let mut rsrc = Resources::new(guest.thread_state().dettid);
422            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
423            rsrc.fyi(call.name());
424            // Only guests write or read the other end of an internal fd.
425            rsrc.polls_guest_state_only = internal_fd;
426            // A pipe read: a recorded private `SIGCHLD` ends it as on Linux.
427            rsrc.private_sigchld_decides = reads_a_pipe(guest, wrapped);
428            // A read waits for data, a write for room (`--pipe-wake-latency`).
429            rsrc.polls_channel = crate::pipe_wake::poll_of(&wrapped).and_then(|(fd, wants)| {
430                self.pipe_channel_end(guest, fd)
431                    .map(|end| Box::new((end.channel, wants)))
432            });
433            // In record/replay mode, route an internal-fd (pipe or socketpair) read/write through the
434            // record/replay subtool so its data is captured on record and reproduced on
435            // replay (see retry_nonblocking_syscall). In plain `hermit run` there is no
436            // recorder, so execute directly (subtool = None).
437            let subtool = (self.cfg.recordreplay_modes && internal_fd).then_some(self);
438            Ok(retry_nonblocking_syscall(guest, call, rsrc, subtool).await?)
439        } else {
440            assert!(action == IOAction::PassThru);
441            tracing::trace!(
442                "NonblockableSyscall: just passing it through: {}",
443                call.name()
444            );
445            // Otherwise, the socket was already nonblocking, so we can safely execute it just once.
446            self.record_or_replay_preserving_tool_errors(guest, wrapped)
447                .await
448        }
449    }
450
451    // AUTONOMOUS-BOT-IMPLEMENTED
452    // TODO-HUMAN-REVIEW(#547)
453    /// Complete a logically blocking pipe writev after Hermit has made the pipe physically
454    /// nonblocking. A positive short write is an implementation artifact here: without
455    /// O_NONBLOCK, Linux blocks until the full vector is written unless a signal or error
456    /// interrupts it. Atomic vectors retain a private iovec snapshot for every retry; larger
457    /// vectors advance a positive short-write remainder through scalar writes.
458    pub async fn execute_blocking_pipe_writev<G: Guest<Self>>(
459        &self,
460        guest: &mut G,
461        call: syscalls::Writev,
462        expected_open_file: OpenFileId,
463    ) -> Result<i64, Error> {
464        const MAX_IOVECS: usize = 1024;
465        // Linux limits a single vectored transfer to INT_MAX rounded down to a page.
466        const MAX_RW_COUNT: usize = 0x7fff_f000;
467        // Linux guarantees pipe writes through this size are atomic.
468        const PIPE_BUF: usize = 4096;
469        // Every backend provides at least 512 bytes of tool scratch. Linux's
470        // own fast-iovec path is smaller; this covers common vectors.
471        const STACK_IOVECS: usize = 32;
472
473        let Some(iov_addr) = call.iov() else {
474            return self.execute_nonblockable_fd_syscall(guest, call).await;
475        };
476        if call.len() == 0 || call.len() > MAX_IOVECS {
477            return self.execute_nonblockable_fd_syscall(guest, call).await;
478        }
479
480        let iovecs: Vec<(usize, usize)> = {
481            let mut raw_iovecs = vec![
482                libc::iovec {
483                    iov_base: std::ptr::null_mut(),
484                    iov_len: 0,
485                };
486                call.len()
487            ];
488            guest.memory().read_values(iov_addr, &mut raw_iovecs)?;
489            raw_iovecs
490                .into_iter()
491                .map(|iovec| (iovec.iov_base as usize, iovec.iov_len))
492                .collect()
493        };
494        let requested = iovecs.iter().try_fold(0usize, |total, (_, length)| {
495            total.checked_add(*length).ok_or(Errno::EINVAL)
496        })?;
497        if requested > isize::MAX as usize {
498            return Err(Errno::EINVAL.into());
499        }
500        let target = requested.min(MAX_RW_COUNT);
501        if target == 0 {
502            return self.execute_nonblockable_fd_syscall(guest, call).await;
503        }
504
505        let atomic_pipe_write = target <= PIPE_BUF;
506
507        tracing::trace!(
508            "NonblockableSyscall: converting to nonblocking syscall (internal polling): writev"
509        );
510        let mut resources = pipe_writev_resources(guest.thread_state().dettid, call);
511        resources.polls_channel = self
512            .pipe_channel_end(guest, call.fd())
513            .map(|end| Box::new((end.channel, crate::pipe_wake::Wants::Space)));
514        let subtool = self.cfg.recordreplay_modes.then_some(self);
515        let mut current = Syscall::Writev(call);
516        let mut written_total = 0usize;
517
518        // Keep ordinary signals pending while the scheduler and the target-side
519        // disposition check decide whether a wakeup interrupts this write. The
520        // ptrace-owned backends need the explicit mask while inspecting the
521        // target's current disposition.
522        let blocked_mask = blocked_signal_mask();
523        let mut stack = guest.stack().await;
524        let atomic_scratch_iov = if atomic_pipe_write && iovecs.len() <= STACK_IOVECS {
525            let mut raw_iovecs = [libc::iovec {
526                iov_base: std::ptr::null_mut(),
527                iov_len: 0,
528            }; STACK_IOVECS];
529            for (raw, (base, length)) in raw_iovecs.iter_mut().zip(&iovecs) {
530                raw.iov_base = *base as *mut libc::c_void;
531                raw.iov_len = *length;
532            }
533            let scratch_iov: Addr<libc::iovec> = stack.push(raw_iovecs).cast();
534            Some(scratch_iov.as_raw())
535        } else {
536            None
537        };
538        let blocked_mask_addr = stack.push(blocked_mask);
539        let old_mask_addr = stack.reserve::<KernelSigset>();
540        let turn_mask_cell = stack.reserve::<KernelSigset>();
541        let action_addr = stack.reserve::<KernelSigaction>();
542        let _mask_guard = stack.commit()?;
543        let checks_at_turn = decides_interruption_at_turn(guest, guest_signal_state_task(guest));
544        // Where the turn decides (`read_turn_signals`), the state is read, and
545        // the first attempt made, in the slice of the call's own entry, as the
546        // scalar writer's first attempt is, under the guest's own mask: that
547        // attempt is the guest's own `writev`, which the backend runs as plain
548        // ptrace runs it, with every pending signal left queued in the kernel,
549        // and a copy pending at entry ends the call after it (rules 5 and 6).
550        // No other thread runs between Detcore's snapshot of the iovec array,
551        // taken as it handles the call, and that attempt, so the kernel imports
552        // the array Detcore copied, which every later attempt writes from. A
553        // rewrite that lands before the snapshot (while the call waits at a
554        // checkpoint before its handler runs) is one Linux could also see,
555        // before the call imports the array.
556        // Requesting a turn first let another thread rewrite the array before
557        // the import, and an atomic write to a full pipe then wrote its bytes
558        // (writev_determinism's atomic full-pipe case, which reverted the
559        // first landing of R2b-1). Only a call that goes on polling installs the
560        // private mask, through `KernelSignalWait::block`, in the same turn
561        // (`install_turn_mask`); no copy that ends the call is pending then,
562        // and one Linux discarded at send is held until the call returns.
563        // Installing it first let two such copies stop the installation, and
564        // the backend's single held slot kept only the second (the Claude
565        // implementation review of R2b-1, F2;
566        // https://github.com/rrnewton/reverie/issues/1012).
567        let mut first_turn = if checks_at_turn {
568            let turn = read_turn_signals(guest, None, 0, NamedRealTime::ByDisposition).await?;
569            Some((ResumeStatus::Normal, turn))
570        } else {
571            None
572        };
573        let mut turn_wait = checks_at_turn
574            .then(|| KernelSignalWait::new(guest, 0, false, call.signal_interrupt_errno()));
575        let mut turn_mask: Option<KernelSigset> = None;
576        let guest_signal_mask = if checks_at_turn {
577            0
578        } else {
579            block_signals_for_disposition(guest, blocked_mask_addr, old_mask_addr).await?
580        };
581
582        let result: Result<i64, Error> = loop {
583            let written_before = written_total;
584            // A cross-task signal can replace the initial scheduler request,
585            // before the first physical attempt, as well as a later retry.
586            let (status, turn) = match first_turn.take() {
587                Some((status, turn)) => (status, Some(turn)),
588                None => {
589                    if let Some(wait) = turn_wait.as_mut()
590                        && turn_mask.is_none()
591                    {
592                        match install_turn_mask(guest, wait, turn_mask_cell).await {
593                            Ok(mask) => turn_mask = Some(mask),
594                            Err(Error::Errno(errno)) => {
595                                break if written_total > 0 {
596                                    Ok(written_total as i64)
597                                } else {
598                                    Err(errno.into())
599                                };
600                            }
601                            Err(error) => break Err(error),
602                        }
603                    }
604                    let status = resource_request(guest, resources.clone()).await;
605                    let turn = if checks_at_turn {
606                        // A named signal counts if the guest's own mask leaves
607                        // it unblocked; the private mask keeps every such
608                        // signal pending until this read.
609                        match read_turn_signals(
610                            guest,
611                            turn_mask,
612                            committed_signals(&status),
613                            NamedRealTime::ByDisposition,
614                        )
615                        .await
616                        {
617                            Ok(turn) => Some(turn),
618                            Err(error) => break Err(error),
619                        }
620                    } else {
621                        None
622                    };
623                    (status, turn)
624                }
625            };
626            if turn.is_none() {
627                let disposition = match wait_signal_disposition(
628                    guest,
629                    status.clone(),
630                    &guest_signal_mask,
631                    action_addr,
632                    true,
633                )
634                .await
635                {
636                    Ok(disposition) => disposition,
637                    Err(error) => break Err(error),
638                };
639                if matches!(status, ResumeStatus::Signaled(_))
640                    && let Some(result) =
641                        interrupted_write_result(&call, written_total, disposition)
642                {
643                    break result;
644                }
645            }
646
647            if resources.poll_attempt > 0
648                && !guest
649                    .thread_state()
650                    .with_detfd(call.fd(), |detfd| {
651                        detfd.open_file_id() == expected_open_file
652                    })
653                    .unwrap_or(false)
654            {
655                break if written_total > 0 {
656                    Ok(written_total as i64)
657                } else {
658                    self.refuse_unserviceable_operation(guest, Sysno::writev, Errno::EOPNOTSUPP)
659                        .await
660                };
661            }
662
663            // The first attempt of a call that decides at its turn runs under
664            // the guest's own mask, where a pending signal would stop a
665            // private injection and the backend's single held slot keeps only
666            // the last of two. So it is always the guest's own `writev`, which
667            // the backend runs with every pending signal left queued in the
668            // kernel (the Claude re-check of R2b-1, N2).
669            let own_first_attempt = turn_wait.is_some() && turn_mask.is_none();
670            let result = if atomic_pipe_write && !own_first_attempt {
671                self.execute_atomic_pipe_writev_attempt(guest, call, &iovecs, atomic_scratch_iov)
672                    .await
673            } else {
674                match subtool {
675                    Some(detcore) => {
676                        detcore
677                            .record_or_replay_preserving_tool_errors(guest, current)
678                            .await
679                    }
680                    None => guest.inject_with_retry(current).await.map_err(Error::from),
681                }
682            };
683            match result {
684                Ok(written) if written > 0 => {
685                    let written = match usize::try_from(written) {
686                        Ok(written) => written,
687                        Err(_) => break Err(Errno::EIO.into()),
688                    };
689                    written_total = match written_total.checked_add(written) {
690                        Some(written_total) => written_total,
691                        None => break Err(Errno::EIO.into()),
692                    };
693                    if written_total >= target {
694                        break Ok(written_total as i64);
695                    }
696                    if atomic_pipe_write {
697                        break Ok(written_total as i64);
698                    }
699                    // A short attempt filled the pipe, so the write would wait:
700                    // a wake ends it with the bytes written, decided after the
701                    // attempt, as Linux tests for room first (R2b-1 rule 6).
702                    if turn.is_some_and(|turn| turn.ends(true)) {
703                        break Ok(written_total as i64);
704                    }
705                    current = match remaining_writev_segment(
706                        call.fd(),
707                        &iovecs,
708                        written_total,
709                        target - written_total,
710                    ) {
711                        Ok(Some(write)) => Syscall::Write(write),
712                        Ok(None) => break Ok(written_total as i64),
713                        Err(_) => break Ok(written_total as i64),
714                    };
715                }
716                Ok(0) => break Ok(written_total as i64),
717                Err(Error::Errno(Errno::EAGAIN))
718                    if turn.is_some_and(|turn| turn.ends(written_total > 0)) =>
719                {
720                    break if written_total > 0 {
721                        Ok(written_total as i64)
722                    } else {
723                        Err(call.signal_interrupt_errno().into())
724                    };
725                }
726                Err(Error::Errno(Errno::EAGAIN)) => {
727                    if !atomic_pipe_write && matches!(current, Syscall::Writev(_)) {
728                        current = match remaining_writev_segment(call.fd(), &iovecs, 0, target) {
729                            Ok(Some(write)) => Syscall::Write(write),
730                            Ok(None) => break Ok(0),
731                            Err(error) => break Err(error.into()),
732                        };
733                    }
734                }
735                Err(error) => {
736                    break finish_partial_record_or_replay_write(written_total as i64, error);
737                }
738                Ok(_) => break Err(Errno::EIO.into()),
739            }
740
741            resources.previous_attempt_made_progress = written_total > written_before;
742            // Bytes this attempt wrote ready the readers before this thread
743            // polls for room (`--pipe-wake-latency`).
744            if resources.previous_attempt_made_progress {
745                self.note_fd_readied(guest, call.fd(), crate::pipe_wake::Wants::Data)
746                    .await;
747            }
748            resources.poll_attempt += 1;
749            tracing::trace!(
750                "Retry #{} for {}blocking pipe writev after EAGAIN: {}",
751                resources.poll_attempt,
752                if atomic_pipe_write { "atomic " } else { "" },
753                call.display(&guest.memory())
754            );
755            record_retry_event(guest, call).await;
756        };
757
758        match turn_wait {
759            Some(mut wait) => {
760                let restored = wait.restore(guest, Some(turn_mask_cell)).await;
761                if turn_mask.is_some() {
762                    crate::tool_global::set_saved_guest_sigmask(guest, None).await;
763                }
764                match result_after_restore(restored, result) {
765                    Ok(result) => refuse_held_signal_loss(guest, Sysno::writev, result).await,
766                    Err(error) => Err(error),
767                }
768            }
769            None => {
770                restore_signals_after_disposition(guest, old_mask_addr).await?;
771                result
772            }
773        }
774    }
775
776    // AUTONOMOUS-BOT-IMPLEMENTED
777    // TODO-HUMAN-REVIEW(#2176): Review scalar blocking-pipe write completion and
778    // the fail-closed descriptor-replacement boundary.
779    /// Complete a logically blocking scalar pipe write after Hermit has made the pipe
780    /// physically nonblocking.
781    ///
782    /// Linux may return a positive short write for a request larger than `PIPE_BUF`, then
783    /// continue blocking for the remainder. Hermit's physical `O_NONBLOCK` is an internal
784    /// scheduler mechanism, so exposing that first short write changes guest behavior. Retry
785    /// the unconsumed suffix until the logical write completes, a signal arrives, or a real
786    /// error occurs. A signal or error after progress returns the partial byte count, matching
787    /// Linux.
788    ///
789    /// A concurrent close/dup2 can replace the numeric fd while this helper is yielded. Linux
790    /// keeps the original open-file description alive inside a blocking syscall, but Reverie
791    /// does not yet expose a backend-neutral retained-fd handle. Detect replacement before a
792    /// retry and fail closed rather than writing the suffix into an unrelated object.
793    pub async fn execute_blocking_pipe_write<G: Guest<Self>>(
794        &self,
795        guest: &mut G,
796        call: syscalls::Write,
797        expected_open_file: OpenFileId,
798    ) -> Result<i64, Error> {
799        const MAX_RW_COUNT: usize = 0x7fff_f000;
800
801        let target = call.len().min(MAX_RW_COUNT);
802        if target == 0 {
803            return self.execute_nonblockable_fd_syscall(guest, call).await;
804        }
805
806        tracing::trace!(
807            "NonblockableSyscall: converting to nonblocking syscall (internal polling): write"
808        );
809        let mut resources = Resources::new(guest.thread_state().dettid);
810        resources.insert(ResourceID::InternalIOPolling, Permission::W);
811        resources.fyi(call.name());
812        // Interruptible by a cross-task signal the kernel would deliver, as a
813        // polled read is (`retry_nonblocking_syscall_helper`): the scheduler
814        // answers the next request `Signaled`, and the write returns the
815        // bytes it wrote, or ERESTARTSYS before any
816        // (<https://github.com/rrnewton/hermit/issues/4187>).
817        resources.set_signal_interrupt_errno(call.signal_interrupt_errno());
818        resources.signal_state_task = guest_signal_state_task(guest);
819        // A pipe write: a recorded private `SIGCHLD` ends it as on Linux
820        // (`Resources::private_sigchld_decides`).
821        resources.private_sigchld_decides = true;
822        resources.polls_guest_state_only = true;
823        resources.polls_channel = self
824            .pipe_channel_end(guest, call.fd())
825            .map(|end| Box::new((end.channel, crate::pipe_wake::Wants::Space)));
826        // Without a host task whose kernel state the scheduler can filter by
827        // (KVM), the scheduler keeps every signal and the write checks after
828        // the wake, as `execute_blocking_pipe_writev` does, whether one would
829        // be delivered: a blocked or ignored signal must not end a write that
830        // has made progress, which would return a short count where Linux
831        // keeps waiting.
832        let disposition_scratch = if resources.signal_state_task.is_none() {
833            resources.decides_signal_interruption_itself = true;
834            let mut stack = guest.stack().await;
835            let mask_addr = stack.reserve::<KernelSigset>();
836            let action_addr = stack.reserve::<KernelSigaction>();
837            let guard = stack.commit()?;
838            Some((mask_addr, action_addr, guard))
839        } else {
840            None
841        };
842        let subtool = self.cfg.recordreplay_modes.then_some(self);
843        let mut current = call;
844        let mut written_total = 0usize;
845        let checks_at_turn = decides_interruption_at_turn(guest, resources.signal_state_task);
846        // The write owns the guest's mask while it blocks every blockable
847        // signal, as the generic poll does (`retry_nonblocking_syscall_helper`):
848        // an attempt after the first is a private injection of the
849        // unwritten suffix, which a pending signal could stop and move into
850        // the backend's single held slot, where a second one replaces it
851        // (https://github.com/rrnewton/hermit/issues/4273, stage 2).
852        let mut turn_wait = checks_at_turn
853            .then(|| KernelSignalWait::new(guest, 0, false, call.signal_interrupt_errno()));
854        let mut published = PublishedWaitMask::default();
855
856        let result: Result<i64, Error> = loop {
857            let written_before = written_total;
858            // A signal ends the write only if it would still wait for room:
859            // the attempt below runs first, as Linux's `pipe_write` checks
860            // for a pending signal only when it must wait. After the signal,
861            // the bytes written so far are returned, or the restart errno if
862            // there are none.
863            let status = if resources.poll_attempt > 0 {
864                Some(resource_request(guest, resources.clone()).await)
865            } else {
866                None
867            };
868            // Read before every attempt, the turnless first one included
869            // (`read_turn_signals`): a copy pending at the write's own entry
870            // is decided in this slice, before the writer can yield, so a later
871            // `SIG_IGN` and a new handler cannot take it
872            // (https://github.com/rrnewton/hermit/issues/4273, R2b-1 rule 4).
873            // Once the write blocks, the turn decides under the guest's own
874            // mask, which the write owns (Codex review of the R2b-2 design
875            // rev3, P2-1).
876            let turn = if checks_at_turn {
877                let committed = status.as_ref().map_or(0, committed_signals);
878                // The first attempt is the guest's own write, which the
879                // backend runs with every pending signal left queued, so only
880                // a later attempt needs the block.
881                match turn_signals_with_block(
882                    guest,
883                    &mut turn_wait,
884                    resources.poll_attempt > 0,
885                    committed,
886                    resources.private_sigchld_decides,
887                    &mut published,
888                )
889                .await
890                {
891                    Ok(turn) => Some(turn),
892                    Err(error) => break Err(error),
893                }
894            } else {
895                None
896            };
897            let signaled = if turn.is_some() {
898                false
899            } else {
900                match (&status, &disposition_scratch) {
901                    (Some(ResumeStatus::Signaled(_)), None) => true,
902                    (
903                        Some(status @ ResumeStatus::Signaled(_)),
904                        Some((mask_addr, action_addr, _)),
905                    ) => {
906                        match own_disposition_interrupts(
907                            guest,
908                            status.clone(),
909                            *mask_addr,
910                            *action_addr,
911                        )
912                        .await
913                        {
914                            Ok(interrupts) => interrupts,
915                            Err(error) => break Err(error),
916                        }
917                    }
918                    _ => false,
919                }
920            };
921
922            if resources.poll_attempt > 0
923                && !guest
924                    .thread_state()
925                    .with_detfd(call.fd(), |detfd| {
926                        detfd.open_file_id() == expected_open_file
927                    })
928                    .unwrap_or(false)
929            {
930                break if written_total > 0 {
931                    Ok(written_total as i64)
932                } else {
933                    self.refuse_unserviceable_operation(guest, Sysno::write, Errno::EOPNOTSUPP)
934                        .await
935                };
936            }
937
938            let result = match subtool {
939                Some(detcore) => {
940                    detcore
941                        .record_or_replay_preserving_tool_errors(guest, current)
942                        .await
943                }
944                None => guest.inject_with_retry(current).await.map_err(Error::from),
945            };
946            // As in `retry_nonblocking_syscall_helper`, an attempt that the
947            // pending signal stopped under record and replay is not made again.
948            match result {
949                Ok(written) if written > 0 => {
950                    let Ok(written) = usize::try_from(written) else {
951                        break Err(Errno::EIO.into());
952                    };
953                    let Some(remaining) = target.checked_sub(written_total) else {
954                        break Err(Errno::EIO.into());
955                    };
956                    if written > remaining {
957                        break Err(Errno::EIO.into());
958                    }
959                    let Some(total) = written_total.checked_add(written) else {
960                        break Err(Errno::EIO.into());
961                    };
962                    written_total = total;
963                    // A short attempt filled the pipe, so the write would wait:
964                    // a wake ends it with the bytes written (`TurnSignals::ends`).
965                    if written_total == target || turn.map_or(signaled, |turn| turn.ends(true)) {
966                        break Ok(written_total as i64);
967                    }
968                    let Some(buffer) = call.buf() else {
969                        break Err(Errno::EFAULT.into());
970                    };
971                    let Some(next_buffer) = buffer
972                        .as_raw()
973                        .checked_add(written_total)
974                        .and_then(Addr::<u8>::from_raw)
975                    else {
976                        break finish_partial_record_or_replay_write(
977                            written_total as i64,
978                            Errno::EFAULT.into(),
979                        );
980                    };
981                    current = call
982                        .with_buf(Some(next_buffer))
983                        .with_len(target - written_total);
984                }
985                Ok(0) => break Ok(written_total as i64),
986                Err(Error::Errno(Errno::EAGAIN))
987                    if turn.map_or(signaled, |turn| turn.ends(written_total > 0)) =>
988                {
989                    break if written_total > 0 {
990                        Ok(written_total as i64)
991                    } else {
992                        Err(call.signal_interrupt_errno().into())
993                    };
994                }
995                Err(Error::Errno(Errno::EAGAIN)) => {}
996                Err(error) => {
997                    break finish_partial_record_or_replay_write(written_total as i64, error);
998                }
999                Ok(_) => break Err(Errno::EIO.into()),
1000            }
1001
1002            resources.previous_attempt_made_progress = written_total > written_before;
1003            // Bytes this attempt wrote ready the readers before this thread
1004            // polls for room (`--pipe-wake-latency`).
1005            if resources.previous_attempt_made_progress {
1006                self.note_fd_readied(guest, call.fd(), crate::pipe_wake::Wants::Data)
1007                    .await;
1008            }
1009            resources.poll_attempt += 1;
1010            tracing::trace!(
1011                "Retry #{} for blocking pipe write: {}",
1012                resources.poll_attempt,
1013                call.display(&guest.memory())
1014            );
1015            record_retry_event(guest, call).await;
1016        };
1017
1018        // The single exit, as in `retry_nonblocking_syscall_helper`: the
1019        // guest's mask goes back, through `Guest::set_blocked_signals` with no
1020        // scratch memory, before the result is returned.
1021        match turn_wait {
1022            Some(mut wait) if wait.effective_mask().is_some() => {
1023                let restored = wait.restore(guest, None).await;
1024                publish_wait_mask(guest, None, &mut published).await;
1025                match result_after_restore(restored, result) {
1026                    Ok(result) => refuse_held_signal_loss(guest, Sysno::write, result).await,
1027                    Err(error) => Err(error),
1028                }
1029            }
1030            _ => result,
1031        }
1032    }
1033
1034    async fn execute_atomic_pipe_writev_attempt<G: Guest<Self>>(
1035        &self,
1036        guest: &mut G,
1037        call: syscalls::Writev,
1038        iovecs: &[(usize, usize)],
1039        stack_iov: Option<usize>,
1040    ) -> Result<i64, Error> {
1041        if let Some(stack_iov) = stack_iov {
1042            let scratch_call = call.with_iov(Addr::from_raw(stack_iov));
1043            return if self.cfg.recordreplay_modes {
1044                self.record_or_replay_preserving_tool_errors(guest, scratch_call)
1045                    .await
1046            } else {
1047                guest
1048                    .inject_with_retry(scratch_call)
1049                    .await
1050                    .map_err(Error::from)
1051            };
1052        }
1053
1054        let mapping_len = iovecs
1055            .len()
1056            .checked_mul(std::mem::size_of::<libc::iovec>())
1057            .expect("validated iovec count cannot overflow scratch length");
1058        let mapped = guest
1059            .inject_with_retry(Syscall::Mmap(
1060                syscalls::Mmap::new()
1061                    .with_addr(None)
1062                    .with_len(mapping_len)
1063                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
1064                    .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
1065                    .with_fd(-1)
1066                    .with_offset(0),
1067            ))
1068            .await
1069            .unwrap_or_else(|error| panic!("failed to map atomic writev scratch: {error}"));
1070        let mapped = usize::try_from(mapped)
1071            .unwrap_or_else(|_| panic!("atomic writev scratch mmap returned {mapped}"));
1072        let scratch_iov = Addr::<libc::iovec>::from_raw(mapped)
1073            .unwrap_or_else(|| panic!("atomic writev scratch mmap returned a null address"));
1074        let mapping_addr: Addr<libc::c_void> = scratch_iov.cast();
1075        let write_result = {
1076            let raw_iovecs: Vec<libc::iovec> = iovecs
1077                .iter()
1078                .map(|(base, length)| libc::iovec {
1079                    iov_base: *base as *mut libc::c_void,
1080                    iov_len: *length,
1081                })
1082                .collect();
1083            // SAFETY: the injected anonymous mapping is exclusively owned scratch space.
1084            guest
1085                .memory()
1086                .write_values(unsafe { scratch_iov.into_mut() }, &raw_iovecs)
1087        };
1088        if let Err(write_error) = write_result {
1089            guest
1090                .inject_with_retry(Syscall::Munmap(
1091                    syscalls::Munmap::new()
1092                        .with_addr(Some(mapping_addr))
1093                        .with_len(mapping_len),
1094                ))
1095                .await
1096                .unwrap_or_else(|cleanup_error| {
1097                    panic!(
1098                        "failed to populate atomic writev scratch ({write_error}); cleanup failed ({cleanup_error})"
1099                    )
1100                });
1101            panic!("failed to populate atomic writev scratch: {write_error}");
1102        }
1103
1104        let scratch_call = call.with_iov(Some(scratch_iov));
1105        let result = if self.cfg.recordreplay_modes {
1106            self.record_or_replay_preserving_tool_errors(guest, scratch_call)
1107                .await
1108        } else {
1109            guest
1110                .inject_with_retry(scratch_call)
1111                .await
1112                .map_err(Error::from)
1113        };
1114        guest
1115            .inject_with_retry(Syscall::Munmap(
1116                syscalls::Munmap::new()
1117                    .with_addr(Some(mapping_addr))
1118                    .with_len(mapping_len),
1119            ))
1120            .await
1121            .unwrap_or_else(|error| panic!("failed to unmap atomic writev scratch: {error}"));
1122        result
1123    }
1124
1125    /// Override physically_nonblocking to true for the file descriptor, if appropriate.
1126    pub fn maybe_set_nonblocking_fd<G: Guest<Self>>(&self, guest: &G, fd: i32) {
1127        if self.cfg.sequentialize_threads && !self.cfg.debug_externalize_sockets {
1128            guest
1129                .thread_state()
1130                .with_detfd(fd, |detfd| {
1131                    detfd.set_physically_nonblocking();
1132                })
1133                .unwrap();
1134        }
1135    }
1136}
1137
1138fn remaining_writev_segment(
1139    fd: i32,
1140    iovecs: &[(usize, usize)],
1141    mut consumed: usize,
1142    remaining_limit: usize,
1143) -> Result<Option<syscalls::Write>, Errno> {
1144    for (base, length) in iovecs {
1145        if consumed >= *length {
1146            consumed -= *length;
1147            continue;
1148        }
1149        let base = base.checked_add(consumed).ok_or(Errno::EFAULT)?;
1150        let buffer = Addr::<u8>::from_raw(base).ok_or(Errno::EFAULT)?;
1151        return Ok(Some(
1152            syscalls::Write::new()
1153                .with_fd(fd)
1154                .with_buf(Some(buffer))
1155                .with_len((*length - consumed).min(remaining_limit)),
1156        ));
1157    }
1158    Ok(None)
1159}
1160
1161/// A blocking syscall that involves a fail descriptor may be handled in these three ways:
1162#[derive(PartialEq, Eq, Debug)]
1163pub enum IOAction {
1164    /// It may physically block and we can't change that.  Treat it as ExternalBlockingIO.
1165    Blocking,
1166    /// We can nonblockize and retry the call.
1167    NonblockizeRetry,
1168    /// The call is nonblocking already, and safe to execute.
1169    PassThru,
1170}
1171
1172/// Returns the strategy for an FD-based call that may block when executed.
1173///
1174/// Failure means descriptor metadata could not classify the call; the caller must preserve the
1175/// kernel's authority over the syscall result rather than exposing this advisory lookup error.
1176pub fn ioaction_based_on_fd_status<
1177    G: Guest<Detcore<T>>,
1178    T: RecordOrReplay,
1179    C: SyscallInfo + Into<Syscall>,
1180>(
1181    guest: &mut G,
1182    call: C,
1183) -> Result<IOAction, Errno> {
1184    let wrapped: Syscall = call.into();
1185    let fd = get_fd(wrapped).unwrap_or_else(|| panic!("Failed to get fd for {}", call.name()));
1186    let (phys, virt) = guest.thread_state().with_detfd(fd, |detfd| {
1187        (detfd.physically_nonblocking(), detfd.is_nonblocking())
1188    })?;
1189    tracing::trace!(
1190        "Checking FD {} for nonblocking: physical {} / virtual {}",
1191        fd,
1192        phys,
1193        virt
1194    );
1195    if virt && !phys {
1196        // TF: simulate nonblocking on top of physically blocking? How?
1197        panic!(
1198            "Invariant violation, fd {}: we cannot simulate nonblocking behavior when set to blocking mode in the kernel.",
1199            fd
1200        );
1201    } else if !virt && !phys {
1202        // FF: logically blocking, physically blocking, this could only work with BlockingExternalIO.
1203        Ok(IOAction::Blocking)
1204    } else if virt && phys {
1205        // TT: both nonblocking, so firing once is sufficient
1206        Ok(IOAction::PassThru)
1207    } else {
1208        // FT: Need to simulate blocking on top of nonblocking.
1209        Ok(IOAction::NonblockizeRetry)
1210    }
1211}
1212
1213/// Does this single-fd syscall operate on a container-INTERNAL file descriptor?
1214///
1215/// This recognizes pipes, whose two endpoints are always both owned by guest
1216/// processes inside the deterministic container, and `socketpair(2)` endpoints, which
1217/// have that same property for the same reason. Internal fds are made physically
1218/// nonblocking (see `handle_pipe2` and `handle_socketpair`) so a potentially-blocking
1219/// op on them can use the deterministic `InternalIOPolling` nonblockize-and-retry
1220/// strategy instead of `BlockingExternalIO`. Treating an internal fd as external
1221/// blocking IO deadlocks the sequentialized scheduler in record/replay, because a
1222/// reader and its paired writer are not independent.
1223///
1224/// A socketpair is the one socket case where internality is known at creation time:
1225/// the kernel creates BOTH ends, so no peer outside the container can ever hold one.
1226/// That is why it does not need the general internal-vs-external socket detection
1227/// (loopback / AF_UNIX-to-another-guest vs a real host peer) that remains unsolved;
1228/// every OTHER socket still conservatively remains external.
1229///
1230/// The residual assumption, stated because it is an assumption and not a proof: a
1231/// guest could pass a socketpair endpoint out of the container over `SCM_RIGHTS` to a
1232/// process on the host. A pipe fd can escape by exactly the same route and this code
1233/// has always accepted that for pipes, so recognizing socketpairs widens no exposure
1234/// class -- but neither claim is airtight.
1235///
1236/// The converse gap: a socketpair endpoint or pipe that a guest RECEIVES over
1237/// `SCM_RIGHTS` is untracked by Detcore, so it is not recognized here and keeps the
1238/// kernel-authoritative external path. Its open file description is still physically
1239/// nonblocking, so a blocking read through the received descriptor can return EAGAIN
1240/// under record, as it already could for a received pipe.
1241///
1242/// Syscalls whose fd is not directly extractable (e.g. poll/ppoll, which carry a
1243/// pointer to an fd array) return false and keep their existing handling.
1244pub fn syscall_targets_internal_fd<G: Guest<Detcore<T>>, T: RecordOrReplay>(
1245    guest: &mut G,
1246    call: Syscall,
1247) -> bool {
1248    // An epoll wait's descriptor is the epoll set it waits on, never a pipe it
1249    // reads; a guest that passes a pipe gets EINVAL from the kernel.
1250    if matches!(call, Syscall::EpollWait(_) | Syscall::EpollPwait(_)) {
1251        return false;
1252    }
1253    match get_fd(call) {
1254        Some(fd) => guest
1255            .thread_state()
1256            .with_detfd(fd, |detfd| {
1257                // This is read-end provenance, not a blanket external-fd
1258                // classification: writes and socketpairs retain the guard.
1259                if matches!(call, Syscall::Read(_) | Syscall::Readv(_))
1260                    && detfd.inherited_external_read().is_some()
1261                {
1262                    return false;
1263                }
1264                matches!(detfd.ty(), FdType::Pipe) || detfd.is_socketpair_endpoint()
1265            })
1266            .unwrap_or(false),
1267        None => false,
1268    }
1269}
1270
1271/// Whether `call` is a `read` or `readv` of a descriptor Detcore records as
1272/// a pipe (`FdType::Pipe`: a pipe, or a FIFO that joined internal polling),
1273/// the restartable reads a recorded private `SIGCHLD` ends
1274/// (`Resources::private_sigchld_decides`; R2b-2 stage 3,
1275/// https://github.com/rrnewton/hermit/issues/4273). A socket read keeps
1276/// holding it (rev4 1e).
1277fn reads_a_pipe<G: Guest<Detcore<T>>, T: RecordOrReplay>(guest: &mut G, call: Syscall) -> bool {
1278    matches!(call, Syscall::Read(_) | Syscall::Readv(_))
1279        && get_fd(call).is_some_and(|fd| {
1280            guest
1281                .thread_state()
1282                .with_detfd(fd, |detfd| matches!(detfd.ty(), FdType::Pipe))
1283                .unwrap_or(false)
1284        })
1285}
1286
1287/// Does `call` read a descriptor Detcore records as a signalfd
1288/// (`Resources::reads_signalfd`)? Only `read`, `readv` and `preadv2` at the
1289/// current offset can: a positioned read of a signalfd fails with ESPIPE.
1290fn call_reads_signalfd<G: Guest<Detcore<T>>, T: RecordOrReplay>(
1291    guest: &mut G,
1292    call: Syscall,
1293) -> bool {
1294    let fd = match call {
1295        Syscall::Read(c) => c.fd(),
1296        Syscall::Readv(c) => c.fd(),
1297        Syscall::Preadv2(c) => c.fd(),
1298        _ => return false,
1299    };
1300    guest
1301        .thread_state()
1302        .with_detfd(fd, |detfd| detfd.ty() == crate::fd::FdType::Signalfd)
1303        .unwrap_or(false)
1304}
1305
1306/// The descriptor a `read`, `readv` or `preadv2` reads (`Resources::read_fd`).
1307fn read_family_fd(call: Syscall) -> Option<i32> {
1308    match call {
1309        Syscall::Read(c) => Some(c.fd()),
1310        Syscall::Readv(c) => Some(c.fd()),
1311        Syscall::Preadv2(c) => Some(c.fd()),
1312        _ => None,
1313    }
1314}
1315
1316/// Does replay answer this call from the recording rather than by running it?
1317///
1318/// This follows the replayer's dispatch. It serves `accept`, `accept4`, `connect`,
1319/// `sendto`, `sendmsg`, `recvfrom` and `recvmsg` from its log whatever the descriptor
1320/// is, so they count even on a descriptor Detcore does not track, such as a listener
1321/// received over `SCM_RIGHTS`; an untagged accept there would let its stand-in take a
1322/// slot at a host-timed point. `read`, `readv`, `write` and `writev` count only on a
1323/// socket Detcore created with `socket(2)` or `accept(2)`: on other descriptors,
1324/// replay may run them for real as eventfd operations, which can block, so an unknown
1325/// descriptor is not assumed to be served from the log. `recvmmsg` and `sendmmsg` are
1326/// recorded by neither recorder nor replayer (on an accepted connection record/replay
1327/// refuses them, see `refuse_log_served_mmsg`).
1328fn replay_serves_socket_call_from_log<G: Guest<Detcore<T>>, T: RecordOrReplay>(
1329    guest: &mut G,
1330    call: Syscall,
1331) -> bool {
1332    let fd = match call {
1333        Syscall::Accept(_)
1334        | Syscall::Accept4(_)
1335        | Syscall::Connect(_)
1336        | Syscall::Sendto(_)
1337        | Syscall::Sendmsg(_)
1338        | Syscall::Recvfrom(_)
1339        | Syscall::Recvmsg(_) => return true,
1340        Syscall::Read(s) => s.fd(),
1341        Syscall::Readv(s) => s.fd(),
1342        Syscall::Write(s) => s.fd(),
1343        Syscall::Writev(s) => s.fd(),
1344        _ => return false,
1345    };
1346    is_log_served_socket(guest, fd)
1347}
1348
1349/// Does replay answer this otherwise blocking call from the recording alone?
1350///
1351/// The replayer serves `poll`, `ppoll`, `select` and `pselect6` from the log
1352/// without running them. `epoll_wait` is excluded because replay reapplies its
1353/// side effects on live descriptors, which may block.
1354fn replay_serves_blocking_call_from_log(call: Syscall) -> bool {
1355    matches!(
1356        call,
1357        Syscall::Poll(_) | Syscall::Ppoll(_) | Syscall::Select(_) | Syscall::Pselect6(_)
1358    )
1359}
1360
1361/// Is `fd` a socket whose connection record and replay keep only in the log?
1362///
1363/// That is a socket Detcore created with `socket(2)` or `accept(2)`, but not a
1364/// socketpair endpoint: replay recreates a socketpair, and its operations run
1365/// live.
1366fn is_log_served_socket<G: Guest<Detcore<T>>, T: RecordOrReplay>(guest: &mut G, fd: i32) -> bool {
1367    guest
1368        .thread_state()
1369        .with_detfd(fd, |detfd| {
1370            matches!(detfd.ty(), FdType::Socket) && !detfd.is_socketpair_endpoint()
1371        })
1372        .unwrap_or(false)
1373}
1374
1375/// Is `fd` a connection that `accept(2)` or `accept4(2)` returned? Record and
1376/// replay keep such a connection only in the log, and replay stands in an
1377/// eventfd for it, so an operation that runs live during replay meets that
1378/// eventfd rather than a connected socket.
1379pub(crate) fn is_accepted_connection<G: Guest<Detcore<T>>, T: RecordOrReplay>(
1380    guest: &mut G,
1381    fd: i32,
1382) -> bool {
1383    guest
1384        .thread_state()
1385        .with_detfd(fd, |detfd| detfd.is_accepted_connection())
1386        .unwrap_or(false)
1387}
1388
1389/// A large subset of system calls have a single, unique file descriptor argument.  This
1390/// is a convenience function for grabbing that argument.
1391///
1392/// It does not cover system calls with multiple fd arguments, with pointers to heap
1393/// structures that contain fds.
1394pub(crate) fn get_fd(s: Syscall) -> Option<i32> {
1395    match s {
1396        Syscall::Recvfrom(s) => Some(s.fd()),
1397        Syscall::Recvmsg(s) => Some(s.sockfd()),
1398        Syscall::Recvmmsg(s) => Some(s.fd()),
1399        Syscall::Sendto(s) => Some(s.fd()),
1400        Syscall::Sendmsg(s) => Some(s.fd()),
1401        Syscall::Sendmmsg(s) => Some(s.sockfd()),
1402        Syscall::Accept(s) => Some(s.sockfd()),
1403        Syscall::Accept4(s) => Some(s.sockfd()),
1404        Syscall::Connect(s) => Some(s.fd()),
1405        Syscall::Bind(s) => Some(s.fd()),
1406        Syscall::Listen(s) => Some(s.fd()),
1407        Syscall::Getsockname(s) => Some(s.fd()),
1408        Syscall::Getpeername(s) => Some(s.fd()),
1409        Syscall::Setsockopt(s) => Some(s.fd()),
1410        Syscall::Getsockopt(s) => Some(s.fd()),
1411
1412        Syscall::Read(s) => Some(s.fd()),
1413        Syscall::Write(s) => Some(s.fd()),
1414        Syscall::Close(s) => Some(s.fd()),
1415        Syscall::Fstat(s) => Some(s.fd()),
1416        Syscall::Lseek(s) => Some(s.fd()),
1417        Syscall::Mmap(s) => Some(s.fd()),
1418        Syscall::Ioctl(s) => Some(s.fd()),
1419        Syscall::Pread64(s) => Some(s.fd()),
1420        Syscall::Pwrite64(s) => Some(s.fd()),
1421        Syscall::Readv(s) => Some(s.fd()),
1422        Syscall::Writev(s) => Some(s.fd()),
1423
1424        Syscall::Shutdown(s) => Some(s.fd()),
1425        Syscall::Fcntl(s) => Some(s.fd()),
1426        Syscall::Flock(s) => Some(s.fd()),
1427        Syscall::Fsync(s) => Some(s.fd()),
1428        Syscall::Fdatasync(s) => Some(s.fd()),
1429        Syscall::Ftruncate(s) => Some(s.fd()),
1430        Syscall::Fchdir(s) => Some(s.fd()),
1431        Syscall::Fchmod(s) => Some(s.fd()),
1432        Syscall::Fchown(s) => Some(s.fd()),
1433        Syscall::Fstatfs(s) => Some(s.fd()),
1434        Syscall::Readahead(s) => Some(s.fd()),
1435        Syscall::Fsetxattr(s) => Some(s.fd()),
1436        Syscall::Fgetxattr(s) => Some(s.fd()),
1437        Syscall::Flistxattr(s) => Some(s.fd()),
1438        Syscall::Fremovexattr(s) => Some(s.fd()),
1439        Syscall::Fadvise64(s) => Some(s.fd()),
1440        Syscall::InotifyAddWatch(s) => Some(s.fd()),
1441        Syscall::InotifyRmWatch(s) => Some(s.fd()),
1442        Syscall::SyncFileRange(s) => Some(s.fd()),
1443        Syscall::Vmsplice(s) => Some(s.fd()),
1444        Syscall::Utimensat(s) => Some(s.dirfd()),
1445        Syscall::Signalfd(s) => Some(s.fd()),
1446        Syscall::Fallocate(s) => Some(s.fd()),
1447        Syscall::TimerfdSettime(s) => Some(s.fd()),
1448        Syscall::TimerfdGettime(s) => Some(s.fd()),
1449        Syscall::Signalfd4(s) => Some(s.fd()),
1450        Syscall::Preadv(s) => Some(s.fd()),
1451        Syscall::Pwritev(s) => Some(s.fd()),
1452        Syscall::Syncfs(s) => Some(s.fd()),
1453        Syscall::Setns(s) => Some(s.fd()),
1454        Syscall::FinitModule(s) => Some(s.fd()),
1455        Syscall::Preadv2(s) => Some(s.fd()),
1456        Syscall::Pwritev2(s) => Some(s.fd()),
1457
1458        Syscall::Openat(s) => Some(s.dirfd()),
1459        Syscall::Mkdirat(s) => Some(s.dirfd()),
1460        Syscall::Mknodat(s) => Some(s.dirfd()),
1461        Syscall::Fchownat(s) => Some(s.dirfd()),
1462        Syscall::Futimesat(s) => Some(s.dirfd()),
1463        Syscall::Newfstatat(s) => Some(s.dirfd()),
1464        Syscall::Unlinkat(s) => Some(s.dirfd()),
1465        Syscall::Readlinkat(s) => Some(s.dirfd()),
1466        Syscall::Fchmodat(s) => Some(s.dirfd()),
1467        Syscall::Faccessat(s) => Some(s.dirfd()),
1468        Syscall::NameToHandleAt(s) => Some(s.dirfd()),
1469        Syscall::Execveat(s) => Some(s.dirfd()),
1470        Syscall::Statx(s) => Some(s.dirfd()),
1471        Syscall::Symlinkat(s) => Some(s.newdirfd()),
1472        Syscall::PerfEventOpen(s) => Some(s.group_fd()),
1473        Syscall::OpenByHandleAt(s) => Some(s.mount_fd()),
1474
1475        Syscall::EpollCtl(s) => Some(s.epfd()),
1476        Syscall::EpollWait(s) => Some(s.epfd()),
1477        Syscall::EpollPwait(s) => Some(s.epfd()),
1478
1479        // Ambiguous, 2 fds, no answer:
1480        Syscall::Dup2(_) => None,
1481        // Ambiguous, 2 fds, no answer:
1482        Syscall::Sendfile(_) => None,
1483        // Ambiguous, 2 fds, no answer:
1484        Syscall::Renameat(_) => None,
1485        // Ambiguous, 2 fds, no answer:
1486        Syscall::Linkat(_) => None,
1487        // Ambiguous, 2 fds, no answer:
1488        Syscall::FanotifyMark(_) => None,
1489        // Ambiguous, 2 fds, no answer:
1490        Syscall::Renameat2(_) => None,
1491        // Ambiguous, 2 fds, no answer:
1492        Syscall::Dup3(_) => None,
1493        // Ambiguous, 2 fds, no answer:
1494        Syscall::KexecLoad(_) => None,
1495
1496        // Takes a pointer to fd, not directly accessible:
1497        Syscall::Poll(_) => None,
1498        // Takes a pointer to fd, not directly accessible:
1499        Syscall::Ppoll(_) => None,
1500
1501        _ => None,
1502    }
1503}
1504
1505/// A system call which may or may not block, but which can be MADE nonblocking.
1506// `async_trait` rewrites `into_nonblocking` to return a boxed future and marks it
1507// `#[must_use]`; the future is already `#[must_use]` in its own right, so clippy sees a double
1508// annotation. Both are generated, so the lint's own suggestion -- give the `must_use` an explicit
1509// reason -- cannot be applied at this source. Allowed at the item rather than crate-wide so any
1510// hand-written double `must_use` elsewhere still fails `#![deny(clippy::all)]` (detcore/src/lib.rs:35).
1511// Appeared with nightly-2026-08-08 (rustc 1.99.0-nightly 1a98b1e13) against an unchanged tree.
1512#[allow(clippy::double_must_use)]
1513#[async_trait]
1514pub trait NonblockableSyscall: SyscallInfo {
1515    /// Convert the system call to a nonblocking version of itself.  Sometimes this means
1516    /// setting a zero timeout, and sometimes it means something else.
1517    ///
1518    /// This may need to stack allocate, so it returns a StackGuard.
1519    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1520        self,
1521        guest: &mut G,
1522    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>);
1523
1524    /// Check if the result (in nonblocking mode) is analogous to blocking in blocking mode.
1525    /// I.e. the result means "try again".
1526    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1527        res == Ok(0)
1528    }
1529
1530    /// Return the errno used when a signal interrupts this internally polled syscall.
1531    /// Most blocking I/O is restartable when its handler uses `SA_RESTART`.
1532    fn signal_interrupt_errno(&self) -> Errno {
1533        Errno::ERESTARTSYS
1534    }
1535
1536    /// Return the errno for an interrupting signal that ends this wait after it began,
1537    /// on a backend that decides interruption from the kernel's signal state
1538    /// (`supports_blocked_wait_signal_interruption`). The kernel applies the
1539    /// guest's disposition to it on resume, so it must be the restart code Linux uses
1540    /// for this call: a handler then turns it into `EINTR` or a restart, and a signal
1541    /// with no handler restarts the call.
1542    fn kernel_restart_errno(&self) -> Errno {
1543        self.signal_interrupt_errno()
1544    }
1545
1546    /// Whether Linux restarts this call, after [`kernel_restart_errno`](Self::kernel_restart_errno)
1547    /// with no handler, through a restart block that keeps its absolute deadline: a
1548    /// `poll` with a positive timeout (`do_restart_poll`) and a timed `FUTEX_WAIT` or
1549    /// `FUTEX_WAIT_BITSET` (`futex_wait_restart`). Its restart code is then
1550    /// `ERESTART_RESTARTBLOCK`, and
1551    /// Detcore keeps the deadline in a [`RestartBlock`] for the `restart_syscall` that
1552    /// the kernel runs next (<https://github.com/rrnewton/hermit/issues/3358>).
1553    ///
1554    /// Such a wait is also not ended by a default job-control stop signal
1555    /// (`KernelSignalState::interrupting_wait`), so that a stop Linux discards in an
1556    /// orphaned process group does not end the call before its deadline.
1557    fn restart_keeps_deadline(&self) -> bool {
1558        false
1559    }
1560
1561    /// Signals the wait itself accepts rather than being interrupted by, read from
1562    /// guest memory. Only `rt_sigtimedwait` has any.
1563    fn signals_consumed_by_wait<M: MemoryAccess>(&self, _memory: &M) -> KernelSigset {
1564        0
1565    }
1566
1567    /// Convert a physical nonblocking completion into the result expected by the guest.
1568    /// `retried` is true after a prior result was classified as blocked.
1569    fn normalize_nonblocking_result(
1570        &self,
1571        res: Result<i64, Errno>,
1572        _retried: bool,
1573    ) -> Result<i64, Errno> {
1574        res
1575    }
1576}
1577
1578/// A system call which can logically timeout and then would return a given value
1579/// indicating that timeout.
1580pub trait TimeoutableSyscall: SyscallInfo {
1581    /// What would the syscall return IF it timed out?
1582    fn timeout_return_val(&self) -> Result<i64, Errno>;
1583}
1584
1585fn interrupted_write_result<C: NonblockableSyscall>(
1586    call: &C,
1587    written_total: usize,
1588    disposition: Option<WaitSignalDisposition>,
1589) -> Option<Result<i64, Error>> {
1590    match disposition {
1591        None => None,
1592        Some(_) if written_total > 0 => Some(Ok(written_total as i64)),
1593        Some(_) => Some(Err(call.signal_interrupt_errno().into())),
1594    }
1595}
1596
1597fn pipe_writev_resources(dettid: DetTid, call: reverie::syscalls::Writev) -> Resources {
1598    let mut resources = Resources::new(dettid);
1599    resources.insert(ResourceID::InternalIOPolling, Permission::W);
1600    resources.fyi(call.name());
1601    resources.set_signal_interrupt_errno(call.signal_interrupt_errno());
1602    // Polls with every ordinary signal blocked and checks the target's
1603    // disposition itself after a `Signaled` wake, so the scheduler's drain
1604    // must not filter by the kernel mask (`execute_blocking_pipe_writev`).
1605    resources.decides_signal_interruption_itself = true;
1606    resources.polls_guest_state_only = true;
1607    resources
1608}
1609
1610#[async_trait]
1611impl NonblockableSyscall for reverie::syscalls::Poll {
1612    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1613        self,
1614        _guest: &mut G,
1615    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1616        (self.with_timeout(0), None)
1617    }
1618
1619    fn signal_interrupt_errno(&self) -> Errno {
1620        Errno::EINTR
1621    }
1622
1623    /// Linux ends an interrupted `poll` with a restart code that a handler turns into
1624    /// `EINTR` and that restarts the call when no handler runs.
1625    ///
1626    /// With a positive timeout that code is Linux's own, `ERESTART_RESTARTBLOCK`: the
1627    /// kernel then runs `restart_syscall`, which Detcore resumes with the deadline it
1628    /// kept ([`RestartBlock`]), as `do_restart_poll` does
1629    /// (https://github.com/rrnewton/hermit/issues/3358). An infinite timeout has no
1630    /// deadline to keep, so it returns `ERESTARTNOHAND`, and running `poll` again with
1631    /// its original arguments is the same restart.
1632    fn kernel_restart_errno(&self) -> Errno {
1633        if self.restart_keeps_deadline() {
1634            Errno::ERESTART_RESTARTBLOCK
1635        } else {
1636            Errno::ERESTARTNOHAND
1637        }
1638    }
1639
1640    /// A zero timeout never blocks, and a negative one never expires.
1641    fn restart_keeps_deadline(&self) -> bool {
1642        self.timeout() > 0
1643    }
1644}
1645
1646impl TimeoutableSyscall for reverie::syscalls::Poll {
1647    fn timeout_return_val(&self) -> Result<i64, Errno> {
1648        Ok(0)
1649    }
1650}
1651
1652#[async_trait]
1653impl NonblockableSyscall for reverie::syscalls::Ppoll {
1654    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1655        self,
1656        guest: &mut G,
1657    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1658        let (tp, guard) = zero_timespec(guest).await;
1659        // SAFETY: `tp` points to exclusively owned scratch storage kept alive by `guard`.
1660        let tp = unsafe { tp.into_mut() };
1661        (self.with_timeout(Some(tp)), Some(guard))
1662    }
1663
1664    fn signal_interrupt_errno(&self) -> Errno {
1665        Errno::EINTR
1666    }
1667
1668    /// Linux ends an interrupted `ppoll` with a restart code that a handler turns into
1669    /// `EINTR` and that restarts the call when no handler runs.
1670    fn kernel_restart_errno(&self) -> Errno {
1671        Errno::ERESTARTNOHAND
1672    }
1673}
1674
1675impl TimeoutableSyscall for reverie::syscalls::Ppoll {
1676    fn timeout_return_val(&self) -> Result<i64, Errno> {
1677        Ok(0)
1678    }
1679}
1680
1681#[async_trait]
1682impl NonblockableSyscall for reverie::syscalls::EpollWait {
1683    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1684        self,
1685        _guest: &mut G,
1686    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1687        (self.with_timeout(0), None)
1688    }
1689
1690    fn signal_interrupt_errno(&self) -> Errno {
1691        Errno::EINTR
1692    }
1693}
1694
1695impl TimeoutableSyscall for reverie::syscalls::EpollWait {
1696    fn timeout_return_val(&self) -> Result<i64, Errno> {
1697        Ok(0)
1698    }
1699}
1700
1701// `epoll_pwait` was the one member of the
1702// poll/epoll family with no nonblocking form, even though `Ppoll` -- the
1703// sigmask variant of `poll` -- has had one all along. Programs that issue
1704// `epoll_pwait` DIRECTLY (libuv does, which is how the `cmake` hang surfaced)
1705// therefore reached an unhandled path while the `EpollWait` impl above went
1706// unused by them. Note this is NOT glibc's `epoll_wait(2)` on x86_64: glibc
1707// only spells it `epoll_pwait` where `__NR_epoll_wait` is absent, which x86_64
1708// is not. With a NULL sigmask the two calls are semantically identical, so the
1709// nonblocking form is the same: timeout 0, EINTR, and a 0 (no events) timeout
1710// return.
1711#[async_trait]
1712impl NonblockableSyscall for reverie::syscalls::EpollPwait {
1713    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1714        self,
1715        _guest: &mut G,
1716    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1717        (self.with_timeout(0), None)
1718    }
1719
1720    fn signal_interrupt_errno(&self) -> Errno {
1721        Errno::EINTR
1722    }
1723}
1724
1725impl TimeoutableSyscall for reverie::syscalls::EpollPwait {
1726    fn timeout_return_val(&self) -> Result<i64, Errno> {
1727        Ok(0)
1728    }
1729}
1730
1731/// What to do with the copy of the standard `signal` this thread just took
1732/// (`rt_sigtimedwait`, a signalfd record), after which its queues held
1733/// `after` (when read): drop it, as a copy Linux discarded when it was sent
1734/// or a stale POSIX timer entry, or return it with another siginfo
1735/// (`DiscardedSignalControl::Take`). The scheduler pops and promotes either
1736/// way.
1737pub(crate) async fn take_outcome<T, G>(
1738    guest: &mut G,
1739    signal: i32,
1740    after: Option<(u64, u64)>,
1741) -> crate::scheduler::posix_timer_coalesce::TakeOutcome
1742where
1743    T: RecordOrReplay,
1744    G: Guest<Detcore<T>>,
1745{
1746    use crate::scheduler::discarded_at_send::DiscardedSignalAnswer;
1747    use crate::scheduler::discarded_at_send::DiscardedSignalControl;
1748    use crate::scheduler::posix_timer_coalesce::TakeOutcome;
1749    let at = guest.thread_state().thread_logical_time.as_nanos();
1750    match crate::tool_global::discarded_signal(
1751        guest,
1752        DiscardedSignalControl::Take { signal, at, after },
1753    )
1754    .await
1755    {
1756        DiscardedSignalAnswer::Taken(outcome) => outcome,
1757        _ => TakeOutcome {
1758            skip: false,
1759            rewrite: None,
1760        },
1761    }
1762}
1763
1764async fn zero_timespec<'stack, T: RecordOrReplay, G: Guest<Detcore<T>>>(
1765    guest: &mut G,
1766) -> (Addr<'stack, Timespec>, <G::Stack as Stack>::StackGuard) {
1767    let mut stack = guest.stack().await;
1768    let tp_val = Timespec {
1769        tv_sec: 0,
1770        tv_nsec: 0,
1771    };
1772    let tp = stack.push(tp_val);
1773    let guard = stack.commit().expect("stack.commit to succeed");
1774    (tp, guard)
1775}
1776
1777#[async_trait]
1778impl NonblockableSyscall for reverie::syscalls::Wait4 {
1779    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1780        self,
1781        _guest: &mut G,
1782    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1783        let call2 = self.with_options(self.options() | WaitPidFlag::WNOHANG);
1784        (call2, None)
1785    }
1786
1787    // Child has not changed state yet, so we go to the scheduler and wait to poll again.
1788    // In scenarios with lots of outstanding waits, this polling strategy can change the asymptotic
1789    // complexity of the program. Ideally, we would model the blocking `wait4` (and process state
1790    // transitions) directly in the scheduler, and execute it only when we know it will complete.
1791    //
1792    // The polling backoff strategy mitigates this problem however.
1793    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1794        res == Ok(0)
1795    }
1796}
1797
1798#[async_trait]
1799/// Used only for FUTEX_WAIT
1800impl NonblockableSyscall for reverie::syscalls::Futex {
1801    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1802        self,
1803        guest: &mut G,
1804    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1805        let (tp, guard) = zero_timespec(guest).await;
1806        (self.with_timeout(Some(tp)), Some(guard))
1807    }
1808
1809    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1810        // EAGAIN can mean the futex wait's compare-and-block failed and we should return that to
1811        // the guest.  With timeout=0, the timeout is what shows that it would have blocked.
1812        res == Err(Errno::ETIMEDOUT)
1813    }
1814
1815    /// Linux restarts an untimed `FUTEX_WAIT` under `SA_RESTART` (`-ERESTARTSYS`), but a
1816    /// timed wait returns `-ERESTART_RESTARTBLOCK`, which a handler always turns into
1817    /// `EINTR` (https://github.com/rrnewton/hermit/issues/3146).
1818    ///
1819    /// A timed `FUTEX_WAIT` or `FUTEX_WAIT_BITSET` returns Linux's code: with no
1820    /// handler the kernel then runs `restart_syscall`, which Detcore resumes with the
1821    /// deadline it kept ([`RestartBlock`]), as `futex_wait_restart` does
1822    /// (https://github.com/rrnewton/hermit/issues/3358). Linux's `futex_wait` keeps
1823    /// the absolute deadline of every timed wait in the restart block, so a
1824    /// `FUTEX_WAIT_BITSET` deadline the guest moves in memory after the wait began
1825    /// does not change when the restarted wait ends. `FUTEX_WAIT_BITSET` used to
1826    /// return `ERESTARTNOHAND`, which ran the call again with its original
1827    /// arguments and so read the deadline again (round-10 finding Medium 4 on
1828    /// https://github.com/rrnewton/hermit/pull/3361).
1829    fn kernel_restart_errno(&self) -> Errno {
1830        if self.restart_keeps_deadline() {
1831            Errno::ERESTART_RESTARTBLOCK
1832        } else if self.timeout().is_some() {
1833            Errno::ERESTARTNOHAND
1834        } else {
1835            Errno::ERESTARTSYS
1836        }
1837    }
1838
1839    /// Every timed wait: `FUTEX_WAIT`'s relative timeout and `FUTEX_WAIT_BITSET`'s
1840    /// absolute deadline both become the absolute deadline Linux's restart keeps.
1841    fn restart_keeps_deadline(&self) -> bool {
1842        matches!(
1843            self.futex_op() & libc::FUTEX_CMD_MASK,
1844            libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET
1845        ) && self.timeout().is_some()
1846    }
1847}
1848
1849impl TimeoutableSyscall for reverie::syscalls::Futex {
1850    fn timeout_return_val(&self) -> Result<i64, Errno> {
1851        Err(Errno::ETIMEDOUT)
1852    }
1853}
1854
1855#[async_trait]
1856impl NonblockableSyscall for reverie::syscalls::RtSigtimedwait {
1857    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1858        self,
1859        guest: &mut G,
1860    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1861        // This is a bit more complicated because we need a new timespec to point to in
1862        // the guest memory.
1863        let (tp, guard) = zero_timespec(guest).await;
1864        (self.with_timeout(Some(tp)), Some(guard))
1865    }
1866
1867    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1868        res == Err(Errno::EAGAIN)
1869    }
1870
1871    fn signal_interrupt_errno(&self) -> Errno {
1872        Errno::EINTR
1873    }
1874
1875    /// Signals in the wait's own set are accepted by it, not interrupting. A set
1876    /// that cannot be read counts as empty, which nothing observes: the wait's
1877    /// first probe runs before any pending signal is considered
1878    /// (`KernelSignalWait::inject_first_probe`) and fails with `EFAULT`, as Linux
1879    /// fails the call when it cannot copy the set.
1880    fn signals_consumed_by_wait<M: MemoryAccess>(&self, memory: &M) -> KernelSigset {
1881        self.set()
1882            .and_then(|set| memory.read_value(set.cast::<KernelSigset>()).ok())
1883            .unwrap_or(0)
1884    }
1885}
1886
1887impl TimeoutableSyscall for reverie::syscalls::RtSigtimedwait {
1888    fn timeout_return_val(&self) -> Result<i64, Errno> {
1889        Err(Errno::EAGAIN)
1890    }
1891}
1892
1893/// While the read syscall is quite general, this nonblocking capacity is used
1894/// ONLY for sockets and pipes.
1895#[async_trait]
1896impl NonblockableSyscall for reverie::syscalls::Read {
1897    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1898        self,
1899        guest: &mut G,
1900    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1901        network_comm_syscall(self, guest)
1902    }
1903
1904    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1905        // A return value of Ok(0) indicates end of file.
1906        // Note that we've ruled out 0-count reads before this point.
1907        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
1908    }
1909}
1910
1911/// While the read syscall is quite general, this nonblocking capacity is used
1912/// ONLY for sockets and pipes.
1913#[async_trait]
1914impl NonblockableSyscall for reverie::syscalls::Write {
1915    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1916        self,
1917        guest: &mut G,
1918    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1919        network_comm_syscall(self, guest)
1920    }
1921
1922    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1923        // A return value of Ok(0) indicates end of file.
1924        // Note that we've ruled out 0-count reads before this point.
1925        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
1926    }
1927}
1928
1929// AUTONOMOUS-BOT-IMPLEMENTED
1930// TODO-HUMAN-REVIEW(#794)
1931/// Vectored reads have the same blocking behavior as scalar reads on pipes and sockets.
1932#[async_trait]
1933impl NonblockableSyscall for reverie::syscalls::Readv {
1934    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1935        self,
1936        guest: &mut G,
1937    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1938        network_comm_syscall(self, guest)
1939    }
1940
1941    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1942        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
1943    }
1944}
1945
1946// AUTONOMOUS-BOT-IMPLEMENTED
1947// TODO-HUMAN-REVIEW(#547)
1948/// Vectored writes have the same blocking behavior as scalar writes on pipes and sockets.
1949#[async_trait]
1950impl NonblockableSyscall for reverie::syscalls::Writev {
1951    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1952        self,
1953        guest: &mut G,
1954    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1955        network_comm_syscall(self, guest)
1956    }
1957
1958    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1959        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
1960    }
1961}
1962
1963/// A common helper shared among several network syscalls.
1964/// We can't actually CONVERT these syscalls into nonblocking, but we can assert that they are by
1965/// checking the status of their file descriptor.
1966fn network_comm_syscall<T: RecordOrReplay, G: Guest<Detcore<T>>, C: SyscallInfo + Into<Syscall>>(
1967    call: C,
1968    guest: &mut G,
1969) -> (C, Option<<G::Stack as Stack>::StackGuard>) {
1970    // Already nonblocking because we've assured the socket is.
1971    let fd = get_fd(call.into()).unwrap_or_else(|| {
1972        panic!(
1973            "network_comm_syscall called on invalid syscall / unknown fd: {}",
1974            call.name()
1975        );
1976    });
1977    guest
1978        .thread_state()
1979        .with_detfd(fd, |detfd| {
1980            assert!(
1981                detfd.physically_nonblocking(),
1982                "expecting sockets/pipes to be physically nonblocking"
1983            );
1984        })
1985        .unwrap();
1986    (call, None)
1987}
1988
1989#[async_trait]
1990impl NonblockableSyscall for reverie::syscalls::Accept4 {
1991    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1992        self,
1993        guest: &mut G,
1994    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
1995        network_comm_syscall(self, guest)
1996    }
1997
1998    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
1999        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2000    }
2001}
2002
2003impl TimeoutableSyscall for reverie::syscalls::Accept4 {
2004    fn timeout_return_val(&self) -> Result<i64, Errno> {
2005        Ok(0)
2006    }
2007}
2008
2009#[async_trait]
2010impl NonblockableSyscall for reverie::syscalls::Recvfrom {
2011    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2012        self,
2013        guest: &mut G,
2014    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2015        network_comm_syscall(self, guest)
2016    }
2017
2018    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2019        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2020    }
2021}
2022
2023#[async_trait]
2024impl NonblockableSyscall for reverie::syscalls::Recvmsg {
2025    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2026        self,
2027        guest: &mut G,
2028    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2029        network_comm_syscall(self, guest)
2030    }
2031
2032    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2033        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2034    }
2035}
2036
2037#[async_trait]
2038impl NonblockableSyscall for reverie::syscalls::Recvmmsg {
2039    // This system call has a timeout argument, but we ignore it because the underlying
2040    // socket is nonblocking anyway (in runs where we call this).
2041    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2042        self,
2043        guest: &mut G,
2044    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2045        network_comm_syscall(self, guest)
2046    }
2047
2048    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2049        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2050    }
2051}
2052
2053#[async_trait]
2054impl NonblockableSyscall for reverie::syscalls::Sendto {
2055    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2056        self,
2057        guest: &mut G,
2058    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2059        network_comm_syscall(self, guest)
2060    }
2061
2062    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2063        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2064    }
2065}
2066
2067#[async_trait]
2068impl NonblockableSyscall for reverie::syscalls::Sendmmsg {
2069    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2070        self,
2071        guest: &mut G,
2072    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2073        network_comm_syscall(self, guest)
2074    }
2075
2076    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2077        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2078    }
2079}
2080
2081#[async_trait]
2082impl NonblockableSyscall for reverie::syscalls::Sendmsg {
2083    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2084        self,
2085        guest: &mut G,
2086    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2087        network_comm_syscall(self, guest)
2088    }
2089
2090    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2091        res == Err(Errno::EAGAIN) || res == Err(Errno::EWOULDBLOCK)
2092    }
2093}
2094
2095#[async_trait]
2096impl NonblockableSyscall for reverie::syscalls::Connect {
2097    async fn into_nonblocking<T: RecordOrReplay, G: Guest<Detcore<T>>>(
2098        self,
2099        guest: &mut G,
2100    ) -> (Self, Option<<G::Stack as Stack>::StackGuard>) {
2101        network_comm_syscall(self, guest)
2102    }
2103
2104    fn syscall_would_have_blocked(&self, res: Result<i64, Errno>) -> bool {
2105        res == Err(Errno::EAGAIN)
2106            || res == Err(Errno::EWOULDBLOCK)
2107            || res == Err(Errno::EINPROGRESS)
2108            || res == Err(Errno::EALREADY)
2109    }
2110
2111    fn normalize_nonblocking_result(
2112        &self,
2113        res: Result<i64, Errno>,
2114        retried: bool,
2115    ) -> Result<i64, Errno> {
2116        match (retried, res) {
2117            (true, Err(Errno::EISCONN)) => Ok(0),
2118            (_, res) => res,
2119        }
2120    }
2121}
2122
2123/// Transform a syscall to nonblocking, then retry it until it returns a successful result.
2124/// Retry a nonblockizable syscall (e.g. a pipe/socket read or write) until it succeeds.
2125///
2126/// `subtool` selects how each poll iteration executes the underlying syscall. Pass
2127/// `Some(detcore)` in record/replay mode for a container-INTERNAL fd (currently pipes):
2128/// each iteration is then routed through `Detcore::record_or_replay`, so the read's
2129/// bytes (and every intervening `EAGAIN`) are captured in the recording and reproduced
2130/// verbatim on replay. Without this, an internal-pipe read on the InternalIOPolling path
2131/// bypasses the recorder and replay reads live from a pipe whose cross-process writer
2132/// schedule is not reproduced -- the reader sees EOF instead of the recorded data and
2133/// replay desyncs. Pass `None` for plain `hermit run` (no recording) or for external fds.
2134pub async fn retry_nonblocking_syscall<T, G, C>(
2135    guest: &mut G,
2136    call: C,
2137    rsrc: Resources,
2138    subtool: Option<&Detcore<T>>,
2139) -> Result<i64, Error>
2140where
2141    C: NonblockableSyscall + Into<Syscall>,
2142    T: RecordOrReplay,
2143    G: Guest<Detcore<T>>,
2144{
2145    // Bogus 99 return value is dead code below:
2146    retry_nonblocking_syscall_helper(guest, call, rsrc, None, subtool).await
2147}
2148
2149/// What a wait that ended with `ERESTART_RESTARTBLOCK` keeps for the
2150/// `restart_syscall` that Linux runs next when no handler runs
2151/// (`NonblockableSyscall::restart_keeps_deadline`). Linux keeps the call and its
2152/// absolute deadline in the thread's restart block (`do_restart_poll`,
2153/// `futex_wait_restart`). Detcore emulates the wait, so the kernel's restart block
2154/// does not describe it, and Detcore keeps its own
2155/// (https://github.com/rrnewton/hermit/issues/3358).
2156///
2157/// The record lives until the thread's next syscall, which takes it
2158/// (`Detcore::handle_syscall_event`). Other first syscalls, sigreturn and exec
2159/// discard the record; separate threads and newly initialized children have
2160/// independent records. A caught handler does not discard it: Linux resets its
2161/// restart block at sigreturn (`restore_sigcontext`), not when it sets up the
2162/// handler, so a handler whose first syscall is `restart_syscall` resumes the
2163/// interrupted wait with the copied arguments and deadline. Detcore does the
2164/// same when that call stops at the interrupted call's address, as it does
2165/// through libc's `syscall()` (the `restartfirst` mode of the
2166/// `external_signal_interrupt` guest). Linux also keeps its restart block across
2167/// the handler's other syscalls and resumes it from any address; Detcore does
2168/// not, so a `restart_syscall` after another syscall or at another address takes
2169/// the unsupported-syscall policy.
2170#[derive(Clone, Copy, Debug, Eq, PartialEq)]
2171pub(crate) struct RestartBlock {
2172    /// The instruction pointer at the interrupted call's syscall stop: the address
2173    /// after its `syscall` instruction. The kernel's restart moves the instruction
2174    /// pointer back onto that instruction with `restart_syscall` in `rax`, so the
2175    /// restart stops at the same address.
2176    pub(crate) rip: u64,
2177    /// The wait's absolute deadline.
2178    pub(crate) deadline: Option<LogicalTime>,
2179    /// The interrupted call.
2180    pub(crate) call: RestartCall,
2181}
2182
2183/// A call whose restart keeps its deadline.
2184#[derive(Clone, Copy, Debug, Eq, PartialEq)]
2185pub(crate) enum RestartCall {
2186    Poll(syscalls::Poll),
2187    Futex(syscalls::Futex),
2188    /// A relative `nanosleep` or `clock_nanosleep` that ended for a claimed
2189    /// `SIGCHLD` (`syscalls::signal::SleepSignal::Claimed`).
2190    Nanosleep(reverie::syscalls::family::NanosleepFamily),
2191}
2192
2193impl RestartBlock {
2194    /// The record, if a `restart_syscall` that stopped at `rip` is the kernel's
2195    /// restart of the interrupted call. At any other address the guest made the
2196    /// call itself.
2197    pub(crate) fn resumed_at(self, rip: u64) -> Option<Self> {
2198        (self.rip == rip).then_some(self)
2199    }
2200}
2201
2202/// Keeps `deadline` for the kernel's restart of `call` when the wait ended with
2203/// `ERESTART_RESTARTBLOCK` (`RestartBlock`).
2204pub(crate) async fn keep_restart_block<T, G>(
2205    guest: &mut G,
2206    result: &Result<i64, Error>,
2207    call: RestartCall,
2208    deadline: Option<LogicalTime>,
2209) where
2210    T: RecordOrReplay,
2211    G: Guest<Detcore<T>>,
2212{
2213    if matches!(result, Err(Error::Errno(errno)) if *errno == Errno::ERESTART_RESTARTBLOCK) {
2214        let rip = guest.regs().await.rip;
2215        let block = RestartBlock {
2216            rip,
2217            deadline,
2218            call,
2219        };
2220        tracing::trace!(
2221            "[tid {}] the wait keeps {:?} for its restart",
2222            guest.tid(),
2223            block
2224        );
2225        guest.thread_state_mut().restart_block = Some(block);
2226    }
2227}
2228
2229/// The restart code that ends a wait for a signal the backend holds and delivers
2230/// when the guest resumes. The backend passes a held signal on without reporting it
2231/// to the tool when the call returns `ERESTART_RESTARTBLOCK`, so for any signal but
2232/// `SIGSTOP`, which it never reports, the wait returns `ERESTARTNOHAND` instead. A
2233/// handler turns either code into `EINTR`, and a signal that kills the process
2234/// leaves no restart. The difference is a stop, which `SIGSTOP` alone can be here:
2235/// a default job-control stop does not end a wait whose restart keeps its deadline
2236/// (`KernelSignalState::interrupting_wait`).
2237///
2238/// A claimed relative `nanosleep` makes the opposite choice on purpose
2239/// (`syscalls::time`, `RestartCall::Nanosleep`): it returns
2240/// `ERESTART_RESTARTBLOCK`, so the held `SIGCHLD` is passed on unreported, and
2241/// the kernel's `restart_syscall` alone says no handler ran
2242/// (https://github.com/rrnewton/hermit/issues/4346).
2243fn held_signal_restart_errno(restart_errno: Errno, signal: i32) -> Errno {
2244    if restart_errno == Errno::ERESTART_RESTARTBLOCK && signal != libc::SIGSTOP {
2245        Errno::ERESTARTNOHAND
2246    } else {
2247        restart_errno
2248    }
2249}
2250
2251/// The deadline a polling request carries so the scheduler can restore a
2252/// backed-off poller once committed virtual time passes it
2253/// (`Resources::poll_deadline`, <https://github.com/rrnewton/hermit/issues/3952>).
2254/// `None` under record/replay, whose schedule must not change.
2255pub(crate) fn poll_deadline_for<T, G>(
2256    guest: &G,
2257    deadline: Option<LogicalTime>,
2258) -> Option<LogicalTime>
2259where
2260    T: RecordOrReplay,
2261    G: Guest<Detcore<T>>,
2262{
2263    if guest.config().recordreplay_modes {
2264        None
2265    } else {
2266        deadline
2267    }
2268}
2269
2270/// Retry a non-blocking syscall until it succeeds. Set the timeout to zero for the actual
2271/// syscalls (retries), while monitoring the clock to see if/when the logical timeout
2272/// should trigger.  Timeout is passed as an ABSOLUTE TIME (not duration).
2273pub async fn retry_nonblocking_syscall_with_timeout<T, G, C>(
2274    guest: &mut G,
2275    call: C,
2276    rsrc: Resources,
2277    // Logical timeout:
2278    maybe_timeout: Option<LogicalTime>,
2279) -> Result<i64, Error>
2280where
2281    C: NonblockableSyscall + TimeoutableSyscall + Into<Syscall>,
2282    T: RecordOrReplay,
2283    G: Guest<Detcore<T>>,
2284{
2285    let maybe_tup = maybe_timeout.map(|t| (t, call.timeout_return_val()));
2286    if guest
2287        .config()
2288        .backend
2289        .supports_blocked_wait_signal_interruption
2290    {
2291        return retry_blocking_wait_with_kernel_signal_state(guest, call, rsrc, maybe_tup).await;
2292    }
2293    // poll/epoll_wait/futex/rt_sigtimedwait keep their existing execution (raw
2294    // inject_with_retry): their record/replay handling is out of scope for the internal
2295    // pipe data-ordering fix, and their fds are not necessarily internal pipes.
2296    retry_nonblocking_syscall_helper(guest, call, rsrc, maybe_tup, None).await
2297}
2298
2299/// The task whose kernel signal state the scheduler may read to decide which
2300/// signal ends an internal IO poll: the guest thread itself where guest thread
2301/// IDs name host tasks, and `None` elsewhere (KVM), where
2302/// `/proc/<pid>/task/<tid>` would describe an unrelated host task.
2303pub(crate) fn guest_signal_state_task<T, G>(guest: &G) -> Option<(i32, i32)>
2304where
2305    T: RecordOrReplay,
2306    G: Guest<Detcore<T>>,
2307{
2308    crate::procfs_inode::guest_tids_name_host_tasks(&guest.config().backend, None)
2309        .then(|| (guest.pid().as_raw(), guest.tid().as_raw()))
2310}
2311
2312/// Whether a signal that woke a poll would be delivered to this thread now,
2313/// read from the backend's own state of the thread: its current mask (the
2314/// old set of a query-only `rt_sigprocmask`) and each signal's disposition
2315/// (`wait_signal_disposition`). A blocked or ignored signal, or one whose
2316/// default action ignores it, does not.
2317async fn own_disposition_interrupts<T, G>(
2318    guest: &mut G,
2319    status: ResumeStatus,
2320    mask_addr: AddrMut<'_, KernelSigset>,
2321    action_addr: AddrMut<'_, KernelSigaction>,
2322) -> Result<bool, Error>
2323where
2324    T: RecordOrReplay,
2325    G: Guest<Detcore<T>>,
2326{
2327    let query = syscalls::RtSigprocmask::new()
2328        .with_how(libc::SIG_BLOCK)
2329        .with_set(None)
2330        .with_oldset(Some(mask_addr.cast()))
2331        .with_sigsetsize(KERNEL_SIGSET_SIZE);
2332    guest.inject_with_retry(query).await?;
2333    let mask: KernelSigset = guest.memory().read_value(mask_addr)?;
2334    Ok(
2335        wait_signal_disposition(guest, status, &mask, action_addr, true)
2336            .await?
2337            .is_some(),
2338    )
2339}
2340
2341// Private helper.
2342async fn retry_nonblocking_syscall_helper<T, G, C>(
2343    guest: &mut G,
2344    call0: C,
2345    rsrc: Resources,
2346    maybe_timeout: Option<(LogicalTime, Result<i64, Errno>)>,
2347    subtool: Option<&Detcore<T>>,
2348) -> Result<i64, Error>
2349where
2350    C: NonblockableSyscall + Into<Syscall>,
2351    T: RecordOrReplay,
2352    G: Guest<Detcore<T>>,
2353{
2354    // The signals the wait takes from the queue (rt_sigtimedwait's set).
2355    let consumed = call0.signals_consumed_by_wait(&guest.memory());
2356    // The stack-allocated memory here needs to live across the loop, which means
2357    // surviving multiple syscall injections:
2358    let (mut call, mut maybe_stackguard) = call0.into_nonblocking(guest).await;
2359    let mut rsrc = rsrc.clone();
2360    rsrc.poll_deadline = poll_deadline_for(guest, maybe_timeout.map(|(deadline, _)| deadline));
2361    // A restartable call parked in internal IO polling, such as a `read` of an
2362    // empty pipe, is interrupted by a signal another task sends, as a parked
2363    // pipe write is (`pipe_writev_resources`). The marker lets the scheduler
2364    // record the signal for it (`Scheduler::notify_signal_pending`) and answer
2365    // its next turn `Signaled`; the call then returns `ERESTARTSYS`, and the
2366    // kernel applies the guest's disposition when it resumes: a handler runs
2367    // and the call fails with `EINTR` or restarts under `SA_RESTART`. Without
2368    // it, the poll never saw the signal and waited forever
2369    // (<https://github.com/rrnewton/hermit/issues/4187>).
2370    if rsrc.signal_interrupt_errno().is_none()
2371        && rsrc.resources.len() == 1
2372        && rsrc.resources.contains_key(&ResourceID::InternalIOPolling)
2373        && call.signal_interrupt_errno() == Errno::ERESTARTSYS
2374    {
2375        rsrc.set_signal_interrupt_errno(Errno::ERESTARTSYS);
2376        // Where guest thread IDs are not host tasks (KVM) the scheduler keeps
2377        // every signal: the call has made no progress when it returns
2378        // ERESTARTSYS, and the backend restarts it unless a signal it would
2379        // deliver is pending, so a blocked or ignored signal leaves it waiting.
2380        rsrc.signal_state_task = guest_signal_state_task(guest);
2381    }
2382    let checks_at_turn = rsrc.signal_interrupt_errno() == Some(Errno::ERESTARTSYS.into_raw())
2383        && decides_interruption_at_turn(guest, rsrc.signal_state_task);
2384    // Where the turn decides, the call owns the guest's mask while it blocks
2385    // every blockable signal (`KernelSignalWait::block_in_place`), from the
2386    // first turn that finds a pending signal a private injection could take
2387    // until the call returns: two such signals once stopped the probe and
2388    // its retry in turn, and the backend's single held slot kept only the
2389    // second, so one handler never ran (Claude review of the R2b-2 design,
2390    // F1; https://github.com/rrnewton/hermit/issues/4273, stage 2).
2391    let mut turn_wait = checks_at_turn
2392        .then(|| KernelSignalWait::new(guest, 0, false, call.signal_interrupt_errno()));
2393    let mut published = PublishedWaitMask::default();
2394
2395    let result: Result<i64, Error> = loop {
2396        let resumed = match call.into() {
2397            Syscall::Read(read) if maybe_timeout.is_none() && maybe_stackguard.is_none() => {
2398                crate::tool_global::polled_read_request(guest, read, rsrc.clone()).await
2399            }
2400            _ => resource_request(guest, rsrc.clone()).await,
2401        };
2402        // The turn's signals, read before its first injection
2403        // (`read_turn_signals`): the timerfd publication and the real-time
2404        // action below may inject, and a pending copy could stop that
2405        // injection and move into the backend's held slot. Every turn reads,
2406        // the first included, since a signal sent before the poll filed its
2407        // first request was admitted by no drain
2408        // (https://github.com/rrnewton/hermit/issues/4273). A backend's own
2409        // observation of a signal (`Signaled(None)`) is trusted as it is: that
2410        // signal has already left the kernel's queue.
2411        // Once the call blocks, the turn decides under the guest's own mask,
2412        // which the call owns, never under the full one now installed (Codex
2413        // review of the R2b-2 design rev3, P2-1).
2414        let turn = if checks_at_turn && !matches!(resumed, ResumeStatus::Signaled(None)) {
2415            match turn_signals_with_block(
2416                guest,
2417                &mut turn_wait,
2418                true,
2419                committed_signals(&resumed),
2420                rsrc.private_sigchld_decides,
2421                &mut published,
2422            )
2423            .await
2424            {
2425                Ok(turn) => Some(turn),
2426                Err(error) => break Err(error),
2427            }
2428        } else {
2429            None
2430        };
2431        // A virtual timerfd this probe may observe is readable on the host
2432        // exactly when its virtual deadline has passed by this turn
2433        // (`crate::syscalls::timerfd`); its next deadline restores this
2434        // poller if it backs off.
2435        // Publishing may take the scratch stack, which the nonblocking form
2436        // holds; release it first and convert again after.
2437        let reconvert =
2438            maybe_stackguard.is_some() && crate::syscalls::timerfd::may_publish(guest, call.into());
2439        if reconvert {
2440            maybe_stackguard = None;
2441        }
2442        rsrc.poll_deadline = crate::syscalls::timerfd::publish_before_probe(
2443            guest,
2444            call.into(),
2445            maybe_timeout.map(|(deadline, _)| deadline),
2446        )
2447        .await;
2448        if reconvert {
2449            (call, maybe_stackguard) = call0.into_nonblocking(guest).await;
2450        }
2451        // A signal ends the call only if it would still block, as Linux
2452        // checks for a pending signal only when the call must wait: a byte
2453        // written, or the last writer closed, before the signal is read
2454        // first. The probe below goes through the record/replay path like
2455        // every attempt (Codex review of
2456        // https://github.com/rrnewton/hermit/pull/4198).
2457        // This call transfers nothing until it completes, so only a copy still
2458        // pending ends it (`TurnSignals::ends`).
2459        let signaled = match turn {
2460            Some(turn) => turn.ends(false),
2461            None => matches!(resumed, ResumeStatus::Signaled(_)),
2462        };
2463        // A pending real-time timer expiration in the set this wait takes
2464        // (https://github.com/rrnewton/hermit/issues/4089).
2465        let pending = pending_real_time_among(guest, consumed).await;
2466        act_on_pending_real_time(guest, pending, consumed, 0).await;
2467        // Route through the record/replay subtool for internal pipes so each poll (an
2468        // EAGAIN, or the final data-bearing read) becomes one recorded event that replay
2469        // reproduces deterministically; otherwise execute the syscall directly.
2470        let res = match subtool {
2471            Some(detcore) => {
2472                detcore
2473                    .record_or_replay_preserving_tool_errors(guest, call)
2474                    .await
2475            }
2476            None => guest.inject_with_retry(call).await.map_err(Error::from),
2477        };
2478        // Under record and replay the attempt is a plain injection, which the
2479        // signal that woke this call, still pending, stops before it runs
2480        // (ERESTARTSYS, not run): the call then returns that restart errno,
2481        // as on main, though a byte, end of file or room may have been ready.
2482        // Making the attempt again would replace the held signal with any
2483        // other pending one (https://github.com/rrnewton/reverie/issues/1012),
2484        // and record and replay could not agree on when it is safe.
2485        let syscall_result = match res {
2486            Ok(value) => Ok(value),
2487            Err(Error::Errno(error)) => Err(error),
2488            Err(error) => break Err(error),
2489        };
2490        if signaled && call.syscall_would_have_blocked(syscall_result) {
2491            let errno = call.signal_interrupt_errno();
2492            tracing::trace!(
2493                "retry_nonblocking_syscall: interrupted by signal while {} would block: {:?}",
2494                call.display(&guest.memory()),
2495                errno
2496            );
2497            break Err(errno.into());
2498        }
2499        if call.syscall_would_have_blocked(syscall_result) {
2500            rsrc.poll_attempt += 1;
2501            if let Some((timeout, timeout_result)) = maybe_timeout {
2502                let new_time = thread_observe_time(guest).await;
2503                if new_time >= timeout {
2504                    tracing::trace!(
2505                        "Timing out syscall after #{} retries: {}",
2506                        rsrc.poll_attempt - 1,
2507                        call.display(&guest.memory())
2508                    );
2509                    break timeout_result.map_err(|e| e.into());
2510                } else {
2511                    tracing::trace!(
2512                        "Retry #{} for syscall due to result {:?}, {} from timeout: {}",
2513                        rsrc.poll_attempt,
2514                        syscall_result,
2515                        timeout - new_time,
2516                        call.display(&guest.memory())
2517                    );
2518                    record_retry_event(guest, call).await;
2519                }
2520            } else {
2521                tracing::trace!(
2522                    "Retry #{} for syscall due to result {:?}: {}",
2523                    rsrc.poll_attempt,
2524                    syscall_result,
2525                    call.display(&guest.memory())
2526                );
2527                record_retry_event(guest, call).await;
2528            }
2529        } else {
2530            let res = call
2531                .normalize_nonblocking_result(syscall_result, rsrc.poll_attempt > 0)
2532                .map_err(|e| e.into());
2533            tracing::trace!(
2534                "retry_nonblocking_syscall: syscall completed after {} retries: {} = {:?}",
2535                rsrc.poll_attempt,
2536                call.display(&guest.memory()),
2537                res
2538            );
2539            break res;
2540        }
2541    };
2542
2543    // The single exit: the guest's mask goes back before the result is
2544    // returned. A mask `block_in_place` installed goes back through
2545    // `Guest::set_blocked_signals`, with no scratch memory, and only a
2546    // refusal falls back to an injected restoration (`KernelSignalWait::restore`).
2547    // A mask that cannot be put back ends the run before the guest resumes.
2548    match turn_wait {
2549        Some(mut wait) if wait.effective_mask().is_some() => {
2550            let restored = wait.restore(guest, None).await;
2551            publish_wait_mask(guest, None, &mut published).await;
2552            match result_after_restore(restored, result) {
2553                Ok(result) => refuse_held_signal_loss(guest, call0.number(), result).await,
2554                Err(error) => Err(error),
2555            }
2556        }
2557        _ => result,
2558    }
2559}
2560
2561/// Retry a blocking wait on a backend that decides signal interruption from the
2562/// kernel's signal state (`supports_blocked_wait_signal_interruption`).
2563///
2564/// A wait ends early only for a signal that would end it natively: one the guest
2565/// does not block and that is caught, or whose default action terminates or stops
2566/// the process (https://github.com/rrnewton/hermit/issues/3146). Blocked,
2567/// ignored, and default-ignored signals do not end it, and neither does a default
2568/// job-control stop when Linux's restart of the call keeps its deadline
2569/// (`NonblockableSyscall::restart_keeps_deadline`). Such a signal that stops one
2570/// of the wait's injections is absorbed, and the wait runs on. A stop that
2571/// `KernelSignalWait::inject_absorbing` cannot absorb ends the wait with a
2572/// transparent restart when the backend holds nothing whose loss matters, and
2573/// otherwise with a [`HeldSignalRefusal`], which `refuse_held_signal_loss`
2574/// turns into the unsupported-operation refusal once the guest's mask is back.
2575///
2576/// The first probe runs under the guest's own mask, and before the first check
2577/// for a pending signal (`KernelSignalWait::inject_first_probe`): Linux reports a
2578/// descriptor that is ready when the call begins, a queued event, and an
2579/// argument error before it looks at pending signals, so the probe's result
2580/// stands whenever the signal arrived. If it would block, every blockable signal
2581/// is blocked for the rest of the wait, so later probes cannot be stopped by one
2582/// and every signal that arrives stays pending in the kernel, where `/proc`
2583/// reports it. Each turn classifies the pending set against the guest's mask and
2584/// dispositions, and an interrupting signal ends the wait with the call's restart
2585/// errno (see `KernelSignalWait::interrupted_with_state`). The guest's mask is
2586/// restored before returning, so the signal is delivered as the call returns.
2587/// The signals a scheduler resume names (`ResumeStatus::Signaled`): signals the
2588/// scheduler committed to the thread at that point.
2589fn committed_signals(resumed: &ResumeStatus) -> KernelSigset {
2590    match resumed {
2591        ResumeStatus::Signaled(Some(signals)) => signals.iter().fold(0, |set, signal| {
2592            set | kernel_sigset_bit(signal.0 as libc::c_int)
2593        }),
2594        _ => 0,
2595    }
2596}
2597
2598/// What a restartable internal IO poll or a parked pipe write finds at a turn,
2599/// read from the thread's own state before the turn's first injection, while it
2600/// is still stopped at its request: every signal sent since is still in the
2601/// kernel's pending set, and none is yet in the backend's held slot. A copy
2602/// the turn's own injections later absorb is counted here
2603/// (<https://github.com/rrnewton/hermit/issues/4273>, R2b-1 rules 2-4).
2604#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
2605struct TurnSignals {
2606    /// The signals the turn's answer names (`committed_signals`) that the
2607    /// call's mask leaves unblocked: a kept send's wake, which Linux's
2608    /// `TIF_SIGPENDING` keeps in force until the call returns, whatever a later
2609    /// flush does. For `writev`, which the drain never filters, a real-time
2610    /// signal, outside the record of copies discarded at send, counts only if
2611    /// its disposition delivers it now (`NamedRealTime::ByDisposition`); for
2612    /// the generic poll and the scalar writer the drain's own disposition test
2613    /// has already decided it, at the wake (R2b-1 rules 1 and 2).
2614    named: KernelSigset,
2615    /// The kept copies pending now that would end the call: unblocked under the
2616    /// call's mask, caught or acting by default, not held (`SIGCHLD` and the
2617    /// host-timed signals, except one the scheduler committed:
2618    /// `futex_wait_held_after_wake`), and not discarded at send
2619    /// (`threads::without_discarded`).
2620    pending: KernelSigset,
2621}
2622
2623impl TurnSignals {
2624    /// Whether a call that would wait now ends. After progress (`progress`),
2625    /// Linux returns the bytes transferred on any wake, so a named wake or a
2626    /// pending copy ends the call. With none, Linux returns `-ERESTARTSYS`,
2627    /// which delivers a pending copy or restarts invisibly, so only a pending
2628    /// copy ends it; otherwise the call keeps polling, which the guest cannot
2629    /// tell from that restart (R2b-1 rule 3).
2630    fn ends(&self, progress: bool) -> bool {
2631        self.pending != 0 || (progress && self.named != 0)
2632    }
2633}
2634
2635/// [`TurnSignals`] for a call whose mask is `mask` (the kernel's, by default:
2636/// the generic poll and the scalar writer install none) and to which the
2637/// scheduler committed `committed` at this wake (`committed_signals`; none
2638/// before a turnless first attempt). A thread that is gone ends the call with
2639/// `ERESTARTNOINTR`, which nothing observes, and a live one whose state cannot
2640/// be read ends the run (`read_wait_signal_state`).
2641async fn read_turn_signals<T, G>(
2642    guest: &mut G,
2643    mask: Option<KernelSigset>,
2644    committed: KernelSigset,
2645    real_time: NamedRealTime,
2646) -> Result<TurnSignals, Error>
2647where
2648    T: RecordOrReplay,
2649    G: Guest<Detcore<T>>,
2650{
2651    Ok(
2652        read_turn_signals_and_state(guest, mask, committed, real_time)
2653            .await?
2654            .0,
2655    )
2656}
2657
2658/// `read_turn_signals`, also returning the thread's signal state that the
2659/// turn read.
2660async fn read_turn_signals_and_state<T, G>(
2661    guest: &mut G,
2662    mask: Option<KernelSigset>,
2663    committed: KernelSigset,
2664    real_time: NamedRealTime,
2665) -> Result<(TurnSignals, KernelSignalState), Error>
2666where
2667    T: RecordOrReplay,
2668    G: Guest<Detcore<T>>,
2669{
2670    let state = read_wait_signal_state(guest.pid(), guest.tid())?;
2671    let mask = mask.unwrap_or(state.blocked);
2672    let host_timed = host_timed_signals(guest).await;
2673    Ok((
2674        turn_signals_from_state(guest, &state, mask, host_timed, committed, real_time, 0).await,
2675        state,
2676    ))
2677}
2678
2679/// [`TurnSignals`] from the thread's state `state` read in this turn, with the
2680/// record of copies Linux discarded at send applied
2681/// (`threads::without_discarded`); `private` as for
2682/// `turn_signals_before_discard`.
2683async fn turn_signals_from_state<T, G>(
2684    guest: &mut G,
2685    state: &KernelSignalState,
2686    mask: KernelSigset,
2687    host_timed: KernelSigset,
2688    committed: KernelSigset,
2689    real_time: NamedRealTime,
2690    private: KernelSigset,
2691) -> TurnSignals
2692where
2693    T: RecordOrReplay,
2694    G: Guest<Detcore<T>>,
2695{
2696    let before =
2697        turn_signals_before_discard(state, mask, host_timed, committed, real_time, private);
2698    let pending =
2699        crate::syscalls::threads::without_discarded(guest, state, before.pending, committed).await;
2700    TurnSignals { pending, ..before }
2701}
2702
2703/// A restartable poll's turn on a pipe or a socket that decides at its turn:
2704/// read the thread's signal state before the turn's first injection, block
2705/// every blockable signal in place if one pending could stop that injection
2706/// and `may_block` (`KernelSignalWait::block_in_place`, stage 2 of
2707/// https://github.com/rrnewton/hermit/issues/4273), then decide the turn's
2708/// signals under the guest's own mask, which the call owns once it blocks.
2709///
2710/// A `SIGCHLD` a guest sent the thread, which the schedule recorded in its
2711/// private queue, ends the call where `private_decides`
2712/// (`Resources::private_sigchld_decides`), as on Linux (stage 3): it is
2713/// admitted only while the block holds (`saved_mask`), so no injection of
2714/// this turn can take it into the backend's single held slot, and only if
2715/// the read found it in the thread's own queue, from which only this stopped
2716/// thread can take it. Nothing runs between the read and the block. The
2717/// host-timed signals and the record come in one round trip, before any
2718/// injection (`host_timed_and_private_sigchld`).
2719async fn turn_signals_with_block<T, G>(
2720    guest: &mut G,
2721    wait: &mut Option<KernelSignalWait>,
2722    may_block: bool,
2723    committed: KernelSigset,
2724    private_decides: bool,
2725    published: &mut PublishedWaitMask,
2726) -> Result<TurnSignals, Error>
2727where
2728    T: RecordOrReplay,
2729    G: Guest<Detcore<T>>,
2730{
2731    let mask = wait.as_ref().and_then(KernelSignalWait::effective_mask);
2732    let state = read_wait_signal_state(guest.pid(), guest.tid())?;
2733    let (host_timed, recorded) = crate::tool_global::host_timed_and_private_sigchld(guest).await;
2734    let mut private = 0;
2735    if let Some(wait) = wait.as_mut() {
2736        // Block before the publication and the probe, so neither can be
2737        // stopped by a blockable signal, and every pending one stays in the
2738        // kernel's queue until the guest resumes.
2739        if may_block
2740            && wait.needs_block()
2741            && pending_could_stop_injection(&state)
2742            && wait.block_in_place(guest, host_timed).await?
2743        {
2744            publish_wait_mask(guest, wait.effective_mask(), published).await;
2745        }
2746        if private_decides
2747            && wait.saved_mask.is_some()
2748            && state.thread_pending & kernel_sigset_bit(libc::SIGCHLD) != 0
2749        {
2750            private = recorded;
2751        }
2752    }
2753    let mask = mask.unwrap_or(state.blocked);
2754    Ok(turn_signals_from_state(
2755        guest,
2756        &state,
2757        mask,
2758        host_timed,
2759        committed,
2760        NamedRealTime::Woken,
2761        private,
2762    )
2763    .await)
2764}
2765
2766/// Whether a private injection could be stopped by a signal pending in
2767/// `state`: one pending, on the thread's or the process's queue, that the
2768/// thread's current mask leaves unblocked and that a mask can block. Such a
2769/// stop moves the signal into the backend's single held slot, where a second
2770/// stop replaces it (https://github.com/rrnewton/hermit/issues/4273, stage 2).
2771fn pending_could_stop_injection(state: &KernelSignalState) -> bool {
2772    state.pending & !state.blocked & blocked_signal_mask() != 0
2773}
2774
2775/// [`TurnSignals`] from the thread's state (`state`), the call's mask (`mask`),
2776/// the host-timed signals (`host_timed`) and the scheduler's commitment
2777/// (`committed`), before the record of copies Linux discarded at send is
2778/// applied to `pending` (`threads::without_discarded`). The hold leaves out
2779/// `SIGCHLD` and every host-timed signal, except a signal the scheduler
2780/// committed that no host-timed source can post (`futex_wait_held_after_wake`),
2781/// and a recorded private `SIGCHLD` the turn admits (`private`).
2782fn turn_signals_before_discard(
2783    state: &KernelSignalState,
2784    mask: KernelSigset,
2785    host_timed: KernelSigset,
2786    committed: KernelSigset,
2787    real_time: NamedRealTime,
2788    private: KernelSigset,
2789) -> TurnSignals {
2790    use crate::scheduler::discarded_at_send::STANDARD_SIGNALS;
2791    // A `SIGCHLD` a guest sent this thread, which the schedule recorded in its
2792    // private queue, is not held where the turn admits it (`private`,
2793    // `turn_signals_with_block`).
2794    let held =
2795        crate::syscalls::threads::futex_wait_held_after_wake(host_timed, committed) & !private;
2796    let pending = state.pending_interrupting(mask, false) & !held;
2797    let counted = match real_time {
2798        NamedRealTime::Woken => !0,
2799        NamedRealTime::ByDisposition => {
2800            STANDARD_SIGNALS | (state.interrupting(mask) & !STANDARD_SIGNALS)
2801        }
2802    };
2803    let named = committed & !mask & counted;
2804    TurnSignals { named, pending }
2805}
2806
2807/// How a turn counts a real-time signal its answer names
2808/// ([`TurnSignals::named`]).
2809#[derive(Clone, Copy, Debug, PartialEq, Eq)]
2810enum NamedRealTime {
2811    /// As any named signal: the drain woke the call only for one whose
2812    /// disposition delivered it then, and Linux's wake stands after a later
2813    /// flush (the generic poll and the scalar writer).
2814    Woken,
2815    /// Only if its disposition delivers it now: the drain never filters
2816    /// `writev` (R2b-1 rule 2).
2817    ByDisposition,
2818}
2819
2820/// Whether a poll or a parked pipe write decides interruption at its own turn
2821/// (`signals_interrupting_poll`): where the record of copies Linux discarded
2822/// at send is kept (`discarded_at_send::records`, ptrace with sequentialized
2823/// threads) and the thread's state can be read (`task`, its
2824/// `Resources::signal_state_task`, which needs guest thread IDs that name host
2825/// tasks). Elsewhere the earlier decision stands: on KVM the backend restarts
2826/// the call unless it would deliver a signal, and its polled-read observation
2827/// (`Guest::polled_read_signal_site`) takes a caught signal before the turn,
2828/// where a `/proc` read could not see it (the Claude re-check of the R2b-1
2829/// design, R4-4).
2830fn decides_interruption_at_turn<T, G>(guest: &G, task: Option<(i32, i32)>) -> bool
2831where
2832    T: RecordOrReplay,
2833    G: Guest<Detcore<T>>,
2834{
2835    task.is_some() && crate::scheduler::discarded_at_send::records(guest.config())
2836}
2837
2838/// Install the private mask of a pipe `writev` that decides at its turn
2839/// (`decides_interruption_at_turn`) and goes on polling after its first
2840/// attempt, through `wait` (`KernelSignalWait::block`, scratch `cell`), and
2841/// publish the guest's own mask to the scheduler while it is installed
2842/// (`set_saved_guest_sigmask`). Returns the guest's own mask. A signal that
2843/// stops the installation is held as `inject_absorbing` holds one, a
2844/// host-timed one and a copy Linux discarded at send included
2845/// (`hold_until_return`), and one that would replace a
2846/// held signal whose loss matters ends the call: with the restart errno, as
2847/// `Error::Errno`, when the held one would end it natively, and otherwise with
2848/// a [`HeldSignalRefusal`], which the caller turns into the refusal once the
2849/// guest's mask is back (`refuse_held_signal_loss`; R2b-1 rule 5). A mask that
2850/// cannot be installed ends the call with `EFAULT`, as a failed
2851/// scratch-stack commit does.
2852async fn install_turn_mask<T, G>(
2853    guest: &mut G,
2854    wait: &mut KernelSignalWait,
2855    cell: AddrMut<'_, KernelSigset>,
2856) -> Result<KernelSigset, Error>
2857where
2858    T: RecordOrReplay,
2859    G: Guest<Detcore<T>>,
2860{
2861    // A copy Linux discarded at send that the kernel still holds (a traced
2862    // task's copy is queued whatever its disposition) is left out of the
2863    // turn's `pending` (`without_discarded`), so it must not end the call
2864    // here either: it is held until the call returns, where it is delivered
2865    // late (https://github.com/rrnewton/hermit/issues/3995), as the turn
2866    // decided (the Claude re-check of R2b-1, N1).
2867    let state = read_wait_signal_state(guest.pid(), guest.tid())?;
2868    let kept = crate::syscalls::threads::without_discarded(guest, &state, state.pending, 0).await;
2869    wait.hold_until_return(host_timed_signals(guest).await | (state.pending & !kept));
2870    wait.block(guest, Some(cell)).await?;
2871    let Some(mask) = wait.effective_mask() else {
2872        return Err(Errno::EFAULT.into());
2873    };
2874    crate::tool_global::set_saved_guest_sigmask(guest, Some(mask)).await;
2875    Ok(mask)
2876}
2877
2878/// The waiting thread's mask as last told to the scheduler
2879/// (`publish_wait_mask`). It is deliberately not `Copy`: a wait loop in an
2880/// `async move` block must reborrow it, or the block would publish into a
2881/// copy and the clear after the block would see nothing to clear.
2882#[derive(Debug, Default)]
2883pub(crate) struct PublishedWaitMask(Option<KernelSigset>);
2884
2885/// Tell the scheduler the waiting thread's effective mask
2886/// (`KernelSignalWait::effective_mask`, or `None` once the wait is over) if it
2887/// differs from `published`, the last one told. The scheduler reads it in
2888/// place of the thread's `SigBlk` (`set_saved_guest_sigmask`), for example to
2889/// decide whether a leader ignores an `ITIMER_REAL` expiry at generation
2890/// (https://github.com/rrnewton/hermit/issues/4139). Only under signal-target
2891/// modelling, the only configuration whose scheduler reads it for a wait.
2892pub(crate) async fn publish_wait_mask<T, G>(
2893    guest: &mut G,
2894    mask: Option<KernelSigset>,
2895    published: &mut PublishedWaitMask,
2896) where
2897    T: RecordOrReplay,
2898    G: Guest<Detcore<T>>,
2899{
2900    if mask == published.0
2901        || !detcore_model::bundled_signal_facts::models_signal_targets(guest.config())
2902    {
2903        return;
2904    }
2905    crate::tool_global::set_saved_guest_sigmask(guest, mask).await;
2906    published.0 = mask;
2907}
2908
2909async fn retry_blocking_wait_with_kernel_signal_state<T, G, C>(
2910    guest: &mut G,
2911    call0: C,
2912    rsrc: Resources,
2913    maybe_timeout: Option<(LogicalTime, Result<i64, Errno>)>,
2914) -> Result<i64, Error>
2915where
2916    C: NonblockableSyscall + Into<Syscall>,
2917    T: RecordOrReplay,
2918    G: Guest<Detcore<T>>,
2919{
2920    retry_blocking_wait_under_mask(guest, call0, rsrc, maybe_timeout, None)
2921        .await
2922        .0
2923}
2924
2925/// `retry_blocking_wait_with_kernel_signal_state` for a call that sleeps under
2926/// `wait_mask` instead of the guest's own mask, when it is set: the temporary
2927/// mask of an `epoll_pwait` (`KernelSignalWait::with_wait_mask`). `call0`
2928/// carries no mask, so its probes run under the guest's own mask until every
2929/// blockable signal is blocked, as for any other wait. Also returns whether the
2930/// signal that ended the wait must still be delivered under `wait_mask`: one
2931/// that only `wait_mask` lets in, pending in the kernel under the guest's own
2932/// mask once it is put back, which the caller delivers with
2933/// `inject_signal_delivery`, as a masked pselect6 does.
2934pub(crate) async fn retry_blocking_wait_under_mask<T, G, C>(
2935    guest: &mut G,
2936    call0: C,
2937    rsrc: Resources,
2938    maybe_timeout: Option<(LogicalTime, Result<i64, Errno>)>,
2939    wait_mask: Option<KernelSigset>,
2940) -> (Result<i64, Error>, bool)
2941where
2942    C: NonblockableSyscall + Into<Syscall>,
2943    T: RecordOrReplay,
2944    G: Guest<Detcore<T>>,
2945{
2946    let mut signals = KernelSignalWait::new(
2947        guest,
2948        call0.signals_consumed_by_wait(&guest.memory()),
2949        call0.restart_keeps_deadline(),
2950        call0.kernel_restart_errno(),
2951    )
2952    .with_deadline(maybe_timeout.is_some())
2953    .with_wait_mask(wait_mask);
2954    // Set when a signal that only `wait_mask` lets in ends the wait.
2955    let mut deliver_under_wait_mask = false;
2956    let mut published = PublishedWaitMask::default();
2957    publish_wait_mask(guest, signals.effective_mask(), &mut published).await;
2958    let mut rsrc = rsrc.clone();
2959    rsrc.poll_deadline = poll_deadline_for(guest, maybe_timeout.map(|(deadline, _)| deadline));
2960    let (mut call, mut guard) = call0.into_nonblocking(guest).await;
2961    let mut first_turn = true;
2962    // Set when only a signal the scheduler committed in this turn ends the
2963    // wait: the turn's probe runs first, and the wait ends with the restart
2964    // errno only if the call has nothing to report.
2965    let mut interrupt_after_probe;
2966
2967    let result = loop {
2968        interrupt_after_probe = false;
2969        // A scheduler `Signaled` answer only says a signal may be pending. The kernel's
2970        // state below decides whether it ends the wait.
2971        let resumed = resource_request(guest, rsrc.clone()).await;
2972        // Read in this turn, before any injection: another thread may have
2973        // armed a host-timed source since the last turn, and none can until
2974        // this turn ends. The same round trip gives the `SIGCHLD` a guest sent
2975        // this thread that the schedule recorded in its private queue, which
2976        // an injection of this turn (the timerfd publication below) could
2977        // otherwise take into the backend's single held slot (R2b-2 stage 3,
2978        // https://github.com/rrnewton/hermit/issues/4273).
2979        let (host_timed, recorded) =
2980            crate::tool_global::host_timed_and_private_sigchld(guest).await;
2981        signals.hold_until_return(host_timed);
2982        // A `SIGCHLD` the scheduler committed to this thread in this turn, sent
2983        // at a commit point (a child's child-exit timer, or a POSIX timer whose
2984        // signal is `SIGCHLD`), ends the wait, as on Linux
2985        // (https://github.com/rrnewton/hermit/issues/4005), and so does a
2986        // recorded private one: both are admitted (`KernelSignalWait::admit`).
2987        let committed = committed_signals(&resumed) & kernel_sigset_bit(libc::SIGCHLD);
2988        let private = match signals
2989            .admit_under_block(guest, committed, recorded, host_timed, &mut published)
2990            .await
2991        {
2992            Ok(private) => private,
2993            Err(error) => break Err(error),
2994        };
2995        signals.admit(committed, private);
2996        // As in `retry_nonblocking_syscall_helper`: virtual timerfds first.
2997        // As in `retry_nonblocking_syscall_helper`: release the nonblocking
2998        // form's scratch stack before publishing, and convert again after.
2999        let reconvert =
3000            guard.is_some() && crate::syscalls::timerfd::may_publish(guest, call.into());
3001        if reconvert {
3002            guard = None;
3003        }
3004        rsrc.poll_deadline = crate::syscalls::timerfd::publish_before_probe(
3005            guest,
3006            call.into(),
3007            maybe_timeout.map(|(deadline, _)| deadline),
3008        )
3009        .await;
3010        if reconvert {
3011            (call, guard) = call0.into_nonblocking(guest).await;
3012        }
3013        // A pending real-time timer expiration that this wait would consume or
3014        // be ended by (https://github.com/rrnewton/hermit/issues/4089).
3015        let pending = pending_real_time_among(guest, REAL_TIME_SIGNALS).await;
3016        if pending != 0 {
3017            match signals.observable_now() {
3018                Ok(observable) => act_on_pending_real_time(guest, pending, observable, 0).await,
3019                Err(error) => break Err(error),
3020            }
3021        }
3022        let first = std::mem::take(&mut first_turn);
3023        // Never `inject_with_retry`: see `KernelSignalWait`.
3024        let injected = if first {
3025            // The first probe runs before the check, so a source that was ready when
3026            // the call began, or an argument error, is reported as Linux reports it
3027            // whatever signal is pending (`inject_first_probe`).
3028            signals.inject_first_probe(guest, call).await
3029        } else {
3030            let state = match signals.interrupted_with_state() {
3031                Ok((false, state)) => state,
3032                // Linux takes a completion before it returns EINTR: a queued
3033                // signal of rt_sigtimedwait's set (`do_sigtimedwait` dequeues
3034                // first, and again after it sleeps), a ready descriptor of poll
3035                // or epoll_wait. A signal the scheduler committed in this turn
3036                // was sent at the same fixed point as any completion this turn
3037                // can see, so the completion wins, as on Linux (Codex review of
3038                // https://github.com/rrnewton/hermit/pull/4039).
3039                Ok((true, state)) if signals.interrupts_only_by_committed(&state) => {
3040                    interrupt_after_probe = true;
3041                    deliver_under_wait_mask = signals.interrupts_only_under_wait_mask(&state);
3042                    state
3043                }
3044                Ok((true, state)) => {
3045                    deliver_under_wait_mask = signals.interrupts_only_under_wait_mask(&state);
3046                    let errno = call0.kernel_restart_errno();
3047                    tracing::trace!(
3048                        "retry_nonblocking_syscall: pending signals interrupt {}: {:?}",
3049                        call.display(&guest.memory()),
3050                        errno
3051                    );
3052                    break Err(errno.into());
3053                }
3054                Err(error) => break Err(error),
3055            };
3056            signals.inject_absorbing_after(guest, call, state).await
3057        };
3058        let syscall_result = match injected {
3059            Ok(result) => result,
3060            Err(error) => {
3061                tracing::trace!(
3062                    "retry_nonblocking_syscall: a signal stop ends the wait in {}: {:?}",
3063                    call.display(&guest.memory()),
3064                    error
3065                );
3066                break Err(error);
3067            }
3068        };
3069        if !call.syscall_would_have_blocked(syscall_result) {
3070            let res = call
3071                .normalize_nonblocking_result(syscall_result, rsrc.poll_attempt > 0)
3072                .map_err(|e| e.into());
3073            tracing::trace!(
3074                "retry_nonblocking_syscall: syscall completed after {} retries: {} = {:?}",
3075                rsrc.poll_attempt,
3076                call.display(&guest.memory()),
3077                res
3078            );
3079            break res;
3080        }
3081        if interrupt_after_probe {
3082            let errno = call0.kernel_restart_errno();
3083            tracing::trace!(
3084                "retry_nonblocking_syscall: a committed signal interrupts {}: {:?}",
3085                call.display(&guest.memory()),
3086                errno
3087            );
3088            break Err(errno.into());
3089        }
3090        if first {
3091            // The first turn's check, after its probe found nothing to report.
3092            match signals.interrupted_with_state() {
3093                Ok((false, _)) => {}
3094                Ok((true, state)) => {
3095                    deliver_under_wait_mask = signals.interrupts_only_under_wait_mask(&state);
3096                    let errno = call0.kernel_restart_errno();
3097                    tracing::trace!(
3098                        "retry_nonblocking_syscall: pending signals interrupt {}: {:?}",
3099                        call.display(&guest.memory()),
3100                        errno
3101                    );
3102                    break Err(errno.into());
3103                }
3104                Err(error) => break Err(error),
3105            }
3106        }
3107        if signals.needs_block() {
3108            // Only one scratch-stack guard may be live, so release the probe's, block
3109            // signals from a fresh one, and rebuild the probe.
3110            guard = None;
3111            if let Err(error) = signals.block(guest, None).await {
3112                break Err(error);
3113            }
3114            publish_wait_mask(guest, signals.effective_mask(), &mut published).await;
3115            (call, guard) = call0.into_nonblocking(guest).await;
3116        }
3117        rsrc.poll_attempt += 1;
3118        if let Some((timeout, timeout_result)) = maybe_timeout {
3119            let new_time = thread_observe_time(guest).await;
3120            if new_time >= timeout {
3121                tracing::trace!(
3122                    "Timing out syscall after #{} retries: {}",
3123                    rsrc.poll_attempt - 1,
3124                    call.display(&guest.memory())
3125                );
3126                break timeout_result.map_err(|e| e.into());
3127            }
3128            tracing::trace!(
3129                "Retry #{} for syscall due to result {:?}, {} from timeout: {}",
3130                rsrc.poll_attempt,
3131                syscall_result,
3132                timeout - new_time,
3133                call.display(&guest.memory())
3134            );
3135        } else {
3136            tracing::trace!(
3137                "Retry #{} for syscall due to result {:?}: {}",
3138                rsrc.poll_attempt,
3139                syscall_result,
3140                call.display(&guest.memory())
3141            );
3142        }
3143        record_retry_event(guest, call).await;
3144    };
3145
3146    drop(guard);
3147    let restored = signals.restore(guest, None).await;
3148    publish_wait_mask(guest, None, &mut published).await;
3149    let result = match result_after_restore(restored, result) {
3150        Ok(result) => result,
3151        Err(error) => return (Err(error), false),
3152    };
3153    // A signal the backend holds is delivered as the guest resumes, under the
3154    // guest's own mask (https://github.com/rrnewton/reverie/issues/1011).
3155    let deliver = deliver_under_wait_mask && !signals.holds_signal() && result.is_err();
3156    (
3157        refuse_held_signal_loss(guest, call0.number(), result).await,
3158        deliver,
3159    )
3160}
3161
3162/// The policy of `Detcore::refuse_unserviceable_operation`, for a caller that
3163/// holds the guest but not the tool. `panic_on_unsupported_syscalls` is the
3164/// setting of that name: the tool's own copy in the method, the guest's
3165/// configuration in `refuse_held_signal_loss`.
3166pub(crate) async fn refuse_unserviceable_operation_with<T, G>(
3167    guest: &mut G,
3168    panic_on_unsupported_syscalls: bool,
3169    sysno: Sysno,
3170    fallback: Errno,
3171    reason: Option<&str>,
3172) -> Result<i64, Error>
3173where
3174    T: RecordOrReplay,
3175    G: Guest<Detcore<T>>,
3176{
3177    if !panic_on_unsupported_syscalls {
3178        return Err(fallback.into());
3179    }
3180    if guest.config().shutdown_on_unsupported_syscall {
3181        // Fail-closed policy: the operation is unserviceable and the config
3182        // forbids passing it through. Say why first: on an in-guest backend
3183        // the exit below ends only the guest process, and the launcher learns
3184        // the reason from the coordinator.
3185        let reason = match reason {
3186            Some(reason) => format!("{sysno}: {reason}"),
3187            None => format!(
3188                "{sysno} cannot be serviced on this backend (with \
3189                 --allow-unsupported-syscalls the guest would see {fallback})"
3190            ),
3191        };
3192        crate::tool_global::report_policy_refusal(guest, reason).await;
3193        crate::tool_global::unrecoverable_shutdown(
3194            guest,
3195            detcore_model::HERMIT_POLICY_REFUSAL_EXIT,
3196        )
3197        .await;
3198    }
3199    if guest.config().exit_on_unsupported_syscall {
3200        return Err(Error::Tool(anyhow::Error::new(
3201            crate::UnsupportedSyscallError(sysno),
3202        )));
3203    }
3204    panic!("unserviceable operation on syscall: {sysno:?}");
3205}
3206
3207/// Refuse the guest's `sysno` call when its wait ended with a
3208/// [`HeldSignalRefusal`], through the unsupported-operation policy
3209/// (`refuse_unserviceable_operation_with`): a fail-closed run, which ordinary
3210/// `hermit run` is, ends with the policy's exit, and a run started with
3211/// `--allow-unsupported-syscalls` gets `ERESTARTNOINTR`, the transparent
3212/// restart that such a wait returned before (round-10 High 1 on
3213/// https://github.com/rrnewton/hermit/pull/3361). The message names the call,
3214/// the signals and that pull request. Callers pass the wait's result after the
3215/// wait has put the guest's mask back. Every other result passes through.
3216///
3217/// Whether a wait meets such a stop can depend on host timing, as a signal
3218/// sent from outside the guest does, so a refusal can be host-timed: it
3219/// replaces a run that would have gone on to depend on that timing.
3220pub(crate) async fn refuse_held_signal_loss<T, G>(
3221    guest: &mut G,
3222    sysno: Sysno,
3223    result: Result<i64, Error>,
3224) -> Result<i64, Error>
3225where
3226    T: RecordOrReplay,
3227    G: Guest<Detcore<T>>,
3228{
3229    use std::io::Write as _;
3230    let refusal = match &result {
3231        Err(Error::Tool(error)) => match error.downcast_ref::<HeldSignalRefusal>() {
3232            Some(refusal) => HeldSignalRefusal {
3233                wait: Some(sysno),
3234                ..*refusal
3235            },
3236            None => return result,
3237        },
3238        _ => return result,
3239    };
3240    let panic_on_unsupported_syscalls = guest.config().panic_on_unsupported_syscalls;
3241    tracing::error!("[tid {}] {}", guest.tid(), refusal);
3242    if panic_on_unsupported_syscalls {
3243        // The run ends: report why even when logging is disabled or redirected,
3244        // as the refusal of a nonleader exec does.
3245        let _ = writeln!(crate::util::RetryingStderr, "{refusal}");
3246    }
3247    refuse_unserviceable_operation_with(
3248        guest,
3249        panic_on_unsupported_syscalls,
3250        sysno,
3251        Errno::ERESTARTNOINTR,
3252        None,
3253    )
3254    .await
3255}
3256
3257/// Signal handling for one blocking wait whose interruption is decided from the
3258/// kernel's signal state (`supports_blocked_wait_signal_interruption`).
3259///
3260/// A wait ends early only for a signal that would end it natively: one the guest
3261/// does not block and that is caught, or whose default action terminates or stops
3262/// the process (https://github.com/rrnewton/hermit/issues/3146). Blocked,
3263/// ignored, and default-ignored signals do not end it, and neither does a default
3264/// job-control stop when `defers_default_stops` is set
3265/// (`KernelSignalState::interrupting_wait`), apart from the stops that
3266/// `inject_absorbing` cannot absorb safely, which end it with a restart.
3267///
3268/// The first probe runs under the guest's own mask. If it would block, `block`
3269/// blocks every blockable signal for the rest of the wait, so later probes cannot
3270/// be stopped by one and every signal that arrives stays pending in the kernel,
3271/// where `/proc` reports it. `interrupted_with_state` classifies the pending set
3272/// against the guest's mask and dispositions each turn, and `restore` puts the
3273/// guest's mask back before the call returns, so a pending interrupting signal
3274/// is delivered as the call returns its restart errno.
3275///
3276/// Probes and the mask change go through `inject_absorbing`, never
3277/// `inject_with_retry`. A signal that stops the guest around an injection is
3278/// dequeued from the kernel and held by the backend in a single slot, so a blind
3279/// retry that is stopped again would replace it. `inject_absorbing` works out
3280/// from `/proc` which signal the backend holds and injects again only when that
3281/// signal would not end the wait natively. Before the mask is set, a signal
3282/// pending at the turn's `/proc` read that would end the wait is reported by
3283/// `interrupted_with_state`, and any other unblocked one stops the next
3284/// injection and is absorbed; a signal that arrives after the read can stop an
3285/// injection in a way that cannot be identified, and is held without ending the
3286/// wait, so the wait keeps its deadline and its checks, unless the backend held
3287/// a signal whose loss matters, which ends the wait with a
3288/// [`HeldSignalRefusal`] (`inject_absorbing`).
3289/// Afterwards only a signal that cannot be blocked can stop an injection. A stop
3290/// after a probe ran replaces its result, so a probe that consumed something (an
3291/// edge-triggered event, a dequeued signal) loses it; that remains a known gap.
3292///
3293/// No failure of this machinery reaches the guest as an errno the wait call
3294/// cannot return. A `/proc` read that fails for a thread that still exists, or a
3295/// guest mask that cannot be put back, ends the run with a
3296/// [`BlockedWaitSignalError`]; a thread that no longer exists gets
3297/// `ERESTARTNOINTR`, which nothing observes (`read_wait_signal_state`). If the
3298/// mask cannot be changed at all (no scratch room below the guest's stack
3299/// pointer, https://github.com/rrnewton/hermit/issues/3328), `block` leaves the
3300/// guest's own mask in place and every later probe runs under it, as the first
3301/// probe does.
3302/// The real-time signals, 32 to 64, as kernel sigset bits.
3303pub(crate) const REAL_TIME_SIGNALS: KernelSigset = !0 << 31;
3304
3305/// The signals a thread whose mask becomes `mask` lets the kernel take from
3306/// its queues: those `mask` does not block, split into the ones whose delivery
3307/// the guest observes and the ones Linux discards on delivery because their
3308/// disposition is `SIG_IGN`.
3309pub(crate) fn unblocked_by(
3310    state: &KernelSignalState,
3311    mask: KernelSigset,
3312) -> (KernelSigset, KernelSigset) {
3313    unblocked_by_ignored(state.ignored, mask)
3314}
3315
3316/// [`unblocked_by`] given only the thread's ignored set, from wherever it
3317/// comes (the kernel's `/proc` view or Detcore's copy).
3318pub(crate) fn unblocked_by_ignored(
3319    ignored: KernelSigset,
3320    mask: KernelSigset,
3321) -> (KernelSigset, KernelSigset) {
3322    let unblocked = !mask;
3323    (unblocked & !ignored, unblocked & ignored)
3324}
3325
3326/// The real-time timer expirations among `candidates` (a kernel sigset) that
3327/// are pending for the calling thread's process because every thread blocked
3328/// them when they expired (`Scheduler::pending_real_time_expirations`,
3329/// https://github.com/rrnewton/hermit/issues/4089). 0 without asking the
3330/// scheduler until one has been kept pending in this run
3331/// (`scheduler::real_time_expiration_kept_pending`), or when `candidates`
3332/// holds no real-time signal. Asked in the calling thread's turn.
3333pub(crate) async fn pending_real_time_among<T, G>(guest: &mut G, candidates: KernelSigset) -> u64
3334where
3335    T: RecordOrReplay,
3336    G: Guest<Detcore<T>>,
3337{
3338    let candidates = candidates & REAL_TIME_SIGNALS;
3339    if candidates == 0 || !crate::scheduler::real_time_expiration_kept_pending() {
3340        return 0;
3341    }
3342    let Some(detpid) = guest.thread_state().detpid else {
3343        return 0;
3344    };
3345    crate::tool_global::pending_real_time_expirations(guest, detpid).await & candidates
3346}
3347
3348/// Where a call lets the guest observe the signals in `observable` (deliver,
3349/// dequeue or report them), refuse the run by name if one of the `pending`
3350/// real-time timer expirations (`pending_real_time_among`) is among them, and
3351/// discard the pending ones in `discarded`, which Linux discards there.
3352pub(crate) async fn act_on_pending_real_time<T, G>(
3353    guest: &mut G,
3354    pending: KernelSigset,
3355    observable: KernelSigset,
3356    discarded: KernelSigset,
3357) where
3358    T: RecordOrReplay,
3359    G: Guest<Detcore<T>>,
3360{
3361    let observed = pending & observable;
3362    if observed != 0 {
3363        crate::scheduler::refuse_real_time_expiration(observed.trailing_zeros() as i32 + 1);
3364    }
3365    if pending & discarded != 0
3366        && let Some(detpid) = guest.thread_state().detpid
3367    {
3368        crate::tool_global::discard_pending_real_time_expirations(
3369            guest,
3370            detpid,
3371            pending & discarded,
3372        )
3373        .await;
3374    }
3375}
3376
3377/// For a call that runs under the temporary mask `mask`: refuse by name for a
3378/// pending real-time timer expiration the mask lets the kernel deliver, and
3379/// discard one it lets the kernel discard. Reads the thread's dispositions
3380/// only when one is pending.
3381pub(crate) async fn observe_under_mask<T, G>(guest: &mut G, mask: KernelSigset) -> Result<(), Error>
3382where
3383    T: RecordOrReplay,
3384    G: Guest<Detcore<T>>,
3385{
3386    let pending = pending_real_time_among(guest, !mask).await;
3387    if pending != 0 {
3388        let ignored = match crate::syscalls::signal_shadow::copied_dispositions(guest) {
3389            Some(copied) => copied.ignored,
3390            None => read_thread_wait_signal_state(guest.pid(), guest.tid())?.ignored,
3391        };
3392        let (observable, discarded) = unblocked_by_ignored(ignored, mask);
3393        act_on_pending_real_time(guest, pending, observable, discarded).await;
3394    }
3395    Ok(())
3396}
3397
3398pub(crate) struct KernelSignalWait {
3399    pid: reverie::Pid,
3400    tid: reverie::Pid,
3401    /// Signals the wait itself consumes (rt_sigtimedwait's set), which never
3402    /// interrupt it.
3403    consumed: KernelSigset,
3404    /// Whether a default job-control stop leaves the wait running, because Linux's
3405    /// restart of the call keeps its deadline
3406    /// (`NonblockableSyscall::restart_keeps_deadline`).
3407    defers_default_stops: bool,
3408    /// The errno that ends the wait for an interrupting signal: the restart code
3409    /// Linux uses for the call (`NonblockableSyscall::kernel_restart_errno`). A
3410    /// signal the backend holds turns `ERESTART_RESTARTBLOCK` into `ERESTARTNOHAND`
3411    /// (`held_signal_restart_errno`).
3412    restart_errno: Errno,
3413    /// Signals that never end the wait, even ones that would end it natively.
3414    /// They stay pending in the kernel, or held by the backend, and are
3415    /// delivered as the call returns, once the guest's mask is put back. In
3416    /// every wait but `select`'s and `pselect6`'s (`for_select`) this is
3417    /// `SIGCHLD`, whichever process sent it: the kernel also posts one for a
3418    /// child's exit, stop or continue at a moment set by host timing, and
3419    /// `/proc` shows no siginfo that would tell the two apart
3420    /// (https://github.com/rrnewton/hermit/issues/3146). The scheduler's own
3421    /// send of a `SIGCHLD` to this thread at a commit point lifts the hold for the
3422    /// turn whose resume names it (`admit`,
3423    /// https://github.com/rrnewton/hermit/issues/4005). The gated loop adds,
3424    /// in each of its turns, every signal a host-timed source armed by a guest
3425    /// can post to this process (`hold_until_return`).
3426    held_until_return: KernelSigset,
3427    /// Whether the wait has a finite deadline (`with_deadline`). Hermit cannot
3428    /// install the restart block with which Linux keeps the absolute deadline
3429    /// of a restarted `poll` or timed futex wait, and a restarted `ppoll`,
3430    /// `epoll_wait`, `epoll_pwait` or `rt_sigtimedwait` runs again with the
3431    /// guest's unchanged timeout. So a transparent restart would start the
3432    /// timeout again, and such a wait never ends with `ERESTARTNOINTR`
3433    /// (`inject_absorbing`).
3434    deadline: bool,
3435    /// The guest's own mask while the wait runs with every signal blocked.
3436    saved_mask: Option<KernelSigset>,
3437    /// `block` could not change the mask, so probes run under the guest's own.
3438    unblockable: bool,
3439    /// `saved_mask` was installed by `block_in_place`, through
3440    /// `Guest::set_blocked_signals`, so `restore` puts it back the same way,
3441    /// with no injection and no scratch memory.
3442    blocked_in_place: bool,
3443    /// The signal the backend holds since `inject_absorbing` absorbed a stop;
3444    /// `None` also after a stop it could not identify (`held_unidentified`).
3445    held: Option<HeldSignal>,
3446    /// The backend holds a signal from a stop that `inject_absorbing` could not
3447    /// identify, which may be one whose loss matters, so no later stop may
3448    /// replace it (`would_replace_precious`).
3449    held_unidentified: bool,
3450    /// The signals `hold_until_return` added because a host-timed source armed
3451    /// by a guest can post them; a committed signal never lifts these
3452    /// (`admit`).
3453    host_timed: KernelSigset,
3454    /// Signals the scheduler committed to this thread in the current turn,
3455    /// which end the wait even though it holds them (`admit`).
3456    committed: KernelSigset,
3457    /// The `SIGCHLD` a guest sent this thread, which the schedule recorded in
3458    /// its private queue, admitted in the current turn (`admit_under_block`):
3459    /// it ends the wait from the thread's own queue only, even though the
3460    /// wait holds it (R2b-2 stage 3,
3461    /// https://github.com/rrnewton/hermit/issues/4273).
3462    private: KernelSigset,
3463    /// The mask the wait sleeps under, when it is not the guest's own: the
3464    /// temporary mask of a `pselect6` (`with_wait_mask`). A signal decides
3465    /// against it whether it ends the wait; `restore` still puts back the
3466    /// guest's own mask (https://github.com/rrnewton/hermit/issues/3991).
3467    wait_mask: Option<KernelSigset>,
3468}
3469
3470/// A signal that stopped one of a wait's injections and that the backend holds
3471/// for delivery when the guest resumes (`KernelSignalWait::inject_absorbing`).
3472#[derive(Clone, Copy, Debug, Eq, PartialEq)]
3473struct HeldSignal {
3474    signal: i32,
3475    queue: SignalQueue,
3476    kind: HeldKind,
3477}
3478
3479/// Whether losing a held signal, which a later stop would replace, changes what
3480/// the guest or the scheduler observes.
3481#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
3482enum HeldKind {
3483    /// Its delivery does nothing: it is ignored, or default-ignored and not
3484    /// `SIGCHLD`.
3485    Harmless,
3486    /// Its delivery matters, or is kept as if it did: a signal the wait holds
3487    /// until the call returns (`held_until_return`), which may run a handler
3488    /// then, any other `SIGCHLD`, or a default job-control stop that the wait
3489    /// defers.
3490    Precious,
3491}
3492
3493/// How a wait would lose a signal that the backend holds, or deliver it in
3494/// place of the result Linux gives (`HeldSignalRefusal`).
3495#[derive(Clone, Copy, Debug, Eq, PartialEq)]
3496pub(crate) enum HeldSignalLoss {
3497    /// Another pending signal would stop the next injection, and the backend,
3498    /// which has one slot for a held signal, would drop the held one for it.
3499    Replaced,
3500    /// A stop that `/proc` cannot identify replaced a held signal whose loss
3501    /// matters (`HeldKind::Precious`), or one that could not be identified
3502    /// either and so may matter.
3503    UnidentifiedStop,
3504    /// The wait reached `MAX_ABSORBED_STOPS` absorbed stops while the backend
3505    /// held a signal whose loss matters or that could not be identified.
3506    StopBound,
3507    /// A signal that a wait without a deadline consumes stopped an injection,
3508    /// so the backend holds it and delivers it rather than the wait returning
3509    /// it, and either it is one the wait holds until the call returns
3510    /// (`held_until_return`) or it replaced a held signal whose loss matters.
3511    Consumed,
3512    /// A signal stopped an injection of `restore`, which puts the guest's mask
3513    /// back and so must run whatever is pending, and the backend dropped a held
3514    /// signal whose loss matters, or one that could not be identified, for it.
3515    Restoration,
3516}
3517
3518/// A wait that ends because going on, or restarting the call, would lose a
3519/// signal the backend holds, or deliver it in place of the result Linux gives.
3520///
3521/// Every path that used to end such a wait with a fallback that returns
3522/// success (a transparent `ERESTARTNOINTR` restart, or a wait that went on and
3523/// let a stop replace the held signal) returns this instead (round-10 High 1 on
3524/// https://github.com/rrnewton/hermit/pull/3361). The wait puts the guest's mask
3525/// back, and its caller then applies the unsupported-operation policy
3526/// (`refuse_held_signal_loss`). A complete successful repair preserving signal
3527/// information needs additional framework support with the current generic
3528/// API: the backend holds one signal, does not say which, and delivers it
3529/// without the tool. A Detcore-only refusal or capability withdrawal can
3530/// prevent the determinism regression.
3531#[derive(Clone, Copy, Debug, Eq, PartialEq)]
3532pub(crate) struct HeldSignalRefusal {
3533    /// The guest call whose wait ends, once the caller names it
3534    /// (`refuse_held_signal_loss`).
3535    pub(crate) wait: Option<Sysno>,
3536    /// The signal the backend holds that would be lost or delivered wrongly;
3537    /// `None` when it could not be identified.
3538    pub(crate) held: Option<i32>,
3539    /// The signal that would replace it, or that stopped the injection, when
3540    /// known.
3541    pub(crate) replacing: Option<i32>,
3542    /// How it would be lost.
3543    pub(crate) loss: HeldSignalLoss,
3544}
3545
3546/// A signal's name, such as `SIGCHLD`, or its number for a real-time signal.
3547fn signal_label(signal: Option<i32>) -> String {
3548    match signal {
3549        Some(signal) => match nix::sys::signal::Signal::try_from(signal) {
3550            Ok(named) => named.as_str().to_string(),
3551            Err(_) => format!("signal {signal}"),
3552        },
3553        None => "a signal that could not be identified".to_string(),
3554    }
3555}
3556
3557impl std::fmt::Display for HeldSignalRefusal {
3558    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3559        let wait = self
3560            .wait
3561            .map_or_else(|| "a blocking".to_string(), |sysno| sysno.to_string());
3562        let held = match self.held {
3563            Some(_) => format!("the held signal {}", signal_label(self.held)),
3564            None => "a held signal that could not be identified".to_string(),
3565        };
3566        let replacing = signal_label(self.replacing);
3567        match self.loss {
3568            HeldSignalLoss::Replaced => write!(
3569                f,
3570                "unsupported: the {wait} wait cannot keep {held}: the pending {replacing} \
3571                 would stop the next injection and replace it"
3572            )?,
3573            HeldSignalLoss::UnidentifiedStop => write!(
3574                f,
3575                "unsupported: the {wait} wait cannot keep {held}: a signal stop that /proc \
3576                 cannot identify replaced it"
3577            )?,
3578            HeldSignalLoss::StopBound => write!(
3579                f,
3580                "unsupported: the {wait} wait cannot keep {held}: the wait absorbed the \
3581                 maximum number of signal stops"
3582            )?,
3583            HeldSignalLoss::Consumed => {
3584                write!(
3585                    f,
3586                    "unsupported: the {wait} wait cannot return {replacing}, which it consumes: \
3587                     the signal stopped an injection, so the backend would deliver it instead"
3588                )?;
3589                if self.held.is_some() {
3590                    write!(f, ", in place of {held}")?;
3591                }
3592            }
3593            HeldSignalLoss::Restoration => write!(
3594                f,
3595                "unsupported: the {wait} wait cannot keep {held}: {replacing} stopped the \
3596                 injection that puts the guest's signal mask back and replaced it"
3597            )?,
3598        }
3599        write!(
3600            f,
3601            " (scope reduction of https://github.com/rrnewton/hermit/pull/3361; rerun with \
3602             --allow-unsupported-syscalls to restart the call instead)"
3603        )
3604    }
3605}
3606
3607impl std::error::Error for HeldSignalRefusal {}
3608
3609/// What a signal that stopped one of a wait's injections means for the wait.
3610#[derive(Clone, Copy, Debug, Eq, PartialEq)]
3611enum StopVerdict {
3612    /// The wait goes on; the backend holds the signal.
3613    Absorb(HeldKind),
3614    /// The wait ends with this errno.
3615    End(Errno),
3616}
3617
3618/// The first real-time signal number in the kernel. A standard signal below it
3619/// is pending at most once; a second one sent while it is pending is merged.
3620const KERNEL_SIGRTMIN: i32 = 32;
3621
3622impl KernelSignalWait {
3623    pub(crate) fn new<T, G>(
3624        guest: &G,
3625        consumed: KernelSigset,
3626        defers_default_stops: bool,
3627        restart_errno: Errno,
3628    ) -> Self
3629    where
3630        T: RecordOrReplay,
3631        G: Guest<Detcore<T>>,
3632    {
3633        Self {
3634            pid: guest.pid(),
3635            tid: guest.tid(),
3636            consumed,
3637            defers_default_stops,
3638            restart_errno,
3639            held_until_return: kernel_sigset_bit(libc::SIGCHLD),
3640            deadline: false,
3641            saved_mask: None,
3642            unblockable: false,
3643            blocked_in_place: false,
3644            held: None,
3645            held_unidentified: false,
3646            host_timed: 0,
3647            committed: 0,
3648            private: 0,
3649            wait_mask: None,
3650        }
3651    }
3652
3653    /// This wait, with a finite deadline when `deadline` is set (the `deadline`
3654    /// field): no fallback of `inject_absorbing` then ends it with
3655    /// `ERESTARTNOINTR`, which would start the guest's timeout again.
3656    pub(crate) fn with_deadline(self, deadline: bool) -> Self {
3657        Self { deadline, ..self }
3658    }
3659
3660    /// The wait of `select` and of `pselect6`, which holds no signal until the
3661    /// call returns (`held_until_return` is empty); a `pselect6` with a
3662    /// temporary mask adds it with `with_wait_mask`:
3663    /// any pending signal that could interrupt it ends it, `SIGCHLD` included.
3664    ///
3665    /// Linux ends these calls with `ERESTARTNOHAND` whenever no descriptor is
3666    /// ready and a signal is pending (`core_sys_select`), so a caught `SIGCHLD`
3667    /// ends them whoever sent it. Detcore's select and pselect6 waits did the
3668    /// same before this machinery existed: their probes ran under the guest's
3669    /// own mask, and a pending caught signal stopped one.
3670    ///
3671    /// This is a known gap that these waits had before, and it is left as it
3672    /// was: the `SIGCHLD` the kernel posts for a child's exit, stop or continue
3673    /// ends the wait at the first turn whose read sees it, and host timing
3674    /// decides which turn that is (https://github.com/rrnewton/hermit/issues/3146).
3675    /// Every other wait holds `SIGCHLD` until it returns, unless the scheduler
3676    /// commits it to the thread in that turn (`admit`).
3677    pub(crate) fn for_select<T, G>(guest: &G) -> Self
3678    where
3679        T: RecordOrReplay,
3680        G: Guest<Detcore<T>>,
3681    {
3682        Self {
3683            held_until_return: 0,
3684            ..Self::new(guest, 0, false, Errno::ERESTARTNOHAND)
3685        }
3686    }
3687
3688    /// This wait, sleeping under `mask` instead of the guest's own (`wait_mask`):
3689    /// a `pselect6` with a temporary mask. Linux installs that mask for the
3690    /// whole call, so a signal it blocks never ends the call, even one the
3691    /// guest's own mask leaves unblocked, and one it leaves unblocked ends the
3692    /// call although the guest's own mask blocks it.
3693    pub(crate) fn with_wait_mask(self, mask: Option<KernelSigset>) -> Self {
3694        Self {
3695            wait_mask: mask,
3696            ..self
3697        }
3698    }
3699
3700    /// The mask Linux's `blocked` holds for the waiting thread when the
3701    /// kernel's `SigBlk` does not show it: the wait's temporary mask
3702    /// (`wait_mask`), or else the guest's own mask once `block` has replaced
3703    /// it (`saved_mask`). `None` while `SigBlk` is the guest's own mask.
3704    pub(crate) fn effective_mask(&self) -> Option<KernelSigset> {
3705        self.wait_mask.or(self.saved_mask)
3706    }
3707
3708    /// Whether the backend holds a signal from a stop of one of this wait's
3709    /// injections (`held`, `held_unidentified`), which it delivers when the
3710    /// guest resumes.
3711    pub(crate) fn holds_signal(&self) -> bool {
3712        self.held.is_some() || self.held_unidentified
3713    }
3714
3715    /// Whether a signal that ends the wait, pending in the kernel per `state`,
3716    /// is one the guest's own mask blocks: it ends the wait only because the
3717    /// wait mask (`with_wait_mask`) leaves it unblocked, and it stays pending
3718    /// when the guest's own mask is put back. A signal the wait holds until
3719    /// the call returns counts once the scheduler committed it in this turn
3720    /// (`admit`), as in `interrupted_with_state`: otherwise a
3721    /// committed `SIGCHLD` that only the wait mask lets in ended the call
3722    /// without its handler (Claude review of
3723    /// https://github.com/rrnewton/hermit/pull/4217).
3724    pub(crate) fn interrupts_only_under_wait_mask(&self, state: &KernelSignalState) -> bool {
3725        let own_mask = self.saved_mask.unwrap_or(state.blocked);
3726        let held_until_return = self.held_until_return & !self.committed;
3727        let could_interrupt = self.could_interrupt(state);
3728        let interrupting = (state.pending & !held_until_return
3729            | state.thread_pending & self.private)
3730            & could_interrupt;
3731        self.wait_mask.is_some() && interrupting & own_mask != 0
3732    }
3733
3734    /// Adds `signals` to the ones this wait holds until the call returns
3735    /// (`held_until_return`). The gated loop passes, in each of its turns, the
3736    /// signals that a host-timed source armed by a guest can post to this
3737    /// process, such as a parent-death signal (`tool_global::host_timed_signals`):
3738    /// the kernel posts those at a moment set by host timing, so ending the wait
3739    /// for one would make the run depend on host timing. Never called for a
3740    /// `select` wait (`for_select`), which holds nothing.
3741    pub(crate) fn hold_until_return(&mut self, signals: KernelSigset) {
3742        self.held_until_return |= signals;
3743        self.host_timed |= signals;
3744    }
3745
3746    /// Sets the signals the scheduler committed to this thread in this turn
3747    /// (`committed`): its resume named them (`ResumeStatus::Signaled`). Such a
3748    /// signal was sent at a fixed point of the schedule, so a wait may end for
3749    /// it although the wait holds it, unless a host-timed source can post it
3750    /// too (`host_timed`). The loop passes a committed `SIGCHLD`, which the
3751    /// scheduler sends at a commit point (a child's child-exit timer, or a
3752    /// POSIX timer whose signal is `SIGCHLD`); the kernel's
3753    /// own copy of it, posted at a host-timed moment, decides nothing, since
3754    /// only the resume that names it lifts the hold, for that turn alone
3755    /// (https://github.com/rrnewton/hermit/issues/4005).
3756    ///
3757    /// `private` is the `SIGCHLD` a guest sent this thread, recorded in its
3758    /// private queue, that the turn admits (`admit_under_block`): it lifts the
3759    /// hold only against the thread's own queue, for this turn alone.
3760    pub(crate) fn admit(&mut self, committed: KernelSigset, private: KernelSigset) {
3761        self.committed = committed & !self.host_timed;
3762        self.private = private & !self.host_timed;
3763    }
3764
3765    /// The private `SIGCHLD` this turn admits (`admit`), from `recorded`, the
3766    /// schedule's record (`Scheduler::private_sigchld`). A turn that admits a
3767    /// `SIGCHLD`, committed or recorded, first blocks every blockable signal
3768    /// in place, before any injection of the turn, and publishes the guest's
3769    /// mask while it holds (`block_in_place`, `publish_wait_mask`). The
3770    /// recorded one is then kept only while that block holds (`saved_mask`;
3771    /// an earlier injected `block` that failed leaves none), and only if the
3772    /// thread's own queue holds `SIGCHLD`, read after the block: only this
3773    /// stopped thread can take it from there, and no injection can now. If
3774    /// the setter refuses, the wait keeps its fallback, the injected `block`
3775    /// after the first probe (rev4 1f), and holds the recorded `SIGCHLD` as
3776    /// before.
3777    pub(crate) async fn admit_under_block<T, G>(
3778        &mut self,
3779        guest: &mut G,
3780        committed: KernelSigset,
3781        recorded: KernelSigset,
3782        host_timed: KernelSigset,
3783        published: &mut PublishedWaitMask,
3784    ) -> Result<KernelSigset, Error>
3785    where
3786        T: RecordOrReplay,
3787        G: Guest<Detcore<T>>,
3788    {
3789        if (committed | recorded) & !host_timed == 0 {
3790            return Ok(0);
3791        }
3792        if self.needs_block() {
3793            if self.block_in_place(guest, host_timed).await? {
3794                publish_wait_mask(guest, self.effective_mask(), published).await;
3795            } else {
3796                // Keep today's fallback for this wait.
3797                self.unblockable = false;
3798            }
3799        }
3800        if recorded == 0 || self.saved_mask.is_none() {
3801            return Ok(0);
3802        }
3803        let state = read_wait_signal_state(self.pid, self.tid)?;
3804        Ok(recorded & state.thread_pending)
3805    }
3806
3807    /// Whether, of the signals that end the wait per `state`, only signals the
3808    /// scheduler committed in this turn do (`admit`): without them
3809    /// the wait would go on.
3810    pub(crate) fn interrupts_only_by_committed(&self, state: &KernelSignalState) -> bool {
3811        let held = self.held.map_or(0, |held| kernel_sigset_bit(held.signal));
3812        let interrupting = (state.pending | held) & self.could_interrupt(state);
3813        (self.committed | self.private) != 0 && interrupting & !self.held_until_return == 0
3814    }
3815
3816    /// Whether the caller should still call `block`: it has neither blocked the
3817    /// guest's signals nor found that it cannot.
3818    pub(crate) fn needs_block(&self) -> bool {
3819        self.saved_mask.is_none() && !self.unblockable
3820    }
3821
3822    /// The signals that would end the wait natively under the guest's mask, given
3823    /// the kernel's `state`.
3824    /// The signals whose pending presence this wait would observe now: those
3825    /// it consumes, and those that would end it under the guest's mask, or
3826    /// the wait mask when it has one (`could_interrupt`). Read from the kernel's state in this turn.
3827    pub(crate) fn observable_now(&self) -> Result<KernelSigset, Error> {
3828        let state = read_wait_signal_state(self.pid, self.tid)?;
3829        Ok(self.consumed | self.could_interrupt(&state))
3830    }
3831
3832    fn could_interrupt(&self, state: &KernelSignalState) -> KernelSigset {
3833        let guest_mask = self.wait_mask.or(self.saved_mask).unwrap_or(state.blocked);
3834        state.interrupting_wait(guest_mask, self.defers_default_stops) & !self.consumed
3835    }
3836
3837    /// `interrupted_with_state` without the state, for the tests.
3838    #[cfg(test)]
3839    pub(crate) fn interrupted(&self) -> Result<bool, Error> {
3840        Ok(self.interrupted_with_state()?.0)
3841    }
3842
3843    /// Whether a signal that would end the wait natively is pending, in which case
3844    /// the caller returns the call's restart errno, with the kernel's state that
3845    /// this read, which `inject_absorbing_after` takes as its first read in the same
3846    /// turn. The guest thread has been stopped inside the call since it was
3847    /// intercepted, so such a signal arrived while the call was waiting, and Linux
3848    /// returns the restart errno for that. Linux reports a source that was ready
3849    /// when the call began, or an argument error, before any pending signal, so
3850    /// `retry_blocking_wait_with_kernel_signal_state` runs its first probe before
3851    /// this check (`inject_first_probe`). There, a source that becomes ready in a
3852    /// later turn in which a signal is also pending is put behind the signal,
3853    /// because the turn cannot tell which came first. The waits of `select` and
3854    /// `pselect6` run every probe before this check, as Linux's do_select polls
3855    /// every descriptor on each pass before it tests for a pending signal. A
3856    /// signal the wait holds until the call returns (`held_until_return`) never
3857    /// counts. A signal that the backend holds since `inject_absorbing` absorbed
3858    /// it counts as pending. A failed read is never returned as the call's errno
3859    /// (`read_wait_signal_state`).
3860    pub(crate) fn interrupted_with_state(&self) -> Result<(bool, KernelSignalState), Error> {
3861        let state = read_wait_signal_state(self.pid, self.tid)?;
3862        let could_interrupt = self.could_interrupt(&state);
3863        let held = self.held.map_or(0, |held| kernel_sigset_bit(held.signal));
3864        let held_until_return = self.held_until_return & !self.committed;
3865        // An admitted private `SIGCHLD` counts against the thread's own queue
3866        // only (`admit`).
3867        let interrupting = ((state.pending | held) & !held_until_return
3868            | state.thread_pending & self.private)
3869            & could_interrupt;
3870        if interrupting != 0 {
3871            tracing::trace!(
3872                "[tid {}] pending signals {:#x} interrupt a blocking wait",
3873                self.tid,
3874                interrupting
3875            );
3876        }
3877        Ok((interrupting != 0, state))
3878    }
3879
3880    /// Inject `call`, a probe or a mask change, absorbing the signal stops that do
3881    /// not end the wait. `Ok` carries the call's own result; `Err` ends the wait.
3882    ///
3883    /// A signal that stops the guest around an injection is dequeued from the
3884    /// kernel and held by the backend, which delivers it when the guest resumes,
3885    /// and the injection returns a restart errno instead of the call's result.
3886    /// The backend does not say which signal it holds, so the kernel's state is
3887    /// read before each injection (in a polling turn of
3888    /// `retry_blocking_wait_with_kernel_signal_state` under the full mask, the
3889    /// turn's own read: `inject_absorbing_after`), which names the signal the
3890    /// kernel dequeues next (`KernelSignalState::next_dequeued`), and again
3891    /// after a stop. The stop is identified only if exactly that signal left its queue
3892    /// and the mask and dispositions did not change; it then decides:
3893    ///
3894    /// - A signal the wait consumes (`consumed`) is delivered rather than
3895    ///   consumed. In a wait without a deadline it ends the wait with
3896    ///   `ERESTARTNOINTR`, and the call runs again, unless the wait holds it
3897    ///   until the call returns (`held_until_return`), so that its delivery now
3898    ///   could follow host timing: then the wait ends with a
3899    ///   [`HeldSignalRefusal`]. In a wait with a deadline (`deadline`) it is
3900    ///   classified as if the wait did not consume it, by the rules below.
3901    /// - A signal that would end the wait natively ends it with the restart
3902    ///   errno, except a signal the wait holds until the call returns
3903    ///   (`held_until_return`), which is held.
3904    /// - Any other `SIGCHLD`, and a default job-control stop that the wait
3905    ///   defers, are held, and so are an ignored signal and a default-ignored
3906    ///   one. The injection runs again.
3907    /// - A signal that the wait mask (`with_wait_mask`) blocks is held: Linux
3908    ///   keeps it pending until the call returns.
3909    /// - Anything else, which is the backend's own preemption signal, ends the
3910    ///   wait with `ERESTARTNOINTR`, or is held in a wait with a deadline.
3911    ///
3912    /// A pending signal that would end the wait ends it before the injection,
3913    /// with the restart errno, so it is never held, except by a probe made by
3914    /// `inject_first_probe`: the first probe of a wait, and every probe of the
3915    /// waits of `select` and `pselect6`. A stop that cannot be identified, by a
3916    /// signal that arrived after the read, does not end the wait while the
3917    /// backend held nothing whose loss matters: the backend holds that signal
3918    /// in place of any held one and the injection runs again, as the blind
3919    /// retry before this machinery did, so the wait keeps its deadline and
3920    /// every check that ends it. Which signal it was would need the backend to
3921    /// say, so it is recorded only as unidentified (`held_unidentified`), and
3922    /// it is delivered as the call returns.
3923    ///
3924    /// The backend has one slot for a held signal, and a stop replaces what it
3925    /// holds. A held signal whose loss matters (`HeldKind::Precious`), or one
3926    /// that could not be identified and so may matter, is never given up for a
3927    /// result that reads as success, with or without a deadline:
3928    ///
3929    /// - An injection that another pending signal would stop is not made. If
3930    ///   the held signal would end the wait natively, the wait ends with the
3931    ///   restart errno, as Linux ends it for that signal; otherwise it ends
3932    ///   with a `HeldSignalRefusal`. The same standard signal on the same queue
3933    ///   is the exception, because Linux merges the two.
3934    /// - A stop that cannot be identified, which has already replaced such a
3935    ///   signal, ends the wait with a `HeldSignalRefusal`.
3936    /// - After `MAX_ABSORBED_STOPS` absorbed stops, a wait without a deadline
3937    ///   ends with a `HeldSignalRefusal`, or with `ERESTARTNOINTR` when the
3938    ///   backend holds nothing whose loss matters. A wait with a deadline,
3939    ///   whose restart would start the guest's timeout again, absorbs stops
3940    ///   without a bound.
3941    ///
3942    /// Each refusal is a scope reduction. It replaces a transparent
3943    /// `ERESTARTNOINTR` restart, or, in a wait with a deadline, an injection
3944    /// that went on and let a stop replace the held signal (round-10 High 1 on
3945    /// https://github.com/rrnewton/hermit/pull/3361): the restart made the
3946    /// backend deliver the held signal before the wait completed, at a moment
3947    /// host timing could set. A complete successful repair preserving signal
3948    /// information needs additional framework support with the current generic
3949    /// API. A Detcore-only refusal or capability withdrawal can prevent the
3950    /// determinism regression.
3951    ///
3952    /// In a probe made by `inject_first_probe` that two pending signals would
3953    /// stop in turn, the first of which would end the wait, the wait ends with
3954    /// the restart errno before the probe has run, so a ready source, or an
3955    /// argument error, is reported behind the signal: the order compromise that
3956    /// a later turn of `retry_blocking_wait_with_kernel_signal_state` already
3957    /// makes (`interrupted_with_state`).
3958    pub(crate) async fn inject_absorbing<T, G, S>(
3959        &mut self,
3960        guest: &mut G,
3961        call: S,
3962    ) -> Result<Result<i64, Errno>, Error>
3963    where
3964        T: RecordOrReplay,
3965        G: Guest<Detcore<T>>,
3966        S: SyscallInfo,
3967    {
3968        self.inject_absorbing_from(guest, call, None, false).await
3969    }
3970
3971    /// The first probe of a wait, and every probe of the waits of `select` and
3972    /// `pselect6`, which runs before the turn's `interrupted_with_state` check:
3973    /// `inject_absorbing`, except that a signal that would end the wait neither
3974    /// ends it before the injection nor when it stops the injection.
3975    ///
3976    /// Linux reports a descriptor that is ready when the call begins, a queued
3977    /// event, and an argument error before it looks at pending signals:
3978    /// `do_poll` tests `signal_pending` only when no descriptor is ready, and so
3979    /// does `core_sys_select`, whose `max_select_fd` first returns `EBADF` for a
3980    /// descriptor in the sets that is not open; `ep_poll` sends queued events
3981    /// before it tests it, `do_epoll_wait` rejects a bad descriptor or
3982    /// `maxevents` first, and `do_sigtimedwait` copies its set first. So the
3983    /// probe runs even when such a signal is pending. `do_select` also polls
3984    /// every descriptor on each pass before it tests `signal_pending`, so the
3985    /// waits of `select` and `pselect6` make every probe this way; once `block`
3986    /// has blocked every blockable signal, a pending one cannot stop a probe
3987    /// there, and the check that follows a probe that would block counts it.
3988    /// A pending signal that the guest does not block stops the injection
3989    /// before the probe runs; when the stop is identified, the signal is held
3990    /// as a precious one (`HeldKind::Precious`) and the probe runs again, so
3991    /// its result stands, and the backend delivers the signal as the call
3992    /// returns. If the probe would block, the caller's check that follows
3993    /// counts the held signal (`interrupted_with_state`) and ends the wait with
3994    /// the restart errno. A stop that cannot be identified is held, as
3995    /// `inject_absorbing` describes.
3996    pub(crate) async fn inject_first_probe<T, G, S>(
3997        &mut self,
3998        guest: &mut G,
3999        call: S,
4000    ) -> Result<Result<i64, Errno>, Error>
4001    where
4002        T: RecordOrReplay,
4003        G: Guest<Detcore<T>>,
4004        S: SyscallInfo,
4005    {
4006        self.inject_absorbing_from(guest, call, None, true).await
4007    }
4008
4009    /// `inject_absorbing` in a turn whose `interrupted_with_state` read `state`
4010    /// and found no signal that ends the wait.
4011    ///
4012    /// Once `block` has blocked every blockable signal (`saved_mask`), `state`
4013    /// serves as the first read before the injection, so a polling turn reads
4014    /// `/proc` once, as it did before injections absorbed stops. The caller must
4015    /// run nothing between the two that resumes the guest thread or changes its
4016    /// signal state. `retry_blocking_wait_with_kernel_signal_state`, which serves
4017    /// ppoll, poll, epoll_pwait, epoll_wait, rt_sigtimedwait and polling futex
4018    /// waits and is the only caller, runs nothing there. So between the two reads
4019    /// the guest thread stays stopped and only it can change its own mask, and
4020    /// with threads sequentialized no other guest thread runs in its turn, so a
4021    /// signal that arrives meanwhile arrives at a
4022    /// host-timed moment: sent from outside the guest, or posted by the kernel.
4023    /// A signal that the full mask blocks stays pending, cannot stop the
4024    /// injection, and is classified at the next turn's read, as one that arrives
4025    /// just after a fresh read is. One that the full mask leaves unblocked
4026    /// (`SIGKILL`, `SIGSTOP`, glibc's two reserved signals, `PERF_EVENT_SIGNAL`)
4027    /// and that stops the injection is not named by `state`, so the stop is not
4028    /// identified and is handled as a stop by a signal that arrives just after a
4029    /// fresh read is. `interrupted_with_state` found
4030    /// no signal in `state` that ends the wait, so the check before the injection
4031    /// does not end it either.
4032    ///
4033    /// Before `block` takes effect, or when it cannot, the probe runs under the
4034    /// guest's own mask and a fresh read is taken, so a signal that arrived
4035    /// after `state` is still identified or ends the wait before the injection.
4036    pub(crate) async fn inject_absorbing_after<T, G, S>(
4037        &mut self,
4038        guest: &mut G,
4039        call: S,
4040        state: KernelSignalState,
4041    ) -> Result<Result<i64, Errno>, Error>
4042    where
4043        T: RecordOrReplay,
4044        G: Guest<Detcore<T>>,
4045        S: SyscallInfo,
4046    {
4047        let first = self.saved_mask.is_some().then_some(state);
4048        self.inject_absorbing_from(guest, call, first, false).await
4049    }
4050
4051    /// `inject_absorbing`, taking `first`, if any, as the state read before the
4052    /// first injection. For `first_probe`, a signal that would end the wait does
4053    /// not end it, and one that stops the injection is held
4054    /// (`inject_first_probe`).
4055    async fn inject_absorbing_from<T, G, S>(
4056        &mut self,
4057        guest: &mut G,
4058        call: S,
4059        mut first: Option<KernelSignalState>,
4060        first_probe: bool,
4061    ) -> Result<Result<i64, Errno>, Error>
4062    where
4063        T: RecordOrReplay,
4064        G: Guest<Detcore<T>>,
4065        S: SyscallInfo,
4066    {
4067        // Each absorbed stop takes one signal off a kernel queue, so only signals
4068        // sent faster than the injections run can reach this. A wait with a
4069        // deadline has no bound, as the blind retry before this machinery had
4070        // none: ending it would start its timeout again (`deadline`).
4071        const MAX_ABSORBED_STOPS: usize = 64;
4072        let mut absorbed = 0;
4073        loop {
4074            let before = match first.take() {
4075                Some(state) => state,
4076                None => read_wait_signal_state(self.pid, self.tid)?,
4077            };
4078            let ends_wait = self.could_interrupt(&before) & !self.held_until_return;
4079            if !first_probe && before.pending & ends_wait != 0 {
4080                return Err(self.restart_errno.into());
4081            }
4082            let next = before.next_dequeued(before.blocked);
4083            if let Some((signal, queue)) = next
4084                && self.would_replace_precious(signal, queue)
4085            {
4086                if let Some(held) = self.held
4087                    && self.held_ends_wait(&before, held.signal)
4088                {
4089                    tracing::trace!(
4090                        "[tid {}] signal {} would replace the held signal {}, which ends the wait",
4091                        self.tid,
4092                        signal,
4093                        held.signal
4094                    );
4095                    return Err(held_signal_restart_errno(self.restart_errno, held.signal).into());
4096                }
4097                // Round-10 High 1 on https://github.com/rrnewton/hermit/pull/3361:
4098                // this used to end a wait without a deadline with ERESTARTNOINTR,
4099                // and let a wait with one go on and lose the held signal.
4100                tracing::trace!(
4101                    "[tid {}] signal {} would replace the held signal {:?}; the wait is refused",
4102                    self.tid,
4103                    signal,
4104                    self.held
4105                );
4106                return Err(self.refusal(Some(signal), HeldSignalLoss::Replaced));
4107            }
4108            let result = guest.inject(call).await;
4109            let Err(errno) = result else {
4110                return Ok(result);
4111            };
4112            if !probe_was_interrupted_by_signal(errno) {
4113                return Ok(result);
4114            }
4115            let after = read_wait_signal_state(self.pid, self.tid)?;
4116            // A probe that carries the call's temporary mask, as a masked
4117            // ppoll's does (`with_wait_mask`), and that the kernel itself
4118            // ended, for a pending signal the mask lets in, leaves that mask
4119            // installed with its restore pending until the signal is delivered
4120            // as the guest resumes, so `/proc` reports a mask other than the one
4121            // before the injection. That ERESTARTNOHAND is the call's own
4122            // result, not a stop, and no injection may follow it: a repeated
4123            // probe would save the temporary mask as the guest's
4124            // (https://github.com/rrnewton/reverie/issues/1003). A pselect6
4125            // wait's probes carry no mask, so this never holds for one.
4126            if self.wait_mask.is_some()
4127                && errno == Errno::ERESTARTNOHAND
4128                && after.blocked != before.blocked
4129            {
4130                return Ok(result);
4131            }
4132            let identified =
4133                next.filter(|&(signal, queue)| stop_took_only(&before, &after, signal, queue));
4134            let Some((signal, queue)) = identified else {
4135                // A signal that `before` did not show stopped the injection. The
4136                // backend holds it in place of any held one and delivers it when
4137                // the guest resumes, but `/proc` cannot name it. If the backend
4138                // held a signal whose loss matters, or one it could not identify
4139                // either, that signal is gone, and the wait is refused. Otherwise
4140                // the wait goes on and the injection runs again, as the blind
4141                // retry before this machinery did, so the wait keeps its
4142                // deadline; the signals that `/proc` still shows are classified
4143                // as before, and every check that ends the wait still runs at
4144                // the read before the injection and at each turn's
4145                // `interrupted_with_state`.
4146                if self.holds_precious() {
4147                    tracing::trace!(
4148                        "[tid {}] a signal stop that cannot be identified replaced the held signal {:?}; the wait is refused",
4149                        self.tid,
4150                        self.held
4151                    );
4152                    return Err(self.refusal(None, HeldSignalLoss::UnidentifiedStop));
4153                }
4154                if !self.deadline && absorbed >= MAX_ABSORBED_STOPS {
4155                    // The backend now holds the unidentified signal.
4156                    self.held = None;
4157                    self.held_unidentified = true;
4158                    return Err(self.refusal(None, HeldSignalLoss::StopBound));
4159                }
4160                absorbed += 1;
4161                tracing::trace!(
4162                    "[tid {}] a signal stop that cannot be identified is held; the injection runs again",
4163                    self.tid
4164                );
4165                self.held = None;
4166                self.held_unidentified = true;
4167                continue;
4168            };
4169            let bit = kernel_sigset_bit(signal);
4170            let verdict = match self.stop_verdict(&before, signal) {
4171                // A probe made by `inject_first_probe` holds a signal that would
4172                // end the wait and runs again.
4173                StopVerdict::End(_)
4174                    if first_probe
4175                        && self.consumed & bit == 0
4176                        && self.could_interrupt(&before) & bit != 0 =>
4177                {
4178                    StopVerdict::Absorb(HeldKind::Precious)
4179                }
4180                verdict => verdict,
4181            };
4182            match verdict {
4183                StopVerdict::Absorb(kind) => {
4184                    let kind = self.held.map_or(kind, |held| held.kind.max(kind));
4185                    let unidentified = self.held_unidentified;
4186                    self.held = Some(HeldSignal {
4187                        signal,
4188                        queue,
4189                        kind,
4190                    });
4191                    self.held_unidentified = false;
4192                    if !self.deadline && absorbed >= MAX_ABSORBED_STOPS {
4193                        if kind == HeldKind::Precious || unidentified {
4194                            return Err(self.refusal(None, HeldSignalLoss::StopBound));
4195                        }
4196                        return Err(Errno::ERESTARTNOINTR.into());
4197                    }
4198                    absorbed += 1;
4199                    tracing::trace!(
4200                        "[tid {}] signal {} stopped an injection and is held ({:?})",
4201                        self.tid,
4202                        signal,
4203                        kind
4204                    );
4205                }
4206                // A signal that a wait without a deadline consumes, delivered
4207                // rather than returned: refused when the wait holds it until the
4208                // call returns, or when it replaced a held signal whose loss
4209                // matters, and otherwise ended with ERESTARTNOINTR (stop_verdict).
4210                StopVerdict::End(_)
4211                    if !self.deadline
4212                        && self.consumed & bit != 0
4213                        && (self.held_until_return & bit != 0 || self.holds_precious()) =>
4214                {
4215                    tracing::trace!(
4216                        "[tid {}] consumed signal {} stopped an injection; the wait is refused",
4217                        self.tid,
4218                        signal
4219                    );
4220                    return Err(self.refusal(Some(signal), HeldSignalLoss::Consumed));
4221                }
4222                // The backend holds `signal`, which stopped the injection.
4223                StopVerdict::End(errno) => {
4224                    return Err(held_signal_restart_errno(errno, signal).into());
4225                }
4226            }
4227        }
4228    }
4229
4230    /// What a stop by `signal` means for the wait, given the kernel's state
4231    /// `before` the injection (see `inject_absorbing`).
4232    fn stop_verdict(&self, before: &KernelSignalState, signal: i32) -> StopVerdict {
4233        let bit = kernel_sigset_bit(signal);
4234        let interrupts = if self.consumed & bit != 0 {
4235            if !self.deadline {
4236                return StopVerdict::End(Errno::ERESTARTNOINTR);
4237            }
4238            // The backend delivers the signal rather than the wait consuming it,
4239            // as Linux does for one the guest does not block, so it is classified
4240            // as if the wait did not consume it.
4241            let guest_mask = self.wait_mask.or(self.saved_mask).unwrap_or(before.blocked);
4242            before.interrupting_wait(guest_mask, self.defers_default_stops) & bit != 0
4243        } else {
4244            self.could_interrupt(before) & bit != 0
4245        };
4246        if interrupts {
4247            return if self.held_until_return & bit != 0 {
4248                StopVerdict::Absorb(HeldKind::Precious)
4249            } else {
4250                StopVerdict::End(self.restart_errno)
4251            };
4252        }
4253        if signal == libc::SIGCHLD
4254            || (self.defers_default_stops && before.default_job_control_stops() & bit != 0)
4255        {
4256            return StopVerdict::Absorb(HeldKind::Precious);
4257        }
4258        let default_ignored = [libc::SIGCONT, libc::SIGURG, libc::SIGWINCH]
4259            .into_iter()
4260            .fold(0, |set, signal| set | kernel_sigset_bit(signal));
4261        if (before.ignored | (default_ignored & !before.caught)) & bit != 0 {
4262            return StopVerdict::Absorb(HeldKind::Harmless);
4263        }
4264        // A signal that the wait mask blocks, and the guest's own mask does
4265        // not, can stop an injection that runs before `block` takes effect.
4266        // Linux keeps it pending for the whole call, under the temporary mask,
4267        // and delivers it as the call returns, so it is held and never ends
4268        // the wait (review of
4269        // https://github.com/rrnewton/hermit/pull/4051).
4270        if self.deadline || self.wait_mask.is_some_and(|mask| mask & bit != 0) {
4271            StopVerdict::Absorb(HeldKind::Precious)
4272        } else {
4273            StopVerdict::End(Errno::ERESTARTNOINTR)
4274        }
4275    }
4276
4277    /// Whether an injection that `signal`, pending on `queue`, stops would make
4278    /// the backend drop a held signal whose delivery matters
4279    /// (`HeldKind::Precious`), or one it could not identify, which may matter
4280    /// (`held_unidentified`). Linux merges a standard signal into the same one
4281    /// pending on the same queue, so that one replaces nothing.
4282    fn would_replace_precious(&self, signal: i32, queue: SignalQueue) -> bool {
4283        self.held_unidentified
4284            || self.held.is_some_and(|held| {
4285                held.kind == HeldKind::Precious
4286                    && !(signal == held.signal && queue == held.queue && signal < KERNEL_SIGRTMIN)
4287            })
4288    }
4289
4290    /// Whether the backend holds a signal whose loss matters
4291    /// (`HeldKind::Precious`), or one it could not identify, which may matter.
4292    fn holds_precious(&self) -> bool {
4293        self.held_unidentified
4294            || self
4295                .held
4296                .is_some_and(|held| held.kind == HeldKind::Precious)
4297    }
4298
4299    /// The `HeldSignalRefusal` that ends the wait, naming the signal the backend
4300    /// holds, if known, and `replacing`, the one that would replace it or that
4301    /// stopped the injection.
4302    fn refusal(&self, replacing: Option<i32>, loss: HeldSignalLoss) -> Error {
4303        Error::Tool(anyhow::Error::new(HeldSignalRefusal {
4304            wait: None,
4305            held: self.held.map(|held| held.signal),
4306            replacing,
4307            loss,
4308        }))
4309    }
4310
4311    /// Whether a held `signal` would end the wait natively, given the kernel's
4312    /// state `before` an injection: it could interrupt the wait, and the wait
4313    /// does not hold it until the call returns (`held_until_return`).
4314    fn held_ends_wait(&self, before: &KernelSignalState, signal: i32) -> bool {
4315        self.could_interrupt(before) & !self.held_until_return & kernel_sigset_bit(signal) != 0
4316    }
4317
4318    /// Block every blockable signal for the rest of the wait, and keep blocked the
4319    /// signals the guest blocks itself, which the blockable set leaves out (the C
4320    /// library's reserved signals). `scratch` is a guest cell for the mask when
4321    /// the caller holds the only scratch-stack guard; otherwise a fresh guard is
4322    /// taken. The change goes through `inject_absorbing`, so a signal that stops
4323    /// it is handled as one that stops a probe. If that ends the wait, the guest's
4324    /// mask is still recorded, and the caller's final `restore` reads the
4325    /// kernel's mask and puts the guest's back if the change took effect.
4326    ///
4327    /// If the mask cannot be changed for another reason, the guest's mask is
4328    /// unchanged and no wait call can return that error, so the wait continues
4329    /// with every probe under the guest's own mask, as the first probe runs, and
4330    /// `block` is not tried again (`needs_block`). `interrupted_with_state` reads
4331    /// that mask from the kernel each turn. The scratch-stack commit fails this
4332    /// way on a guest stack with no room below its stack pointer
4333    /// (https://github.com/rrnewton/hermit/issues/3328); poll and epoll_wait
4334    /// probes need no scratch of their own, so for them this is the first need.
4335    pub(crate) async fn block<'a, T, G>(
4336        &mut self,
4337        guest: &mut G,
4338        scratch: Option<AddrMut<'a, KernelSigset>>,
4339    ) -> Result<(), Error>
4340    where
4341        T: RecordOrReplay,
4342        G: Guest<Detcore<T>>,
4343    {
4344        let guest_mask = read_wait_signal_state(self.pid, self.tid)?.blocked;
4345        let mask = blocked_signal_mask() | guest_mask;
4346        let result = match scratch {
4347            Some(cell) => match guest.memory().write_value(cell, &mask) {
4348                Ok(()) => {
4349                    self.inject_absorbing(guest, set_signal_mask_call(cell.into()))
4350                        .await
4351                }
4352                Err(errno) => Ok(Err(errno)),
4353            },
4354            None => {
4355                let mut stack = guest.stack().await;
4356                let cell = stack.push(mask);
4357                match stack.commit() {
4358                    Ok(_guard) => {
4359                        self.inject_absorbing(guest, set_signal_mask_call(cell))
4360                            .await
4361                    }
4362                    Err(_) => Ok(Err(Errno::EFAULT)),
4363                }
4364            }
4365        };
4366        match result {
4367            Ok(Ok(_)) => {
4368                self.saved_mask = Some(guest_mask);
4369                Ok(())
4370            }
4371            Ok(Err(errno)) => {
4372                tracing::debug!(
4373                    "[tid {}] cannot block signals for a wait ({}); its probes run under the \
4374                     guest's mask",
4375                    self.tid,
4376                    errno
4377                );
4378                self.unblockable = true;
4379                Ok(())
4380            }
4381            Err(error) => {
4382                self.saved_mask = Some(guest_mask);
4383                Err(error)
4384            }
4385        }
4386    }
4387
4388    /// Block every blockable signal for the rest of the wait, as `block` does,
4389    /// but through `Guest::set_blocked_signals`: no guest code runs, so no
4390    /// pending signal is taken from the kernel's queues, and every one stays
4391    /// there for the kernel to deliver, in its own order, once `restore` puts
4392    /// the guest's mask back. `block` instead injects `rt_sigprocmask`, which a
4393    /// pending signal can stop before it runs, moving that signal into the
4394    /// backend's single held slot, where a second one replaces it
4395    /// (https://github.com/rrnewton/hermit/issues/4273, stage 2). No scratch
4396    /// memory is needed, here or in `restore` (the Claude review of the R2b-2
4397    /// design, M1).
4398    ///
4399    /// `host_timed` is the turn's host-timed signals, held until the call
4400    /// returns as `hold_until_return` holds them.
4401    ///
4402    /// Returns whether the mask is now blocked. A refusal changes nothing
4403    /// (`MaskChangeRefused::Unsupported`, `RestorePending`), and neither does a
4404    /// failure that put the old mask back, so the wait goes on under the
4405    /// guest's own mask, as before this existed. A failure that leaves the mask
4406    /// unknown ends the run before the guest resumes
4407    /// ([`BlockedWaitSignalError::MaskNotRestored`]).
4408    pub(crate) async fn block_in_place<T, G>(
4409        &mut self,
4410        guest: &mut G,
4411        host_timed: KernelSigset,
4412    ) -> Result<bool, Error>
4413    where
4414        T: RecordOrReplay,
4415        G: Guest<Detcore<T>>,
4416    {
4417        // As `install_turn_mask` does for `writev`: the signals a host-timed
4418        // source can post (`host_timed`) are held until the call returns, so a
4419        // fallback injected restoration holds one that stops it
4420        // (`absorb_restoration_stop`) rather than counting it lost.
4421        self.hold_until_return(host_timed);
4422        let guest_mask = read_wait_signal_state(self.pid, self.tid)?.blocked;
4423        match guest
4424            .set_blocked_signals(blocked_signal_mask() | guest_mask)
4425            .await
4426        {
4427            Ok(old) => {
4428                self.saved_mask = Some(old);
4429                self.blocked_in_place = true;
4430                Ok(true)
4431            }
4432            Err(MaskChangeRefused::Failed {
4433                errno,
4434                mask_unknown: true,
4435            }) => Err(self.mask_not_restored(1, Some(errno))),
4436            Err(refused) => {
4437                tracing::debug!(
4438                    "[tid {}] cannot block signals in place for a wait ({}); its attempts run \
4439                     under the guest's mask",
4440                    self.tid,
4441                    refused
4442                );
4443                // Not tried again for this wait (`needs_block`).
4444                self.unblockable = true;
4445                Ok(false)
4446            }
4447        }
4448    }
4449
4450    /// The error that ends the run when the guest's mask cannot be put back.
4451    fn mask_not_restored(&self, attempts: usize, last_error: Option<Errno>) -> Error {
4452        Error::Tool(anyhow::Error::new(
4453            BlockedWaitSignalError::MaskNotRestored {
4454                pid: self.pid,
4455                tid: self.tid,
4456                attempts,
4457                last_error,
4458            },
4459        ))
4460    }
4461
4462    /// Put back the guest's mask, if `block` replaced it. A signal can stop the guest
4463    /// around the call, before or after it takes effect, so success is read back
4464    /// from the kernel and the call is repeated until the kernel reports the
4465    /// guest's mask. The guest never resumes with every signal blocked: if the
4466    /// mask cannot be put back, the run ends with
4467    /// [`BlockedWaitSignalError::MaskNotRestored`].
4468    ///
4469    /// The backend holds the signal that stops one of these injections, in place
4470    /// of any it held, as it does for a probe (`inject_absorbing`). Each such
4471    /// stop is recorded from the read before the injection and the read after it
4472    /// (`absorb_restoration_stop`). If one replaced a held signal whose loss
4473    /// matters, or one that could not be identified, the mask is still put back
4474    /// and then the first such loss is returned as a [`HeldSignalRefusal`]
4475    /// (`HeldSignalLoss::Restoration`), which the caller turns into the wait's
4476    /// result (`result_after_restore`). Round-11 High F1 on
4477    /// https://github.com/rrnewton/hermit/pull/3361: these stops used to be
4478    /// retried without that check, so the held signal was lost silently.
4479    pub(crate) async fn restore<'a, T, G>(
4480        &mut self,
4481        guest: &mut G,
4482        scratch: Option<AddrMut<'a, KernelSigset>>,
4483    ) -> Result<(), Error>
4484    where
4485        T: RecordOrReplay,
4486        G: Guest<Detcore<T>>,
4487    {
4488        let Some(guest_mask) = self.saved_mask else {
4489            return Ok(());
4490        };
4491        // A mask `block_in_place` installed goes back the same way, with no
4492        // injection, so no signal can stop the restoration and none is held.
4493        // That call is refused under the same rules as the block; a refusal
4494        // or a failure that left the mask as it was falls back to the
4495        // injected restoration below, which needs scratch memory (the Codex
4496        // and Claude reviews of https://github.com/rrnewton/reverie/pull/1083,
4497        // F4).
4498        if std::mem::take(&mut self.blocked_in_place) {
4499            match guest.set_blocked_signals(guest_mask).await {
4500                Ok(_) | Err(MaskChangeRefused::Gone) => {
4501                    self.saved_mask = None;
4502                    return Ok(());
4503                }
4504                Err(MaskChangeRefused::Failed {
4505                    errno,
4506                    mask_unknown: true,
4507                }) => {
4508                    self.saved_mask = None;
4509                    return Err(self.mask_not_restored(1, Some(errno)));
4510                }
4511                Err(refused) => {
4512                    tracing::debug!(
4513                        "[tid {}] cannot restore the mask in place ({}); injecting it",
4514                        self.tid,
4515                        refused
4516                    );
4517                }
4518            }
4519        }
4520        // `stop_verdict` reads the guest's mask from `saved_mask`, so it is cleared
4521        // only once the restoration has ended.
4522        let restored = self.restore_mask(guest, guest_mask, scratch).await;
4523        self.saved_mask = None;
4524        restored
4525    }
4526
4527    /// `restore`, for a wait whose guest mask is `guest_mask`.
4528    async fn restore_mask<'a, T, G>(
4529        &mut self,
4530        guest: &mut G,
4531        guest_mask: KernelSigset,
4532        scratch: Option<AddrMut<'a, KernelSigset>>,
4533    ) -> Result<(), Error>
4534    where
4535        T: RecordOrReplay,
4536        G: Guest<Detcore<T>>,
4537    {
4538        // Under the all-blocked mask only a signal that cannot be blocked (SIGKILL,
4539        // SIGSTOP) can stop the call before it takes effect, and each such stop needs
4540        // another signal sent, so a bound this large is never reached in practice.
4541        const ATTEMPTS: usize = 16;
4542        let mut attempts = 0;
4543        let mut last_error = None;
4544        // The kernel's state before an injection that a signal stopped, until the
4545        // next read records the stop.
4546        let mut stopped = None;
4547        // The first held signal that a stop replaced, as the refusal to return once
4548        // the mask is back.
4549        let mut loss = None;
4550        while attempts < ATTEMPTS {
4551            let state = read_wait_signal_state(self.pid, self.tid)?;
4552            if let Some(before) = stopped.take() {
4553                let replaced = self.absorb_restoration_stop(&before, &state);
4554                loss = loss.or(replaced);
4555            }
4556            if state.blocked == guest_mask {
4557                return loss.map_or(Ok(()), Err);
4558            }
4559            attempts += 1;
4560            match inject_signal_mask(guest, guest_mask, scratch).await {
4561                Ok(()) => return loss.map_or(Ok(()), Err),
4562                // Stopped by a signal: the next read records the stop and decides
4563                // whether the mask took effect.
4564                Err(errno) if probe_was_interrupted_by_signal(errno) => {
4565                    last_error = Some(errno);
4566                    stopped = Some(state);
4567                }
4568                // The call could not run, so the mask is unchanged.
4569                Err(errno) => {
4570                    last_error = Some(errno);
4571                    break;
4572                }
4573            }
4574        }
4575        let state = read_wait_signal_state(self.pid, self.tid)?;
4576        if let Some(before) = stopped.take() {
4577            let replaced = self.absorb_restoration_stop(&before, &state);
4578            loss = loss.or(replaced);
4579        }
4580        if state.blocked == guest_mask {
4581            return loss.map_or(Ok(()), Err);
4582        }
4583        Err(Error::Tool(anyhow::Error::new(
4584            BlockedWaitSignalError::MaskNotRestored {
4585                pid: self.pid,
4586                tid: self.tid,
4587                attempts,
4588                last_error,
4589            },
4590        )))
4591    }
4592
4593    /// Record a signal stop of an injection of `restore`, given the kernel's state
4594    /// `before` the injection and `after` it, as `inject_absorbing` records a stop
4595    /// of a probe: the backend holds the signal that stopped it in place of any it
4596    /// held. Returns the `HeldSignalRefusal` when that replaced a held signal
4597    /// whose loss matters, or one that could not be identified
4598    /// (`would_replace_precious`, `holds_precious`), naming the held signal as it
4599    /// was before the stop.
4600    ///
4601    /// A stop is identified only when exactly the signal that the kernel would
4602    /// take next under the mask `before` left its queue and the mask did not
4603    /// change (`stop_took_only`); a stop after which the mask took effect, or one
4604    /// that `before` did not show, is recorded as unidentified. The call's result
4605    /// is already decided, so a signal that would have ended the wait is kept as
4606    /// one whose delivery matters.
4607    fn absorb_restoration_stop(
4608        &mut self,
4609        before: &KernelSignalState,
4610        after: &KernelSignalState,
4611    ) -> Option<Error> {
4612        let identified = before
4613            .next_dequeued(before.blocked)
4614            .filter(|&(signal, queue)| stop_took_only(before, after, signal, queue));
4615        let Some((signal, queue)) = identified else {
4616            let loss = self
4617                .holds_precious()
4618                .then(|| self.refusal(None, HeldSignalLoss::Restoration));
4619            tracing::trace!(
4620                "[tid {}] a signal stop that cannot be identified stopped the mask restoration; it replaced the held signal {:?}",
4621                self.tid,
4622                self.held
4623            );
4624            self.held = None;
4625            self.held_unidentified = true;
4626            return loss;
4627        };
4628        let loss = self
4629            .would_replace_precious(signal, queue)
4630            .then(|| self.refusal(Some(signal), HeldSignalLoss::Restoration));
4631        let kind = match self.stop_verdict(before, signal) {
4632            StopVerdict::Absorb(kind) => kind,
4633            StopVerdict::End(_) => HeldKind::Precious,
4634        };
4635        let kind = self.held.map_or(kind, |held| held.kind.max(kind));
4636        tracing::trace!(
4637            "[tid {}] signal {} stopped the mask restoration and is held ({:?}) in place of {:?}",
4638            self.tid,
4639            signal,
4640            kind,
4641            self.held
4642        );
4643        self.held = Some(HeldSignal {
4644            signal,
4645            queue,
4646            kind,
4647        });
4648        self.held_unidentified = false;
4649        loss
4650    }
4651}
4652
4653/// The wait's result once `restore` has put the guest's mask back. A
4654/// [`HeldSignalRefusal`] from the restoration (`HeldSignalLoss::Restoration`)
4655/// replaces `result`, as a loss during the wait does, unless `result` is
4656/// already such a refusal, which came first; the caller then applies the
4657/// unsupported-operation policy (`refuse_held_signal_loss`). Every other
4658/// restoration error, such as [`BlockedWaitSignalError::MaskNotRestored`], is
4659/// returned as the error that ends the run, as before.
4660pub(crate) fn result_after_restore(
4661    restored: Result<(), Error>,
4662    result: Result<i64, Error>,
4663) -> Result<Result<i64, Error>, Error> {
4664    let is_refusal =
4665        |error: &Error| matches!(error, Error::Tool(error) if error.is::<HeldSignalRefusal>());
4666    match restored {
4667        Ok(()) => Ok(result),
4668        Err(refusal) if is_refusal(&refusal) => match &result {
4669            Err(error) if is_refusal(error) => Ok(result),
4670            _ => Ok(Err(refusal)),
4671        },
4672        Err(error) => Err(error),
4673    }
4674}
4675
4676/// Replace the guest's signal mask with `mask`, written to `scratch` or, when the
4677/// caller holds no scratch-stack guard, to a fresh one.
4678async fn inject_signal_mask<'a, T, G>(
4679    guest: &mut G,
4680    mask: KernelSigset,
4681    scratch: Option<AddrMut<'a, KernelSigset>>,
4682) -> Result<(), Errno>
4683where
4684    T: RecordOrReplay,
4685    G: Guest<Detcore<T>>,
4686{
4687    match scratch {
4688        Some(cell) => {
4689            guest.memory().write_value(cell, &mask)?;
4690            guest
4691                .inject(set_signal_mask_call(cell.into()))
4692                .await
4693                .map(drop)
4694        }
4695        None => {
4696            let mut stack = guest.stack().await;
4697            let cell = stack.push(mask);
4698            let _guard = stack.commit().map_err(|_| Errno::EFAULT)?;
4699            guest.inject(set_signal_mask_call(cell)).await.map(drop)
4700        }
4701    }
4702}
4703
4704/// `rt_sigprocmask(SIG_SETMASK, cell, NULL)`.
4705fn set_signal_mask_call(cell: Addr<'_, KernelSigset>) -> syscalls::RtSigprocmask {
4706    syscalls::RtSigprocmask::new()
4707        .with_how(libc::SIG_SETMASK)
4708        .with_set(Some(cell.cast()))
4709        .with_oldset(None)
4710        .with_sigsetsize(KERNEL_SIGSET_SIZE)
4711}
4712
4713/// Whether a signal stop between the kernel states `before` and `after` took
4714/// exactly `signal` off `queue`: it is no longer there, no other signal left
4715/// either queue, and the mask and dispositions did not change. Signals may have
4716/// arrived in between.
4717fn stop_took_only(
4718    before: &KernelSignalState,
4719    after: &KernelSignalState,
4720    signal: i32,
4721    queue: SignalQueue,
4722) -> bool {
4723    let bit = kernel_sigset_bit(signal);
4724    let other = match queue {
4725        SignalQueue::Thread => SignalQueue::Shared,
4726        SignalQueue::Shared => SignalQueue::Thread,
4727    };
4728    before.blocked == after.blocked
4729        && before.ignored == after.ignored
4730        && before.caught == after.caught
4731        && after.queued(queue) & bit == 0
4732        && before.queued(queue) & !bit & !after.queued(queue) == 0
4733        && before.queued(other) & !after.queued(other) == 0
4734}
4735
4736/// Whether an injected call's error means a signal stopped the guest around it
4737/// rather than that the call produced a result: the backend's restart errno, or
4738/// `EINTR` where a backend runs the call itself. None of these calls blocks.
4739pub(crate) fn probe_was_interrupted_by_signal(errno: Errno) -> bool {
4740    matches!(
4741        errno,
4742        Errno::EINTR
4743            | Errno::ERESTARTSYS
4744            | Errno::ERESTARTNOINTR
4745            | Errno::ERESTARTNOHAND
4746            | Errno::ERESTART_RESTARTBLOCK
4747    )
4748}
4749
4750pub(crate) async fn record_retry_event<G, C, T>(guest: &mut G, call: C)
4751where
4752    C: SyscallInfo,
4753    T: RecordOrReplay,
4754    G: Guest<Detcore<T>>,
4755{
4756    let dettid = guest.thread_state().dettid;
4757    let cfg = &guest.config();
4758    if cfg.sequentialize_threads && cfg.should_trace_schedevent() {
4759        trace_schedevent(
4760            guest,
4761            with_guest_time(
4762                guest,
4763                SchedEvent::syscall(dettid, call.number(), SyscallPhase::Polling),
4764            ),
4765            true,
4766        )
4767        .await;
4768    }
4769}
4770
4771// A helper function for enriching the schedevent with local information.
4772pub fn with_guest_time<G, T>(guest: &G, event: SchedEvent) -> SchedEvent
4773where
4774    G: Guest<Detcore<T>>,
4775    T: RecordOrReplay,
4776{
4777    let dettime = &guest.thread_state().thread_logical_time;
4778    event.with_dettime(dettime)
4779}
4780
4781// Enrich the event with the RIP register from the current guest state, but only if it is unset.
4782pub async fn with_guest_rip<G, T>(guest: &mut G, mut event: SchedEvent) -> SchedEvent
4783where
4784    G: Guest<Detcore<T>>,
4785    T: RecordOrReplay,
4786{
4787    assert!(event.end_rip.is_none());
4788
4789    let regs = guest.regs().await;
4790    let end_rip = NonZeroUsize::new(regs.rip.try_into().unwrap()).unwrap();
4791    event.end_rip = Some(end_rip);
4792    event
4793}
4794
4795// Convert to absolute logical time point for the timeout.
4796// 0 duration means no timeout, and this will return None.
4797pub async fn millis_duration_to_absolute_timeout<G: Guest<Detcore<T>>, T: RecordOrReplay>(
4798    guest: &mut G,
4799    timeout_millis: i32,
4800) -> Option<LogicalTime> {
4801    match positive_millis_as_nanos(timeout_millis) {
4802        Some(timeout_nanos) => nanos_duration_to_absolute_timeout(guest, timeout_nanos).await,
4803        None => None,
4804    }
4805}
4806
4807/// Milliseconds to nanoseconds for a strictly positive timeout; `None` for the
4808/// non-positive values Linux treats as "return immediately" (0) or "wait
4809/// forever" (-1), neither of which is a deadline.
4810///
4811/// Kept as a separate, unit-bracketed function on purpose. This conversion was
4812/// previously inlined as `* 1000` instead of `* 1_000_000`, which made every
4813/// finite deadline 1000x too short (a 1 ms timeout expired after 1 us). That
4814/// is invisible in an end-to-end test that only checks a syscall's return
4815/// value, so the arithmetic is pinned here by `millis_to_nanos_conversion`.
4816fn positive_millis_as_nanos(timeout_millis: i32) -> Option<u128> {
4817    (timeout_millis > 0).then(|| (timeout_millis as u128) * 1_000_000)
4818}
4819
4820// Convert to absolute logical time point for the timeout.
4821// 0 duration means no timeout, and this will return None.
4822pub async fn nanos_duration_to_absolute_timeout<G: Guest<Detcore<T>>, T: RecordOrReplay>(
4823    guest: &mut G,
4824    timeout_nanos: u128,
4825) -> Option<LogicalTime> {
4826    if timeout_nanos > 0 {
4827        let ns_delta = Duration::from_nanos(timeout_nanos as u64);
4828        let base_time = thread_observe_time(guest).await;
4829        let target_time = base_time + ns_delta;
4830        Some(target_time)
4831    } else {
4832        None
4833    }
4834}
4835
4836/// The number of `pollfd` entries `poll` and `ppoll` read. Linux declares
4837/// their `nfds` parameter `unsigned int`, so only the low 32 bits of the
4838/// register count; a guest may leave the high word set. Every reader of a
4839/// guest's pollfd array sizes it from this, never from `nfds` itself.
4840pub fn poll_nfds(nfds: libc::nfds_t) -> u32 {
4841    nfds as u32
4842}
4843
4844#[cfg(test)]
4845mod tests {
4846    use super::*;
4847
4848    /// Bracket the millisecond-to-nanosecond timeout conversion in both
4849    /// directions: the non-positive values that are NOT deadlines, and the
4850    /// positive values whose magnitude must be exactly 1e6 ns per ms.
4851    ///
4852    /// The 1 ms case is the specific regression guard: an inlined `* 1000`
4853    /// yields 1_000 here instead of 1_000_000, i.e. a deadline 1000x too
4854    /// short. Asserting the exact value (not merely "nonzero" or "greater
4855    /// than") is what makes that failure visible.
4856    #[test]
4857    fn millis_to_nanos_conversion() {
4858        // Not deadlines: -1 is "infinite", 0 is "return immediately".
4859        assert_eq!(positive_millis_as_nanos(-1), None);
4860        assert_eq!(positive_millis_as_nanos(i32::MIN), None);
4861        assert_eq!(positive_millis_as_nanos(0), None);
4862
4863        // Positive timeouts: exactly 1e6 nanoseconds per millisecond.
4864        assert_eq!(positive_millis_as_nanos(1), Some(1_000_000));
4865        assert_eq!(positive_millis_as_nanos(1_000), Some(1_000_000_000));
4866        assert_eq!(
4867            positive_millis_as_nanos(i32::MAX),
4868            Some(i32::MAX as u128 * 1_000_000)
4869        );
4870
4871        // The scale itself, stated independently of any single case so a
4872        // future refactor cannot satisfy the above by coincidence.
4873        for millis in [1, 2, 7, 250, 1_000, 86_400_000] {
4874            assert_eq!(
4875                positive_millis_as_nanos(millis),
4876                Some(millis as u128 * 1_000_000),
4877                "1 ms must convert to 1_000_000 ns, not 1_000"
4878            );
4879        }
4880    }
4881
4882    #[test]
4883    fn connect_nonblocking_results() {
4884        let call = reverie::syscalls::Connect::new();
4885        assert!(call.syscall_would_have_blocked(Err(Errno::EINPROGRESS)));
4886        assert!(call.syscall_would_have_blocked(Err(Errno::EALREADY)));
4887        assert_eq!(
4888            call.normalize_nonblocking_result(Err(Errno::EISCONN), true),
4889            Ok(0)
4890        );
4891        assert_eq!(
4892            call.normalize_nonblocking_result(Err(Errno::EISCONN), false),
4893            Err(Errno::EISCONN)
4894        );
4895    }
4896
4897    #[test]
4898    fn signal_interruption_errno_matches_linux_restart_policy() {
4899        assert_eq!(
4900            reverie::syscalls::Poll::new().signal_interrupt_errno(),
4901            Errno::EINTR
4902        );
4903        assert_eq!(
4904            reverie::syscalls::Ppoll::new().signal_interrupt_errno(),
4905            Errno::EINTR
4906        );
4907        assert_eq!(
4908            reverie::syscalls::EpollWait::new().signal_interrupt_errno(),
4909            Errno::EINTR
4910        );
4911        let sigtimedwait = reverie::syscalls::RtSigtimedwait::new();
4912        assert_eq!(sigtimedwait.signal_interrupt_errno(), Errno::EINTR);
4913        assert!(sigtimedwait.syscall_would_have_blocked(Err(Errno::EAGAIN)));
4914        assert_eq!(sigtimedwait.timeout_return_val(), Err(Errno::EAGAIN));
4915        assert_eq!(
4916            reverie::syscalls::Read::new().signal_interrupt_errno(),
4917            Errno::ERESTARTSYS
4918        );
4919        // A zero-progress writev interruption returns this internal errno on
4920        // ptrace so Linux applies the handler's SA_RESTART policy.
4921        assert_eq!(
4922            reverie::syscalls::Writev::new().signal_interrupt_errno(),
4923            Errno::ERESTARTSYS
4924        );
4925        assert_eq!(
4926            reverie::syscalls::Futex::new().signal_interrupt_errno(),
4927            Errno::ERESTARTSYS
4928        );
4929    }
4930
4931    #[test]
4932    fn kernel_restart_errno_matches_linux_restart_policy() {
4933        // Signal-state interruption hands the kernel the wait's own restart code, so
4934        // the guest's disposition decides between a handler's EINTR and a restart
4935        // (https://github.com/rrnewton/hermit/issues/3146).
4936        // A poll with a positive timeout and a timed futex wait end with Linux's own
4937        // code: a handler turns it into EINTR, and with no handler the kernel runs
4938        // restart_syscall, which Detcore resumes with the deadline it kept
4939        // (`RestartBlock`, https://github.com/rrnewton/hermit/issues/3358).
4940        assert_eq!(
4941            reverie::syscalls::Poll::new()
4942                .with_timeout(300)
4943                .kernel_restart_errno(),
4944            Errno::ERESTART_RESTARTBLOCK
4945        );
4946        // A zero timeout never blocks and a negative one never expires, so there is
4947        // no deadline to keep, and running the call again is Linux's restart.
4948        assert_eq!(
4949            reverie::syscalls::Poll::new().kernel_restart_errno(),
4950            Errno::ERESTARTNOHAND
4951        );
4952        assert_eq!(
4953            reverie::syscalls::Poll::new()
4954                .with_timeout(-1)
4955                .kernel_restart_errno(),
4956            Errno::ERESTARTNOHAND
4957        );
4958        assert_eq!(
4959            reverie::syscalls::Ppoll::new().kernel_restart_errno(),
4960            Errno::ERESTARTNOHAND
4961        );
4962        // epoll_wait and sigtimedwait never restart after a handler.
4963        assert_eq!(
4964            reverie::syscalls::EpollWait::new().kernel_restart_errno(),
4965            Errno::EINTR
4966        );
4967        assert_eq!(
4968            reverie::syscalls::RtSigtimedwait::new().kernel_restart_errno(),
4969            Errno::EINTR
4970        );
4971        assert_eq!(
4972            reverie::syscalls::Futex::new().kernel_restart_errno(),
4973            Errno::ERESTARTSYS
4974        );
4975        // A timed wait is never restarted after a handler runs. FUTEX_WAIT's timeout
4976        // is relative, so its deadline is kept as poll's is.
4977        let timeout = reverie::syscalls::Addr::from_raw(0x1000).unwrap();
4978        assert_eq!(
4979            reverie::syscalls::Futex::new()
4980                .with_timeout(Some(timeout))
4981                .kernel_restart_errno(),
4982            Errno::ERESTART_RESTARTBLOCK
4983        );
4984        // FUTEX_WAIT_BITSET's timeout is an absolute deadline, which Linux copies
4985        // into the restart block as it does FUTEX_WAIT's, so a deadline the guest
4986        // moves in memory after the wait began has no effect. Running the call
4987        // again, which ERESTARTNOHAND did, read the moved deadline (round-10
4988        // finding Medium 4 on https://github.com/rrnewton/hermit/pull/3361).
4989        let bitset = reverie::syscalls::Futex::new()
4990            .with_futex_op(libc::FUTEX_WAIT_BITSET | libc::FUTEX_PRIVATE_FLAG)
4991            .with_val3(-1);
4992        assert_eq!(bitset.kernel_restart_errno(), Errno::ERESTARTSYS);
4993        assert!(!bitset.restart_keeps_deadline());
4994        assert_eq!(
4995            bitset.with_timeout(Some(timeout)).kernel_restart_errno(),
4996            Errno::ERESTART_RESTARTBLOCK
4997        );
4998        assert!(bitset.with_timeout(Some(timeout)).restart_keeps_deadline());
4999    }
5000
5001    #[test]
5002    fn a_held_signal_is_reported_unless_it_is_sigstop() {
5003        // The backend passes a held signal on unreported when the call returns
5004        // ERESTART_RESTARTBLOCK, so a held signal other than SIGSTOP ends the wait
5005        // with ERESTARTNOHAND, which a handler also turns into EINTR.
5006        for signal in [libc::SIGUSR1, libc::SIGTERM, libc::SIGTSTP, libc::SIGCHLD] {
5007            assert_eq!(
5008                held_signal_restart_errno(Errno::ERESTART_RESTARTBLOCK, signal),
5009                Errno::ERESTARTNOHAND,
5010                "signal {signal}"
5011            );
5012        }
5013        // SIGSTOP is never reported, and its restart must keep the deadline.
5014        assert_eq!(
5015            held_signal_restart_errno(Errno::ERESTART_RESTARTBLOCK, libc::SIGSTOP),
5016            Errno::ERESTART_RESTARTBLOCK
5017        );
5018        // Every other restart code is the call's own.
5019        for errno in [
5020            Errno::ERESTARTNOHAND,
5021            Errno::ERESTARTSYS,
5022            Errno::ERESTARTNOINTR,
5023            Errno::EINTR,
5024        ] {
5025            for signal in [libc::SIGUSR1, libc::SIGSTOP] {
5026                assert_eq!(held_signal_restart_errno(errno, signal), errno);
5027            }
5028        }
5029    }
5030
5031    #[test]
5032    fn a_restart_block_resumes_only_at_the_interrupted_call() {
5033        let timeout = reverie::syscalls::Addr::from_raw(0x1000).unwrap();
5034        let block = RestartBlock {
5035            rip: 0x4000_1234,
5036            deadline: Some(LogicalTime::from_nanos(300_000_000)),
5037            call: RestartCall::Futex(reverie::syscalls::Futex::new().with_timeout(Some(timeout))),
5038        };
5039        // The kernel's restart runs restart_syscall at the interrupted call's address.
5040        assert_eq!(block.resumed_at(0x4000_1234), Some(block));
5041        // A restart_syscall anywhere else is the guest's own call.
5042        assert_eq!(block.resumed_at(0x4000_1236), None);
5043        assert_eq!(block.resumed_at(0x4000_1232), None);
5044    }
5045
5046    #[test]
5047    fn writev_signal_result_uses_disposition_and_progress() {
5048        let call = reverie::syscalls::Writev::new();
5049        for disposition in [
5050            WaitSignalDisposition::Interrupt,
5051            WaitSignalDisposition::Restart,
5052        ] {
5053            assert!(matches!(
5054                interrupted_write_result(&call, 0, Some(disposition)),
5055                Some(Err(Error::Errno(Errno::ERESTARTSYS)))
5056            ));
5057            assert!(matches!(
5058                interrupted_write_result(&call, 17, Some(disposition)),
5059                Some(Ok(17))
5060            ));
5061        }
5062        assert!(interrupted_write_result(&call, 0, None).is_none());
5063        assert!(interrupted_write_result(&call, 17, None).is_none());
5064    }
5065
5066    #[test]
5067    fn pipe_writev_requests_signal_disposition() {
5068        let dettid = DetTid::from_raw(42);
5069        let call = reverie::syscalls::Writev::new();
5070        let request = pipe_writev_resources(dettid, call);
5071
5072        assert_eq!(
5073            request.signal_interrupt_errno(),
5074            Some(Errno::ERESTARTSYS.into_raw())
5075        );
5076        assert!(request.decides_signal_interruption_itself);
5077        assert_eq!(request.resources.len(), 1);
5078    }
5079}
5080
5081/// `KernelSignalWait` against a scripted guest and a scripted `/proc` read
5082/// (`signal_state_read_seam`). No failure of the wait's signal handling may reach
5083/// the guest as an errno its wait call cannot return, and the guest must never
5084/// resume with every signal blocked
5085/// (https://github.com/rrnewton/hermit/issues/3146).
5086#[cfg(test)]
5087mod kernel_signal_wait_failures {
5088    use std::collections::VecDeque;
5089    use std::sync::Arc;
5090    use std::sync::Mutex;
5091
5092    use reverie::GlobalRPC;
5093    use reverie::GlobalTool;
5094    use reverie::Pid;
5095    use reverie::syscalls::LocalMemory;
5096
5097    use super::*;
5098    use crate::Config;
5099    use crate::GlobalState;
5100    use crate::ThreadState;
5101    use crate::syscalls::threads::KernelSignalState;
5102    use crate::syscalls::threads::kernel_sigset_bit;
5103    use crate::syscalls::threads::signal_state_read_seam;
5104    use crate::types::DetPid;
5105
5106    /// What an injected `rt_sigprocmask` does.
5107    #[derive(Clone, Copy, Debug)]
5108    enum MaskOutcome {
5109        /// The call runs: the mask changes and it returns 0.
5110        Apply,
5111        /// A signal stops the guest before the call runs: the mask is unchanged
5112        /// and the backend reports its restart errno.
5113        StoppedBefore,
5114        /// The call cannot run at all.
5115        Fail(Errno),
5116        /// `StoppedBefore`, by a signal that `/proc` never showed because it
5117        /// arrived after the read before the injection, such as a `SIGSTOP`
5118        /// sent from outside: the backend holds it in its single slot
5119        /// (`FakeKernel::held_slot`).
5120        StoppedBy(i32),
5121    }
5122
5123    /// The kernel's view of the guest thread, shared by the scripted `/proc`
5124    /// read and the scripted guest.
5125    #[derive(Default)]
5126    struct FakeKernel {
5127        /// The thread's mask (`SigBlk`).
5128        blocked: KernelSigset,
5129        /// Pending signals (`SigPnd | ShdPnd`).
5130        pending: KernelSigset,
5131        /// The signals of `pending` pending only on the thread group's shared
5132        /// queue (`ShdPnd`); every other one is on the thread's own
5133        /// (`SigPnd`).
5134        shared: KernelSigset,
5135        /// Signals with a handler (`SigCgt`).
5136        caught: KernelSigset,
5137        /// Signals whose disposition is `SIG_IGN` (`SigIgn`).
5138        ignored: KernelSigset,
5139        /// Whether a pending signal outside the mask stops each injection before
5140        /// the call runs, as on ptrace, where an ignored signal still queues for
5141        /// a traced task: it leaves the queue for the backend to hold
5142        /// (`taken`), and the injection reports a restart errno.
5143        stops_for_pending: bool,
5144        /// The signals that stopped an injection, in order.
5145        taken: Vec<i32>,
5146        /// Errors for the next reads, one per read.
5147        read_failures: VecDeque<Errno>,
5148        /// Outcomes for the next `rt_sigprocmask` calls; `Apply` once empty.
5149        outcomes: VecDeque<MaskOutcome>,
5150        /// Every mask the guest was asked to set, in order.
5151        requested: Vec<KernelSigset>,
5152        /// How many more signals that stop an injection are sent again, as by
5153        /// a sender faster than the injections: each such signal is pending
5154        /// again from the read after the one that follows the stop, which still
5155        /// shows it gone, so the stop is identified (`pending_repost`).
5156        repost_after_take: usize,
5157        /// The signals sent again, which the read after the next one shows.
5158        pending_repost: KernelSigset,
5159        /// The backend's one slot for a held signal: each signal that stops an
5160        /// injection (`taken`, `MaskOutcome::StoppedBy`) replaces the one there,
5161        /// as Reverie's ptrace backend does (`hold_pending_signal`).
5162        held_slot: Option<i32>,
5163        /// The signals that a stop dropped from `held_slot`, in order. A standard
5164        /// signal that replaces itself is merged, as Linux merges a second one
5165        /// sent while the first is pending, and is not lost.
5166        lost: Vec<i32>,
5167        /// Answers for the next `Guest::set_blocked_signals` calls: `None`
5168        /// sets the mask and returns the old one; once empty, every call is
5169        /// refused as `Unsupported`, as the trait's default refuses.
5170        setter: VecDeque<Option<MaskChangeRefused>>,
5171        /// Every mask `Guest::set_blocked_signals` was asked to set, in order.
5172        set_calls: Vec<KernelSigset>,
5173        /// The scheduler's answer to `HostTimedAndPrivateSigchld`: the
5174        /// host-timed signals, then the recorded private `SIGCHLD`. `None`
5175        /// panics, as every other request does.
5176        private_record: Option<(KernelSigset, KernelSigset)>,
5177    }
5178
5179    impl FakeKernel {
5180        /// The backend holds `signal`, which stopped an injection.
5181        fn hold(&mut self, signal: i32) {
5182            if let Some(previous) = self.held_slot.replace(signal)
5183                && !(previous == signal && signal < KERNEL_SIGRTMIN)
5184            {
5185                self.lost.push(previous);
5186            }
5187        }
5188    }
5189
5190    type Kernel = Arc<Mutex<FakeKernel>>;
5191
5192    /// Room for one mask, 8-byte aligned like a real stack slot.
5193    const ARENA_WORDS: usize = 2;
5194
5195    /// A scratch stack in this process's memory whose commit can fail like the
5196    /// ptrace scratch below an `rsp` with no writable memory under it
5197    /// (https://github.com/rrnewton/hermit/issues/3328).
5198    struct WaitStack {
5199        commit_fails: bool,
5200        arena: usize,
5201    }
5202
5203    struct WaitStackGuard;
5204
5205    impl Drop for WaitStackGuard {
5206        fn drop(&mut self) {}
5207    }
5208
5209    impl reverie::Stack for WaitStack {
5210        type StackGuard = WaitStackGuard;
5211
5212        fn size(&self) -> usize {
5213            panic!("a blocked wait must not query the scratch size")
5214        }
5215        fn capacity(&self) -> usize {
5216            panic!("a blocked wait must not query the scratch capacity")
5217        }
5218        fn push<'stack, T>(&mut self, value: T) -> Addr<'stack, T> {
5219            assert!(std::mem::size_of::<T>() <= ARENA_WORDS * std::mem::size_of::<u64>());
5220            // SAFETY: the arena is a live, 8-byte aligned buffer owned by the guest,
5221            // large enough for `T` (asserted above).
5222            unsafe { std::ptr::write(self.arena as *mut T, value) };
5223            Addr::from_raw(self.arena).unwrap()
5224        }
5225        fn reserve<'stack, T>(&mut self) -> AddrMut<'stack, T> {
5226            panic!("a blocked wait pushes its mask rather than reserving room")
5227        }
5228        fn commit(self) -> Result<Self::StackGuard, Errno> {
5229            if self.commit_fails {
5230                Err(Errno::EFAULT)
5231            } else {
5232                Ok(WaitStackGuard)
5233            }
5234        }
5235    }
5236
5237    struct WaitGuest {
5238        config: Config,
5239        thread: ThreadState<()>,
5240        pid: Pid,
5241        tid: Pid,
5242        commit_fails: bool,
5243        arena: Box<[u64; ARENA_WORDS]>,
5244        kernel: Kernel,
5245    }
5246
5247    impl WaitGuest {
5248        /// A guest for thread `tid` of this process, with the guest's own `mask`
5249        /// installed.
5250        fn new(tid: Pid, mask: KernelSigset) -> (Self, Kernel) {
5251            let config = Config::default();
5252            let thread = ThreadState::new(DetPid::from_raw(1), &config, ());
5253            let kernel = Arc::new(Mutex::new(FakeKernel {
5254                blocked: mask,
5255                ..FakeKernel::default()
5256            }));
5257            let guest = Self {
5258                config,
5259                thread,
5260                pid: Pid::from_raw(std::process::id() as i32),
5261                tid,
5262                commit_fails: false,
5263                arena: Box::new([u64::MAX; ARENA_WORDS]),
5264                kernel: kernel.clone(),
5265            };
5266            (guest, kernel)
5267        }
5268
5269        /// A guest for the calling thread, which exists.
5270        fn live(mask: KernelSigset) -> (Self, Kernel) {
5271            // SAFETY: gettid has no preconditions.
5272            Self::new(Pid::from_raw(unsafe { libc::gettid() }), mask)
5273        }
5274    }
5275
5276    #[test]
5277    fn inherited_input_exempts_only_authenticated_reads_from_the_internal_guard() {
5278        use std::os::fd::AsRawFd;
5279        let (mut guest, _) = WaitGuest::live(guest_mask());
5280        let slot = tempfile::tempfile().unwrap();
5281        let fd = slot.as_raw_fd();
5282        let input = reverie::InheritedInput::pipe(fd).unwrap();
5283        let identity = input.identity().clone();
5284        let (reader, _writer) = input.into_reader_and_writer();
5285        assert_eq!(unsafe { libc::dup2(reader.as_raw_fd(), fd) }, fd);
5286        guest
5287            .thread
5288            .add_fd(fd, nix::fcntl::OFlag::O_RDONLY, FdType::Pipe, None)
5289            .unwrap();
5290        let calls = [
5291            Syscall::from(syscalls::Read::new().with_fd(fd)),
5292            Syscall::from(syscalls::Readv::new().with_fd(fd)),
5293            Syscall::from(syscalls::Write::new().with_fd(fd)),
5294            Syscall::from(syscalls::Writev::new().with_fd(fd)),
5295        ];
5296        for call in calls {
5297            assert!(syscall_targets_internal_fd(&mut guest, call));
5298        }
5299        guest
5300            .thread
5301            .file_metadata
5302            .lock()
5303            .unwrap()
5304            .apply_exec_fd_state(
5305                guest.thread.dettid,
5306                crate::tool_local::ExecFdState {
5307                    initial_input: Some(identity),
5308                    ..Default::default()
5309                },
5310                true,
5311            )
5312            .unwrap();
5313        for (index, call) in calls.into_iter().enumerate() {
5314            assert_eq!(syscall_targets_internal_fd(&mut guest, call), index >= 2);
5315        }
5316        assert!(
5317            !guest
5318                .thread
5319                .with_detfd(fd, |d| d.physically_nonblocking())
5320                .unwrap()
5321        );
5322        assert_eq!(
5323            unsafe { libc::fcntl(fd, libc::F_GETFL) } & libc::O_NONBLOCK,
5324            0
5325        );
5326        let (internal, _writer) = nix::unistd::pipe().unwrap();
5327        guest
5328            .thread
5329            .add_fd(
5330                internal.as_raw_fd(),
5331                nix::fcntl::OFlag::O_RDONLY,
5332                FdType::Pipe,
5333                None,
5334            )
5335            .unwrap();
5336        assert!(syscall_targets_internal_fd(
5337            &mut guest,
5338            syscalls::Read::new().with_fd(internal.as_raw_fd()).into()
5339        ));
5340        // Socketpair ownership remains internal as well.
5341        let (socket, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
5342        guest
5343            .thread
5344            .add_fd(
5345                socket.as_raw_fd(),
5346                nix::fcntl::OFlag::O_RDWR,
5347                FdType::Socket,
5348                None,
5349            )
5350            .unwrap();
5351        guest
5352            .thread
5353            .with_detfd(socket.as_raw_fd(), |d| d.set_socketpair_endpoint())
5354            .unwrap();
5355        assert!(syscall_targets_internal_fd(
5356            &mut guest,
5357            syscalls::Readv::new().with_fd(socket.as_raw_fd()).into()
5358        ));
5359    }
5360
5361    /// Answer this thread's `/proc` reads from `kernel` until the result drops.
5362    fn scripted_proc(kernel: &Kernel) -> signal_state_read_seam::Installed {
5363        let kernel = kernel.clone();
5364        signal_state_read_seam::install(move |_, _| {
5365            let mut kernel = kernel.lock().unwrap();
5366            let read = match kernel.read_failures.pop_front() {
5367                Some(errno) => Err(errno),
5368                None => Ok(KernelSignalState {
5369                    pending: kernel.pending,
5370                    thread_pending: kernel.pending & !kernel.shared,
5371                    shared_pending: kernel.pending & kernel.shared,
5372                    blocked: kernel.blocked,
5373                    caught: kernel.caught,
5374                    ignored: kernel.ignored,
5375                }),
5376            };
5377            kernel.pending |= std::mem::take(&mut kernel.pending_repost);
5378            Some(read)
5379        })
5380    }
5381
5382    #[reverie::tool]
5383    impl GlobalRPC<GlobalState> for WaitGuest {
5384        async fn send_rpc(
5385            &self,
5386            message: <GlobalState as GlobalTool>::Request,
5387        ) -> <GlobalState as GlobalTool>::Response {
5388            match (&message.2, self.kernel.lock().unwrap().private_record) {
5389                (
5390                    crate::tool_global::GlobalRequest::HostTimedAndPrivateSigchld(_),
5391                    Some((host_timed, private)),
5392                ) => (
5393                    None,
5394                    crate::tool_global::GlobalResponse::HostTimedAndPrivateSigchld(
5395                        host_timed, private,
5396                    ),
5397                ),
5398                _ => panic!("these waits must not send an RPC: {:?}", message.2),
5399            }
5400        }
5401        fn config(&self) -> &Config {
5402            &self.config
5403        }
5404    }
5405
5406    #[reverie::tool]
5407    impl Guest<Detcore> for WaitGuest {
5408        type Memory = LocalMemory;
5409        type Stack = WaitStack;
5410
5411        fn tid(&self) -> Pid {
5412            self.tid
5413        }
5414        fn pid(&self) -> Pid {
5415            self.pid
5416        }
5417        fn ppid(&self) -> Option<Pid> {
5418            None
5419        }
5420        fn memory(&self) -> Self::Memory {
5421            LocalMemory::new()
5422        }
5423        fn thread_state_mut(&mut self) -> &mut ThreadState<()> {
5424            &mut self.thread
5425        }
5426        fn thread_state(&self) -> &ThreadState<()> {
5427            &self.thread
5428        }
5429        async fn regs(&mut self) -> libc::user_regs_struct {
5430            panic!("a blocked wait must not read registers")
5431        }
5432        async fn stack(&mut self) -> Self::Stack {
5433            WaitStack {
5434                commit_fails: self.commit_fails,
5435                arena: self.arena.as_mut_ptr() as usize,
5436            }
5437        }
5438        async fn daemonize(&mut self) {
5439            panic!("a blocked wait must not daemonize")
5440        }
5441        async fn inject<S: SyscallInfo>(&mut self, syscall: S) -> Result<i64, Errno> {
5442            let (number, args) = syscall.into_parts();
5443            let Syscall::RtSigprocmask(call) = Syscall::from_raw(number, args) else {
5444                panic!("a blocked wait injected {number}, not rt_sigprocmask")
5445            };
5446            assert_eq!(call.how(), libc::SIG_SETMASK);
5447            assert!(call.oldset().is_none());
5448            let set = call.set().expect("rt_sigprocmask without a mask");
5449            let mask: KernelSigset = LocalMemory::new().read_value(set.cast::<KernelSigset>())?;
5450            let mut kernel = self.kernel.lock().unwrap();
5451            kernel.requested.push(mask);
5452            let deliverable = kernel.pending & !kernel.blocked;
5453            if kernel.stops_for_pending && deliverable != 0 {
5454                let signal = deliverable.trailing_zeros() as i32 + 1;
5455                kernel.pending &= !kernel_sigset_bit(signal);
5456                kernel.taken.push(signal);
5457                kernel.hold(signal);
5458                if kernel.repost_after_take > 0 {
5459                    kernel.repost_after_take -= 1;
5460                    kernel.pending_repost |= kernel_sigset_bit(signal);
5461                }
5462                return Err(Errno::ERESTARTSYS);
5463            }
5464            match kernel.outcomes.pop_front().unwrap_or(MaskOutcome::Apply) {
5465                MaskOutcome::Apply => {
5466                    kernel.blocked = mask;
5467                    Ok(0)
5468                }
5469                MaskOutcome::StoppedBefore => Err(Errno::ERESTARTNOINTR),
5470                MaskOutcome::StoppedBy(signal) => {
5471                    kernel.hold(signal);
5472                    Err(Errno::ERESTARTNOINTR)
5473                }
5474                MaskOutcome::Fail(errno) => Err(errno),
5475            }
5476        }
5477        async fn set_blocked_signals(&mut self, mask: u64) -> Result<u64, MaskChangeRefused> {
5478            let mut kernel = self.kernel.lock().unwrap();
5479            kernel.set_calls.push(mask);
5480            match kernel.setter.pop_front() {
5481                Some(None) => Ok(std::mem::replace(&mut kernel.blocked, mask)),
5482                Some(Some(refused)) => Err(refused),
5483                None => Err(MaskChangeRefused::Unsupported),
5484            }
5485        }
5486
5487        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
5488            panic!("a blocked wait must not retire the guest")
5489        }
5490        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
5491            panic!("a blocked wait must not set a timer")
5492        }
5493        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
5494            panic!("a blocked wait must not set a timer")
5495        }
5496        fn read_clock(&mut self) -> Result<u64, Error> {
5497            panic!("a blocked wait must not read a clock")
5498        }
5499    }
5500
5501    /// The guest's own mask in these tests.
5502    fn guest_mask() -> KernelSigset {
5503        kernel_sigset_bit(libc::SIGUSR2)
5504    }
5505
5506    /// The diagnostic a result ends the run with.
5507    fn diagnostic<V: std::fmt::Debug>(result: Result<V, Error>) -> BlockedWaitSignalError {
5508        match result {
5509            Err(Error::Tool(error)) => *error
5510                .downcast_ref::<BlockedWaitSignalError>()
5511                .unwrap_or_else(|| panic!("not a blocked-wait diagnostic: {error:#}")),
5512            other => panic!("expected the run to end with a diagnostic, got {other:?}"),
5513        }
5514    }
5515
5516    /// The held-signal refusal a result ends the wait with.
5517    fn refusal<V: std::fmt::Debug>(result: Result<V, Error>) -> HeldSignalRefusal {
5518        match result {
5519            Err(Error::Tool(error)) => *error
5520                .downcast_ref::<HeldSignalRefusal>()
5521                .unwrap_or_else(|| panic!("not a held-signal refusal: {error:#}")),
5522            other => panic!("expected the wait to end with a held-signal refusal, got {other:?}"),
5523        }
5524    }
5525
5526    /// A wait whose guest mask `block` replaced with the all-blocked mask.
5527    async fn blocked_wait(guest: &mut WaitGuest, kernel: &Kernel) -> KernelSignalWait {
5528        let mut wait = KernelSignalWait::new(guest, 0, false, Errno::ERESTARTSYS);
5529        wait.block(guest, None).await.unwrap();
5530        assert!(!wait.needs_block());
5531        assert_eq!(kernel.lock().unwrap().blocked, blocked_signal_mask());
5532        wait
5533    }
5534
5535    /// Each stopped attempt is a stop by a signal that `/proc` cannot identify,
5536    /// which the backend holds in place of the one before. `restore` used to
5537    /// return success here; the second stop drops the first unidentified one,
5538    /// which may matter, so the mask is still put back and the wait now ends
5539    /// with a `HeldSignalRefusal`, as a wait loop that meets two such stops
5540    /// does (round-11 High F1 on
5541    /// https://github.com/rrnewton/hermit/pull/3361).
5542    #[tokio::test]
5543    async fn restore_repeats_the_mask_change_until_the_kernel_reports_it() {
5544        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5545        let _proc = scripted_proc(&kernel);
5546        let mut wait = blocked_wait(&mut guest, &kernel).await;
5547        kernel
5548            .lock()
5549            .unwrap()
5550            .outcomes
5551            .extend([MaskOutcome::StoppedBefore; 5]);
5552
5553        let result = wait.restore(&mut guest, None).await;
5554
5555        assert_eq!(
5556            refusal(result),
5557            HeldSignalRefusal {
5558                wait: None,
5559                held: None,
5560                replacing: None,
5561                loss: HeldSignalLoss::Restoration,
5562            }
5563        );
5564        let kernel = kernel.lock().unwrap();
5565        assert_eq!(kernel.blocked, guest_mask());
5566        assert_eq!(
5567            kernel.requested.len(),
5568            1 + 6,
5569            "block, then five stopped attempts and one that ran"
5570        );
5571        assert!(
5572            kernel.requested[1..]
5573                .iter()
5574                .all(|&mask| mask == guest_mask())
5575        );
5576    }
5577
5578    #[tokio::test]
5579    async fn a_mask_that_signals_keep_stopping_ends_the_run_instead_of_resuming_the_guest() {
5580        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5581        let _proc = scripted_proc(&kernel);
5582        let mut wait = blocked_wait(&mut guest, &kernel).await;
5583        kernel
5584            .lock()
5585            .unwrap()
5586            .outcomes
5587            .extend([MaskOutcome::StoppedBefore; 64]);
5588
5589        let error = diagnostic(wait.restore(&mut guest, None).await);
5590
5591        assert_eq!(
5592            error,
5593            BlockedWaitSignalError::MaskNotRestored {
5594                pid: guest.pid,
5595                tid: guest.tid,
5596                attempts: 16,
5597                last_error: Some(Errno::ERESTARTNOINTR),
5598            }
5599        );
5600        let message = error.to_string();
5601        assert!(
5602            message.starts_with("cannot restore the signal mask of guest thread")
5603                && message.contains("(16 attempts, last error ")
5604                && message.contains("ERESTARTNOINTR")
5605                && message.ends_with("); it would resume with every signal blocked"),
5606            "{message}"
5607        );
5608        assert_eq!(kernel.lock().unwrap().requested.len(), 1 + 16);
5609    }
5610
5611    #[tokio::test]
5612    async fn a_mask_change_that_cannot_run_ends_the_run_instead_of_resuming_the_guest() {
5613        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5614        let _proc = scripted_proc(&kernel);
5615        let mut wait = blocked_wait(&mut guest, &kernel).await;
5616        kernel
5617            .lock()
5618            .unwrap()
5619            .outcomes
5620            .push_back(MaskOutcome::Fail(Errno::EFAULT));
5621
5622        let error = diagnostic(wait.restore(&mut guest, None).await);
5623
5624        assert_eq!(
5625            error,
5626            BlockedWaitSignalError::MaskNotRestored {
5627                pid: guest.pid,
5628                tid: guest.tid,
5629                attempts: 1,
5630                last_error: Some(Errno::EFAULT),
5631            }
5632        );
5633    }
5634
5635    /// `block_in_place` blocks through `Guest::set_blocked_signals`, with no
5636    /// injection, and `restore` puts the guest's mask back the same way: no
5637    /// scratch memory is touched, so a stack with no room below it (a failing
5638    /// commit) changes nothing (Claude review of the R2b-2 design, M1).
5639    #[tokio::test]
5640    async fn an_in_place_block_and_its_restore_make_no_injection() {
5641        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5642        let _proc = scripted_proc(&kernel);
5643        guest.commit_fails = true;
5644        kernel.lock().unwrap().setter.extend([None, None]);
5645        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5646        assert!(wait.block_in_place(&mut guest, 0).await.unwrap());
5647        assert_eq!(wait.effective_mask(), Some(guest_mask()));
5648        assert_eq!(
5649            kernel.lock().unwrap().blocked,
5650            blocked_signal_mask() | guest_mask()
5651        );
5652        wait.restore(&mut guest, None).await.unwrap();
5653        let kernel = kernel.lock().unwrap();
5654        assert_eq!(kernel.blocked, guest_mask());
5655        assert_eq!(
5656            kernel.set_calls,
5657            vec![blocked_signal_mask() | guest_mask(), guest_mask()]
5658        );
5659        assert!(
5660            kernel.requested.is_empty(),
5661            "no rt_sigprocmask was injected"
5662        );
5663        assert_eq!(wait.effective_mask(), None);
5664    }
5665
5666    /// The in-place block holds the turn's host-timed signals until the call
5667    /// returns (`hold_until_return`), as `install_turn_mask` does for
5668    /// `writev`, so a fallback injected restoration that one of them stops
5669    /// holds it rather than counting it lost (Claude re-check of R2b-2 stage
5670    /// 2, F2).
5671    #[tokio::test]
5672    async fn an_in_place_block_holds_the_host_timed_signals() {
5673        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5674        let _proc = scripted_proc(&kernel);
5675        kernel.lock().unwrap().setter.push_back(None);
5676        let host_timed = kernel_sigset_bit(libc::SIGIO) | kernel_sigset_bit(libc::SIGHUP);
5677        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5678        assert!(wait.block_in_place(&mut guest, host_timed).await.unwrap());
5679        assert_eq!(wait.held_until_return & host_timed, host_timed);
5680        assert_eq!(wait.host_timed & host_timed, host_timed);
5681    }
5682
5683    /// A refused in-place block changes nothing: the wait goes on under the
5684    /// guest's own mask, does not try again (`needs_block`), and has nothing
5685    /// to restore.
5686    #[tokio::test]
5687    async fn a_refused_in_place_block_leaves_the_guest_mask() {
5688        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5689        let _proc = scripted_proc(&kernel);
5690        kernel
5691            .lock()
5692            .unwrap()
5693            .setter
5694            .push_back(Some(MaskChangeRefused::RestorePending {
5695                saved: guest_mask(),
5696                effective: 0,
5697            }));
5698        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5699        assert!(!wait.block_in_place(&mut guest, 0).await.unwrap());
5700        assert!(!wait.needs_block());
5701        assert_eq!(wait.effective_mask(), None);
5702        wait.restore(&mut guest, None).await.unwrap();
5703        let kernel = kernel.lock().unwrap();
5704        assert_eq!(kernel.blocked, guest_mask());
5705        assert_eq!(kernel.set_calls.len(), 1);
5706        assert!(kernel.requested.is_empty());
5707    }
5708
5709    /// A restore the setter refuses falls back to the injected restoration,
5710    /// which puts the guest's mask back (the reviews of
5711    /// https://github.com/rrnewton/reverie/pull/1083, F4).
5712    #[tokio::test]
5713    async fn a_refused_in_place_restore_falls_back_to_an_injection() {
5714        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5715        let _proc = scripted_proc(&kernel);
5716        kernel
5717            .lock()
5718            .unwrap()
5719            .setter
5720            .extend([None, Some(MaskChangeRefused::Unsupported)]);
5721        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5722        assert!(wait.block_in_place(&mut guest, 0).await.unwrap());
5723        wait.restore(&mut guest, None).await.unwrap();
5724        let kernel = kernel.lock().unwrap();
5725        assert_eq!(kernel.blocked, guest_mask());
5726        assert_eq!(kernel.requested, vec![guest_mask()], "one injected restore");
5727    }
5728
5729    /// A block or restore whose failure leaves the mask unknown ends the run
5730    /// before the guest resumes.
5731    #[tokio::test]
5732    async fn an_unknown_mask_after_an_in_place_change_ends_the_run() {
5733        let unknown = Some(MaskChangeRefused::Failed {
5734            errno: Errno::EIO,
5735            mask_unknown: true,
5736        });
5737        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5738        let _proc = scripted_proc(&kernel);
5739        let not_restored = BlockedWaitSignalError::MaskNotRestored {
5740            pid: guest.pid,
5741            tid: guest.tid,
5742            attempts: 1,
5743            last_error: Some(Errno::EIO),
5744        };
5745        kernel.lock().unwrap().setter.push_back(unknown);
5746        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5747        assert_eq!(
5748            diagnostic(wait.block_in_place(&mut guest, 0).await),
5749            not_restored
5750        );
5751
5752        kernel.lock().unwrap().setter.extend([None, unknown]);
5753        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5754        assert!(wait.block_in_place(&mut guest, 0).await.unwrap());
5755        assert_eq!(
5756            diagnostic(wait.restore(&mut guest, None).await),
5757            not_restored
5758        );
5759        assert!(kernel.lock().unwrap().requested.is_empty());
5760    }
5761
5762    /// A thread that is gone when the mask goes back has nothing to restore.
5763    #[tokio::test]
5764    async fn a_gone_thread_needs_no_restore() {
5765        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5766        let _proc = scripted_proc(&kernel);
5767        kernel
5768            .lock()
5769            .unwrap()
5770            .setter
5771            .extend([None, Some(MaskChangeRefused::Gone)]);
5772        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5773        assert!(wait.block_in_place(&mut guest, 0).await.unwrap());
5774        wait.restore(&mut guest, None).await.unwrap();
5775        assert!(kernel.lock().unwrap().requested.is_empty());
5776    }
5777
5778    #[tokio::test]
5779    async fn an_unreadable_signal_state_of_a_live_thread_ends_the_run() {
5780        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5781        let _proc = scripted_proc(&kernel);
5782        let (pid, tid) = (guest.pid, guest.tid);
5783        let expected = |errno| BlockedWaitSignalError::StateUnreadable { pid, tid, errno };
5784
5785        // The turn's check, before the mask is set.
5786        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5787        kernel.lock().unwrap().read_failures.push_back(Errno::EIO);
5788        assert_eq!(diagnostic(wait.interrupted()), expected(Errno::EIO));
5789
5790        // `block`'s read of the guest's mask.
5791        kernel.lock().unwrap().read_failures.push_back(Errno::ESRCH);
5792        assert_eq!(
5793            diagnostic(wait.block(&mut guest, None).await),
5794            expected(Errno::ESRCH)
5795        );
5796        assert!(kernel.lock().unwrap().requested.is_empty());
5797
5798        // `restore`'s read, with every signal blocked.
5799        wait.block(&mut guest, None).await.unwrap();
5800        kernel.lock().unwrap().read_failures.push_back(Errno::ESRCH);
5801        assert_eq!(
5802            diagnostic(wait.restore(&mut guest, None).await),
5803            expected(Errno::ESRCH)
5804        );
5805        let error = expected(Errno::EIO).to_string();
5806        assert!(
5807            error.starts_with("cannot read the signal state of guest thread"),
5808            "{error}"
5809        );
5810    }
5811
5812    #[tokio::test]
5813    async fn a_thread_that_no_longer_exists_ends_its_wait_with_erestartnointr() {
5814        // SAFETY: gettid has no preconditions.
5815        let exited = std::thread::spawn(|| unsafe { libc::gettid() })
5816            .join()
5817            .unwrap();
5818        // `join` returns when the kernel clears the thread's TID word, early in
5819        // its exit; the thread stays in `/proc` and answers `tgkill` until the
5820        // kernel releases it a moment later. Measured on the development host,
5821        // 62 of 20000 joined threads were still listed right after `join`, and
5822        // a GitHub-hosted run read such a thread's status here
5823        // (https://github.com/rrnewton/hermit/actions/runs/37683205050). So wait
5824        // for the release. The path is in this process's own task directory, so
5825        // no other process's thread can appear under it, and Linux hands out
5826        // TIDs cyclically, so this one is not reissued here before the counter
5827        // wraps.
5828        let task = format!("/proc/self/task/{exited}");
5829        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
5830        while std::path::Path::new(&task).exists() {
5831            assert!(
5832                std::time::Instant::now() < deadline,
5833                "thread {exited} is still in /proc 10 s after it was joined"
5834            );
5835            std::thread::sleep(std::time::Duration::from_millis(1));
5836        }
5837        let (guest, _kernel) = WaitGuest::new(Pid::from_raw(exited), guest_mask());
5838        // No script: the read goes to the real `/proc`, where the thread is gone.
5839
5840        let wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5841        assert!(matches!(
5842            wait.interrupted(),
5843            Err(Error::Errno(Errno::ERESTARTNOINTR))
5844        ));
5845        assert!(matches!(
5846            read_wait_signal_state(guest.pid, guest.tid),
5847            Err(Error::Errno(Errno::ERESTARTNOINTR))
5848        ));
5849    }
5850
5851    #[tokio::test]
5852    async fn a_stack_with_no_scratch_room_leaves_the_wait_under_the_guest_mask() {
5853        let (mut guest, kernel) = WaitGuest::live(guest_mask());
5854        guest.commit_fails = true;
5855        let _proc = scripted_proc(&kernel);
5856        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5857
5858        wait.block(&mut guest, None).await.unwrap();
5859
5860        assert!(!wait.needs_block(), "block must not be tried again");
5861        assert_eq!(kernel.lock().unwrap().blocked, guest_mask());
5862        assert!(kernel.lock().unwrap().requested.is_empty());
5863
5864        // Later turns classify against the guest's own mask, read each turn.
5865        {
5866            let mut kernel = kernel.lock().unwrap();
5867            kernel.caught = kernel_sigset_bit(libc::SIGUSR1) | kernel_sigset_bit(libc::SIGUSR2);
5868            kernel.pending = kernel_sigset_bit(libc::SIGUSR2);
5869        }
5870        assert!(!wait.interrupted().unwrap(), "SIGUSR2 is blocked");
5871        kernel.lock().unwrap().pending = kernel_sigset_bit(libc::SIGUSR1);
5872        assert!(wait.interrupted().unwrap(), "SIGUSR1 is not blocked");
5873
5874        wait.restore(&mut guest, None).await.unwrap();
5875        assert!(
5876            kernel.lock().unwrap().requested.is_empty(),
5877            "nothing to put back"
5878        );
5879        assert_eq!(kernel.lock().unwrap().blocked, guest_mask());
5880    }
5881
5882    /// A guest whose injections a pending signal outside the mask stops, as on
5883    /// ptrace, with `pending` queued and `ignored` set to `SIG_IGN`.
5884    fn stopping_guest(pending: KernelSigset, ignored: KernelSigset) -> (WaitGuest, Kernel) {
5885        let (guest, kernel) = WaitGuest::live(guest_mask());
5886        {
5887            let mut kernel = kernel.lock().unwrap();
5888            kernel.stops_for_pending = true;
5889            kernel.pending = pending;
5890            kernel.ignored = ignored;
5891        }
5892        (guest, kernel)
5893    }
5894
5895    /// Inject a mask change to `mask` through `wait.inject_absorbing`.
5896    async fn inject_mask_absorbing(
5897        wait: &mut KernelSignalWait,
5898        guest: &mut WaitGuest,
5899        mask: KernelSigset,
5900    ) -> Result<Result<i64, Errno>, Error> {
5901        let mut stack = guest.stack().await;
5902        let cell = stack.push(mask);
5903        let _guard = stack.commit().unwrap();
5904        wait.inject_absorbing(guest, set_signal_mask_call(cell))
5905            .await
5906    }
5907
5908    /// An ignored signal that was already pending stops the mask change of
5909    /// `block`, which used to end the wait with a restart (review finding F2 on
5910    /// https://github.com/rrnewton/hermit/pull/3361). Linux would not end the
5911    /// wait for it, so the stop is absorbed: the backend holds the signal, the
5912    /// change runs again, and the held signal does not interrupt the wait.
5913    #[tokio::test]
5914    async fn an_ignored_signal_that_stops_the_mask_change_does_not_end_the_wait() {
5915        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
5916        let (mut guest, kernel) = stopping_guest(usr1, usr1);
5917        let _proc = scripted_proc(&kernel);
5918        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5919
5920        wait.block(&mut guest, None).await.unwrap();
5921
5922        assert!(!wait.needs_block());
5923        let all_blocked = blocked_signal_mask() | guest_mask();
5924        {
5925            let kernel = kernel.lock().unwrap();
5926            assert_eq!(kernel.taken, vec![libc::SIGUSR1]);
5927            assert_eq!(kernel.requested, vec![all_blocked, all_blocked]);
5928            assert_eq!(kernel.blocked, all_blocked);
5929        }
5930        assert_eq!(
5931            wait.held,
5932            Some(HeldSignal {
5933                signal: libc::SIGUSR1,
5934                queue: SignalQueue::Thread,
5935                kind: HeldKind::Harmless,
5936            })
5937        );
5938        assert!(
5939            !wait.interrupted().unwrap(),
5940            "an ignored signal does not end the wait"
5941        );
5942        wait.restore(&mut guest, None).await.unwrap();
5943        assert_eq!(kernel.lock().unwrap().blocked, guest_mask());
5944    }
5945
5946    /// A default-ignored signal that stops an injection is held the same way,
5947    /// and the injection then returns its own result (review finding F2 on
5948    /// https://github.com/rrnewton/hermit/pull/3361).
5949    #[tokio::test]
5950    async fn a_default_ignored_signal_that_stops_an_injection_is_held() {
5951        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGWINCH), 0);
5952        let _proc = scripted_proc(&kernel);
5953        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5954
5955        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
5956
5957        assert!(matches!(result, Ok(Ok(0))), "{result:?}");
5958        assert_eq!(kernel.lock().unwrap().taken, vec![libc::SIGWINCH]);
5959        assert_eq!(kernel.lock().unwrap().requested.len(), 2);
5960        assert_eq!(wait.held.map(|held| held.kind), Some(HeldKind::Harmless));
5961        assert!(!wait.interrupted().unwrap());
5962    }
5963
5964    /// A pending signal that would end the wait natively ends it before any
5965    /// injection, with the restart errno, and stays queued for the guest.
5966    #[tokio::test]
5967    async fn a_pending_caught_signal_ends_the_wait_before_the_injection() {
5968        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
5969        let (mut guest, kernel) = stopping_guest(usr1, 0);
5970        kernel.lock().unwrap().caught = usr1;
5971        let _proc = scripted_proc(&kernel);
5972        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
5973
5974        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
5975
5976        assert!(
5977            matches!(result, Err(Error::Errno(Errno::ERESTARTSYS))),
5978            "{result:?}"
5979        );
5980        let kernel = kernel.lock().unwrap();
5981        assert!(kernel.requested.is_empty(), "nothing is injected");
5982        assert_eq!(kernel.pending, usr1);
5983        assert_eq!(wait.held, None);
5984    }
5985
5986    /// The backend holds one signal. Once it holds one whose loss would matter,
5987    /// a `SIGCHLD` here, an injection that a different pending signal would stop
5988    /// is not made. The wait used to end with `ERESTARTNOINTR`, a transparent
5989    /// restart; it now ends with a `HeldSignalRefusal`, which its caller turns
5990    /// into the unsupported-operation refusal (round-10 High 1 on
5991    /// https://github.com/rrnewton/hermit/pull/3361).
5992    #[tokio::test]
5993    async fn a_held_sigchld_is_never_replaced_by_another_stop() {
5994        let (mut guest, kernel) = stopping_guest(
5995            kernel_sigset_bit(libc::SIGCHLD) | kernel_sigset_bit(libc::SIGWINCH),
5996            0,
5997        );
5998        let _proc = scripted_proc(&kernel);
5999        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
6000
6001        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6002
6003        assert_eq!(
6004            refusal(result),
6005            HeldSignalRefusal {
6006                wait: None,
6007                held: Some(libc::SIGCHLD),
6008                replacing: Some(libc::SIGWINCH),
6009                loss: HeldSignalLoss::Replaced,
6010            }
6011        );
6012        let kernel = kernel.lock().unwrap();
6013        assert_eq!(kernel.taken, vec![libc::SIGCHLD]);
6014        assert_eq!(
6015            kernel.requested.len(),
6016            1,
6017            "the second injection is not made"
6018        );
6019        assert_eq!(kernel.pending, kernel_sigset_bit(libc::SIGWINCH));
6020        assert_eq!(wait.held.map(|held| held.kind), Some(HeldKind::Precious));
6021    }
6022
6023    /// A wait whose `block` was stopped by a default `SIGCHLD`, which the
6024    /// backend holds as a signal whose loss matters (`HeldKind::Precious`).
6025    async fn wait_holding_sigchld(guest: &mut WaitGuest, kernel: &Kernel) -> KernelSignalWait {
6026        let mut wait = KernelSignalWait::new(&*guest, 0, false, Errno::ERESTARTSYS);
6027        wait.block(guest, None).await.unwrap();
6028        assert_eq!(
6029            wait.held.map(|held| (held.signal, held.kind)),
6030            Some((libc::SIGCHLD, HeldKind::Precious))
6031        );
6032        let kernel = kernel.lock().unwrap();
6033        assert_eq!(kernel.blocked, blocked_signal_mask() | guest_mask());
6034        assert_eq!(kernel.held_slot, Some(libc::SIGCHLD));
6035        wait
6036    }
6037
6038    /// A signal that `/proc` never showed, a `SIGSTOP` sent from outside here,
6039    /// stops the injection that puts the guest's mask back before it runs, and
6040    /// the next attempt runs. The backend holds one signal, so the `SIGSTOP`
6041    /// replaced the held `SIGCHLD`, and `restore` used to return success, so
6042    /// the guest resumed without its `SIGCHLD` (round-11 High F1 on
6043    /// https://github.com/rrnewton/hermit/pull/3361). The mask is still put
6044    /// back, and the wait now ends with a `HeldSignalRefusal`.
6045    #[tokio::test]
6046    async fn a_stop_of_the_mask_restoration_that_replaces_a_held_sigchld_is_refused() {
6047        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGCHLD), 0);
6048        let _proc = scripted_proc(&kernel);
6049        let mut wait = wait_holding_sigchld(&mut guest, &kernel).await;
6050        kernel
6051            .lock()
6052            .unwrap()
6053            .outcomes
6054            .push_back(MaskOutcome::StoppedBy(libc::SIGSTOP));
6055
6056        let result = wait.restore(&mut guest, None).await;
6057
6058        {
6059            let kernel = kernel.lock().unwrap();
6060            assert_eq!(kernel.blocked, guest_mask(), "the guest's mask is back");
6061            assert_eq!(
6062                kernel.requested[2..],
6063                [guest_mask(), guest_mask()],
6064                "one stopped restoration attempt and one that ran"
6065            );
6066            assert_eq!(kernel.held_slot, Some(libc::SIGSTOP));
6067            assert_eq!(kernel.lost, vec![libc::SIGCHLD]);
6068        }
6069        assert_eq!(
6070            refusal(result),
6071            HeldSignalRefusal {
6072                wait: None,
6073                held: Some(libc::SIGCHLD),
6074                replacing: None,
6075                loss: HeldSignalLoss::Restoration,
6076            }
6077        );
6078    }
6079
6080    /// The same with a signal that `/proc` shows before the restoration and
6081    /// that the all-blocked mask leaves unblocked: signal 32, which the C
6082    /// library reserves and leaves out of the blockable set. The refusal names
6083    /// it.
6084    #[tokio::test]
6085    async fn an_identified_stop_of_the_mask_restoration_that_replaces_a_held_sigchld_is_refused() {
6086        const RESERVED: i32 = 32;
6087        assert_eq!(blocked_signal_mask() & kernel_sigset_bit(RESERVED), 0);
6088        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGCHLD), 0);
6089        let _proc = scripted_proc(&kernel);
6090        let mut wait = wait_holding_sigchld(&mut guest, &kernel).await;
6091        kernel.lock().unwrap().pending = kernel_sigset_bit(RESERVED);
6092
6093        let result = wait.restore(&mut guest, None).await;
6094
6095        {
6096            let kernel = kernel.lock().unwrap();
6097            assert_eq!(kernel.blocked, guest_mask(), "the guest's mask is back");
6098            assert_eq!(kernel.taken, vec![libc::SIGCHLD, RESERVED]);
6099            assert_eq!(kernel.held_slot, Some(RESERVED));
6100            assert_eq!(kernel.lost, vec![libc::SIGCHLD]);
6101        }
6102        let refused = refusal(result);
6103        assert_eq!(
6104            refused,
6105            HeldSignalRefusal {
6106                wait: None,
6107                held: Some(libc::SIGCHLD),
6108                replacing: Some(RESERVED),
6109                loss: HeldSignalLoss::Restoration,
6110            }
6111        );
6112        let message = refused.to_string();
6113        assert!(
6114            message.starts_with(
6115                "unsupported: the a blocking wait cannot keep the held signal SIGCHLD: signal 32 \
6116                 stopped the injection that puts the guest's signal mask back and replaced it"
6117            ),
6118            "{message}"
6119        );
6120    }
6121
6122    /// A refusal from the mask restoration replaces the wait's result, whether
6123    /// that is a value or an errno, unless the wait already ended with a refusal
6124    /// of its own, which came first. A mask that could not be put back still
6125    /// ends the run.
6126    #[test]
6127    fn a_restoration_refusal_replaces_the_result_unless_the_wait_refused_first() {
6128        let tool = |refusal: HeldSignalRefusal| Error::Tool(anyhow::Error::new(refusal));
6129        let restoration = HeldSignalRefusal {
6130            wait: None,
6131            held: Some(libc::SIGCHLD),
6132            replacing: None,
6133            loss: HeldSignalLoss::Restoration,
6134        };
6135        let replaced = HeldSignalRefusal {
6136            wait: None,
6137            held: Some(libc::SIGCHLD),
6138            replacing: Some(libc::SIGUSR1),
6139            loss: HeldSignalLoss::Replaced,
6140        };
6141        let not_restored = BlockedWaitSignalError::MaskNotRestored {
6142            pid: Pid::from_raw(1),
6143            tid: Pid::from_raw(1),
6144            attempts: 16,
6145            last_error: Some(Errno::ERESTARTNOINTR),
6146        };
6147
6148        assert_eq!(result_after_restore(Ok(()), Ok(3)).unwrap().unwrap(), 3);
6149        assert_eq!(
6150            refusal(result_after_restore(Err(tool(restoration)), Ok(3)).unwrap()),
6151            restoration
6152        );
6153        assert_eq!(
6154            refusal(
6155                result_after_restore(Err(tool(restoration)), Err(Errno::ERESTARTSYS.into()))
6156                    .unwrap()
6157            ),
6158            restoration
6159        );
6160        assert_eq!(
6161            refusal(result_after_restore(Err(tool(restoration)), Err(tool(replaced))).unwrap()),
6162            replaced
6163        );
6164        assert_eq!(
6165            diagnostic(result_after_restore(
6166                Err(Error::Tool(anyhow::Error::new(not_restored))),
6167                Ok(3)
6168            )),
6169            not_restored
6170        );
6171    }
6172
6173    /// A guest whose next `stops` injections are stopped by a signal that
6174    /// `/proc` never shows, as one that arrives after the read before an
6175    /// injection and that the backend then holds: nothing leaves a queue, so the
6176    /// stop cannot be identified.
6177    fn unidentified_stops_guest(stops: usize) -> (WaitGuest, Kernel) {
6178        let (guest, kernel) = WaitGuest::live(guest_mask());
6179        kernel.lock().unwrap().outcomes =
6180            std::iter::repeat_n(MaskOutcome::StoppedBefore, stops).collect();
6181        (guest, kernel)
6182    }
6183
6184    /// A stop that cannot be identified, such as a default-ignored `SIGCHLD`
6185    /// that arrives after the read, used to end the wait with `ERESTARTNOHAND`
6186    /// for a call whose restart code is not a kernel restart code. With no
6187    /// handler to run, the call then restarted, and a relative `poll` timeout
6188    /// or a timed polling `FUTEX_WAIT` started again with a fresh deadline
6189    /// (round-8 High 1 on https://github.com/rrnewton/hermit/pull/3361). The
6190    /// stop is now held and the injection runs again, so the wait goes on with
6191    /// its absolute deadline, as the blind retry before this machinery did.
6192    #[tokio::test]
6193    async fn a_stop_that_cannot_be_identified_keeps_a_timed_wait_and_its_deadline() {
6194        for deadline in [true, false] {
6195            let (mut guest, kernel) = unidentified_stops_guest(1);
6196            let _proc = scripted_proc(&kernel);
6197            let mut wait = KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND)
6198                .with_deadline(deadline);
6199
6200            let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6201
6202            assert!(
6203                matches!(result, Ok(Ok(0))),
6204                "deadline={deadline}: {result:?}"
6205            );
6206            assert_eq!(
6207                kernel.lock().unwrap().requested.len(),
6208                2,
6209                "deadline={deadline}"
6210            );
6211            assert_eq!(wait.held, None, "deadline={deadline}");
6212        }
6213    }
6214
6215    /// A wait with a deadline absorbs stops without the bound that ends any
6216    /// other wait after `MAX_ABSORBED_STOPS`, because a restart would start its
6217    /// timeout again (round-8 High 1 on
6218    /// https://github.com/rrnewton/hermit/pull/3361). A wait without one still
6219    /// ends at the bound, and, while the backend holds only a signal whose loss
6220    /// does not matter (an ignored `SIGUSR1` sent again and again here), with
6221    /// `ERESTARTNOINTR`: it is not refused.
6222    #[tokio::test]
6223    async fn only_a_wait_without_a_deadline_ends_after_the_absorbed_stop_bound() {
6224        let stops = 100;
6225        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6226        let (mut guest, kernel) = stopping_guest(usr1, usr1);
6227        kernel.lock().unwrap().repost_after_take = stops - 1;
6228        let _proc = scripted_proc(&kernel);
6229        let mut wait =
6230            KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND).with_deadline(true);
6231        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6232        assert!(matches!(result, Ok(Ok(0))), "{result:?}");
6233        assert_eq!(kernel.lock().unwrap().requested.len(), stops + 1);
6234        assert_eq!(wait.held.map(|held| held.kind), Some(HeldKind::Harmless));
6235
6236        let (mut guest, kernel) = stopping_guest(usr1, usr1);
6237        kernel.lock().unwrap().repost_after_take = stops - 1;
6238        let _proc = scripted_proc(&kernel);
6239        let mut wait = KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND);
6240        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6241        assert!(
6242            matches!(result, Err(Error::Errno(Errno::ERESTARTNOINTR))),
6243            "{result:?}"
6244        );
6245        assert_eq!(kernel.lock().unwrap().requested.len(), 65);
6246    }
6247
6248    /// At the same bound, a wait without a deadline whose backend holds a
6249    /// signal whose loss matters (a default `SIGCHLD`, sent again and again)
6250    /// used to end with `ERESTARTNOINTR` too. It now ends with a
6251    /// `HeldSignalRefusal` (round-10 High 1 on
6252    /// https://github.com/rrnewton/hermit/pull/3361).
6253    #[tokio::test]
6254    async fn a_wait_that_reaches_the_stop_bound_holding_a_sigchld_is_refused() {
6255        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGCHLD), 0);
6256        kernel.lock().unwrap().repost_after_take = 100;
6257        let _proc = scripted_proc(&kernel);
6258        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
6259
6260        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6261
6262        assert_eq!(
6263            refusal(result),
6264            HeldSignalRefusal {
6265                wait: None,
6266                held: Some(libc::SIGCHLD),
6267                replacing: None,
6268                loss: HeldSignalLoss::StopBound,
6269            }
6270        );
6271        assert_eq!(kernel.lock().unwrap().requested.len(), 65);
6272    }
6273
6274    /// At the same bound, a stop that cannot be identified, after stops by a
6275    /// signal whose loss does not matter (an ignored `SIGUSR1` sent again and
6276    /// again), used to end a wait without a deadline with `ERESTARTNOINTR`,
6277    /// which let the backend deliver the unidentified signal, possibly a
6278    /// `SIGCHLD`, at a moment host timing could set. It now ends with a
6279    /// `HeldSignalRefusal`; a wait with a deadline, which has no bound, goes on
6280    /// (round-10 High 1 on https://github.com/rrnewton/hermit/pull/3361).
6281    #[tokio::test]
6282    async fn an_unidentified_stop_at_the_stop_bound_is_refused() {
6283        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6284        for deadline in [false, true] {
6285            let (mut guest, kernel) = stopping_guest(usr1, usr1);
6286            {
6287                let mut kernel = kernel.lock().unwrap();
6288                // 64 identified stops, the bound, then one that `/proc` never
6289                // shows.
6290                kernel.repost_after_take = 63;
6291                kernel.outcomes = VecDeque::from([MaskOutcome::StoppedBefore]);
6292            }
6293            let _proc = scripted_proc(&kernel);
6294            let mut wait = KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND)
6295                .with_deadline(deadline);
6296
6297            let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6298
6299            if deadline {
6300                assert!(matches!(result, Ok(Ok(0))), "{result:?}");
6301                assert_eq!(kernel.lock().unwrap().requested.len(), 66);
6302                assert!(wait.held_unidentified);
6303            } else {
6304                assert_eq!(
6305                    refusal(result),
6306                    HeldSignalRefusal {
6307                        wait: None,
6308                        held: None,
6309                        replacing: None,
6310                        loss: HeldSignalLoss::StopBound,
6311                    }
6312                );
6313                assert_eq!(kernel.lock().unwrap().requested.len(), 65);
6314            }
6315            assert_eq!(
6316                kernel.lock().unwrap().taken.len(),
6317                64,
6318                "deadline={deadline}"
6319            );
6320        }
6321    }
6322
6323    /// A stop that cannot be identified while the backend holds a `SIGCHLD`
6324    /// replaced the `SIGCHLD` in the backend's one slot. The wait used to go on
6325    /// and lose it; it now ends with a `HeldSignalRefusal`, with or without a
6326    /// deadline (round-10 High 1 on https://github.com/rrnewton/hermit/pull/3361).
6327    #[tokio::test]
6328    async fn an_unidentified_stop_over_a_held_sigchld_is_refused() {
6329        for deadline in [true, false] {
6330            let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGCHLD), 0);
6331            kernel.lock().unwrap().outcomes = VecDeque::from([MaskOutcome::StoppedBefore]);
6332            let _proc = scripted_proc(&kernel);
6333            let mut wait =
6334                KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS).with_deadline(deadline);
6335
6336            let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6337
6338            assert_eq!(
6339                refusal(result),
6340                HeldSignalRefusal {
6341                    wait: None,
6342                    held: Some(libc::SIGCHLD),
6343                    replacing: None,
6344                    loss: HeldSignalLoss::UnidentifiedStop,
6345                },
6346                "deadline={deadline}"
6347            );
6348            let kernel = kernel.lock().unwrap();
6349            assert_eq!(kernel.requested.len(), 2, "deadline={deadline}");
6350            assert_eq!(kernel.taken, vec![libc::SIGCHLD], "deadline={deadline}");
6351        }
6352    }
6353
6354    /// A second stop that cannot be identified replaced a first one, which may
6355    /// have been a signal whose loss matters. The wait used to go on; it now
6356    /// ends with a `HeldSignalRefusal`, with or without a deadline (round-10
6357    /// High 1 on https://github.com/rrnewton/hermit/pull/3361).
6358    #[tokio::test]
6359    async fn a_second_unidentified_stop_is_refused() {
6360        for deadline in [true, false] {
6361            let (mut guest, kernel) = unidentified_stops_guest(2);
6362            let _proc = scripted_proc(&kernel);
6363            let mut wait = KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND)
6364                .with_deadline(deadline);
6365
6366            let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6367
6368            assert_eq!(
6369                refusal(result),
6370                HeldSignalRefusal {
6371                    wait: None,
6372                    held: None,
6373                    replacing: None,
6374                    loss: HeldSignalLoss::UnidentifiedStop,
6375                },
6376                "deadline={deadline}"
6377            );
6378            assert_eq!(
6379                kernel.lock().unwrap().requested.len(),
6380                2,
6381                "deadline={deadline}"
6382            );
6383        }
6384    }
6385
6386    /// A `SIGCHLD` that arrives after the read before an injection stops it in a
6387    /// way that cannot be identified, and a second one, pending at the next
6388    /// read, would stop the injection made again and replace the first in the
6389    /// backend's one slot. The first may have been a signal whose loss matters,
6390    /// so the wait is refused before that injection, with or without a
6391    /// deadline (round-10 High 1 on https://github.com/rrnewton/hermit/pull/3361),
6392    /// and the backend still holds the first signal. This is the refusal a
6393    /// flood of external `SIGCHLD` racing a timed futex wait's first injections
6394    /// met on hermit main ccbe5ae8 (`external_signal_interrupt`'s test of the
6395    /// flood, now
6396    /// `ptrace_timed_futex_wait_and_poll_keep_their_deadline_after_a_sigchld_flood`,
6397    /// which sends its flood before the wait starts).
6398    #[tokio::test]
6399    async fn a_sigchld_after_an_unidentified_stop_is_refused_before_it_replaces_it() {
6400        let chld = kernel_sigset_bit(libc::SIGCHLD);
6401        for deadline in [true, false] {
6402            let (mut guest, kernel) = stopping_guest(0, 0);
6403            {
6404                let mut kernel = kernel.lock().unwrap();
6405                // Pending only after the first read: the injection's stop is not
6406                // identified. Sent once more, so it is pending again at the read
6407                // before the injection made again.
6408                kernel.pending_repost = chld;
6409                kernel.repost_after_take = 1;
6410            }
6411            let _proc = scripted_proc(&kernel);
6412            let mut wait = KernelSignalWait::new(&guest, 0, true, Errno::ERESTARTNOHAND)
6413                .with_deadline(deadline);
6414
6415            let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6416
6417            let refused = refusal(result);
6418            assert_eq!(
6419                refused,
6420                HeldSignalRefusal {
6421                    wait: None,
6422                    held: None,
6423                    replacing: Some(libc::SIGCHLD),
6424                    loss: HeldSignalLoss::Replaced,
6425                },
6426                "deadline={deadline}"
6427            );
6428            let message = HeldSignalRefusal {
6429                wait: Some(Sysno::futex),
6430                ..refused
6431            }
6432            .to_string();
6433            assert!(
6434                message.starts_with(
6435                    "unsupported: the futex wait cannot keep a held signal that could not be \
6436                     identified: the pending SIGCHLD would stop the next injection and replace it"
6437                ),
6438                "deadline={deadline}: {message}"
6439            );
6440            assert!(wait.held_unidentified, "deadline={deadline}");
6441            let kernel = kernel.lock().unwrap();
6442            assert_eq!(
6443                kernel.requested.len(),
6444                1,
6445                "deadline={deadline}: the second injection is not made"
6446            );
6447            assert_eq!(kernel.taken, vec![libc::SIGCHLD], "deadline={deadline}");
6448            assert_eq!(kernel.held_slot, Some(libc::SIGCHLD), "deadline={deadline}");
6449            assert!(kernel.lost.is_empty(), "deadline={deadline}");
6450            assert_eq!(kernel.pending, chld, "deadline={deadline}");
6451        }
6452    }
6453
6454    /// In a wait with a deadline, a held `SIGCHLD` that would not end the wait
6455    /// is not dropped when another pending signal would stop the next
6456    /// injection. The injection used to be made, and the stop replaced the held
6457    /// signal, as the blind retry allowed (round-8 High 1 on
6458    /// https://github.com/rrnewton/hermit/pull/3361); a restart would start the
6459    /// timeout again. The wait now ends with a `HeldSignalRefusal` before the
6460    /// injection (round-10 High 1 on the same pull request).
6461    #[tokio::test]
6462    async fn a_timed_wait_refuses_to_let_another_stop_replace_a_held_sigchld() {
6463        let (mut guest, kernel) = stopping_guest(
6464            kernel_sigset_bit(libc::SIGCHLD) | kernel_sigset_bit(libc::SIGWINCH),
6465            0,
6466        );
6467        let _proc = scripted_proc(&kernel);
6468        let mut wait =
6469            KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND).with_deadline(true);
6470
6471        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6472
6473        assert_eq!(
6474            refusal(result),
6475            HeldSignalRefusal {
6476                wait: None,
6477                held: Some(libc::SIGCHLD),
6478                replacing: Some(libc::SIGWINCH),
6479                loss: HeldSignalLoss::Replaced,
6480            }
6481        );
6482        let kernel = kernel.lock().unwrap();
6483        assert_eq!(kernel.taken, vec![libc::SIGCHLD]);
6484        assert_eq!(
6485            kernel.requested.len(),
6486            1,
6487            "the second injection is not made"
6488        );
6489        assert_eq!(kernel.pending, kernel_sigset_bit(libc::SIGWINCH));
6490    }
6491
6492    /// In a wait with a deadline, a held signal that would end the wait natively
6493    /// ends it with the restart errno before another stop can replace it, as
6494    /// Linux ends the wait for that signal.
6495    #[tokio::test]
6496    async fn a_timed_wait_ends_for_a_held_signal_that_would_end_it() {
6497        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6498        let (mut guest, kernel) = stopping_guest(usr1 | kernel_sigset_bit(libc::SIGWINCH), 0);
6499        let _proc = scripted_proc(&kernel);
6500        let mut wait =
6501            KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND).with_deadline(true);
6502        wait.held = Some(HeldSignal {
6503            signal: libc::SIGUSR1,
6504            queue: SignalQueue::Thread,
6505            kind: HeldKind::Precious,
6506        });
6507        kernel.lock().unwrap().pending = kernel_sigset_bit(libc::SIGWINCH);
6508        kernel.lock().unwrap().caught = usr1;
6509
6510        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6511
6512        assert!(
6513            matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND))),
6514            "{result:?}"
6515        );
6516        assert!(
6517            kernel.lock().unwrap().requested.is_empty(),
6518            "nothing is injected"
6519        );
6520    }
6521
6522    /// In a wait without a deadline, a held signal that would end the wait
6523    /// natively also ends it with the restart errno before another stop can
6524    /// replace it, as Linux ends the wait for that signal. It used to end with
6525    /// `ERESTARTNOINTR`, which restarted the call after the handler ran
6526    /// (round-10 High 1 on https://github.com/rrnewton/hermit/pull/3361).
6527    #[tokio::test]
6528    async fn a_wait_without_a_deadline_ends_for_a_held_signal_that_would_end_it() {
6529        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6530        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(libc::SIGWINCH), 0);
6531        kernel.lock().unwrap().caught = usr1;
6532        let _proc = scripted_proc(&kernel);
6533        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
6534        wait.held = Some(HeldSignal {
6535            signal: libc::SIGUSR1,
6536            queue: SignalQueue::Thread,
6537            kind: HeldKind::Precious,
6538        });
6539
6540        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6541
6542        assert!(
6543            matches!(result, Err(Error::Errno(Errno::ERESTARTSYS))),
6544            "{result:?}"
6545        );
6546        assert!(
6547            kernel.lock().unwrap().requested.is_empty(),
6548            "nothing is injected"
6549        );
6550    }
6551
6552    /// A signal that a wait without a deadline consumes and that stops an
6553    /// injection is delivered rather than returned. One whose loss does not
6554    /// matter still ends the wait with `ERESTARTNOINTR`, and is not refused;
6555    /// a `SIGCHLD`, which the wait holds until the call returns, used to end it
6556    /// the same way and now ends it with a `HeldSignalRefusal` (round-10 High 1
6557    /// on https://github.com/rrnewton/hermit/pull/3361).
6558    #[tokio::test]
6559    async fn a_consumed_sigchld_that_stops_an_injection_is_refused() {
6560        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
6561        let (mut guest, kernel) = stopping_guest(usr1, 0);
6562        let _proc = scripted_proc(&kernel);
6563        let mut wait = KernelSignalWait::new(&guest, usr1, false, Errno::ERESTARTSYS);
6564        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6565        assert!(
6566            matches!(result, Err(Error::Errno(Errno::ERESTARTNOINTR))),
6567            "{result:?}"
6568        );
6569        assert_eq!(kernel.lock().unwrap().taken, vec![libc::SIGUSR1]);
6570        drop(_proc);
6571
6572        let chld = kernel_sigset_bit(libc::SIGCHLD);
6573        let (mut guest, kernel) = stopping_guest(chld, 0);
6574        let _proc = scripted_proc(&kernel);
6575        let mut wait = KernelSignalWait::new(&guest, chld, false, Errno::ERESTARTSYS);
6576        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6577        assert_eq!(
6578            refusal(result),
6579            HeldSignalRefusal {
6580                wait: None,
6581                held: None,
6582                replacing: Some(libc::SIGCHLD),
6583                loss: HeldSignalLoss::Consumed,
6584            }
6585        );
6586        assert_eq!(kernel.lock().unwrap().taken, vec![libc::SIGCHLD]);
6587    }
6588
6589    /// A stop by a signal outside every class above, such as the backend's own
6590    /// preemption signal, still ends a wait without a deadline with
6591    /// `ERESTARTNOINTR`: the backend holds nothing whose loss matters, so it is
6592    /// not refused.
6593    #[tokio::test]
6594    async fn a_stop_by_the_preemption_signal_still_restarts_a_wait_without_a_deadline() {
6595        let signal = reverie::PERF_EVENT_SIGNAL as i32;
6596        let (mut guest, kernel) = stopping_guest(kernel_sigset_bit(signal), 0);
6597        let _proc = scripted_proc(&kernel);
6598        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS);
6599
6600        let result = inject_mask_absorbing(&mut wait, &mut guest, guest_mask()).await;
6601
6602        assert!(
6603            matches!(result, Err(Error::Errno(Errno::ERESTARTNOINTR))),
6604            "{result:?}"
6605        );
6606        assert_eq!(kernel.lock().unwrap().taken, vec![signal]);
6607    }
6608
6609    /// A wait that ends with a `HeldSignalRefusal` is refused through the
6610    /// unsupported-operation policy that `refuse_unserviceable_operation`
6611    /// applies: a run that is not fail-closed gets the `ERESTARTNOINTR` restart
6612    /// it got before, and a fail-closed one with `exit_on_unsupported_syscall`
6613    /// ends with the typed `UnsupportedSyscallError` for the wait's call. Every
6614    /// other result passes through, and the message names the wait, the
6615    /// signals and the pull request.
6616    #[tokio::test]
6617    async fn a_held_signal_refusal_follows_the_unsupported_operation_policy() {
6618        let refused = || {
6619            Err::<i64, Error>(Error::Tool(anyhow::Error::new(HeldSignalRefusal {
6620                wait: None,
6621                held: Some(libc::SIGCHLD),
6622                replacing: Some(libc::SIGWINCH),
6623                loss: HeldSignalLoss::Replaced,
6624            })))
6625        };
6626        let (mut guest, _kernel) = WaitGuest::live(guest_mask());
6627        guest.config.panic_on_unsupported_syscalls = false;
6628        let result = refuse_held_signal_loss(&mut guest, Sysno::poll, refused()).await;
6629        assert!(
6630            matches!(result, Err(Error::Errno(Errno::ERESTARTNOINTR))),
6631            "{result:?}"
6632        );
6633        let result = refuse_held_signal_loss(&mut guest, Sysno::poll, Ok(3)).await;
6634        assert!(matches!(result, Ok(3)), "{result:?}");
6635        let result =
6636            refuse_held_signal_loss(&mut guest, Sysno::poll, Err(Errno::ERESTARTSYS.into())).await;
6637        assert!(
6638            matches!(result, Err(Error::Errno(Errno::ERESTARTSYS))),
6639            "{result:?}"
6640        );
6641
6642        guest.config.panic_on_unsupported_syscalls = true;
6643        guest.config.exit_on_unsupported_syscall = true;
6644        guest.config.shutdown_on_unsupported_syscall = false;
6645        let result = refuse_held_signal_loss(&mut guest, Sysno::poll, refused()).await;
6646        match result {
6647            Err(Error::Tool(error)) => assert!(
6648                matches!(
6649                    error.downcast_ref::<crate::UnsupportedSyscallError>(),
6650                    Some(crate::UnsupportedSyscallError(Sysno::poll))
6651                ),
6652                "{error:#}"
6653            ),
6654            other => panic!("expected the typed refusal, got {other:?}"),
6655        }
6656
6657        let message = HeldSignalRefusal {
6658            wait: Some(Sysno::poll),
6659            held: Some(libc::SIGCHLD),
6660            replacing: Some(libc::SIGWINCH),
6661            loss: HeldSignalLoss::Replaced,
6662        }
6663        .to_string();
6664        for part in [
6665            "poll",
6666            "SIGCHLD",
6667            "SIGWINCH",
6668            "https://github.com/rrnewton/hermit/pull/3361",
6669        ] {
6670            assert!(message.contains(part), "{part} missing from: {message}");
6671        }
6672    }
6673
6674    /// A guest with a caught `SIGCHLD` pending, outside its mask. With
6675    /// `gated_backend`, its configuration is the one under which the scheduler
6676    /// models signal targets: serialized threads and a backend that reports the
6677    /// kernel's signal state.
6678    fn caught_sigchld_guest(gated_backend: bool) -> (WaitGuest, Kernel) {
6679        let (mut guest, kernel) = WaitGuest::live(guest_mask());
6680        guest.config.sequentialize_threads = gated_backend;
6681        guest
6682            .config
6683            .backend
6684            .supports_blocked_wait_signal_interruption = gated_backend;
6685        {
6686            let mut kernel = kernel.lock().unwrap();
6687            kernel.pending = kernel_sigset_bit(libc::SIGCHLD);
6688            kernel.caught = kernel_sigset_bit(libc::SIGCHLD);
6689        }
6690        (guest, kernel)
6691    }
6692
6693    /// A caught `SIGCHLD` pending outside the guest's mask, which the scheduler
6694    /// did not commit in this turn (`admit`), never ends a gated
6695    /// wait, on any backend and whoever sent it: `/proc` cannot tell a
6696    /// `SIGCHLD` a guest or the scheduler sent at a deterministic point from the
6697    /// one the kernel posts for a child event at a moment set by host timing
6698    /// (https://github.com/rrnewton/hermit/issues/3146). The signal stays queued
6699    /// and is delivered when the call returns. The waits of `select` and
6700    /// `pselect6` hold nothing and end for it, as Linux ends them for any caught
6701    /// signal (`core_sys_select`).
6702    #[tokio::test]
6703    async fn a_pending_caught_sigchld_ends_a_select_wait_but_no_gated_wait() {
6704        for gated_backend in [false, true] {
6705            let (guest, kernel) = caught_sigchld_guest(gated_backend);
6706            let _proc = scripted_proc(&kernel);
6707
6708            let gated = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6709            assert!(
6710                !gated.interrupted().unwrap(),
6711                "a pending caught SIGCHLD does not end a gated wait \
6712                 (gated_backend={gated_backend})"
6713            );
6714
6715            let select = KernelSignalWait::for_select(&guest);
6716            assert!(
6717                select.interrupted().unwrap(),
6718                "the pending caught SIGCHLD ends a select wait (gated_backend={gated_backend})"
6719            );
6720            assert_eq!(
6721                kernel.lock().unwrap().pending,
6722                kernel_sigset_bit(libc::SIGCHLD),
6723                "the signal stays queued for the guest's handler"
6724            );
6725        }
6726    }
6727
6728    /// A caught `SIGCHLD` the scheduler committed to the thread ends a gated
6729    /// wait, but only in the turn whose resume names it
6730    /// (`KernelSignalWait::admit`), and never when a host-timed
6731    /// source a guest armed can post `SIGCHLD` too: that copy could arrive at a
6732    /// moment host timing sets (https://github.com/rrnewton/hermit/issues/4005).
6733    #[tokio::test]
6734    async fn a_committed_sigchld_ends_a_gated_wait_unless_a_host_timed_source_can_post_it() {
6735        let chld = kernel_sigset_bit(libc::SIGCHLD);
6736        let (guest, kernel) = caught_sigchld_guest(true);
6737        let _proc = scripted_proc(&kernel);
6738
6739        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6740        assert!(
6741            !wait.interrupted().unwrap(),
6742            "an uncommitted SIGCHLD is held"
6743        );
6744        wait.admit(chld, 0);
6745        assert!(
6746            wait.interrupted().unwrap(),
6747            "a committed SIGCHLD ends the wait"
6748        );
6749        wait.admit(0, 0);
6750        assert!(
6751            !wait.interrupted().unwrap(),
6752            "the next turn's resume names nothing, so the SIGCHLD is held again"
6753        );
6754
6755        let mut host_timed = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6756        host_timed.hold_until_return(chld);
6757        host_timed.admit(chld, 0);
6758        assert!(
6759            !host_timed.interrupted().unwrap(),
6760            "a SIGCHLD a host-timed source can post stays held although committed"
6761        );
6762    }
6763
6764    /// A `SIGCHLD` a guest sent this thread, which the schedule recorded in its
6765    /// private queue and the turn admits (`KernelSignalWait::admit`), ends a
6766    /// gated wait from the thread's own queue only: one pending only on the
6767    /// shared queue, which a host-timed child event can fill, decides nothing.
6768    /// It is admitted for the turn alone, and never when a host-timed source
6769    /// can post `SIGCHLD` (R2b-2 stage 3,
6770    /// https://github.com/rrnewton/hermit/issues/4273).
6771    #[tokio::test]
6772    async fn an_admitted_private_sigchld_ends_a_gated_wait_from_the_threads_own_queue_only() {
6773        let chld = kernel_sigset_bit(libc::SIGCHLD);
6774        let (guest, kernel) = caught_sigchld_guest(true);
6775        let _proc = scripted_proc(&kernel);
6776
6777        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6778        wait.admit(0, chld);
6779        assert!(
6780            wait.interrupted().unwrap(),
6781            "the thread's own copy ends the wait"
6782        );
6783        assert!(
6784            wait.interrupts_only_by_committed(
6785                &read_wait_signal_state(guest.pid(), guest.tid()).unwrap()
6786            ),
6787            "only the admitted copy ends it, so the turn's probe runs first"
6788        );
6789        kernel.lock().unwrap().shared = chld;
6790        assert!(
6791            !wait.interrupted().unwrap(),
6792            "a SIGCHLD pending only on the shared queue is held"
6793        );
6794        kernel.lock().unwrap().shared = 0;
6795        wait.admit(0, 0);
6796        assert!(!wait.interrupted().unwrap(), "the next turn holds it again");
6797
6798        let mut host_timed = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6799        host_timed.hold_until_return(chld);
6800        host_timed.admit(0, chld);
6801        assert!(
6802            !host_timed.interrupted().unwrap(),
6803            "a SIGCHLD a host-timed source can post stays held"
6804        );
6805    }
6806
6807    /// An admitted private `SIGCHLD` that only the wait mask lets in is
6808    /// delivered under that mask (`interrupts_only_under_wait_mask`), as a
6809    /// committed one is: an `epoll_pwait` whose temporary mask unblocks a
6810    /// `SIGCHLD` the thread's own mask blocks (R2b-2 stage 3).
6811    #[tokio::test]
6812    async fn an_admitted_private_sigchld_that_only_the_wait_mask_lets_in_is_delivered_under_it() {
6813        let chld = kernel_sigset_bit(libc::SIGCHLD);
6814        let (guest, kernel) = caught_sigchld_guest(true);
6815        let _proc = scripted_proc(&kernel);
6816        kernel.lock().unwrap().blocked |= chld;
6817        let mut wait =
6818            KernelSignalWait::new(&guest, 0, false, Errno::EINTR).with_wait_mask(Some(0));
6819        let state = read_wait_signal_state(guest.pid(), guest.tid()).unwrap();
6820        assert!(
6821            !wait.interrupts_only_under_wait_mask(&state),
6822            "held while not admitted"
6823        );
6824        wait.admit(0, chld);
6825        assert!(wait.interrupts_only_under_wait_mask(&state));
6826    }
6827
6828    /// `admit_under_block` keeps a recorded private `SIGCHLD` only once every
6829    /// blockable signal is blocked in place, and only if the thread's own
6830    /// queue holds `SIGCHLD`, read after the block. A turn that admits nothing
6831    /// makes no request; a refused setter keeps the wait's fallback, the
6832    /// injected `block` after the first probe; a wait whose earlier injected
6833    /// `block` failed (`unblockable`, no `saved_mask`) keeps nothing (R2b-2
6834    /// stage 3, M3c of the rev5 review).
6835    #[tokio::test]
6836    async fn a_recorded_private_sigchld_is_kept_only_under_a_block_in_place() {
6837        let chld = kernel_sigset_bit(libc::SIGCHLD);
6838        // The block publishes the guest's own mask, already published here,
6839        // so no request leaves the test (`publish_wait_mask`).
6840        let mut published = PublishedWaitMask(Some(guest_mask()));
6841
6842        let (mut guest, kernel) = caught_sigchld_guest(true);
6843        let _proc = scripted_proc(&kernel);
6844        kernel.lock().unwrap().setter.push_back(None);
6845        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6846        assert_eq!(
6847            wait.admit_under_block(&mut guest, 0, chld, 0, &mut published)
6848                .await
6849                .unwrap(),
6850            chld,
6851            "blocked in place, and the thread's own queue holds it"
6852        );
6853        assert!(wait.blocked_in_place);
6854        wait.restore(&mut guest, None).await.unwrap();
6855        drop(_proc);
6856
6857        let (mut guest, kernel) = caught_sigchld_guest(true);
6858        let _proc = scripted_proc(&kernel);
6859        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6860        assert_eq!(
6861            wait.admit_under_block(&mut guest, 0, 0, 0, &mut published)
6862                .await
6863                .unwrap(),
6864            0
6865        );
6866        assert!(
6867            kernel.lock().unwrap().set_calls.is_empty(),
6868            "nothing admitted, no request"
6869        );
6870        assert_eq!(
6871            wait.admit_under_block(&mut guest, 0, chld, chld, &mut published)
6872                .await
6873                .unwrap(),
6874            0,
6875            "a SIGCHLD a host-timed source can post is not admitted"
6876        );
6877        assert!(kernel.lock().unwrap().set_calls.is_empty());
6878        drop(_proc);
6879
6880        let (mut guest, kernel) = caught_sigchld_guest(true);
6881        let _proc = scripted_proc(&kernel);
6882        kernel.lock().unwrap().shared = chld;
6883        kernel.lock().unwrap().setter.push_back(None);
6884        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6885        assert_eq!(
6886            wait.admit_under_block(&mut guest, 0, chld, 0, &mut published)
6887                .await
6888                .unwrap(),
6889            0,
6890            "only on the shared queue: not the recorded copy"
6891        );
6892        wait.restore(&mut guest, None).await.unwrap();
6893        drop(_proc);
6894
6895        let (mut guest, kernel) = caught_sigchld_guest(true);
6896        let _proc = scripted_proc(&kernel);
6897        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6898        assert_eq!(
6899            wait.admit_under_block(&mut guest, 0, chld, 0, &mut published)
6900                .await
6901                .unwrap(),
6902            0,
6903            "the setter refuses (no answer queued)"
6904        );
6905        assert!(
6906            wait.needs_block(),
6907            "the injected block after the first probe stays"
6908        );
6909        drop(_proc);
6910
6911        let (mut guest, kernel) = caught_sigchld_guest(true);
6912        let _proc = scripted_proc(&kernel);
6913        let mut wait = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
6914        wait.unblockable = true;
6915        assert_eq!(
6916            wait.admit_under_block(&mut guest, 0, chld, 0, &mut published)
6917                .await
6918                .unwrap(),
6919            0,
6920            "an earlier injected block failed: no block, no private copy"
6921        );
6922        assert!(kernel.lock().unwrap().set_calls.is_empty());
6923    }
6924
6925    /// A pipe turn (`turn_signals_with_block`) counts the recorded private
6926    /// `SIGCHLD` only where the gate holds, a block is in force and the
6927    /// thread's own queue holds it. Not on the scalar writer's first attempt,
6928    /// the guest's own write, which blocks nothing (`may_block` false): an
6929    /// injection of that turn could take the copy into the backend's single
6930    /// held slot. Not without the gate, as on a socket. Not from the shared
6931    /// queue alone (R2b-2 stage 3).
6932    #[tokio::test]
6933    async fn a_pipe_turn_counts_a_recorded_private_sigchld_only_under_a_block_in_place() {
6934        let chld = kernel_sigset_bit(libc::SIGCHLD);
6935        let turn = |may_block: bool, gate: bool, shared: bool| async move {
6936            // Thread 1, the thread state's own number, so a request may leave.
6937            let (mut guest, kernel) = WaitGuest::new(Pid::from_raw(1), guest_mask());
6938            {
6939                let mut kernel = kernel.lock().unwrap();
6940                kernel.pending = chld;
6941                kernel.caught = chld;
6942                kernel.shared = if shared { chld } else { 0 };
6943                kernel.setter.push_back(None);
6944                kernel.private_record = Some((0, chld));
6945            }
6946            let _proc = scripted_proc(&kernel);
6947            let mut wait = Some(KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTSYS));
6948            let mut published = PublishedWaitMask(Some(guest_mask()));
6949            let pending =
6950                turn_signals_with_block(&mut guest, &mut wait, may_block, 0, gate, &mut published)
6951                    .await
6952                    .unwrap()
6953                    .pending;
6954            if let Some(wait) = wait.as_mut() {
6955                wait.restore(&mut guest, None).await.unwrap();
6956            }
6957            let blocked_in_place = !kernel.lock().unwrap().set_calls.is_empty();
6958            (pending & chld, blocked_in_place)
6959        };
6960        assert_eq!(
6961            turn(true, true, false).await,
6962            (chld, true),
6963            "blocked in place: admitted"
6964        );
6965        assert_eq!(
6966            turn(false, true, false).await,
6967            (0, false),
6968            "the writer's first attempt blocks nothing: held"
6969        );
6970        assert_eq!(turn(true, false, false).await, (0, true), "no gate: held");
6971        assert_eq!(
6972            turn(true, true, true).await,
6973            (0, true),
6974            "the shared queue alone: held"
6975        );
6976    }
6977
6978    /// The pipe path's hold leaves out an admitted private `SIGCHLD`
6979    /// (`turn_signals_before_discard`'s `private`): it counts in the turn's
6980    /// `pending`, where without it the hold keeps it out (R2b-2 stage 3).
6981    #[test]
6982    fn a_pipe_turn_counts_an_admitted_private_sigchld() {
6983        let chld = kernel_sigset_bit(libc::SIGCHLD);
6984        let state = KernelSignalState {
6985            pending: chld,
6986            thread_pending: chld,
6987            caught: chld,
6988            ..KernelSignalState::default()
6989        };
6990        assert_eq!(
6991            turn_signals_before_discard(&state, 0, 0, 0, NamedRealTime::Woken, 0).pending,
6992            0,
6993            "held"
6994        );
6995        assert_eq!(
6996            turn_signals_before_discard(&state, 0, 0, 0, NamedRealTime::Woken, chld).pending,
6997            chld,
6998            "admitted"
6999        );
7000    }
7001
7002    /// The same `SIGCHLD` ends a select wait before an injection that is not a
7003    /// probe (`inject_absorbing`: the change of mask that blocks signals for the
7004    /// wait), with `ERESTARTNOHAND`, which the handler's run turns into `EINTR`.
7005    /// The waits of `select` and `pselect6` make every probe with
7006    /// `inject_first_probe`. A gated wait makes the injection, and the `SIGCHLD`
7007    /// that stops it is held until the call returns.
7008    #[tokio::test]
7009    async fn a_pending_caught_sigchld_ends_a_select_wait_before_the_injection() {
7010        let (mut guest, kernel) = caught_sigchld_guest(true);
7011        kernel.lock().unwrap().stops_for_pending = true;
7012        let _proc = scripted_proc(&kernel);
7013
7014        let mut select = KernelSignalWait::for_select(&guest);
7015        let result = inject_mask_absorbing(&mut select, &mut guest, guest_mask()).await;
7016        assert!(
7017            matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND))),
7018            "{result:?}"
7019        );
7020        {
7021            let kernel = kernel.lock().unwrap();
7022            assert!(kernel.requested.is_empty(), "nothing is injected");
7023            assert_eq!(kernel.pending, kernel_sigset_bit(libc::SIGCHLD));
7024        }
7025        assert_eq!(select.held, None);
7026
7027        let mut gated = KernelSignalWait::new(&guest, 0, false, Errno::ERESTARTNOHAND);
7028        let result = inject_mask_absorbing(&mut gated, &mut guest, guest_mask()).await;
7029        assert!(matches!(result, Ok(Ok(0))), "{result:?}");
7030        {
7031            let kernel = kernel.lock().unwrap();
7032            assert_eq!(kernel.taken, vec![libc::SIGCHLD]);
7033            assert_eq!(kernel.requested.len(), 2, "stopped once, then ran");
7034        }
7035        assert_eq!(gated.held.map(|held| held.kind), Some(HeldKind::Precious));
7036    }
7037
7038    /// The kernel's next dequeue: the private queue before the shared one, a
7039    /// synchronous signal first, then the lowest number, outside the mask.
7040    #[test]
7041    fn next_dequeued_follows_the_kernel_order() {
7042        let bit = kernel_sigset_bit;
7043        let state = KernelSignalState {
7044            thread_pending: bit(libc::SIGUSR2) | bit(libc::SIGSEGV),
7045            shared_pending: bit(libc::SIGHUP),
7046            ..KernelSignalState::default()
7047        };
7048        assert_eq!(
7049            state.next_dequeued(0),
7050            Some((libc::SIGSEGV, SignalQueue::Thread))
7051        );
7052        assert_eq!(
7053            state.next_dequeued(bit(libc::SIGSEGV)),
7054            Some((libc::SIGUSR2, SignalQueue::Thread))
7055        );
7056        assert_eq!(
7057            state.next_dequeued(bit(libc::SIGSEGV) | bit(libc::SIGUSR2)),
7058            Some((libc::SIGHUP, SignalQueue::Shared))
7059        );
7060        assert_eq!(state.next_dequeued(!0), None);
7061    }
7062
7063    /// A stop is identified only when exactly the predicted signal left its
7064    /// queue and the mask and dispositions are unchanged; arrivals do not matter.
7065    #[test]
7066    fn a_stop_is_identified_only_by_exactly_its_signal() {
7067        let bit = kernel_sigset_bit;
7068        let before = KernelSignalState {
7069            thread_pending: bit(libc::SIGUSR1) | bit(libc::SIGWINCH),
7070            shared_pending: bit(libc::SIGHUP),
7071            ..KernelSignalState::default()
7072        };
7073        let took = |after: KernelSignalState, signal, queue| {
7074            stop_took_only(&before, &after, signal, queue)
7075        };
7076        let after = KernelSignalState {
7077            thread_pending: bit(libc::SIGWINCH) | bit(libc::SIGUSR2),
7078            ..before
7079        };
7080        assert!(took(after, libc::SIGUSR1, SignalQueue::Thread));
7081        assert!(
7082            !took(after, libc::SIGWINCH, SignalQueue::Thread),
7083            "SIGWINCH is still queued"
7084        );
7085        let two_left = KernelSignalState {
7086            thread_pending: 0,
7087            ..before
7088        };
7089        assert!(!took(two_left, libc::SIGUSR1, SignalQueue::Thread));
7090        let shared_left = KernelSignalState {
7091            thread_pending: bit(libc::SIGWINCH),
7092            shared_pending: 0,
7093            ..before
7094        };
7095        assert!(!took(shared_left, libc::SIGUSR1, SignalQueue::Thread));
7096        let mask_changed = KernelSignalState {
7097            blocked: bit(libc::SIGUSR2),
7098            ..after
7099        };
7100        assert!(!took(mask_changed, libc::SIGUSR1, SignalQueue::Thread));
7101        let disposition_changed = KernelSignalState {
7102            ignored: bit(libc::SIGWINCH),
7103            ..after
7104        };
7105        assert!(!took(
7106            disposition_changed,
7107            libc::SIGUSR1,
7108            SignalQueue::Thread
7109        ));
7110    }
7111
7112    /// A select wait with a pselect6 temporary mask (`with_wait_mask`) holds a
7113    /// caught signal that the temporary mask blocks, and the guest's own mask
7114    /// does not, when it stops an injection before `block` takes effect, as
7115    /// Linux keeps it pending for the whole call; without the temporary mask
7116    /// the same stop ends the wait, and a signal only the temporary mask
7117    /// unblocks ends it too (review of
7118    /// https://github.com/rrnewton/hermit/pull/4051).
7119    #[test]
7120    fn a_signal_the_temporary_mask_blocks_is_held_not_ended() {
7121        let bit = kernel_sigset_bit;
7122        let (guest, _kernel) = WaitGuest::live(guest_mask());
7123        let before = KernelSignalState {
7124            pending: bit(libc::SIGALRM),
7125            thread_pending: bit(libc::SIGALRM),
7126            blocked: guest_mask(),
7127            caught: bit(libc::SIGALRM) | bit(libc::SIGUSR2),
7128            ..KernelSignalState::default()
7129        };
7130        let plain = KernelSignalWait::for_select(&guest);
7131        assert_eq!(
7132            plain.stop_verdict(&before, libc::SIGALRM),
7133            StopVerdict::End(Errno::ERESTARTNOHAND)
7134        );
7135        let masked = KernelSignalWait::for_select(&guest).with_wait_mask(Some(bit(libc::SIGALRM)));
7136        assert_eq!(
7137            masked.stop_verdict(&before, libc::SIGALRM),
7138            StopVerdict::Absorb(HeldKind::Precious)
7139        );
7140        let unblocking = KernelSignalWait::for_select(&guest).with_wait_mask(Some(0));
7141        assert_eq!(
7142            unblocking.stop_verdict(&before, libc::SIGUSR2),
7143            StopVerdict::End(Errno::ERESTARTNOHAND)
7144        );
7145    }
7146}
7147
7148#[cfg(test)]
7149mod turn_signal_tests {
7150    use super::*;
7151
7152    fn bit(signal: libc::c_int) -> KernelSigset {
7153        kernel_sigset_bit(signal)
7154    }
7155
7156    fn state(
7157        pending: KernelSigset,
7158        caught: KernelSigset,
7159        blocked: KernelSigset,
7160    ) -> KernelSignalState {
7161        KernelSignalState {
7162            pending,
7163            thread_pending: pending,
7164            caught,
7165            blocked,
7166            ..Default::default()
7167        }
7168    }
7169
7170    /// Rule 3 of R2b-1 (https://github.com/rrnewton/hermit/issues/4273): with
7171    /// no progress only a pending copy ends the call; after progress a named
7172    /// wake does too.
7173    #[test]
7174    fn a_named_wake_ends_a_call_only_after_progress() {
7175        let named = TurnSignals {
7176            named: bit(libc::SIGUSR1),
7177            pending: 0,
7178        };
7179        assert!(!named.ends(false));
7180        assert!(named.ends(true));
7181        let pending = TurnSignals {
7182            named: 0,
7183            pending: bit(libc::SIGUSR1),
7184        };
7185        assert!(pending.ends(false));
7186        assert!(pending.ends(true));
7187        assert!(!TurnSignals::default().ends(true));
7188    }
7189
7190    /// A caught SIGCHLD pending at a poll's turn is held unless the scheduler
7191    /// committed it, and a host-timed signal is held even then (arm A8).
7192    #[test]
7193    fn the_hold_leaves_out_an_uncommitted_sigchld_and_every_host_timed_signal() {
7194        let chld = bit(libc::SIGCHLD);
7195        let hup = bit(libc::SIGHUP);
7196        let s = state(chld | hup, chld | hup, 0);
7197        assert_eq!(
7198            turn_signals_before_discard(&s, 0, hup, 0, NamedRealTime::Woken, 0).pending,
7199            0
7200        );
7201        assert_eq!(
7202            turn_signals_before_discard(&s, 0, hup, chld, NamedRealTime::Woken, 0).pending,
7203            chld
7204        );
7205        assert_eq!(
7206            turn_signals_before_discard(&s, 0, hup, chld | hup, NamedRealTime::Woken, 0).pending,
7207            chld
7208        );
7209    }
7210
7211    /// A named signal counts only if the call's mask leaves it unblocked
7212    /// (rule 2). A real-time one counts only if its disposition delivers it
7213    /// for `writev`, which the drain never filters (rule 2), and as woken for
7214    /// the generic poll and the scalar writer, whose drain already tested it
7215    /// (rule 1), so a flush after the wake does not undo it (the Claude
7216    /// implementation review of R2b-1, F1).
7217    #[test]
7218    fn a_named_signal_counts_only_unblocked_and_a_real_time_one_by_its_call() {
7219        use NamedRealTime::ByDisposition;
7220        use NamedRealTime::Woken;
7221        let usr1 = bit(libc::SIGUSR1);
7222        let rt = bit(libc::SIGRTMIN());
7223        let s = state(0, usr1, usr1);
7224        for real_time in [Woken, ByDisposition] {
7225            assert_eq!(
7226                turn_signals_before_discard(&s, usr1, 0, usr1, real_time, 0).named,
7227                0
7228            );
7229            assert_eq!(
7230                turn_signals_before_discard(&s, 0, 0, usr1, real_time, 0).named,
7231                usr1
7232            );
7233        }
7234        let ignored_rt = KernelSignalState {
7235            ignored: rt,
7236            ..state(0, 0, 0)
7237        };
7238        assert_eq!(
7239            turn_signals_before_discard(&ignored_rt, 0, 0, rt, ByDisposition, 0).named,
7240            0
7241        );
7242        assert_eq!(
7243            turn_signals_before_discard(&ignored_rt, 0, 0, rt, Woken, 0).named,
7244            rt
7245        );
7246        assert_eq!(
7247            turn_signals_before_discard(&ignored_rt, rt, 0, rt, Woken, 0).named,
7248            0
7249        );
7250        let caught_rt = state(0, rt, 0);
7251        assert_eq!(
7252            turn_signals_before_discard(&caught_rt, 0, 0, rt, ByDisposition, 0).named,
7253            rt
7254        );
7255    }
7256}
7257
7258/// The mask a thread is stopped under where its blocking call returned, until
7259/// its continuation turn (`continuation_mask`).
7260#[derive(Clone, Copy, Debug, PartialEq, Eq)]
7261pub(crate) enum ContinuationMask {
7262    /// The call's temporary mask: the call ran and a signal ended it.
7263    Temporary,
7264    /// Not known to the scheduler, in record and replay alike.
7265    Unknown,
7266    /// The thread's own mask, which the kernel restored before the call
7267    /// returned and holds in record and replay alike.
7268    Restored,
7269}
7270
7271/// The mask `call`, having returned `result`, leaves its thread stopped under,
7272/// decided from what the kernel did, which the raw result tells and replay
7273/// serves as recorded:
7274/// - pselect6 and ppoll that a signal ended return `-ERESTARTNOHAND`, or the
7275///   `-EINTR` that `poll_select_finish` can still turn it into after keeping
7276///   the mask (a timeout write-back that faults, or the STICKY_TIMEOUTS
7277///   personality); epoll_pwait and epoll_pwait2 return `-EINTR`. Linux then
7278///   delivers the signal under the temporary mask and `rt_sigreturn` restores
7279///   the saved one (`restore_saved_sigmask_unless`, fs/select.c, fs/eventpoll.c
7280///   and kernel/signal.c at v6.9): `Temporary`.
7281/// - Their normal return: Linux restored the saved mask before returning. Their
7282///   `-ERESTARTSYS`, which the host reports when the signal reached the thread
7283///   before the call ran: the kernel never installed the mask, and the
7284///   recording holds that result. Either way `Restored`.
7285/// - rt_sigsuspend: `Unknown`, whatever its result. Whether it ran is not
7286///   recorded: record injects it live, where a signal arriving first yields a
7287///   host-timed `-ERESTARTSYS` (the kernel never installed the mask), and
7288///   replay re-injects it with retry, which never shows that. A rule on its
7289///   result would differ between the two (the Claude review of d1b9404c), and
7290///   a known temporary mask would claim one the kernel may not have installed
7291///   (the Codex review of da662bb2). The scheduler treats an unknown mask
7292///   alike in both: no `SIGCHLD` taker or signal target, no discard.
7293/// - Any other call: `Restored`; it installed no temporary mask.
7294pub(crate) fn continuation_mask(call: Syscall, result: &Result<i64, Error>) -> ContinuationMask {
7295    let ended_by = |errno: Errno| matches!(result, Err(Error::Errno(error)) if *error == errno);
7296    let kept = match call {
7297        Syscall::RtSigsuspend(_) => return ContinuationMask::Unknown,
7298        Syscall::Pselect6(_) | Syscall::Ppoll(_) => {
7299            ended_by(Errno::ERESTARTNOHAND) || ended_by(Errno::EINTR)
7300        }
7301        Syscall::EpollPwait(_) | Syscall::Other(Sysno::epoll_pwait2, _) => ended_by(Errno::EINTR),
7302        _ => false,
7303    };
7304    if kept {
7305        ContinuationMask::Temporary
7306    } else {
7307        ContinuationMask::Restored
7308    }
7309}
7310
7311#[cfg(test)]
7312mod temporary_mask_tests {
7313    use super::*;
7314
7315    /// The continuation mask follows what the kernel did: the temporary mask
7316    /// for an interrupted pselect6 or ppoll (`-ERESTARTNOHAND`, or the `-EINTR`
7317    /// it can become after the kernel kept the mask) and an interrupted
7318    /// epoll_pwait or epoll_pwait2 (`-EINTR`); the restored own mask for their
7319    /// normal return, a call the signal reached before it ran (`-ERESTARTSYS`)
7320    /// or another errno; unknown for every rt_sigsuspend, whose `-ERESTARTSYS`
7321    /// is host-timed in record and absent in replay; restored for a call
7322    /// without a temporary mask.
7323    #[test]
7324    fn the_continuation_mask_follows_what_the_kernel_did() {
7325        let restart = Err(Error::Errno(Errno::ERESTARTNOHAND));
7326        let eintr = Err(Error::Errno(Errno::EINTR));
7327        let pselect = Syscall::Pselect6(syscalls::Pselect6::new());
7328        let ppoll = Syscall::Ppoll(syscalls::Ppoll::new());
7329        let epoll = Syscall::EpollPwait(syscalls::EpollPwait::new());
7330        let epoll2 = Syscall::Other(
7331            Sysno::epoll_pwait2,
7332            reverie::syscalls::SyscallArgs::new(0, 0, 0, 0, 0, 0),
7333        );
7334        let before_entry = Err(Error::Errno(Errno::ERESTARTSYS));
7335        let sigsuspend = Syscall::RtSigsuspend(syscalls::RtSigsuspend::new());
7336        let read = Syscall::Read(syscalls::Read::new());
7337        let ebadf = Err(Error::Errno(Errno::EBADF));
7338        use ContinuationMask::*;
7339        for call in [pselect, ppoll] {
7340            assert_eq!(continuation_mask(call, &restart), Temporary, "{call:?}");
7341            assert_eq!(continuation_mask(call, &eintr), Temporary, "{call:?}");
7342            assert_eq!(continuation_mask(call, &before_entry), Restored, "{call:?}");
7343            assert_eq!(continuation_mask(call, &ebadf), Restored, "{call:?}");
7344            assert_eq!(continuation_mask(call, &Ok(1)), Restored, "{call:?}");
7345        }
7346        for result in [&restart, &eintr, &before_entry, &Ok(0)] {
7347            assert_eq!(continuation_mask(sigsuspend, result), Unknown, "{result:?}");
7348        }
7349        for call in [epoll, epoll2] {
7350            assert_eq!(continuation_mask(call, &eintr), Temporary, "{call:?}");
7351            assert_eq!(continuation_mask(call, &restart), Restored, "{call:?}");
7352            assert_eq!(continuation_mask(call, &before_entry), Restored, "{call:?}");
7353            assert_eq!(continuation_mask(call, &Ok(0)), Restored, "{call:?}");
7354        }
7355        assert_eq!(continuation_mask(read, &restart), Restored);
7356    }
7357}