Skip to main content

detcore/syscalls/
io.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! System calls dealing with IO and networking.
10//!
11//! Of course this overlaps somewhat with "files.rs".
12
13use std::net::Ipv4Addr;
14use std::net::Ipv6Addr;
15use std::os::unix::io::RawFd;
16use std::time::Duration;
17
18use nix::fcntl::OFlag;
19use reverie::Errno;
20use reverie::Error;
21use reverie::Guest;
22use reverie::Stack;
23use reverie::syscalls;
24use reverie::syscalls::Addr;
25use reverie::syscalls::AddrMut;
26use reverie::syscalls::Displayable;
27use reverie::syscalls::MemoryAccess;
28use reverie::syscalls::Syscall;
29use reverie::syscalls::SyscallArgs;
30use reverie::syscalls::SyscallInfo;
31use reverie::syscalls::Sysno;
32use reverie::syscalls::Timespec;
33use tracing::debug;
34use tracing::trace;
35
36use crate::config::SchedHeuristic;
37use crate::fd::FdType;
38use crate::record_or_replay::RecordOrReplay;
39use crate::resources::LOOPBACK_POLL_YIELD_FYI;
40use crate::resources::Permission;
41use crate::resources::ResourceID;
42use crate::resources::Resources;
43use crate::scheduler::runqueue::FIRST_PRIORITY;
44use crate::syscalls::helpers::KernelSignalWait;
45use crate::syscalls::helpers::NonblockableSyscall;
46use crate::syscalls::helpers::PublishedWaitMask;
47use crate::syscalls::helpers::REAL_TIME_SIGNALS;
48use crate::syscalls::helpers::RestartCall;
49use crate::syscalls::helpers::act_on_pending_real_time;
50use crate::syscalls::helpers::is_accepted_connection;
51use crate::syscalls::helpers::keep_restart_block;
52use crate::syscalls::helpers::millis_duration_to_absolute_timeout;
53use crate::syscalls::helpers::observe_under_mask;
54use crate::syscalls::helpers::pending_real_time_among;
55use crate::syscalls::helpers::poll_deadline_for;
56use crate::syscalls::helpers::publish_wait_mask;
57use crate::syscalls::helpers::record_retry_event;
58use crate::syscalls::helpers::refuse_held_signal_loss;
59use crate::syscalls::helpers::result_after_restore;
60use crate::syscalls::helpers::retry_blocking_wait_under_mask;
61use crate::syscalls::helpers::retry_nonblocking_syscall_with_timeout;
62use crate::syscalls::helpers::unblocked_by;
63use crate::syscalls::network_trace::received_descriptors;
64use crate::syscalls::signal::STACK_RED_ZONE;
65use crate::syscalls::signal::kernel_installed_signal_mask;
66use crate::syscalls::signal::read_kernel_sigset;
67use crate::syscalls::threads::KernelSigset;
68use crate::syscalls::threads::read_thread_signal_state;
69use crate::syscalls::threads::read_thread_wait_signal_state;
70use crate::tool_global::*;
71use crate::tool_local::Detcore;
72use crate::types::DetTid;
73use crate::types::LogicalTime;
74
75// Printing helper
76// TODO: this should be subsumed by better syscall printing.
77fn print_poll(call: &syscalls::Poll) {
78    let len = call.nfds();
79    debug!("POLL: on {} fds, timeout {}", len, call.timeout());
80    // TODO: nicer API for reading arrays from the guest:
81    unsafe {
82        for i in 0..len {
83            debug!(
84                "POLL: fd {} = {}",
85                i,
86                call.fds().unwrap().offset(i as isize)
87            );
88        }
89    }
90}
91
92/// Build the scheduler request for a zero-timeout poll.
93///
94/// An empty request only rotates the caller within its current priority band. That is not a
95/// yield when a busy poller has a higher priority than the producer whose readiness it is
96/// probing. `SchedYield` excludes the caller from the next selection, allowing exactly one
97/// other runnable guest to make progress before the nonblocking poll executes. Limit that strong
98/// yield to SaBRe tasks with a loopback peer: libcurl alternates its loopback socket with an
99/// internal wakeup fd, and either zero-timeout probe can otherwise starve the peer. General
100/// build-tool polling retains the existing empty-turn behavior.
101fn zero_timeout_poll_request(dettid: DetTid, yield_to_peer: bool) -> Resources {
102    let mut request = Resources::new(dettid);
103    if yield_to_peer {
104        request.insert(ResourceID::SchedYield, Permission::W);
105        request.fyi(LOOPBACK_POLL_YIELD_FYI);
106    }
107    request
108}
109
110fn connect_result_allows_peer_classification(result: &Result<i64, Error>) -> bool {
111    match result {
112        Ok(_) => true,
113        Err(Error::Errno(errno)) => *errno == Errno::EINPROGRESS,
114        Err(_) => false,
115    }
116}
117
118const KERNEL_SIGSET_SIZE: usize = std::mem::size_of::<u64>();
119pub(super) const PSELECT6_INTERNAL_MAX_NFDS: i32 =
120    (std::mem::size_of::<libc::c_ulong>() * 8) as i32;
121
122#[derive(Clone, Copy)]
123#[repr(C)]
124pub(super) struct Pselect6SigmaskArg {
125    pub(super) sigmask: usize,
126    pub(super) sigsetsize: usize,
127}
128
129/// Where a call's private cells (`PrivateCells`) live while the kernel reads
130/// them (`stage_private_cells`).
131enum StagedCellsStorage<Guard> {
132    /// The guest stack scratch below the red zone, checked out by the guard.
133    Stack(Guard),
134    /// Part of the guest's red zone, whose first `len` bytes `saved` holds
135    /// until `StagedCells::release` writes them back.
136    RedZone {
137        at: usize,
138        len: usize,
139        saved: [u8; MAX_PRIVATE_CELLS_LEN],
140    },
141}
142
143/// What a call hands the kernel in place of the guest's own memory: a
144/// temporary signal mask, which a sibling could rewrite while the call waits
145/// and which Hermit sanitizes, and the cell that goes with it. The mask comes
146/// first.
147///
148/// Every layout with a mask takes 24 bytes, the size of replay's signal
149/// delivery for an interrupted call (`end_replayed_pselect6_under_its_temporary_mask`),
150/// so replay can deliver wherever recording found room for the call (Claude
151/// re-review of https://github.com/rrnewton/hermit/pull/4087).
152#[derive(Clone, Copy)]
153enum PrivateCells {
154    /// A pselect6 temporary mask and the `{ sigmask, sigsetsize }` wrapper
155    /// that names it.
156    Pselect6Mask(KernelSigset),
157    /// A temporary mask for a call that takes the mask without a wrapper
158    /// (`epoll_pwait`, a ppoll the kernel waits in), and 16 unused bytes.
159    Mask(KernelSigset),
160    /// A temporary mask and a zero timeout (a zero-timeout ppoll probe, and
161    /// the replayed signal delivery).
162    MaskAndZeroTimeout(KernelSigset),
163    /// A zero timeout alone (a zero-timeout ppoll probe with no mask).
164    ZeroTimeout,
165}
166
167const MASK_LEN: usize = std::mem::size_of::<KernelSigset>();
168
169/// The most any `PrivateCells` takes: a mask and a 16-byte cell.
170const MAX_PRIVATE_CELLS_LEN: usize = MASK_LEN + std::mem::size_of::<Timespec>();
171
172// The wrapper and the timeout share the cell after the mask.
173const _: () = assert!(std::mem::size_of::<Pselect6SigmaskArg>() == std::mem::size_of::<Timespec>());
174
175impl PrivateCells {
176    fn len(self) -> usize {
177        match self {
178            Self::Pselect6Mask(_) | Self::Mask(_) | Self::MaskAndZeroTimeout(_) => {
179                MAX_PRIVATE_CELLS_LEN
180            }
181            Self::ZeroTimeout => std::mem::size_of::<Timespec>(),
182        }
183    }
184
185    /// The cells' bytes when they start at `at`. Only the first `len` count,
186    /// and a zero timeout is all zeroes.
187    fn bytes(self, at: usize) -> [u8; MAX_PRIVATE_CELLS_LEN] {
188        let mut cells = [0u8; MAX_PRIVATE_CELLS_LEN];
189        match self {
190            Self::Pselect6Mask(mask) => {
191                cells[..MASK_LEN].copy_from_slice(&mask.to_ne_bytes());
192                cells[MASK_LEN..MASK_LEN + 8].copy_from_slice(&at.to_ne_bytes());
193                cells[MASK_LEN + 8..].copy_from_slice(&KERNEL_SIGSET_SIZE.to_ne_bytes());
194            }
195            Self::Mask(mask) | Self::MaskAndZeroTimeout(mask) => {
196                cells[..MASK_LEN].copy_from_slice(&mask.to_ne_bytes());
197            }
198            Self::ZeroTimeout => {}
199        }
200        cells
201    }
202}
203
204/// A call's private cells in guest memory (`stage_private_cells`).
205struct StagedCells<Guard> {
206    /// The first cell: the mask, or the zero timeout of
207    /// `PrivateCells::ZeroTimeout`.
208    at: usize,
209    storage: StagedCellsStorage<Guard>,
210    /// Memory for making an expired timerfd readable while these cells hold
211    /// the scratch stack (`crate::syscalls::timerfd::publish_expired_in`);
212    /// `None` for red-zone cells, which hold no stack.
213    timerfd_scratch: Option<crate::syscalls::timerfd::Scratch>,
214}
215
216impl<Guard> StagedCells<Guard> {
217    /// The mask copy.
218    fn mask(&self) -> usize {
219        self.at
220    }
221
222    /// The cell after the mask: a pselect6 wrapper, or a zero timeout.
223    fn after_mask(&self) -> usize {
224        self.at + MASK_LEN
225    }
226
227    /// Gives the storage back once the call has returned: drops the stack
228    /// guard, or writes the guest's red-zone bytes back. That is a write to
229    /// guest memory, not an injected syscall, so a call that ended with a
230    /// restart code goes back to the kernel untouched.
231    fn release<G, T>(self, guest: &mut G)
232    where
233        G: Guest<Detcore<T>>,
234        T: RecordOrReplay,
235    {
236        if let StagedCellsStorage::RedZone { at, len, saved } = self.storage
237            && let Err(errno) = AddrMut::<u8>::from_raw(at)
238                .ok_or(Errno::EFAULT)
239                .and_then(|bytes| guest.memory().write_exact(bytes, &saved[..len]))
240        {
241            // Not expected: the same bytes were written before the call.
242            tracing::warn!("[detcore] could not restore the red zone after a syscall: {errno}");
243        }
244    }
245}
246
247/// Stages `cells` where the kernel can read them in place of the guest's own
248/// memory.
249///
250/// The cells go in the guest stack scratch below the red zone when that is
251/// writable. A thread may run with no writable memory there, on a stack it
252/// placed near the start of a page, and a call on such a stack is valid
253/// (Codex re-check of https://github.com/rrnewton/hermit/pull/4053). Then the
254/// cells go in the red zone, whose bytes are saved here and written back by
255/// `StagedCells::release` when the call returns. The red zone may hold the
256/// call's own buffers, which Linux reads and writes, so the cells take the
257/// highest 8-aligned window that overlaps none of `live` (Codex re-check #3).
258/// The guest's own copies of the cells (its mask, wrapper or timeout) may be
259/// overwritten: Linux reads none of them, as the call is redirected to the
260/// private cells, and all are restored. When no window is free and writable,
261/// this returns `None`, and the caller refuses the call
262/// (`refuse_unstageable_pselect6_mask`). The guest runs no code in between:
263/// the call holds the thread in the kernel, a signal frame is built below the
264/// red zone, and a call the kernel restarts comes back as a new syscall with
265/// the guest's own arguments, which is staged again. Nothing is mapped, so the
266/// guest's address space is unchanged (Codex re-check of the earlier
267/// per-thread page).
268///
269/// Whether the scratch faults is a function of the guest's own stack, so the
270/// choice is deterministic.
271async fn stage_private_cells<G, T>(
272    guest: &mut G,
273    cells: PrivateCells,
274    live: &[std::ops::Range<usize>],
275) -> Result<Option<StagedCells<<G::Stack as Stack>::StackGuard>>, Errno>
276where
277    G: Guest<Detcore<T>>,
278    T: RecordOrReplay,
279{
280    let len = cells.len();
281    let mut stack = guest.stack().await;
282    let at = match cells {
283        PrivateCells::ZeroTimeout => stack.reserve::<Timespec>().as_raw(),
284        _ => stack.reserve::<[u64; 3]>().as_raw(),
285    };
286    // Only a process with an armed virtual timerfd can need the publication
287    // scratch; any other keeps the whole stack for its cells, as before
288    // timerfds were virtualized.
289    let timerfd_scratch = crate::syscalls::timerfd::holds_armed_virtual_timerfd(guest)
290        .then(|| crate::syscalls::timerfd::reserve_scratch(&mut stack));
291    match stack.commit() {
292        Ok(guard) => {
293            let bytes = AddrMut::<u8>::from_raw(at).ok_or(Errno::EFAULT)?;
294            // The commit wrote zeroes, which the cells' address fills in.
295            guest.memory().write_exact(bytes, &cells.bytes(at)[..len])?;
296            return Ok(Some(StagedCells {
297                at,
298                storage: StagedCellsStorage::Stack(guard),
299                timerfd_scratch,
300            }));
301        }
302        Err(Errno::EFAULT) => {}
303        Err(errno) => return Err(errno),
304    }
305    let rsp = guest.regs().await.rsp as usize;
306    let Some(top) = rsp.checked_sub(len).map(|top| top & !7) else {
307        return Ok(None);
308    };
309    let bottom = rsp.saturating_sub(STACK_RED_ZONE);
310    let mut saved = [0u8; MAX_PRIVATE_CELLS_LEN];
311    let mut found = None;
312    for at in (bottom..=top).rev().step_by(8) {
313        let window = at..at + len;
314        if live
315            .iter()
316            .any(|range| range.start < window.end && window.start < range.end)
317        {
318            continue;
319        }
320        let Some(bytes) = AddrMut::<u8>::from_raw(at) else {
321            continue;
322        };
323        if guest.memory().read_exact(bytes, &mut saved[..len]).is_ok() {
324            found = Some((at, bytes));
325            break;
326        }
327    }
328    let Some((at, bytes)) = found else {
329        return Ok(None);
330    };
331    let staged = StagedCells {
332        at,
333        storage: StagedCellsStorage::RedZone { at, len, saved },
334        timerfd_scratch: None,
335    };
336    if guest
337        .memory()
338        .write_exact(bytes, &cells.bytes(at)[..len])
339        .is_err()
340    {
341        // A read-only stack page. A write that failed partway may have changed
342        // some bytes, so put them back.
343        staged.release(guest);
344        return Ok(None);
345    }
346    Ok(Some(staged))
347}
348
349/// The temporary mask a record/replay pselect6 that may wait sleeps under,
350/// read at the call's entry, where Linux copies it (recording waits on a
351/// private copy of it, `handle_pselect6`). The mask is read through the kernel
352/// (`read_kernel_sigset`), so a mask the kernel's copy faults on, such as one
353/// on a `PROT_NONE` page that a tracer read would still return, gives `None`:
354/// the call then keeps the guest's wrapper and the kernel fails it with EFAULT
355/// in Linux's order (Claude review of
356/// https://github.com/rrnewton/hermit/pull/4166). `None` too when the call
357/// has no mask, its wrapper cannot be read, or the size is not the kernel's.
358async fn entry_pselect6_temporary_mask<G, T>(
359    guest: &mut G,
360    call: syscalls::Pselect6,
361) -> Option<KernelSigset>
362where
363    G: Guest<Detcore<T>>,
364    T: RecordOrReplay,
365{
366    let wrapper = call.sigmask()?;
367    let argument: Pselect6SigmaskArg = guest.memory().read_value(wrapper.cast()).ok()?;
368    if argument.sigsetsize != KERNEL_SIGSET_SIZE {
369        return None;
370    }
371    let mask_addr = Addr::<libc::sigset_t>::from_raw(argument.sigmask)?;
372    let mask = read_kernel_sigset(guest, mask_addr).await.ok()?;
373    super::signal_shadow::note_wait_mask(guest, mask);
374    Some(mask)
375}
376
377/// The temporary mask a replayed zero-timeout pselect6 sleeps under, read
378/// once the scheduler grants the call, which keeps its turn until it returns;
379/// `None` when the call has no mask or the wrapper or the mask cannot be read
380/// (`end_replayed_pselect6_under_its_temporary_mask`).
381fn replayed_pselect6_temporary_mask<G, T>(
382    guest: &mut G,
383    call: syscalls::Pselect6,
384) -> Option<KernelSigset>
385where
386    G: Guest<Detcore<T>>,
387    T: RecordOrReplay,
388{
389    let wrapper = call.sigmask()?;
390    let argument: Pselect6SigmaskArg = guest.memory().read_value(wrapper.cast()).ok()?;
391    if argument.sigsetsize != KERNEL_SIGSET_SIZE {
392        return None;
393    }
394    let mask_addr = Addr::<KernelSigset>::from_raw(argument.sigmask)?;
395    let mask = guest.memory().read_value(mask_addr).ok()?;
396    super::signal_shadow::note_wait_mask(guest, mask);
397    Some(mask)
398}
399
400/// Whether replay could deliver a signal that interrupts this record/replay
401/// pselect6 (`end_replayed_pselect6_under_its_temporary_mask`), whose 24 bytes
402/// go in the stack scratch or at the top of the red zone. Recording a
403/// zero-timeout call passes the guest's own wrapper to the kernel, so it
404/// accepts the call on any stack, and a call whose stack pointer is less than
405/// 24 bytes above unwritable memory left replay nowhere to deliver: the kernel
406/// restarted the served call and replay stopped at the next syscall
407/// (https://github.com/rrnewton/hermit/issues/4112). The top 24 bytes of the
408/// red zone are readable exactly when the stack pointer is at least 24 bytes
409/// above unwritable memory, and the stack scratch lies below them, so this
410/// reads them. `true` for a call with no mask to deliver under, and for one
411/// whose wrapper Linux cannot read, which it fails before it waits. A function
412/// of the guest's stack and memory, which replay reproduces.
413async fn replayed_pselect6_delivery_fits<G, T>(guest: &mut G, call: syscalls::Pselect6) -> bool
414where
415    G: Guest<Detcore<T>>,
416    T: RecordOrReplay,
417{
418    let Some(wrapper) = call.sigmask() else {
419        return true;
420    };
421    let argument: Result<Pselect6SigmaskArg, _> = guest.memory().read_value(wrapper.cast());
422    match argument {
423        Ok(argument) if argument.sigmask != 0 => {}
424        _ => return true,
425    }
426    let rsp = guest.regs().await.rsp as usize;
427    let mut cells = [0u8; MAX_PRIVATE_CELLS_LEN];
428    rsp.checked_sub(MAX_PRIVATE_CELLS_LEN)
429        .and_then(|top| AddrMut::<u8>::from_raw(top & !7))
430        .is_some_and(|top| guest.memory().read_exact(top, &mut cells).is_ok())
431}
432
433/// Ends a replayed pselect6 that the recording says a signal interrupted
434/// (`ERESTARTNOHAND`), when the signal is one that only the call's temporary
435/// mask unblocks.
436///
437/// Replay serves pselect6 from the recording, so the kernel never installs the
438/// call's temporary mask. Under the thread's own mask, which blocks the signal
439/// the scheduler sent at the recorded point, the kernel finds nothing to
440/// deliver, restarts the call, and the guest's next system call no longer
441/// matches the recording (https://github.com/rrnewton/hermit/issues/3992).
442/// Linux delivers such a signal before it puts the thread's own mask back, and
443/// the handler's frame restores that mask when it returns. Only the kernel can
444/// do both, so replay injects a ppoll with no descriptors, a zero timeout
445/// and a scratch copy of the mask the call read at entry (`temporary_mask`,
446/// from `replayed_pselect6_temporary_mask`), never the guest's buffer, which a
447/// sibling may have rewritten while the call was served (review of
448/// https://github.com/rrnewton/hermit/pull/4052): the kernel installs
449/// the mask, finds the signal pending, returns `ERESTARTNOHAND` and delivers
450/// the signal, as it did when the recorded call returned. A zero timeout never
451/// sleeps, and Linux writes no remaining time back for it, so neither host
452/// timing nor host time reaches the guest.
453///
454/// A zero-timeout masked pselect6 and a zero-timeout masked ppoll end the same
455/// way when a signal their mask unblocks is already pending, and replay serves
456/// them the same way, so both end through this too
457/// (https://github.com/rrnewton/hermit/issues/4054).
458///
459/// Every value this reads (guest memory, and the kernel's pending set, mask
460/// and dispositions in this thread's turn) is a function of the replayed
461/// schedule. When no such signal is pending, the call returns as before.
462async fn end_replayed_pselect6_under_its_temporary_mask<G, T>(
463    guest: &mut G,
464    temporary_mask: KernelSigset,
465) where
466    G: Guest<Detcore<T>>,
467    T: RecordOrReplay,
468{
469    let Ok(state) = read_thread_signal_state(guest.pid(), guest.tid()) else {
470        return;
471    };
472    if state.pending
473        & state.blocked
474        & state.interrupting(kernel_installed_signal_mask(temporary_mask))
475        == 0
476    {
477        return;
478    }
479    // The cells go in the stack scratch, or at the top of the red zone when
480    // the thread runs on a stack it placed near the start of a page, which is
481    // valid. The guest's red-zone bytes go back once the injected call has
482    // returned. The kernel builds a signal frame below the red zone, and the
483    // guest runs no code before the bytes are back, so it never sees them
484    // change. Nothing is mapped, so the replayed address space stays the
485    // recording's. No window is excluded: the call has returned, and Linux
486    // touches only the cells. The 24 bytes fit wherever recording staged its
487    // own 24-byte mask copy (Claude re-review of
488    // https://github.com/rrnewton/hermit/pull/4087).
489    let Ok(Some(staged)) =
490        stage_private_cells(guest, PrivateCells::MaskAndZeroTimeout(temporary_mask), &[]).await
491    else {
492        return;
493    };
494    inject_signal_delivery(guest, staged.mask(), staged.after_mask()).await;
495    staged.release(guest);
496}
497
498/// Injects the zero-timeout ppoll with no descriptors that delivers a
499/// replayed call's signal under its temporary mask (`mask`), as recording ran
500/// the call itself: the kernel installs the mask, finds the signal pending,
501/// returns `ERESTARTNOHAND` and delivers the signal as the injected call
502/// returns, as it did after the recorded call, and the guest then gets the
503/// recorded result. ppoll takes the mask pointer directly, so the delivery
504/// needs no `{ sigmask, sigsetsize }` wrapper, which a pselect6 would.
505async fn inject_signal_delivery<G, T>(guest: &mut G, mask: usize, zero_timeout: usize)
506where
507    G: Guest<Detcore<T>>,
508    T: RecordOrReplay,
509{
510    let _ = guest
511        .inject(
512            syscalls::Ppoll::new()
513                .with_fds(None)
514                .with_nfds(0)
515                .with_timeout(AddrMut::from_raw(zero_timeout))
516                .with_sigmask(Addr::from_raw(mask))
517                .with_sigsetsize(KERNEL_SIGSET_SIZE),
518        )
519        .await;
520}
521
522pub(super) fn pselect6_fd_set_len(nfds: i32) -> Result<usize, Errno> {
523    let nfds = usize::try_from(nfds).map_err(|_| Errno::EINVAL)?;
524    let bits_per_word = std::mem::size_of::<libc::c_ulong>() * 8;
525    Ok(nfds.div_ceil(bits_per_word) * std::mem::size_of::<libc::c_ulong>())
526}
527
528fn pselect6_probe_result(result: Result<i64, Errno>) -> Result<i64, Errno> {
529    match result {
530        // The injected syscall runs outside the guest's original restart frame.
531        // Do not expose this kernel-internal restart instruction at the
532        // rewritten pselect6 call site.
533        Err(Errno::ERESTARTSYS) => Err(Errno::EINTR),
534        result => result,
535    }
536}
537
538pub(super) fn read_pselect6_fd_set<T, G>(
539    guest: &mut G,
540    address: Option<AddrMut<'_, libc::fd_set>>,
541    len: usize,
542) -> Result<Option<Vec<u8>>, Error>
543where
544    T: RecordOrReplay,
545    G: Guest<Detcore<T>>,
546{
547    let Some(address) = address else {
548        return Ok(None);
549    };
550    let mut bytes = vec![0; len];
551    if len != 0 {
552        guest
553            .memory()
554            .read_exact(address.cast(), &mut bytes)
555            .map_err(|_| Errno::EFAULT)?;
556    }
557    Ok(Some(bytes))
558}
559
560pub(super) fn write_pselect6_fd_set<T, G>(
561    guest: &mut G,
562    address: Option<AddrMut<'_, libc::fd_set>>,
563    bytes: &Option<Vec<u8>>,
564) -> Result<(), Error>
565where
566    T: RecordOrReplay,
567    G: Guest<Detcore<T>>,
568{
569    if let (Some(address), Some(bytes)) = (address, bytes)
570        && !bytes.is_empty()
571    {
572        guest
573            .memory()
574            .write_exact(address.cast(), bytes)
575            .map_err(|_| Errno::EFAULT)?;
576    }
577    Ok(())
578}
579
580fn copy_pselect6_fd_set<T, G>(
581    guest: &mut G,
582    source: Option<AddrMut<'_, libc::fd_set>>,
583    destination: Option<AddrMut<'_, libc::fd_set>>,
584    len: usize,
585) -> Result<(), Error>
586where
587    T: RecordOrReplay,
588    G: Guest<Detcore<T>>,
589{
590    if let (Some(source), Some(destination)) = (source, destination)
591        && len != 0
592    {
593        let mut bytes = vec![0; len];
594        guest
595            .memory()
596            .read_exact(source.cast(), &mut bytes)
597            .map_err(|_| Errno::EFAULT)?;
598        guest
599            .memory()
600            .write_exact(destination.cast(), &bytes)
601            .map_err(|_| Errno::EFAULT)?;
602    }
603    Ok(())
604}
605
606pub(super) fn ppoll_timeout_duration(timeout: Timespec) -> Result<Duration, Errno> {
607    let seconds = u64::try_from(timeout.tv_sec).map_err(|_| Errno::EINVAL)?;
608    let nanoseconds = u32::try_from(timeout.tv_nsec).map_err(|_| Errno::EINVAL)?;
609    if nanoseconds >= 1_000_000_000 {
610        return Err(Errno::EINVAL);
611    }
612    Ok(Duration::new(seconds, nanoseconds))
613}
614
615/// `select`'s timeout as Linux reads it. In Linux v7.1 `kern_select`
616/// (`fs/select.c`) first refuses a negative `tv_sec` or `tv_usec` with
617/// `EINVAL`, then passes `tv_sec + tv_usec / USEC_PER_SEC` seconds and
618/// `(tv_usec % USEC_PER_SEC) * NSEC_PER_USEC` nanoseconds to
619/// `poll_select_set_timeout`, which refuses only what `timespec64_valid`
620/// (`include/linux/time64.h`) refuses: so microseconds of a second or more
621/// fold into the seconds. (v6.12 has no separate sign check, so there a
622/// mixed-sign timeval such as `{2, -1000000}` normalizes to 1 s; v7.1 added
623/// the check because the signed sum could wrap a negative timeout into a
624/// valid one. This follows v7.1, the measured host behaviour.) A sum that
625/// would overflow the signed seconds is `EINVAL` here.
626pub(super) fn select_timeout_duration(timeout: libc::timeval) -> Result<Duration, Errno> {
627    if timeout.tv_sec < 0 || timeout.tv_usec < 0 {
628        return Err(Errno::EINVAL);
629    }
630    let seconds = timeout
631        .tv_sec
632        .checked_add(timeout.tv_usec / 1_000_000)
633        .ok_or(Errno::EINVAL)?;
634    let nanoseconds = (timeout.tv_usec % 1_000_000) * 1_000;
635    Ok(Duration::new(seconds as u64, nanoseconds as u32))
636}
637
638fn timespec_from_duration(duration: Duration) -> Timespec {
639    Timespec {
640        tv_sec: duration.as_secs() as libc::time_t,
641        tv_nsec: duration.subsec_nanos() as libc::c_long,
642    }
643}
644
645const SCM_TIMESTAMP_OLD: libc::c_int = 29;
646const SCM_TIMESTAMPNS_OLD: libc::c_int = 35;
647const SCM_TIMESTAMPING_OLD: libc::c_int = 37;
648const SCM_TIMESTAMP_NEW: libc::c_int = 63;
649const SCM_TIMESTAMPNS_NEW: libc::c_int = 64;
650const SCM_TIMESTAMPING_NEW: libc::c_int = 65;
651const MAX_CONTROL_BYTES: usize = 64 * 1024;
652
653#[derive(Clone, Copy)]
654enum SocketTimestampKind {
655    Timeval,
656    Timespec,
657    Timestamping,
658}
659
660#[derive(Clone, Copy)]
661struct SocketTimestampMessage {
662    data_offset: usize,
663    available_data_len: usize,
664    kind: SocketTimestampKind,
665}
666
667fn cmsg_align(length: usize) -> usize {
668    let alignment = std::mem::size_of::<usize>();
669    (length + alignment - 1) & !(alignment - 1)
670}
671
672fn read_control_value<T: Copy>(bytes: &[u8]) -> Option<T> {
673    if bytes.len() < std::mem::size_of::<T>() {
674        return None;
675    }
676    // SAFETY: the length check guarantees a complete T, and read_unaligned
677    // permits the control buffer's byte alignment.
678    Some(unsafe { bytes.as_ptr().cast::<T>().read_unaligned() })
679}
680
681fn write_control_value<T: Copy>(bytes: &mut [u8], value: T) -> bool {
682    if bytes.len() < std::mem::size_of::<T>() {
683        return false;
684    }
685    // SAFETY: the length check guarantees room for T, and write_unaligned
686    // permits the control buffer's byte alignment.
687    unsafe { bytes.as_mut_ptr().cast::<T>().write_unaligned(value) };
688    true
689}
690
691fn write_control_prefix<T: Copy>(bytes: &mut [u8], value: T) -> usize {
692    let value_len = std::mem::size_of::<T>();
693    let write_len = bytes.len().min(value_len);
694    // SAFETY: `value` is alive for this copy and the resulting byte view has
695    // exactly its initialized object representation.
696    let value_bytes =
697        unsafe { std::slice::from_raw_parts((&value as *const T).cast::<u8>(), value_len) };
698    bytes[..write_len].copy_from_slice(&value_bytes[..write_len]);
699    write_len
700}
701
702fn socket_timestamp_messages(control: &[u8]) -> Vec<SocketTimestampMessage> {
703    let header_len = cmsg_align(std::mem::size_of::<libc::cmsghdr>());
704    let mut messages = Vec::new();
705    let mut offset = 0usize;
706
707    while let Some(header_bytes) = control.get(offset..) {
708        let Some(header) = read_control_value::<libc::cmsghdr>(header_bytes) else {
709            break;
710        };
711        if header.cmsg_len < header_len {
712            break;
713        }
714        let Some(end) = offset.checked_add(header.cmsg_len) else {
715            break;
716        };
717
718        if header.cmsg_level == libc::SOL_SOCKET {
719            let data_offset = offset + header_len;
720            let declared_data_len = header.cmsg_len - header_len;
721            let available_data_len = control
722                .len()
723                .saturating_sub(data_offset)
724                .min(declared_data_len);
725            let kind = match header.cmsg_type {
726                SCM_TIMESTAMP_OLD | SCM_TIMESTAMP_NEW => Some(SocketTimestampKind::Timeval),
727                SCM_TIMESTAMPNS_OLD | SCM_TIMESTAMPNS_NEW => Some(SocketTimestampKind::Timespec),
728                SCM_TIMESTAMPING_OLD | SCM_TIMESTAMPING_NEW => {
729                    Some(SocketTimestampKind::Timestamping)
730                }
731                _ => None,
732            };
733            if let Some(kind) = kind {
734                messages.push(SocketTimestampMessage {
735                    data_offset,
736                    available_data_len,
737                    kind,
738                });
739            }
740        }
741
742        if end > control.len() {
743            break;
744        }
745
746        let step = cmsg_align(header.cmsg_len);
747        let Some(next) = offset.checked_add(step) else {
748            break;
749        };
750        if next <= offset {
751            break;
752        }
753        offset = next;
754    }
755    messages
756}
757
758// AUTONOMOUS-BOT-IMPLEMENTED
759// TODO-HUMAN-REVIEW(PR-901)
760fn canonicalize_socket_timestamps(control: &mut [u8], now: LogicalTime) -> usize {
761    let messages = socket_timestamp_messages(control);
762    let timespec = libc::timespec {
763        tv_sec: now.as_secs() as libc::time_t,
764        tv_nsec: now.subsec_nanos() as libc::c_long,
765    };
766    let timeval = libc::timeval {
767        tv_sec: timespec.tv_sec,
768        tv_usec: (timespec.tv_nsec / 1_000) as libc::suseconds_t,
769    };
770
771    for message in &messages {
772        let available_end = message
773            .data_offset
774            .saturating_add(message.available_data_len)
775            .min(control.len());
776        let data = &mut control[message.data_offset..available_end];
777        match message.kind {
778            SocketTimestampKind::Timeval => {
779                write_control_prefix(data, timeval);
780            }
781            SocketTimestampKind::Timespec => {
782                write_control_prefix(data, timespec);
783            }
784            SocketTimestampKind::Timestamping => {
785                let size = std::mem::size_of::<libc::timespec>();
786                let zero = libc::timespec {
787                    tv_sec: 0,
788                    tv_nsec: 0,
789                };
790                for slot in 0..3 {
791                    let start = slot * size;
792                    if start >= data.len() {
793                        break;
794                    }
795                    let end = (start + size).min(data.len());
796                    let slot_bytes = &mut data[start..end];
797                    if slot_bytes.len() != size {
798                        slot_bytes.fill(0);
799                        continue;
800                    }
801                    let original = read_control_value::<libc::timespec>(slot_bytes)
802                        .expect("complete timestamping slot");
803                    let replacement = if original.tv_sec == 0 && original.tv_nsec == 0 {
804                        zero
805                    } else {
806                        timespec
807                    };
808                    let _ = write_control_value(slot_bytes, replacement);
809                }
810            }
811        }
812    }
813    messages.len()
814}
815
816fn sanitize_ppoll_signal_mask(mask: u64) -> u64 {
817    let signal_bit = (reverie::PERF_EVENT_SIGNAL as usize) - 1;
818    mask & !(1_u64 << signal_bit)
819}
820
821/// The pollfd array a ppoll reads and writes, if it has one.
822fn ppoll_fds_range(call: syscalls::Ppoll) -> Option<std::ops::Range<usize>> {
823    call.fds().map(|fds| {
824        let start = fds.as_raw();
825        let len = usize::try_from(call.nfds())
826            .unwrap_or(usize::MAX)
827            .saturating_mul(std::mem::size_of::<libc::pollfd>());
828        start..start.saturating_add(len)
829    })
830}
831
832/// Whether the kernel owns a ppoll's blocking wait: when threads are not
833/// sequentialized, and for every record/replay call, masked or not, as for a
834/// masked pselect6 (https://github.com/rrnewton/hermit/issues/4042). A masked
835/// sequentialized run-mode wait still takes the probe path.
836fn ppoll_uses_kernel_wait(sequentialize_threads: bool, recordreplay_modes: bool) -> bool {
837    !sequentialize_threads || recordreplay_modes
838}
839
840impl<T: RecordOrReplay> Detcore<T> {
841    /// poll syscall (MAYHANG)
842    // TODO-HUMAN-REVIEW(PR-1023): Review zero-timeout poll scheduling across backends.
843    pub async fn handle_poll<G: Guest<Self>>(
844        &self,
845        guest: &mut G,
846
847        call: syscalls::Poll,
848    ) -> Result<i64, Error> {
849        if self.cfg.sequentialize_threads && call.timeout() == 0 {
850            // This cannot block, but still yield a scheduler turn so a polling thread cannot
851            // monopolize the guest between preemptions.
852            let yield_to_peer = self.cfg.backend.loopback_pollers_yield_to_peers
853                && guest.thread_state().has_loopback_peer();
854            resource_request(
855                guest,
856                zero_timeout_poll_request(guest.thread_state().dettid, yield_to_peer),
857            )
858            .await;
859            if self.cfg.recordreplay_modes {
860                Ok(self.record_or_replay(guest, call).await?)
861            } else {
862                // A virtual timerfd among the fds is readable exactly when its
863                // deadline has passed (`crate::syscalls::timerfd`).
864                crate::syscalls::timerfd::publish_expired(guest).await;
865                Ok(guest.inject(call).await?)
866            }
867        } else if !self.cfg.sequentialize_threads || self.cfg.recordreplay_modes {
868            // In replay mode, we cannot assume the existence of FILES during replay.
869            // Thus we must record the poll and replay it from the trace.
870            Ok(self.handle_external_poll(guest, call).await?)
871        } else {
872            // TODO:
873            // if is-external-poll { self.handle_external_poll(guest, call) }
874            self.handle_internal_poll(guest, call).await
875        }
876    }
877
878    /// Record or replay a raw `select` or `pselect6` the way `poll` is: a zero
879    /// timeout cannot block and takes an ordinary scheduler turn; any other call
880    /// may wait in the kernel, so it runs as a blocking external operation. The
881    /// recorder captures the descriptor sets and remaining time, so replay never
882    /// asks the kernel about descriptors it did not recreate.
883    async fn record_or_replay_select_family<G: Guest<Self>>(
884        &self,
885        guest: &mut G,
886        call: Syscall,
887        zero_timeout: bool,
888    ) -> Result<i64, Error> {
889        if zero_timeout {
890            resource_request(guest, Resources::new(guest.thread_state().dettid)).await;
891            Ok(self.record_or_replay(guest, call).await?)
892        } else {
893            self.record_or_replay_blocking(guest, call).await
894        }
895    }
896
897    /// Refuses a large-nfds pselect6 with a temporary mask, or a record/replay
898    /// one that may wait (`record_or_replay_pselect6_under_a_private_mask`),
899    /// whose private copy has nowhere to go: the stack has no writable scratch below its red zone,
900    /// and every red-zone window overlaps one of the call's own buffers
901    /// (`stage_private_cells`). Forwarding the guest's wrapper instead
902    /// would let a sibling change the mask the kernel installs after the
903    /// scheduler has recorded the one it waits for, so the call could time out
904    /// with a wrong answer (Codex re-check #4 of
905    /// https://github.com/rrnewton/hermit/pull/4053). A fail-closed run stops
906    /// with the policy refusal and this message. A run started with
907    /// `--allow-unsupported-syscalls` runs on: the call keeps the guest's
908    /// wrapper, whose mask a sibling may still change, so the scheduler records
909    /// its sleeping mask as unknown (`Resources::blocked_signal_mask_unknown`),
910    /// not the thread's own, and arms no entry barrier for it (Codex re-check
911    /// #5).
912    async fn refuse_unstageable_pselect6_mask<G: Guest<Self>>(
913        &self,
914        guest: &mut G,
915        call: syscalls::Pselect6,
916    ) -> Result<i64, Error> {
917        use std::io::Write as _;
918        let message = "unsupported: pselect6 with a temporary signal mask, on a stack with \
919            no room below its red zone whose red zone the call's own buffers fill: Hermit \
920            has nowhere to put the private copy of the mask the kernel must install \
921            (https://github.com/rrnewton/hermit/pull/4053)";
922        tracing::error!("[tid {}] {message}", guest.tid());
923        if self.cfg.panic_on_unsupported_syscalls {
924            let _ = writeln!(crate::util::RetryingStderr, "{message}");
925            return self
926                .refuse_unserviceable_operation(guest, Sysno::pselect6, Errno::EFAULT)
927                .await;
928        }
929        self.record_or_replay_blocking_with_unknown_mask(guest, Syscall::Pselect6(call))
930            .await
931    }
932
933    /// Refuses a record/replay pselect6 with a temporary mask on a stack less
934    /// than 24 bytes above unwritable memory, where replay could not deliver a
935    /// signal that interrupts it (`replayed_pselect6_delivery_fits`). Recording
936    /// and replay refuse it alike. A fail-closed run stops with the policy
937    /// refusal and this message, whose result this returns. A run started
938    /// with `--allow-unsupported-syscalls` records the call as before, and a
939    /// replay of an interrupted one stops at the next syscall; this returns
940    /// `None` for it.
941    async fn refuse_undeliverable_pselect6_mask<G: Guest<Self>>(
942        &self,
943        guest: &mut G,
944    ) -> Option<Result<i64, Error>> {
945        use std::io::Write as _;
946        let message = "unsupported: pselect6 with a temporary signal mask on a stack less than \
947            24 bytes above unwritable memory: replay has nowhere to deliver a signal that \
948            interrupts it (https://github.com/rrnewton/hermit/issues/4112)";
949        tracing::error!("[tid {}] {message}", guest.tid());
950        if !self.cfg.panic_on_unsupported_syscalls {
951            return None;
952        }
953        let _ = writeln!(crate::util::RetryingStderr, "{message}");
954        Some(
955            self.refuse_unserviceable_operation(guest, Sysno::pselect6, Errno::EFAULT)
956                .await,
957        )
958    }
959
960    /// Records or replays a masked pselect6 that may wait, under a private
961    /// copy of the mask read at its entry (`mask`), staged clear of the fd
962    /// sets and timeout the kernel reads and writes (`stage_private_cells`).
963    /// The outer `Err` is a staging failure; a call with no room for the copy
964    /// is refused (`refuse_unstageable_pselect6_mask`).
965    async fn record_or_replay_pselect6_under_a_private_mask<G: Guest<Self>>(
966        &self,
967        guest: &mut G,
968        call: syscalls::Pselect6,
969        mask: KernelSigset,
970    ) -> Result<Result<i64, Error>, Error> {
971        let set_len = pselect6_fd_set_len(call.nfds()).unwrap_or(0);
972        let live: Vec<std::ops::Range<usize>> = [
973            call.readfds().map(|set| (set.as_raw(), set_len)),
974            call.writefds().map(|set| (set.as_raw(), set_len)),
975            call.exceptfds().map(|set| (set.as_raw(), set_len)),
976            call.timeout()
977                .map(|timeout| (timeout.as_raw(), std::mem::size_of::<Timespec>())),
978        ]
979        .into_iter()
980        .flatten()
981        .map(|(start, len)| start..start.saturating_add(len))
982        .collect();
983        let Some(staged) =
984            stage_private_cells(guest, PrivateCells::Pselect6Mask(mask), &live).await?
985        else {
986            return Ok(self.refuse_unstageable_pselect6_mask(guest, call).await);
987        };
988        let result = self
989            .record_or_replay_blocking_with_unknown_mask(
990                guest,
991                Syscall::Pselect6(call.with_sigmask(Addr::from_raw(staged.after_mask()))),
992            )
993            .await;
994        staged.release(guest);
995        Ok(result)
996    }
997
998    /// pselect6 syscall (MAYHANG).
999    // AUTONOMOUS-BOT-IMPLEMENTED
1000    // TODO-HUMAN-REVIEW(#686): Review scratch fd sets and scheduler polling.
1001    pub async fn handle_pselect6<G: Guest<Self>>(
1002        &self,
1003        guest: &mut G,
1004        call: syscalls::Pselect6,
1005    ) -> Result<i64, Error> {
1006        if self.cfg.recordreplay_modes {
1007            let zero_timeout = call.timeout().is_some_and(|timeout| {
1008                guest
1009                    .memory()
1010                    .read_value(timeout)
1011                    .is_ok_and(|timeout: Timespec| timeout.tv_sec == 0 && timeout.tv_nsec == 0)
1012            });
1013            // A call with a `{ sigmask, sigsetsize }` wrapper may sleep under a
1014            // temporary mask, and the scheduler must not take the thread's
1015            // ordinary mask for it: it would arm the release barrier for a
1016            // signal the call blocks and wait for a wake Linux never delivers
1017            // (https://github.com/rrnewton/hermit/issues/3963). Nor can this turn
1018            // read the mask the kernel will install: the wrapper may sit in
1019            // memory a tracer read cannot reach though the kernel can, and a
1020            // sibling may rewrite the mask before the kernel copies it. So the
1021            // scheduler records no mask for such a call
1022            // (`Resources::blocked_signal_mask_unknown`). Without a wrapper the
1023            // call sleeps under the thread's own mask, which the scheduler reads.
1024            // A call that may wait sleeps under a private copy of its mask,
1025            // read here, at its entry, where Linux copies it. Handing the kernel
1026            // the guest's wrapper let a sibling turn that ran after the grant
1027            // change the mask the kernel copied, at a point host timing chose,
1028            // and replay could not tell (https://github.com/rrnewton/hermit/issues/4095).
1029            // Replay reads the mask at the same point and delivers a recorded
1030            // interruption under it. A zero-timeout call holds its turn until
1031            // it returns, so no sibling runs before the kernel copies the mask,
1032            // and replay reads it once the call is granted (review of
1033            // https://github.com/rrnewton/hermit/pull/4084). A zero timeout still
1034            // installs the mask and ends the call with ERESTARTNOHAND for a
1035            // pending signal it unblocks
1036            // (https://github.com/rrnewton/hermit/issues/4054).
1037            if !replayed_pselect6_delivery_fits(guest, call).await
1038                && let Some(refused) = self.refuse_undeliverable_pselect6_mask(guest).await
1039            {
1040                return refused;
1041            }
1042            let read_mask = self.cfg.replaying && call.sigmask().is_some();
1043            let mut temporary_mask = None;
1044            let result = if call.sigmask().is_some() && !zero_timeout {
1045                // `None` when the call names no mask, or one the kernel rejects
1046                // or the tracer cannot read, though the kernel can: such a call
1047                // keeps the guest's own wrapper.
1048                let entry_mask = entry_pselect6_temporary_mask(guest, call).await;
1049                if read_mask {
1050                    temporary_mask = entry_mask;
1051                }
1052                match entry_mask {
1053                    Some(mask) => {
1054                        self.record_or_replay_pselect6_under_a_private_mask(guest, call, mask)
1055                            .await?
1056                    }
1057                    None => {
1058                        self.record_or_replay_blocking_with_unknown_mask(
1059                            guest,
1060                            Syscall::Pselect6(call),
1061                        )
1062                        .await
1063                    }
1064                }
1065            } else if zero_timeout {
1066                resource_request(guest, Resources::new(guest.thread_state().dettid)).await;
1067                if read_mask {
1068                    temporary_mask = replayed_pselect6_temporary_mask(guest, call);
1069                }
1070                self.record_or_replay(guest, Syscall::Pselect6(call))
1071                    .await
1072                    .map_err(Into::into)
1073            } else {
1074                self.record_or_replay_blocking(guest, Syscall::Pselect6(call))
1075                    .await
1076            };
1077            if let Some(mask) = temporary_mask
1078                && matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND)))
1079            {
1080                end_replayed_pselect6_under_its_temporary_mask(guest, mask).await;
1081            }
1082            return result;
1083        }
1084        if !self.cfg.sequentialize_threads {
1085            return Ok(guest.inject(call).await?);
1086        }
1087
1088        if call.nfds() < 0 {
1089            return Ok(guest.inject(call).await?);
1090        }
1091
1092        // Linux copies pselect6's outer { sigmask, sigsetsize } wrapper before
1093        // validating the timeout. Copy only the wrapper here; validation of the
1094        // pointed-to signal mask remains below, after timeout validation.
1095        let sigmask_argument = match call.sigmask() {
1096            Some(argument) => {
1097                // A split read can fall back to PTRACE_PEEKDATA for the final
1098                // word, bypassing PROT_NONE or reporting EIO for an unmapped
1099                // page. Have Linux validate both wrapper words first. It copies
1100                // this wrapper before rejecting a malformed timeout, without
1101                // reading the inner mask, changing it, waiting, or writing output.
1102                let mut stack = guest.stack().await;
1103                let validation_timeout = stack.reserve::<Timespec>();
1104                let _guard = stack.commit()?;
1105                guest.memory().write_value(
1106                    validation_timeout,
1107                    &Timespec {
1108                        tv_sec: 0,
1109                        tv_nsec: 1_000_000_000,
1110                    },
1111                )?;
1112                let validation = syscalls::Pselect6::new()
1113                    .with_nfds(0)
1114                    .with_readfds(None)
1115                    .with_writefds(None)
1116                    .with_exceptfds(None)
1117                    .with_timeout(Some(validation_timeout))
1118                    .with_sigmask(Some(argument));
1119                match guest.inject(validation).await {
1120                    Err(Errno::EINVAL) => {}
1121                    // The call's first injection
1122                    // (`restart_if_first_probe_not_run`).
1123                    Err(errno) => {
1124                        return crate::syscalls::signal::restart_if_first_probe_not_run(Err(
1125                            errno.into()
1126                        ));
1127                    }
1128                    // Success would mean the backend did not validate the probe.
1129                    Ok(_) => return Err(Errno::EIO.into()),
1130                }
1131                let argument: Pselect6SigmaskArg = guest.memory().read_value(argument.cast())?;
1132                Some(argument)
1133            }
1134            None => None,
1135        };
1136        let raw_timeout = match call.timeout() {
1137            Some(timeout) => {
1138                let timeout: Timespec = guest.memory().read_value(timeout)?;
1139                Some(timeout)
1140            }
1141            None => None,
1142        };
1143        let timeout = raw_timeout.map(ppoll_timeout_duration).transpose()?;
1144        if let Some(argument) = sigmask_argument
1145            && argument.sigmask != 0
1146        {
1147            self.observe_under_temporary_mask(
1148                guest,
1149                Addr::<libc::sigset_t>::from_raw(argument.sigmask),
1150                argument.sigsetsize,
1151            )
1152            .await?;
1153        }
1154        if timeout == Some(Duration::ZERO) {
1155            // A virtual timerfd among the sets is readable exactly when its
1156            // deadline has passed (`crate::syscalls::timerfd`).
1157            crate::syscalls::timerfd::publish_expired(guest).await;
1158            return Ok(guest.inject(call).await?);
1159        }
1160
1161        // Linux clamps raw fd-set copies to the process fd table's current max_fds.
1162        // Its initial table holds one machine word; larger nfds values can therefore
1163        // require fewer bytes than a userspace calculation predicts. Keep those calls
1164        // under kernel ownership rather than over-reading the guest bitmap.
1165        if call.nfds() > PSELECT6_INTERNAL_MAX_NFDS {
1166            // The kernel sleeps under the inner mask, so record it for the
1167            // scheduler's SIGCHLD target choice (`Resources::blocked_signal_mask`).
1168            // A mask the kernel would reject (wrong size, or a pointer it cannot
1169            // read) fails the real call before it sleeps or installs anything, so
1170            // the thread's own mask is the right record there (`None`).
1171            let snapshot = match sigmask_argument {
1172                Some(argument)
1173                    if argument.sigmask != 0 && argument.sigsetsize == KERNEL_SIGSET_SIZE =>
1174                {
1175                    match Addr::<libc::sigset_t>::from_raw(argument.sigmask) {
1176                        Some(mask_addr) => {
1177                            let mask = read_kernel_sigset(guest, mask_addr).await.ok();
1178                            if let Some(mask) = mask {
1179                                super::signal_shadow::note_wait_mask(guest, mask);
1180                            }
1181                            mask
1182                        }
1183                        None => None,
1184                    }
1185                }
1186                _ => None,
1187            };
1188            let Some(mask) = snapshot else {
1189                return self
1190                    .record_or_replay_blocking_with_mask(guest, Syscall::Pselect6(call), None)
1191                    .await;
1192            };
1193            // The call sleeps under a private copy of the mask read here, not the
1194            // guest's wrapper: a sibling may rewrite the guest's buffer before the
1195            // released call reaches the kernel, and the scheduler waits for the
1196            // kernel to install exactly this mask (`background_entry_barriers`,
1197            // Codex review of https://github.com/rrnewton/hermit/pull/4053). The
1198            // wrapper and the mask were validated above, in Linux's order. The
1199            // copy stays readable until the call has rejoined.
1200            // The buffers Linux reads and writes, which the copy must not
1201            // overlap. The fd sets span at most their nominal length; Linux
1202            // may copy less.
1203            let set_len = pselect6_fd_set_len(call.nfds())?;
1204            let live: Vec<std::ops::Range<usize>> = [
1205                call.readfds().map(|set| (set.as_raw(), set_len)),
1206                call.writefds().map(|set| (set.as_raw(), set_len)),
1207                call.exceptfds().map(|set| (set.as_raw(), set_len)),
1208                call.timeout()
1209                    .map(|timeout| (timeout.as_raw(), std::mem::size_of::<Timespec>())),
1210            ]
1211            .into_iter()
1212            .flatten()
1213            .map(|(start, len)| start..start.saturating_add(len))
1214            .collect();
1215            let Some(staged) =
1216                stage_private_cells(guest, PrivateCells::Pselect6Mask(mask), &live).await?
1217            else {
1218                return self.refuse_unstageable_pselect6_mask(guest, call).await;
1219            };
1220            let result = self
1221                .record_or_replay_blocking_with_mask(
1222                    guest,
1223                    Syscall::Pselect6(call.with_sigmask(Addr::from_raw(staged.after_mask()))),
1224                    Some(kernel_installed_signal_mask(mask)),
1225                )
1226                .await;
1227            staged.release(guest);
1228            return result;
1229        }
1230
1231        // Linux wraps pselect6's temporary mask in { pointer, size }. Glibc supplies
1232        // the wrapper even when the inner pointer is null. A real mask must stay in
1233        // effect for the whole wait so an unblocked signal (make's jobserver unblocks
1234        // SIGCHLD) can interrupt it. Previously that forced the external-blocking path,
1235        // whose completion timing is host-decided and is a source of `make -jN`
1236        // execution-log divergence. With SIGCHLD admission now deterministic (scheduler
1237        // `sigchld_deferred`/`sigchld_ready`), honor the mask on each deterministic poll
1238        // probe instead: a pending unblocked signal is observed at a scheduler-decided
1239        // probe point rather than at host signal-arrival time.
1240        let sigmask = if let Some(argument) = sigmask_argument {
1241            if argument.sigmask != 0 {
1242                if argument.sigsetsize != KERNEL_SIGSET_SIZE {
1243                    return Err(Errno::EINVAL.into());
1244                }
1245                let mask_addr =
1246                    Addr::<libc::sigset_t>::from_raw(argument.sigmask).ok_or(Errno::EFAULT)?;
1247                let mask = read_kernel_sigset(guest, mask_addr).await?;
1248                super::signal_shadow::note_wait_mask(guest, mask);
1249                Some(sanitize_ppoll_signal_mask(mask))
1250            } else {
1251                None
1252            }
1253        } else {
1254            None
1255        };
1256        // The inner mask was snapshotted above. Do not let later guest mutations of the
1257        // outer wrapper change the meaning of a retry probe.
1258        let call = call.with_sigmask(None);
1259
1260        self.handle_internal_pselect6(guest, call, timeout, sigmask)
1261            .await
1262    }
1263
1264    async fn handle_internal_pselect6<G: Guest<Self>>(
1265        &self,
1266        guest: &mut G,
1267        call: syscalls::Pselect6,
1268        timeout: Option<Duration>,
1269        sigmask: Option<u64>,
1270    ) -> Result<i64, Error> {
1271        let len = pselect6_fd_set_len(call.nfds())?;
1272        let deadline = match timeout {
1273            Some(timeout) => Some(thread_observe_time(guest).await + timeout),
1274            None => None,
1275        };
1276        let original_readfds = match read_pselect6_fd_set(guest, call.readfds(), len) {
1277            Ok(value) => value,
1278            Err(error) => {
1279                self.write_pselect6_remaining(guest, call, deadline).await?;
1280                return Err(error);
1281            }
1282        };
1283        let original_writefds = match read_pselect6_fd_set(guest, call.writefds(), len) {
1284            Ok(value) => value,
1285            Err(error) => {
1286                self.write_pselect6_remaining(guest, call, deadline).await?;
1287                return Err(error);
1288            }
1289        };
1290        let original_exceptfds = match read_pselect6_fd_set(guest, call.exceptfds(), len) {
1291            Ok(value) => value,
1292            Err(error) => {
1293                self.write_pselect6_remaining(guest, call, deadline).await?;
1294                return Err(error);
1295            }
1296        };
1297
1298        let mut stack = guest.stack().await;
1299        let readfds = call.readfds().map(|_| stack.reserve::<libc::fd_set>());
1300        let writefds = call.writefds().map(|_| stack.reserve::<libc::fd_set>());
1301        let exceptfds = call.exceptfds().map(|_| stack.reserve::<libc::fd_set>());
1302        // pselect6's timeout is a writable in-out kernel timespec, so the probe
1303        // needs a mutable scratch cell (re-zeroed each iteration below to keep
1304        // every probe a non-blocking poll).
1305        let probe_timeout = stack.reserve::<Timespec>();
1306        // Carry the temporary signal mask on every zero-timeout probe so the kernel
1307        // applies it atomically: a pending, mask-unblocked signal makes the probe return
1308        // EINTR at a deterministic scheduler point. The probe's wrapper points at scratch
1309        // memory the guard keeps alive across each injection.
1310        // On a backend whose kernel reports the guest's signal state, a
1311        // `KernelSignalWait` below decides interruption against the temporary
1312        // mask instead (`with_wait_mask`), and the probes carry no mask.
1313        let kernel_signal_wait = self.cfg.backend.supports_blocked_wait_signal_interruption;
1314        let probe_sigmask = sigmask.filter(|_| !kernel_signal_wait).map(|mask| {
1315            let sigset = stack.push(mask);
1316            stack
1317                .push(Pselect6SigmaskArg {
1318                    sigmask: sigset.as_raw(),
1319                    sigsetsize: KERNEL_SIGSET_SIZE,
1320                })
1321                .cast()
1322        });
1323        // On a backend whose kernel reports the guest's signal state, only a
1324        // signal that would end the wait natively does; the mask cell lets the
1325        // wait block signals under the one scratch-stack guard
1326        // (https://github.com/rrnewton/hermit/issues/3146). A temporary mask is
1327        // the mask the call sleeps under, as Linux installs it for the whole
1328        // call: a signal it blocks never ends the call, and one it unblocks ends
1329        // it although the guest's own mask blocks it (`with_wait_mask`,
1330        // https://github.com/rrnewton/hermit/issues/3991). A restart resumes from
1331        // the remaining time written back below, so a default stop ends the wait
1332        // as on Linux. Unlike the other waits, it holds no signal until the call
1333        // returns, so a pending caught `SIGCHLD` ends it as on Linux, whoever
1334        // sent it, at a turn that host timing can choose: a known gap that this
1335        // wait had before (`KernelSignalWait::for_select`).
1336        let mut signals = kernel_signal_wait.then(|| {
1337            KernelSignalWait::for_select(guest)
1338                .with_wait_mask(sigmask.map(crate::syscalls::signal::kernel_installed_signal_mask))
1339        });
1340        // Set when a signal the temporary mask unblocks, pending in the kernel,
1341        // ends the call: the kernel must then deliver it under that mask (see
1342        // below).
1343        let mut deliver_under_temporary_mask = false;
1344        let mask_cell = signals.as_ref().map(|_| stack.reserve::<KernelSigset>());
1345        // This frame holds the scratch stack across every probe, so the
1346        // memory that makes an expired timerfd readable is reserved here
1347        // (`crate::syscalls::timerfd::publish_expired_in`).
1348        let timerfd_scratch = crate::syscalls::timerfd::reserve_scratch(&mut stack);
1349        let _guard = stack.commit()?;
1350        // The scheduler reads the effective mask while the wait parks
1351        // (`publish_wait_mask`).
1352        let mut published = PublishedWaitMask::default();
1353        if let Some(signals) = signals.as_ref() {
1354            publish_wait_mask(guest, signals.effective_mask(), &mut published).await;
1355        }
1356        let probe = call
1357            .with_readfds(readfds)
1358            .with_writefds(writefds)
1359            .with_exceptfds(exceptfds)
1360            .with_timeout(Some(probe_timeout))
1361            .with_sigmask(probe_sigmask);
1362
1363        let mut resources = Resources::new(guest.thread_state().dettid);
1364        resources.insert(ResourceID::InternalIOPolling, Permission::W);
1365        resources.fyi("pselect6");
1366        resources.poll_deadline = poll_deadline_for(guest, deadline);
1367        // Keep the request metadata accurate, but do not make it eligible for
1368        // the scheduler's ERESTARTSYS wakeup. A cross-task signal must first be
1369        // checked against pselect6's snapshotted temporary mask and disposition.
1370        resources.set_signal_interrupt_errno(Errno::EINTR);
1371
1372        // Every exit, including a `?` on a guest-memory write, must reach the mask
1373        // restore below, so the loop runs in its own async block.
1374        let result: Result<i64, Error> = {
1375            // Moved reborrows: a future holding a shared reference to a scratch
1376            // address would not be `Send`.
1377            let guest = &mut *guest;
1378            let signals = &mut signals;
1379            let resources = &mut resources;
1380            let published = &mut published;
1381            let deliver_under_temporary_mask = &mut deliver_under_temporary_mask;
1382            async move {
1383                loop {
1384                    let signaled = matches!(
1385                        resource_request(guest, resources.clone()).await,
1386                        ResumeStatus::Signaled(_)
1387                    );
1388                    // Virtual timerfds first (`crate::syscalls::timerfd`).
1389                    let next_timerfd =
1390                        crate::syscalls::timerfd::publish_expired_in(guest, Some(timerfd_scratch))
1391                            .await;
1392                    resources.poll_deadline =
1393                        crate::syscalls::timerfd::poll_deadline_with(guest, deadline, next_timerfd);
1394                    // A pending real-time timer expiration that this wait would
1395                    // be ended by, under the guest's mask or the call's temporary
1396                    // one (https://github.com/rrnewton/hermit/issues/4089).
1397                    let pending = pending_real_time_among(guest, REAL_TIME_SIGNALS).await;
1398                    if pending != 0 {
1399                        let (observable, discarded) = match (signals.as_ref(), sigmask) {
1400                            (Some(signals), _) => (signals.observable_now()?, 0),
1401                            (None, Some(mask)) => unblocked_by(
1402                                &read_thread_wait_signal_state(guest.pid(), guest.tid())?,
1403                                mask,
1404                            ),
1405                            (None, None) => (0, 0),
1406                        };
1407                        act_on_pending_real_time(guest, pending, observable, discarded).await;
1408                    }
1409                    // Every turn probes before it looks at pending signals, as Linux
1410                    // does: do_select polls every descriptor on each pass and returns
1411                    // the count of ready ones before it tests signal_pending, and at
1412                    // the start max_select_fd returns EBADF for a descriptor that is
1413                    // not open (`core_sys_select`). So a descriptor that becomes ready
1414                    // in a later turn in which a signal is also pending is reported
1415                    // (round-12 Medium on https://github.com/rrnewton/hermit/pull/3361).
1416                    // Each probe is a new select call, so a descriptor closed during
1417                    // the wait gets EBADF, where Linux reports it ready. Without the
1418                    // kernel's signal state, a scheduler `Signaled` answer still ends
1419                    // the call before the probe.
1420                    if signals.is_none() && signaled {
1421                        self.write_pselect6_remaining(guest, call, deadline).await?;
1422                        return Err(Errno::EINTR.into());
1423                    }
1424                    guest.memory().write_value(
1425                        probe_timeout,
1426                        &Timespec {
1427                            tv_sec: 0,
1428                            tv_nsec: 0,
1429                        },
1430                    )?;
1431                    write_pselect6_fd_set(guest, probe.readfds(), &original_readfds)?;
1432                    write_pselect6_fd_set(guest, probe.writefds(), &original_writefds)?;
1433                    write_pselect6_fd_set(guest, probe.exceptfds(), &original_exceptfds)?;
1434
1435                    let raw_result = match signals.as_mut() {
1436                        // A signal stop that does not end the wait is absorbed (see
1437                        // `KernelSignalWait`). Every probe runs before the turn's check
1438                        // (`inject_first_probe`): a signal that would end the wait and
1439                        // stops the probe is held, the probe runs again, and the signal
1440                        // is delivered as the call returns. Once `block` has blocked
1441                        // every blockable signal, a pending one cannot stop the probe.
1442                        Some(signals) => match signals.inject_first_probe(guest, probe).await {
1443                            Ok(result) => result,
1444                            Err(error) => {
1445                                self.write_pselect6_remaining(guest, call, deadline).await?;
1446                                break Err(error);
1447                            }
1448                        },
1449                        None => guest.inject(probe).await,
1450                    };
1451                    let result = pselect6_probe_result(raw_result);
1452                    if result != Ok(0) {
1453                        let copy_result = if result.is_ok() {
1454                            self.copy_pselect6_results(guest, probe, call, len)
1455                        } else {
1456                            Ok(())
1457                        };
1458                        self.write_pselect6_remaining(guest, call, deadline).await?;
1459                        copy_result?;
1460                        break result.map_err(Into::into);
1461                    }
1462                    // The turn's check, after its probe found no descriptor ready and no
1463                    // error: only then does a pending signal end the call. A scheduler
1464                    // `Signaled` answer is only a hint here; the kernel's state decides.
1465                    // pselect6 returns ERESTARTNOHAND: EINTR after a handler, a restart
1466                    // with the remaining timeout after a stop.
1467                    if let Some(signals) = signals.as_ref() {
1468                        match signals.interrupted_with_state() {
1469                            Ok((false, _)) => {}
1470                            Ok((true, state)) => {
1471                                self.write_pselect6_remaining(guest, call, deadline).await?;
1472                                // A signal the backend holds, or one the guest's own
1473                                // mask leaves unblocked, is delivered as the call
1474                                // returns. One that only the temporary mask unblocks
1475                                // stays pending under the guest's own mask, and must be
1476                                // delivered under the temporary mask.
1477                                *deliver_under_temporary_mask = !signals.holds_signal()
1478                                    && signals.interrupts_only_under_wait_mask(&state);
1479                                break Err(Errno::ERESTARTNOHAND.into());
1480                            }
1481                            Err(error) => break Err(error),
1482                        }
1483                    }
1484                    if let Some(signals) = signals.as_mut()
1485                        && signals.needs_block()
1486                        && let Err(error) = signals.block(guest, mask_cell).await
1487                    {
1488                        self.write_pselect6_remaining(guest, call, deadline).await?;
1489                        break Err(error);
1490                    }
1491                    if let Some(signals) = signals.as_ref() {
1492                        publish_wait_mask(guest, signals.effective_mask(), published).await;
1493                    }
1494
1495                    resources.poll_attempt += 1;
1496                    if let Some(deadline) = deadline
1497                        && thread_observe_time(guest).await >= deadline
1498                    {
1499                        let copy_result = self.copy_pselect6_results(guest, probe, call, len);
1500                        self.write_pselect6_remaining(guest, call, Some(deadline))
1501                            .await?;
1502                        copy_result?;
1503                        break Ok(0);
1504                    }
1505                    trace!(
1506                        "Retry #{} for syscall due to result Ok(0): {}",
1507                        resources.poll_attempt,
1508                        probe.display(&guest.memory())
1509                    );
1510                    record_retry_event(guest, probe).await;
1511                }
1512            }
1513            .await
1514        };
1515        let result = match &mut signals {
1516            Some(signals) => {
1517                let restored = signals.restore(guest, mask_cell).await;
1518                publish_wait_mask(guest, None, &mut published).await;
1519                result_after_restore(restored, result)?
1520            }
1521            None => result,
1522        };
1523        // Restoring the guest's mask cannot deliver that signal, which the mask
1524        // blocks, but check again that the backend holds nothing.
1525        if deliver_under_temporary_mask
1526            && !signals.as_ref().is_some_and(KernelSignalWait::holds_signal)
1527            && let Some(mask) = sigmask
1528            && matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND)))
1529        {
1530            // Linux delivers such a signal before it puts the guest's own mask
1531            // back, which may block it, and the handler's frame restores the
1532            // guest's mask when it returns. Only the kernel can do both, so the
1533            // thread makes one more call, a ppoll with no descriptors, a zero
1534            // timeout and the call's temporary mask, as replay delivers a
1535            // recorded call's signal (`inject_signal_delivery`): the kernel
1536            // installs the mask, finds the signal pending, returns
1537            // ERESTARTNOHAND and delivers it as the call returns, EINTR after a
1538            // handler (https://github.com/rrnewton/hermit/issues/3991).
1539            // - The mask is a private copy of the one this call read at entry
1540            //   (`sigmask`), as Linux copies it once at entry; the guest's
1541            //   buffer, which a sibling may have rewritten since, is not read
1542            //   again (review of https://github.com/rrnewton/hermit/pull/4051).
1543            // - A zero timeout never sleeps, and Linux writes no remaining time
1544            //   back for it; the guest's timeout already holds the remaining
1545            //   time written above.
1546            // - A plain injection, not a tail injection, so the rest of this
1547            //   handler and Detcore's post-syscall work still run.
1548            drop(_guard);
1549            // No room for the cells cannot happen in practice: this call's
1550            // probe cells, at least as large, were committed in the same stack
1551            // scratch above. Should it happen, the signal stays pending under
1552            // the guest's own mask and the call returns EINTR without its
1553            // handler run, as before this delivery existed.
1554            match stage_private_cells(guest, PrivateCells::MaskAndZeroTimeout(mask), &[]).await? {
1555                Some(staged) => {
1556                    inject_signal_delivery(guest, staged.mask(), staged.after_mask()).await;
1557                    staged.release(guest);
1558                }
1559                None => tracing::warn!(
1560                    "[tid {}] no room to deliver a pselect6 signal under its temporary mask; \
1561                     its handler runs only once the guest unblocks it",
1562                    guest.tid()
1563                ),
1564            }
1565        }
1566        refuse_held_signal_loss(guest, Sysno::pselect6, result).await
1567    }
1568
1569    fn copy_pselect6_results<G: Guest<Self>>(
1570        &self,
1571        guest: &mut G,
1572        probe: syscalls::Pselect6,
1573        call: syscalls::Pselect6,
1574        len: usize,
1575    ) -> Result<(), Error> {
1576        copy_pselect6_fd_set(guest, probe.readfds(), call.readfds(), len)?;
1577        copy_pselect6_fd_set(guest, probe.writefds(), call.writefds(), len)?;
1578        copy_pselect6_fd_set(guest, probe.exceptfds(), call.exceptfds(), len)
1579    }
1580
1581    pub(super) async fn write_pselect6_remaining<G: Guest<Self>>(
1582        &self,
1583        guest: &mut G,
1584        call: syscalls::Pselect6,
1585        deadline: Option<LogicalTime>,
1586    ) -> Result<(), Error> {
1587        if let (Some(timeout), Some(deadline)) = (call.timeout(), deadline) {
1588            let now = thread_observe_time(guest).await;
1589            let remaining = deadline.as_nanos().saturating_sub(now.as_nanos());
1590            let remaining = Timespec {
1591                tv_sec: (remaining / 1_000_000_000) as libc::time_t,
1592                tv_nsec: (remaining % 1_000_000_000) as libc::c_long,
1593            };
1594            // pselect6's timeout is a writable in-out kernel timespec; reverie-syscalls
1595            // now types it as `AddrMut<Timespec>`, so the remaining time can be written
1596            // back directly without an unsafe pointer cast.
1597            if let Err(error) = guest.memory().write_value(timeout, &remaining) {
1598                // Linux preserves the pselect6 result when remaining-time copyout faults.
1599                trace!(?error, "ignoring pselect6 timeout writeback failure");
1600            }
1601        }
1602        Ok(())
1603    }
1604
1605    /// select syscall (MAYHANG).
1606    ///
1607    /// `select` is the classic `timeval` sibling of `pselect6` (which is already
1608    /// Determinized). It reuses the pselect6 fd-set scratch machinery, but takes
1609    /// a `struct timeval` timeout (which Linux updates in place with the time not
1610    /// slept) and carries no signal mask.
1611    // AUTONOMOUS-BOT-IMPLEMENTED
1612    // TODO-HUMAN-REVIEW(#800): Review select determinization mirroring pselect6.
1613    pub async fn handle_select<G: Guest<Self>>(
1614        &self,
1615        guest: &mut G,
1616        call: syscalls::Select,
1617    ) -> Result<i64, Error> {
1618        if self.cfg.recordreplay_modes {
1619            let zero_timeout = call.timeout().is_some_and(|timeout| {
1620                guest
1621                    .memory()
1622                    .read_value(timeout)
1623                    .is_ok_and(|timeout: libc::timeval| timeout.tv_sec == 0 && timeout.tv_usec == 0)
1624            });
1625            return self
1626                .record_or_replay_select_family(guest, Syscall::Select(call), zero_timeout)
1627                .await;
1628        }
1629        if !self.cfg.sequentialize_threads {
1630            return Ok(guest.inject(call).await?);
1631        }
1632
1633        if call.nfds() < 0 {
1634            return Ok(guest.inject(call).await?);
1635        }
1636
1637        let raw_timeout = match call.timeout() {
1638            Some(timeout) => {
1639                let timeout: libc::timeval = guest.memory().read_value(timeout)?;
1640                Some(timeout)
1641            }
1642            None => None,
1643        };
1644        if matches!(raw_timeout, Some(timeout) if timeout.tv_sec == 0 && timeout.tv_usec == 0) {
1645            // A zero timeout is a pure non-blocking poll; the kernel can service it directly,
1646            // once a virtual timerfd among the sets is readable exactly when its deadline
1647            // has passed (`crate::syscalls::timerfd`).
1648            crate::syscalls::timerfd::publish_expired(guest).await;
1649            return Ok(guest.inject(call).await?);
1650        }
1651
1652        // Mirror pselect6: keep large fd tables under kernel ownership rather than
1653        // over-reading the guest bitmap (Linux clamps raw fd-set copies to max_fds).
1654        if call.nfds() > PSELECT6_INTERNAL_MAX_NFDS {
1655            return self
1656                .record_or_replay_blocking(guest, Syscall::Select(call))
1657                .await;
1658        }
1659
1660        let timeout = raw_timeout.map(select_timeout_duration).transpose()?;
1661        self.handle_internal_select(guest, call, timeout).await
1662    }
1663
1664    async fn handle_internal_select<G: Guest<Self>>(
1665        &self,
1666        guest: &mut G,
1667        call: syscalls::Select,
1668        timeout: Option<Duration>,
1669    ) -> Result<i64, Error> {
1670        let len = pselect6_fd_set_len(call.nfds())?;
1671        let deadline = match timeout {
1672            Some(timeout) => Some(thread_observe_time(guest).await + timeout),
1673            None => None,
1674        };
1675        let original_readfds = match read_pselect6_fd_set(guest, call.readfds(), len) {
1676            Ok(value) => value,
1677            Err(error) => {
1678                self.write_select_remaining(guest, call, deadline).await?;
1679                return Err(error);
1680            }
1681        };
1682        let original_writefds = match read_pselect6_fd_set(guest, call.writefds(), len) {
1683            Ok(value) => value,
1684            Err(error) => {
1685                self.write_select_remaining(guest, call, deadline).await?;
1686                return Err(error);
1687            }
1688        };
1689        let original_exceptfds = match read_pselect6_fd_set(guest, call.exceptfds(), len) {
1690            Ok(value) => value,
1691            Err(error) => {
1692                self.write_select_remaining(guest, call, deadline).await?;
1693                return Err(error);
1694            }
1695        };
1696
1697        let mut stack = guest.stack().await;
1698        let readfds = call.readfds().map(|_| stack.reserve::<libc::fd_set>());
1699        let writefds = call.writefds().map(|_| stack.reserve::<libc::fd_set>());
1700        let exceptfds = call.exceptfds().map(|_| stack.reserve::<libc::fd_set>());
1701        // select modifies its timeout in place, so the probe timeout must be a
1702        // writable scratch cell. It is re-zeroed each iteration to keep every
1703        // probe a non-blocking poll (a NULL timeout would block indefinitely).
1704        let probe_timeout = stack.reserve::<libc::timeval>();
1705        // On a backend whose kernel reports the guest's signal state, only a signal
1706        // that would end the wait natively does; the mask cell lets the wait block
1707        // signals under the one scratch-stack guard
1708        // (https://github.com/rrnewton/hermit/issues/3146). A restart resumes from
1709        // the remaining time written back below, so a default stop ends the wait
1710        // as on Linux. Unlike the other waits, it holds no signal until the call
1711        // returns, so a pending caught `SIGCHLD` ends it as on Linux, whoever
1712        // sent it, at a turn that host timing can choose: a known gap that this
1713        // wait had before (`KernelSignalWait::for_select`).
1714        let mut signals = self
1715            .cfg
1716            .backend
1717            .supports_blocked_wait_signal_interruption
1718            .then(|| KernelSignalWait::for_select(guest));
1719        let mask_cell = signals.as_ref().map(|_| stack.reserve::<KernelSigset>());
1720        // This frame holds the scratch stack across every probe, so the
1721        // memory that makes an expired timerfd readable is reserved here
1722        // (`crate::syscalls::timerfd::publish_expired_in`).
1723        let timerfd_scratch = crate::syscalls::timerfd::reserve_scratch(&mut stack);
1724        let _guard = stack.commit()?;
1725        // The scheduler reads the effective mask while the wait parks
1726        // (`publish_wait_mask`).
1727        let mut published = PublishedWaitMask::default();
1728        if let Some(signals) = signals.as_ref() {
1729            publish_wait_mask(guest, signals.effective_mask(), &mut published).await;
1730        }
1731        let probe = call
1732            .with_readfds(readfds)
1733            .with_writefds(writefds)
1734            .with_exceptfds(exceptfds)
1735            .with_timeout(Some(probe_timeout));
1736
1737        let mut resources = Resources::new(guest.thread_state().dettid);
1738        resources.insert(ResourceID::InternalIOPolling, Permission::W);
1739        resources.fyi("select");
1740        resources.poll_deadline = poll_deadline_for(guest, deadline);
1741        // EINTR records select's interruption result. The scheduler only wakes
1742        // ERESTARTSYS requests: blocked and ignored signals still need a target-
1743        // side disposition check before this Signaled path can be used.
1744        resources.set_signal_interrupt_errno(Errno::EINTR);
1745
1746        // Every exit, including a `?` on a guest-memory write, must reach the mask
1747        // restore below, so the loop runs in its own async block.
1748        let result: Result<i64, Error> = {
1749            // Moved reborrows: a future holding a shared reference to a scratch
1750            // address would not be `Send`.
1751            let guest = &mut *guest;
1752            let signals = &mut signals;
1753            let resources = &mut resources;
1754            let published = &mut published;
1755            async move {
1756                loop {
1757                    let signaled = matches!(
1758                        resource_request(guest, resources.clone()).await,
1759                        ResumeStatus::Signaled(_)
1760                    );
1761                    // Virtual timerfds first (`crate::syscalls::timerfd`).
1762                    let next_timerfd =
1763                        crate::syscalls::timerfd::publish_expired_in(guest, Some(timerfd_scratch))
1764                            .await;
1765                    resources.poll_deadline =
1766                        crate::syscalls::timerfd::poll_deadline_with(guest, deadline, next_timerfd);
1767                    // A pending real-time timer expiration that this wait would
1768                    // be ended by (https://github.com/rrnewton/hermit/issues/4089).
1769                    let pending = pending_real_time_among(guest, REAL_TIME_SIGNALS).await;
1770                    if pending != 0
1771                        && let Some(signals) = signals.as_ref()
1772                    {
1773                        let observable = signals.observable_now()?;
1774                        act_on_pending_real_time(guest, pending, observable, 0).await;
1775                    }
1776                    // Every turn probes before it looks at pending signals, as Linux
1777                    // does: do_select polls every descriptor on each pass and returns
1778                    // the count of ready ones before it tests signal_pending, and at
1779                    // the start max_select_fd returns EBADF for a descriptor that is
1780                    // not open (`core_sys_select`). So a descriptor that becomes ready
1781                    // in a later turn in which a signal is also pending is reported
1782                    // (round-12 Medium on https://github.com/rrnewton/hermit/pull/3361).
1783                    // Each probe is a new select call, so a descriptor closed during
1784                    // the wait gets EBADF, where Linux reports it ready. Without the
1785                    // kernel's signal state, a scheduler `Signaled` answer still ends
1786                    // the call before the probe.
1787                    if signals.is_none() && signaled {
1788                        self.write_select_remaining(guest, call, deadline).await?;
1789                        return Err(Errno::EINTR.into());
1790                    }
1791                    guest.memory().write_value(
1792                        probe_timeout,
1793                        &libc::timeval {
1794                            tv_sec: 0,
1795                            tv_usec: 0,
1796                        },
1797                    )?;
1798                    write_pselect6_fd_set(guest, probe.readfds(), &original_readfds)?;
1799                    write_pselect6_fd_set(guest, probe.writefds(), &original_writefds)?;
1800                    write_pselect6_fd_set(guest, probe.exceptfds(), &original_exceptfds)?;
1801
1802                    let result = match signals.as_mut() {
1803                        // A signal stop that does not end the wait is absorbed (see
1804                        // `KernelSignalWait`). Every probe runs before the turn's check
1805                        // (`inject_first_probe`): a signal that would end the wait and
1806                        // stops the probe is held, the probe runs again, and the signal
1807                        // is delivered as the call returns. Once `block` has blocked
1808                        // every blockable signal, a pending one cannot stop the probe.
1809                        Some(signals) => match signals.inject_first_probe(guest, probe).await {
1810                            Ok(result) => result,
1811                            Err(error) => {
1812                                self.write_select_remaining(guest, call, deadline).await?;
1813                                break Err(error);
1814                            }
1815                        },
1816                        None => guest.inject(probe).await,
1817                    };
1818                    if result != Ok(0) {
1819                        let copy_result = if result.is_ok() {
1820                            self.copy_select_results(guest, probe, call, len)
1821                        } else {
1822                            Ok(())
1823                        };
1824                        self.write_select_remaining(guest, call, deadline).await?;
1825                        copy_result?;
1826                        break result.map_err(Into::into);
1827                    }
1828                    // The turn's check, after its probe found no descriptor ready and no
1829                    // error: only then does a pending signal end the call. A scheduler
1830                    // `Signaled` answer is only a hint here; the kernel's state decides.
1831                    // select returns ERESTARTNOHAND: EINTR after a handler, a restart
1832                    // with the remaining timeout after a stop.
1833                    if let Some(signals) = signals.as_ref() {
1834                        match signals.interrupted_with_state() {
1835                            Ok((false, _)) => {}
1836                            Ok((true, _)) => {
1837                                self.write_select_remaining(guest, call, deadline).await?;
1838                                break Err(Errno::ERESTARTNOHAND.into());
1839                            }
1840                            Err(error) => break Err(error),
1841                        }
1842                    }
1843                    if let Some(signals) = signals.as_mut()
1844                        && signals.needs_block()
1845                        && let Err(error) = signals.block(guest, mask_cell).await
1846                    {
1847                        self.write_select_remaining(guest, call, deadline).await?;
1848                        break Err(error);
1849                    }
1850                    if let Some(signals) = signals.as_ref() {
1851                        publish_wait_mask(guest, signals.effective_mask(), published).await;
1852                    }
1853
1854                    resources.poll_attempt += 1;
1855                    if let Some(deadline) = deadline
1856                        && thread_observe_time(guest).await >= deadline
1857                    {
1858                        let copy_result = self.copy_select_results(guest, probe, call, len);
1859                        self.write_select_remaining(guest, call, Some(deadline))
1860                            .await?;
1861                        copy_result?;
1862                        break Ok(0);
1863                    }
1864                    trace!(
1865                        "Retry #{} for syscall due to result Ok(0): {}",
1866                        resources.poll_attempt,
1867                        probe.display(&guest.memory())
1868                    );
1869                    record_retry_event(guest, probe).await;
1870                }
1871            }
1872            .await
1873        };
1874        let result = match &mut signals {
1875            Some(signals) => {
1876                let restored = signals.restore(guest, mask_cell).await;
1877                publish_wait_mask(guest, None, &mut published).await;
1878                result_after_restore(restored, result)?
1879            }
1880            None => result,
1881        };
1882        refuse_held_signal_loss(guest, Sysno::select, result).await
1883    }
1884
1885    fn copy_select_results<G: Guest<Self>>(
1886        &self,
1887        guest: &mut G,
1888        probe: syscalls::Select,
1889        call: syscalls::Select,
1890        len: usize,
1891    ) -> Result<(), Error> {
1892        copy_pselect6_fd_set(guest, probe.readfds(), call.readfds(), len)?;
1893        copy_pselect6_fd_set(guest, probe.writefds(), call.writefds(), len)?;
1894        copy_pselect6_fd_set(guest, probe.exceptfds(), call.exceptfds(), len)
1895    }
1896
1897    pub(super) async fn write_select_remaining<G: Guest<Self>>(
1898        &self,
1899        guest: &mut G,
1900        call: syscalls::Select,
1901        deadline: Option<LogicalTime>,
1902    ) -> Result<(), Error> {
1903        if let (Some(timeout), Some(deadline)) = (call.timeout(), deadline) {
1904            let now = thread_observe_time(guest).await;
1905            let remaining = deadline.as_nanos().saturating_sub(now.as_nanos());
1906            let remaining = libc::timeval {
1907                tv_sec: (remaining / 1_000_000_000) as libc::time_t,
1908                tv_usec: ((remaining % 1_000_000_000) / 1_000) as libc::suseconds_t,
1909            };
1910            // select's timeout is a writable in-out kernel timeval reporting the
1911            // time not slept; derive it from deterministic virtual time.
1912            if let Err(error) = guest.memory().write_value(timeout, &remaining) {
1913                // Linux preserves the select result when remaining-time copyout faults.
1914                trace!(?error, "ignoring select timeout writeback failure");
1915            }
1916        }
1917        Ok(())
1918    }
1919
1920    /// ppoll syscall (MAYHANG)
1921    // TODO-HUMAN-REVIEW(PR-273)
1922    pub async fn handle_ppoll<G: Guest<Self>>(
1923        &self,
1924        guest: &mut G,
1925        call: syscalls::Ppoll,
1926    ) -> Result<i64, Error> {
1927        let timeout_address = call.timeout();
1928        let timeout = match timeout_address {
1929            Some(timeout) => Some(ppoll_timeout_duration(guest.memory().read_value(timeout)?)?),
1930            None => None,
1931        };
1932
1933        let result: Result<i64, Error> = if timeout == Some(Duration::ZERO) {
1934            if self.cfg.recordreplay_modes {
1935                resource_request(guest, Resources::new(guest.thread_state().dettid)).await;
1936            } else {
1937                // A virtual timerfd among the fds is readable exactly when its
1938                // deadline has passed (`crate::syscalls::timerfd`); before the
1939                // probe's copies take the scratch stack.
1940                crate::syscalls::timerfd::publish_expired(guest).await;
1941            }
1942            // A virtual timerfd's expiration is published first, so the
1943            // mask's read is not the call's first step.
1944            let (probe, staged) = match self.prepare_ppoll_probe(guest, call, false).await? {
1945                Some((probe, staged)) => (probe, Some(staged)),
1946                None => {
1947                    if let Some(refused) = self.refuse_unstageable_ppoll_copy(guest).await {
1948                        return refused;
1949                    }
1950                    // Runs on with the guest's own zero timeout and mask.
1951                    (call, None)
1952                }
1953            };
1954            // The mask the probe installs, read at entry, for replay to deliver
1955            // under (https://github.com/rrnewton/hermit/issues/4054).
1956            let temporary_mask = if self.cfg.replaying {
1957                match call.sigmask() {
1958                    Some(signal_mask) => read_kernel_sigset(guest, signal_mask)
1959                        .await
1960                        .ok()
1961                        .map(sanitize_ppoll_signal_mask),
1962                    None => None,
1963                }
1964            } else {
1965                None
1966            };
1967            if let Some(mask) = temporary_mask {
1968                super::signal_shadow::note_wait_mask(guest, mask);
1969            }
1970            // No `?` on the call's own result: an interruption must reach the
1971            // replay delivery below.
1972            let result: Result<i64, Error> = if self.cfg.recordreplay_modes {
1973                self.record_or_replay(guest, probe)
1974                    .await
1975                    .map_err(Into::into)
1976            } else {
1977                guest.inject_with_retry(probe).await.map_err(Into::into)
1978            };
1979            if let Some(staged) = staged {
1980                staged.release(guest);
1981            }
1982            // Replay serves the probe from the recording, so the kernel never
1983            // installs its mask; deliver a recorded interruption under it, as
1984            // for pselect6.
1985            if let Some(mask) = temporary_mask
1986                && matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND)))
1987            {
1988                end_replayed_pselect6_under_its_temporary_mask(guest, mask).await;
1989            }
1990            // Linux does not write back an initially zero timeout. Besides matching the
1991            // kernel, omitting this write matters when the timeout aliases the pollfd array:
1992            // the injected probe may have just stored revents in those same bytes.
1993            result
1994        } else if ppoll_uses_kernel_wait(
1995            self.cfg.sequentialize_threads,
1996            self.cfg.recordreplay_modes,
1997        ) {
1998            // The kernel owns the blocking wait (`ppoll_uses_kernel_wait`). Use
1999            // a private copy only for the signal mask so raw ppoll can still
2000            // update the guest timeout.
2001            let mut staged = None;
2002            // The mask the real call sleeps under, recorded for the scheduler's
2003            // SIGCHLD target choice (`Resources::blocked_signal_mask`).
2004            let mut blocked_signal_mask = None;
2005            // The mask read at entry, for replay to deliver under.
2006            let mut temporary_mask = None;
2007            let call = if let Some(signal_mask) = call.sigmask() {
2008                if call.sigsetsize() != KERNEL_SIGSET_SIZE {
2009                    return Err(Errno::EINVAL.into());
2010                }
2011                let signal_mask = crate::syscalls::signal::restart_if_first_probe_not_run(
2012                    read_kernel_sigset(guest, signal_mask).await,
2013                )?;
2014                super::signal_shadow::note_wait_mask(guest, signal_mask);
2015                let signal_mask = sanitize_ppoll_signal_mask(signal_mask);
2016                blocked_signal_mask = Some(kernel_installed_signal_mask(signal_mask));
2017                temporary_mask = Some(signal_mask);
2018                // Linux writes revents into the pollfd array and the time left
2019                // into the timeout, so the copy overlaps neither.
2020                let live: Vec<std::ops::Range<usize>> = ppoll_fds_range(call)
2021                    .into_iter()
2022                    .chain(call.timeout().map(|timeout| {
2023                        let start = timeout.as_raw();
2024                        start..start.saturating_add(std::mem::size_of::<Timespec>())
2025                    }))
2026                    .collect();
2027                match stage_private_cells(guest, PrivateCells::Mask(signal_mask), &live).await? {
2028                    Some(cells) => {
2029                        let mask = cells.mask();
2030                        staged = Some(cells);
2031                        call.with_sigmask(Addr::from_raw(mask))
2032                    }
2033                    None => {
2034                        if let Some(refused) = self.refuse_unstageable_ppoll_copy(guest).await {
2035                            return refused;
2036                        }
2037                        // Runs on with the guest's own mask. A sibling may
2038                        // change it while the call waits, which a masked
2039                        // record/replay wait already allows for: its sleeping
2040                        // mask is recorded as unknown.
2041                        call
2042                    }
2043                }
2044            } else {
2045                call
2046            };
2047            // A masked record/replay wait sleeps under a temporary mask the
2048            // scheduler records as unknown, as a masked pselect6's does
2049            // (`Resources::blocked_signal_mask_unknown`), although Hermit knows
2050            // it exactly. A known mask would let the scheduler wait for the
2051            // kernel to install it, and replay serves the call from the
2052            // recording without the kernel ever doing so; recording and replay
2053            // must schedule the call alike. The result has no `?`: an
2054            // interruption must reach the replay delivery below.
2055            let result: Result<i64, Error> =
2056                if self.cfg.recordreplay_modes && temporary_mask.is_some() {
2057                    self.record_or_replay_blocking_with_unknown_mask(guest, Syscall::Ppoll(call))
2058                        .await
2059                } else {
2060                    self.record_or_replay_blocking_with_mask(
2061                        guest,
2062                        Syscall::Ppoll(call),
2063                        blocked_signal_mask,
2064                    )
2065                    .await
2066                };
2067            if let Some(staged) = staged {
2068                staged.release(guest);
2069            }
2070            // Replay serves the call from the recording, so the kernel never
2071            // installs its mask; deliver a recorded interruption under it
2072            // (https://github.com/rrnewton/hermit/issues/3992).
2073            if self.cfg.replaying
2074                && let Some(mask) = temporary_mask
2075                && matches!(result, Err(Error::Errno(Errno::ERESTARTNOHAND)))
2076            {
2077                end_replayed_pselect6_under_its_temporary_mask(guest, mask).await;
2078            }
2079            result
2080        } else {
2081            self.handle_internal_ppoll(guest, call, timeout).await
2082        };
2083
2084        result
2085    }
2086
2087    /// The zero-timeout probe for `call`: it reads a private zero timeout,
2088    /// and a private, sanitized copy of the call's mask, staged by
2089    /// `stage_private_cells` clear of the pollfd array that Linux writes. So
2090    /// neither a sibling's write nor the guest's own mask can make the probe
2091    /// sleep or block Hermit's timer signal. `None` when the copies have
2092    /// nowhere to go (`refuse_unstageable_ppoll_copy`). `first` says the
2093    /// mask's read is the call's first injection, so a signal that stops it
2094    /// restarts the call (`restart_if_first_probe_not_run`).
2095    async fn prepare_ppoll_probe<G: Guest<Self>>(
2096        &self,
2097        guest: &mut G,
2098        call: syscalls::Ppoll,
2099        first: bool,
2100    ) -> Result<
2101        Option<(
2102            syscalls::Ppoll,
2103            StagedCells<<G::Stack as Stack>::StackGuard>,
2104        )>,
2105        Error,
2106    > {
2107        let signal_mask = match call.sigmask() {
2108            Some(signal_mask) => {
2109                if call.sigsetsize() != KERNEL_SIGSET_SIZE {
2110                    return Err(Errno::EINVAL.into());
2111                }
2112                let read = read_kernel_sigset(guest, signal_mask).await;
2113                let signal_mask = if first {
2114                    crate::syscalls::signal::restart_if_first_probe_not_run(read)?
2115                } else {
2116                    read?
2117                };
2118                super::signal_shadow::note_wait_mask(guest, signal_mask);
2119                // The probe's temporary mask lets the kernel take a pending
2120                // real-time timer expiration that every thread blocked when it
2121                // expired (https://github.com/rrnewton/hermit/issues/4089).
2122                observe_under_mask(guest, signal_mask).await?;
2123                Some(sanitize_ppoll_signal_mask(signal_mask))
2124            }
2125            None => None,
2126        };
2127        let cells = match signal_mask {
2128            Some(signal_mask) => PrivateCells::MaskAndZeroTimeout(signal_mask),
2129            None => PrivateCells::ZeroTimeout,
2130        };
2131        let live: Vec<std::ops::Range<usize>> = ppoll_fds_range(call).into_iter().collect();
2132        let Some(staged) = stage_private_cells(guest, cells, &live).await? else {
2133            return Ok(None);
2134        };
2135        let probe = match signal_mask {
2136            Some(_) => call
2137                .with_timeout(AddrMut::from_raw(staged.after_mask()))
2138                .with_sigmask(Addr::from_raw(staged.mask())),
2139            None => call.with_timeout(AddrMut::from_raw(staged.at)),
2140        };
2141        Ok(Some((probe, staged)))
2142    }
2143
2144    /// Refuses a ppoll whose private copies have nowhere to go
2145    /// (`stage_private_cells`): a zero-timeout probe's zero timeout and mask,
2146    /// or the mask of a call the kernel waits in. The stack has no writable
2147    /// scratch below its red zone, and every red-zone window overlaps the
2148    /// pollfd array or, for a kernel wait, the timeout
2149    /// (https://github.com/rrnewton/hermit/issues/4113). A fail-closed run
2150    /// stops with the policy refusal and this message, whose result this
2151    /// returns. A run started with `--allow-unsupported-syscalls` runs on with
2152    /// the guest's own timeout and mask, and this returns `None`.
2153    async fn refuse_unstageable_ppoll_copy<G: Guest<Self>>(
2154        &self,
2155        guest: &mut G,
2156    ) -> Option<Result<i64, Error>> {
2157        use std::io::Write as _;
2158        let message = "unsupported: ppoll on a stack with no room below its red zone whose \
2159            red zone the call's pollfd array and timeout fill: Hermit has nowhere to put its \
2160            private copy of the timeout and the signal mask \
2161            (https://github.com/rrnewton/hermit/issues/4113)";
2162        tracing::error!("[tid {}] {message}", guest.tid());
2163        if !self.cfg.panic_on_unsupported_syscalls {
2164            return None;
2165        }
2166        let _ = writeln!(crate::util::RetryingStderr, "{message}");
2167        Some(
2168            self.refuse_unserviceable_operation(guest, Sysno::ppoll, Errno::EFAULT)
2169                .await,
2170        )
2171    }
2172
2173    /// Handle a guest-internal `ppoll` using zero-time kernel probes.
2174    async fn handle_internal_ppoll<G: Guest<Self>>(
2175        &self,
2176        guest: &mut G,
2177        call: syscalls::Ppoll,
2178        timeout: Option<Duration>,
2179    ) -> Result<i64, Error> {
2180        debug_assert_ne!(timeout, Some(Duration::ZERO));
2181        let timeout_address = call.timeout();
2182        let started_at = if timeout.is_some() {
2183            Some(thread_observe_time(guest).await)
2184        } else {
2185            None
2186        };
2187        let deadline = match (timeout, started_at) {
2188            (Some(duration), Some(started_at)) => Some(started_at + duration),
2189            (None, None) => None,
2190            _ => unreachable!(),
2191        };
2192
2193        // Every zero-timeout probe carries a private copy of the call's temporary
2194        // mask, so the kernel applies it atomically, as pselect6's probes do
2195        // (`handle_internal_pselect6`). A pending signal that the mask lets in
2196        // ends a probe with ERESTARTNOHAND at that probe's scheduler point, and
2197        // the kernel delivers it under the temporary mask and only then puts the
2198        // thread's own mask back, as Linux does for a ppoll that a signal
2199        // interrupts. That probe is the last injection before the guest
2200        // resumes, so nothing disturbs the pending restore
2201        // (https://github.com/rrnewton/reverie/issues/1003). A ppoll that would
2202        // block used to return ENOSYS here
2203        // (https://github.com/rrnewton/hermit/issues/4042).
2204        if call.sigmask().is_some() {
2205            // Only the virtual clock was read before: the mask's read is the
2206            // call's first injection.
2207            let Some((probe, staged)) = self.prepare_ppoll_probe(guest, call, true).await? else {
2208                // The guest's own mask could block Hermit's timer signal while
2209                // the call is parked, so a run that allows unsupported
2210                // operations gets the same answer as a mask it cannot honor.
2211                return match self.refuse_unstageable_ppoll_copy(guest).await {
2212                    Some(refused) => refused,
2213                    None => Err(Errno::ENOSYS.into()),
2214                };
2215            };
2216            let result = if self.cfg.backend.supports_blocked_wait_signal_interruption {
2217                self.wait_on_masked_ppoll_probe(
2218                    guest,
2219                    probe,
2220                    staged.mask(),
2221                    staged.timerfd_scratch,
2222                    deadline,
2223                )
2224                .await
2225            } else {
2226                // Without the kernel's signal state, Hermit cannot tell whether
2227                // the backend holds a signal that should end the wait, so a
2228                // ppoll that would block still fails closed. An expired
2229                // timerfd on virtual time is made readable first, in the
2230                // staged cells' scratch (`crate::syscalls::timerfd`).
2231                crate::syscalls::timerfd::publish_expired_in(guest, staged.timerfd_scratch).await;
2232                let result = guest.inject_with_retry(probe).await;
2233                if probe.syscall_would_have_blocked(result) {
2234                    Err(Errno::ENOSYS.into())
2235                } else {
2236                    result.map_err(Into::into)
2237                }
2238            };
2239            // Before the time left is written: the copies' red-zone window may
2240            // cover the guest's timeout, which Linux never sees.
2241            staged.release(guest);
2242            if let (Some(timeout_address), Some(timeout), Some(started_at)) =
2243                (timeout_address, timeout, started_at)
2244            {
2245                self.write_ppoll_remaining(guest, timeout_address, timeout, started_at)
2246                    .await?;
2247            }
2248            return result;
2249        }
2250
2251        let mut rsrc = Resources::new(guest.thread_state().dettid);
2252        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2253        rsrc.fyi("ppoll");
2254        let result = retry_nonblocking_syscall_with_timeout(guest, call, rsrc, deadline).await;
2255        if let (Some(timeout_address), Some(timeout), Some(started_at)) =
2256            (timeout_address, timeout, started_at)
2257        {
2258            self.write_ppoll_remaining(guest, timeout_address, timeout, started_at)
2259                .await?;
2260        }
2261        result
2262    }
2263
2264    /// The wait of a ppoll with a temporary mask under sequentialized threads:
2265    /// `probe`, a zero-timeout copy of the call that reads the mask staged at
2266    /// `mask` (`prepare_ppoll_probe`), runs once per scheduler turn until it
2267    /// reports a ready descriptor or an error, until a signal that the mask
2268    /// lets in ends the wait, or until `deadline` passes, which returns 0.
2269    ///
2270    /// The probe carries the mask, so the kernel ends a probe with
2271    /// ERESTARTNOHAND for a pending signal the mask lets in, and delivers it
2272    /// under the mask as the call returns. A signal that the guest's own mask
2273    /// lets in can instead stop a probe before the kernel installs the mask;
2274    /// the backend then holds it, and `KernelSignalWait` decides against the
2275    /// call's mask whether it ends the wait (`with_wait_mask`). Without that,
2276    /// the wait ran on to its deadline, or forever, with the signal held. The
2277    /// backend delivers a held signal under the guest's own mask
2278    /// (https://github.com/rrnewton/reverie/issues/1011). A signal that only
2279    /// the mask lets in can be pending at a turn's check without having ended
2280    /// that turn's probe only if it arrived from outside the guest between
2281    /// the two; the next probe, which carries the mask, ends the call for it
2282    /// and the kernel delivers it under the mask. The wait never blocks
2283    /// signals (`KernelSignalWait::block`): a probe that a signal ended would
2284    /// then leave the all-blocked mask to be restored.
2285    ///
2286    /// Every probe runs before the turn's check, as Linux's do_poll polls every
2287    /// descriptor before it tests for a pending signal. The wait holds no
2288    /// signal until the call returns (`KernelSignalWait::for_select`): the
2289    /// kernel ends a probe for any pending signal the mask lets in, `SIGCHLD`
2290    /// included, so a `SIGCHLD` the kernel posts for a child ends it at a turn
2291    /// that host timing chooses, the known gap that select and pselect6 waits
2292    /// share (https://github.com/rrnewton/hermit/issues/3146).
2293    async fn wait_on_masked_ppoll_probe<G: Guest<Self>>(
2294        &self,
2295        guest: &mut G,
2296        probe: syscalls::Ppoll,
2297        mask: usize,
2298        timerfd_scratch: Option<crate::syscalls::timerfd::Scratch>,
2299        deadline: Option<LogicalTime>,
2300    ) -> Result<i64, Error> {
2301        let temporary_mask: KernelSigset = guest
2302            .memory()
2303            .read_value(Addr::<KernelSigset>::from_raw(mask).ok_or(Errno::EFAULT)?)?;
2304        let mut signals = KernelSignalWait::for_select(guest)
2305            .with_wait_mask(Some(crate::syscalls::signal::kernel_installed_signal_mask(
2306                temporary_mask,
2307            )))
2308            .with_deadline(deadline.is_some());
2309        let mut rsrc = Resources::new(guest.thread_state().dettid);
2310        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2311        rsrc.fyi("ppoll");
2312        rsrc.poll_deadline = poll_deadline_for(guest, deadline);
2313        // As for pselect6: a scheduler `Signaled` answer wakes the wait, and
2314        // the probe and the kernel's state decide whether a signal ends it.
2315        rsrc.set_signal_interrupt_errno(Errno::EINTR);
2316        // Between probes the kernel holds the guest's own mask, while Linux's
2317        // `blocked` is the temporary one for the whole call.
2318        let mut published = PublishedWaitMask::default();
2319        publish_wait_mask(guest, signals.effective_mask(), &mut published).await;
2320        let result = loop {
2321            resource_request(guest, rsrc.clone()).await;
2322            // Virtual timerfds first (`crate::syscalls::timerfd`), in the
2323            // staged cells' scratch while they hold the stack.
2324            let next_timerfd =
2325                crate::syscalls::timerfd::publish_expired_in(guest, timerfd_scratch).await;
2326            rsrc.poll_deadline =
2327                crate::syscalls::timerfd::poll_deadline_with(guest, deadline, next_timerfd);
2328            // A pending real-time timer expiration that the temporary mask lets
2329            // the kernel deliver or discard
2330            // (https://github.com/rrnewton/hermit/issues/4089).
2331            if let Err(error) = observe_under_mask(guest, temporary_mask).await {
2332                break Err(error);
2333            }
2334            let injected = match signals.inject_first_probe(guest, probe).await {
2335                Ok(result) => result,
2336                Err(error) => break Err(error),
2337            };
2338            if !probe.syscall_would_have_blocked(injected) {
2339                break injected.map_err(Into::into);
2340            }
2341            match signals.interrupted_with_state() {
2342                Ok((false, _)) => {}
2343                // The next probe ends the call for it (see above).
2344                Ok((true, state))
2345                    if !signals.holds_signal()
2346                        && signals.interrupts_only_under_wait_mask(&state) =>
2347                {
2348                    continue;
2349                }
2350                Ok((true, _)) => break Err(Errno::ERESTARTNOHAND.into()),
2351                Err(error) => break Err(error),
2352            }
2353            rsrc.poll_attempt += 1;
2354            if let Some(deadline) = deadline
2355                && thread_observe_time(guest).await >= deadline
2356            {
2357                break Ok(0);
2358            }
2359            record_retry_event(guest, probe).await;
2360        };
2361        publish_wait_mask(guest, None, &mut published).await;
2362        refuse_held_signal_loss(guest, Sysno::ppoll, result).await
2363    }
2364
2365    pub(super) async fn write_ppoll_remaining<G: Guest<Self>>(
2366        &self,
2367        guest: &mut G,
2368        timeout_address: AddrMut<'_, Timespec>,
2369        timeout: Duration,
2370        started_at: LogicalTime,
2371    ) -> Result<(), Error> {
2372        let now = thread_observe_time(guest).await;
2373        let elapsed = Duration::from_nanos(now.as_nanos().saturating_sub(started_at.as_nanos()));
2374        let remaining = timeout.saturating_sub(elapsed);
2375        if let Err(error) = guest
2376            .memory()
2377            .write_value(timeout_address, &timespec_from_duration(remaining))
2378        {
2379            // Linux preserves the ppoll result when remaining-time copyout faults.
2380            trace!(?error, "ignoring ppoll timeout writeback failure");
2381        }
2382        Ok(())
2383    }
2384
2385    /// Handle a guest-internal poll call that can be fully determinized.
2386    // TODO-HUMAN-REVIEW(PR-1052): Review scheduler fairness for zero-timeout poll.
2387    pub async fn handle_internal_poll<G: Guest<Self>>(
2388        &self,
2389        guest: &mut G,
2390        call: syscalls::Poll,
2391    ) -> Result<i64, Error> {
2392        let timeout_millis = call.timeout();
2393        if timeout_millis == 0 {
2394            // A nonblocking poll can still be the synchronization point in a
2395            // userspace polling loop. Yield once before probing so backends
2396            // without PMU preemption cannot let that loop starve its producer.
2397            let yield_to_peer = self.cfg.backend.loopback_pollers_yield_to_peers
2398                && guest.thread_state().has_loopback_peer();
2399            resource_request(
2400                guest,
2401                zero_timeout_poll_request(guest.thread_state().dettid, yield_to_peer),
2402            )
2403            .await;
2404            crate::syscalls::timerfd::publish_expired(guest).await;
2405            Ok(guest.inject(call).await?) // Already non-blocking.
2406        } else {
2407            let maybe_timeout_ns = millis_duration_to_absolute_timeout(guest, timeout_millis).await;
2408            self.handle_internal_poll_until(guest, call, maybe_timeout_ns)
2409                .await
2410        }
2411    }
2412
2413    /// The blocking half of `handle_internal_poll`, waiting until `deadline`. A
2414    /// `restart_syscall` resumes an interrupted `poll` here with the deadline the
2415    /// wait kept, as Linux's `do_restart_poll` does
2416    /// (`Detcore::handle_restart_syscall`).
2417    pub(crate) async fn handle_internal_poll_until<G: Guest<Self>>(
2418        &self,
2419        guest: &mut G,
2420        call: syscalls::Poll,
2421        deadline: Option<LogicalTime>,
2422    ) -> Result<i64, Error> {
2423        let mut rsrc = Resources::new(guest.thread_state().dettid);
2424        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2425        rsrc.fyi("poll");
2426        let result = retry_nonblocking_syscall_with_timeout(guest, call, rsrc, deadline).await;
2427        keep_restart_block(guest, &result, RestartCall::Poll(call), deadline).await;
2428        result
2429    }
2430
2431    /// Handle a poll syscall that deponds on external, nondeterminstic IO.
2432    pub async fn handle_external_poll<G: Guest<Self>>(
2433        &self,
2434        guest: &mut G,
2435        call: syscalls::Poll,
2436    ) -> Result<i64, Error> {
2437        let len = call.nfds();
2438        let time_delta = Duration::from_millis(call.timeout() as u64);
2439
2440        if len == 0 && time_delta.is_zero() {
2441            let request = Self::sleep_request(guest, time_delta).await;
2442            resource_request(guest, request).await;
2443            Ok(0)
2444        } else {
2445            print_poll(&call);
2446            Ok(self
2447                .record_or_replay_blocking(guest, Syscall::Poll(call))
2448                .await?)
2449        }
2450    }
2451
2452    /// epoll_create1 syscall
2453    pub async fn handle_epoll_create1<G: Guest<Self>>(
2454        &self,
2455        guest: &mut G,
2456        call: syscalls::EpollCreate1,
2457    ) -> Result<i64, Error> {
2458        let dettid = guest.thread_state().dettid;
2459        resource_request(guest, Resources::new(dettid)).await; // empty request
2460        let fd = self.record_or_replay(guest, call).await? as RawFd;
2461        // Register the epoll fd in the DetFd table like every other
2462        // fd-creating syscall (openat, eventfd2, pipe2, socket, ...). Without
2463        // this, later operations that consult the table via `with_detfd` /
2464        // `dup_fd` (F_GETFL, F_SETFD, F_DUPFD[_CLOEXEC], dup, ...) would fail
2465        // with EBADF even though the underlying kernel fd is valid. This broke,
2466        // for example, running rustup proxies (cargo/rustc) under hermit, whose
2467        // tokio runtime dups its epoll fd at startup.
2468        //
2469        // EPOLL_CLOEXEC shares the same bit value as O_CLOEXEC, so we can carry
2470        // the cloexec flag straight across.
2471        self.add_fd(
2472            guest,
2473            fd,
2474            OFlag::from_bits_truncate(call.flags().bits()),
2475            FdType::Epoll,
2476        )
2477        .await?;
2478        Ok(fd as i64)
2479    }
2480
2481    /// Apply an ADD, MOD, or DEL mutation to an epoll interest list.
2482    ///
2483    /// Determinism: strict execution serializes this mutation, so its result depends only on the
2484    /// operation, event payload, and deterministically reconstructed epoll/file-descriptor state.
2485    /// Record/replay records each answer and replays it; replay reapplies only the recorded
2486    /// successes, so its epoll sets hold what the recording's held
2487    /// (<https://github.com/rrnewton/hermit/issues/31>).
2488    pub async fn handle_epoll_ctl<G: Guest<Self>>(
2489        &self,
2490        guest: &mut G,
2491        call: syscalls::EpollCtl,
2492    ) -> Result<i64, Error> {
2493        let dettid = guest.thread_state().dettid;
2494        resource_request(guest, Resources::new(dettid)).await; // empty request
2495        Ok(self.record_or_replay(guest, call).await?)
2496    }
2497
2498    /// epoll_pwait syscall (MAYHANG)
2499    pub async fn handle_epoll_pwait<G: Guest<Self>>(
2500        &self,
2501        guest: &mut G,
2502        call: syscalls::EpollPwait,
2503    ) -> Result<i64, Error> {
2504        // This used to unconditionally inject the raw
2505        // call and wait for it to return. With an infinite timeout under
2506        // `--sequentialize-threads` that DEADLOCKS the whole guest: the calling
2507        // task holds the scheduler turn while blocked in the kernel, and the
2508        // only task that could ever satisfy the wait is sitting in the run queue
2509        // waiting for a turn that never comes. Observed as `cmake` configure
2510        // hanging forever at zero CPU with a grandchild frozen mid-`openat`;
2511        // hermit's own scheduler log ends at `COMMIT turn N, dettid <parent>`
2512        // injecting `epoll_pwait(..., -1, NULL, 8)` with `queue len 2`.
2513        //
2514        // WHO ACTUALLY REACHES THIS, measured rather than assumed. It is NOT
2515        // glibc's `epoll_wait(2)` on this architecture: glibc calls
2516        // `SYS_epoll_pwait` only where `__NR_epoll_wait` does not exist (arm64
2517        // and friends). x86_64 has it, and `strace` on glibc 2.34/x86_64 shows
2518        // a plain `epoll_wait` syscall, which `handle_epoll_wait` has always
2519        // handled correctly. The callers that land here are programs issuing
2520        // `epoll_pwait` DIRECTLY -- libuv does, which is how the original
2521        // `cmake` hang was found. With a NULL sigmask the two calls are
2522        // semantically identical, so route them together.
2523        //
2524        // A NON-NULL sigmask swaps the signal mask atomically for the duration
2525        // of the wait. Under record and replay a masked call that may wait is
2526        // a kernel wait outside the turn (`record_or_replay_masked_epoll_pwait`).
2527        // A sequentialized run on a backend whose kernel reports the guest's
2528        // signal state polls it under that mask
2529        // (`handle_internal_masked_epoll_pwait`). Otherwise, and for a zero
2530        // timeout, it keeps its turn: on another backend, or without
2531        // sequentialized threads, such a call can still block the scheduler
2532        // (https://github.com/rrnewton/hermit/issues/4041), and because it
2533        // never sleeps outside the runnable set the scheduler needs no record
2534        // of its temporary mask (`Resources::blocked_signal_mask`).
2535        if call.sigmask().is_some() && self.cfg.recordreplay_modes && call.timeout() != 0 {
2536            return self.record_or_replay_masked_epoll_pwait(guest, call).await;
2537        }
2538        if call.sigmask().is_some()
2539            && call.timeout() != 0
2540            && self.cfg.sequentialize_threads
2541            && self.cfg.backend.supports_blocked_wait_signal_interruption
2542        {
2543            return self.handle_internal_masked_epoll_pwait(guest, call).await;
2544        }
2545        if call.sigmask().is_some() {
2546            self.observe_under_temporary_mask(guest, call.sigmask(), call.sigsetsize())
2547                .await?;
2548            let dettid = guest.thread_state().dettid;
2549            resource_request(guest, Resources::new(dettid)).await; // empty request
2550            // The raw call runs in this turn. A zero timeout only probes, once a
2551            // virtual timerfd is readable exactly when its deadline has passed;
2552            // any other waits in the host (`crate::syscalls::timerfd`).
2553            if call.timeout() == 0 {
2554                crate::syscalls::timerfd::publish_expired(guest).await;
2555            } else {
2556                crate::syscalls::timerfd::refuse_host_wait(guest, "epoll_pwait with a signal mask");
2557            }
2558            return Ok(self.record_or_replay(guest, call).await?);
2559        }
2560        if self.cfg.recordreplay_modes && call.timeout() == 0 {
2561            // Cannot block, but still yield a scheduler turn so a polling thread
2562            // cannot monopolize the guest between preemptions.
2563            resource_request(guest, Resources::new(guest.thread_state().dettid)).await;
2564            Ok(self.record_or_replay(guest, call).await?)
2565        } else if !self.cfg.sequentialize_threads || self.cfg.recordreplay_modes {
2566            Ok(self
2567                .record_or_replay_blocking(guest, Syscall::EpollPwait(call))
2568                .await?)
2569        } else {
2570            self.handle_internal_epoll_pwait(guest, call).await
2571        }
2572    }
2573
2574    /// A masked `epoll_pwait` that may wait, under sequentialized threads on a
2575    /// backend whose kernel reports the guest's signal state. It used to run
2576    /// the real call in the thread's turn, so nothing else ran while it waited
2577    /// and it returned 0 at once or at its timeout
2578    /// (https://github.com/rrnewton/hermit/issues/4041). It now polls, as an
2579    /// unmasked `epoll_pwait` does, with probes that carry no mask, and decides
2580    /// interruption against the temporary mask read at entry
2581    /// (`retry_blocking_wait_under_mask`): a signal the mask blocks never ends
2582    /// the call and is delivered after it, and one the mask lets in ends it
2583    /// with EINTR although the guest's own mask may block it. A zero-timeout
2584    /// `epoll_pwait` never looks at pending signals, so no probe could be ended
2585    /// by one in any case. A signal that only the temporary mask lets in stays
2586    /// pending under the guest's own mask once it is put back, and is delivered
2587    /// under the temporary mask (`inject_signal_delivery`), as for a masked
2588    /// pselect6. Linux checks the mask's size, then reads it, before it looks
2589    /// at the epoll descriptor.
2590    async fn handle_internal_masked_epoll_pwait<G: Guest<Self>>(
2591        &self,
2592        guest: &mut G,
2593        call: syscalls::EpollPwait,
2594    ) -> Result<i64, Error> {
2595        if call.sigsetsize() != KERNEL_SIGSET_SIZE {
2596            return Err(Errno::EINVAL.into());
2597        }
2598        let mask_address = call.sigmask().ok_or(Errno::EFAULT)?;
2599        let mask = crate::syscalls::signal::restart_if_first_probe_not_run(
2600            read_kernel_sigset(guest, mask_address.cast()).await,
2601        )?;
2602        super::signal_shadow::note_wait_mask(guest, mask);
2603        // A pending real-time timer expiration that the mask lets the kernel
2604        // deliver or discard (https://github.com/rrnewton/hermit/issues/4089).
2605        observe_under_mask(guest, mask).await?;
2606        let mask = sanitize_ppoll_signal_mask(mask);
2607        let deadline = millis_duration_to_absolute_timeout(guest, call.timeout()).await;
2608        self.wait_on_masked_epoll(
2609            guest,
2610            call.with_sigmask(None),
2611            mask,
2612            deadline,
2613            "epoll_pwait",
2614        )
2615        .await
2616    }
2617
2618    /// The wait of a masked epoll_pwait or epoll_pwait2 under sequentialized
2619    /// threads, once the call's temporary `mask` (sanitized) has been read at
2620    /// entry: `probe`, an unmasked epoll_pwait, polls until an event, an
2621    /// error, a signal that `mask` lets in (EINTR), or `deadline`, which
2622    /// returns 0 (`handle_internal_masked_epoll_pwait`).
2623    async fn wait_on_masked_epoll<G: Guest<Self>>(
2624        &self,
2625        guest: &mut G,
2626        probe: syscalls::EpollPwait,
2627        mask: KernelSigset,
2628        deadline: Option<LogicalTime>,
2629        fyi: &'static str,
2630    ) -> Result<i64, Error> {
2631        let mut rsrc = Resources::new(guest.thread_state().dettid);
2632        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2633        rsrc.fyi(fyi);
2634        let (result, deliver) = retry_blocking_wait_under_mask(
2635            guest,
2636            probe,
2637            rsrc,
2638            // Both calls return 0 at their timeout.
2639            deadline.map(|deadline| (deadline, Ok(0))),
2640            Some(crate::syscalls::signal::kernel_installed_signal_mask(mask)),
2641        )
2642        .await;
2643        if deliver && matches!(result, Err(Error::Errno(Errno::EINTR))) {
2644            // The probes staged nothing, so they say nothing about room for
2645            // these 24 bytes. `stage_private_cells`, which tests a window by
2646            // reading it, finds none only on a stack whose pointer is less
2647            // than 24 bytes above unreadable memory and whose red zone is
2648            // unreadable too
2649            // (https://github.com/rrnewton/hermit/issues/4113). Then the signal
2650            // stays pending under the guest's own mask, and the call returns
2651            // EINTR without its handler run and logs this warning.
2652            match stage_private_cells(guest, PrivateCells::MaskAndZeroTimeout(mask), &[]).await? {
2653                Some(staged) => {
2654                    inject_signal_delivery(guest, staged.mask(), staged.after_mask()).await;
2655                    staged.release(guest);
2656                }
2657                None => tracing::warn!(
2658                    "[tid {}] no room to deliver an {fyi} signal under its temporary mask; its \
2659                     handler runs only once the guest unblocks it",
2660                    guest.tid()
2661                ),
2662            }
2663        }
2664        result
2665    }
2666
2667    /// A masked `epoll_pwait` that may wait, under record and replay. As for a
2668    /// masked pselect6 or ppoll there, the kernel owns the wait outside the
2669    /// scheduler turn, so the timer's signal can end it as on Linux; it kept
2670    /// its turn before, so nothing else ran and the call returned at its
2671    /// timeout (https://github.com/rrnewton/hermit/issues/4041). The call sleeps
2672    /// under a private copy of the mask read at entry, which a sibling cannot
2673    /// rewrite, and the scheduler records its sleeping mask as unknown
2674    /// (`Resources::blocked_signal_mask_unknown`). Replay serves the call from
2675    /// the recording, so for a recorded EINTR it delivers the signal under that
2676    /// mask (`end_replayed_pselect6_under_its_temporary_mask`).
2677    async fn record_or_replay_masked_epoll_pwait<G: Guest<Self>>(
2678        &self,
2679        guest: &mut G,
2680        call: syscalls::EpollPwait,
2681    ) -> Result<i64, Error> {
2682        if call.sigsetsize() != KERNEL_SIGSET_SIZE {
2683            return Err(Errno::EINVAL.into());
2684        }
2685        let mask_address = call.sigmask().ok_or(Errno::EFAULT)?;
2686        let mask = crate::syscalls::signal::restart_if_first_probe_not_run(
2687            read_kernel_sigset(guest, mask_address.cast()).await,
2688        )?;
2689        super::signal_shadow::note_wait_mask(guest, mask);
2690        // The copy may go in the red zone on a stack with no scratch below it,
2691        // clear of the events buffer the kernel writes (`stage_private_cells`;
2692        // re-review of https://github.com/rrnewton/hermit/pull/4087).
2693        let live: Vec<std::ops::Range<usize>> = call
2694            .events()
2695            .map(|events| {
2696                let start = events.as_raw();
2697                let len = usize::try_from(call.maxevents().max(0)).unwrap_or(0)
2698                    * std::mem::size_of::<libc::epoll_event>();
2699                start..start.saturating_add(len)
2700            })
2701            .into_iter()
2702            .collect();
2703        let Some(staged) = stage_private_cells(guest, PrivateCells::Mask(mask), &live).await?
2704        else {
2705            return self.refuse_unstageable_epoll_pwait_mask(guest, call).await;
2706        };
2707        let result = self
2708            .record_or_replay_blocking_with_unknown_mask(
2709                guest,
2710                Syscall::EpollPwait(call.with_sigmask(Addr::from_raw(staged.mask()))),
2711            )
2712            .await;
2713        staged.release(guest);
2714        if self.cfg.replaying && matches!(result, Err(Error::Errno(Errno::EINTR))) {
2715            end_replayed_pselect6_under_its_temporary_mask(guest, mask).await;
2716        }
2717        result
2718    }
2719
2720    /// Refuses a masked record/replay `epoll_pwait` whose private mask copy has
2721    /// nowhere to go: no stack scratch below the red zone, and every red-zone
2722    /// window overlaps the events buffer (`refuse_unstageable_pselect6_mask`
2723    /// for pselect6). A run that allows unsupported operations forwards the
2724    /// guest's own mask.
2725    async fn refuse_unstageable_epoll_pwait_mask<G: Guest<Self>>(
2726        &self,
2727        guest: &mut G,
2728        call: syscalls::EpollPwait,
2729    ) -> Result<i64, Error> {
2730        use std::io::Write as _;
2731        let message = "unsupported: epoll_pwait with a temporary signal mask, on a stack \
2732            with no room below its red zone whose red zone the call's events buffer fills: \
2733            Hermit has nowhere to put the private copy of the mask \
2734            (https://github.com/rrnewton/hermit/pull/4087)";
2735        tracing::error!("[tid {}] {message}", guest.tid());
2736        if self.cfg.panic_on_unsupported_syscalls {
2737            let _ = writeln!(crate::util::RetryingStderr, "{message}");
2738            return self
2739                .refuse_unserviceable_operation(guest, Sysno::epoll_pwait, Errno::EFAULT)
2740                .await;
2741        }
2742        self.record_or_replay_blocking_with_unknown_mask(guest, Syscall::EpollPwait(call))
2743            .await
2744    }
2745
2746    /// Handle a guest-internal `epoll_pwait` (NULL sigmask) that can be fully
2747    /// determinized. Mirrors `handle_internal_epoll_wait`.
2748    pub async fn handle_internal_epoll_pwait<G: Guest<Self>>(
2749        &self,
2750        guest: &mut G,
2751        call: syscalls::EpollPwait,
2752    ) -> Result<i64, Error> {
2753        let timeout_millis = call.timeout();
2754        if timeout_millis == 0 {
2755            // Cannot block, but must still yield a scheduler turn: a
2756            // zero-timeout polling loop that never requests a resource can
2757            // monopolize the guest between preemptions and starve the producer
2758            // it is polling for. `handle_poll` takes a turn for every
2759            // sequential mode, and the record/replay arm of `handle_epoll_pwait`
2760            // does the same; before this PR routed NULL-sigmask `epoll_pwait`
2761            // here, the old handler always made an empty request. Omitting it
2762            // only on the plain-strict path would be a scheduling regression,
2763            // not a refactor.
2764            if self.cfg.sequentialize_threads {
2765                let yield_to_peer = self.cfg.backend.loopback_pollers_yield_to_peers
2766                    && guest.thread_state().has_loopback_peer();
2767                resource_request(
2768                    guest,
2769                    zero_timeout_poll_request(guest.thread_state().dettid, yield_to_peer),
2770                )
2771                .await;
2772            }
2773            crate::syscalls::timerfd::publish_expired(guest).await;
2774            Ok(guest.inject(call).await?) // Already non-blocking.
2775        } else {
2776            let maybe_timeout_ns = millis_duration_to_absolute_timeout(guest, timeout_millis).await;
2777            let mut rsrc = Resources::new(guest.thread_state().dettid);
2778            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2779            rsrc.fyi("epoll_pwait");
2780            retry_nonblocking_syscall_with_timeout(guest, call, rsrc, maybe_timeout_ns).await
2781        }
2782    }
2783
2784    /// epoll_pwait2 syscall (MAYHANG).
2785    ///
2786    /// epoll_pwait2 is epoll_pwait with a `struct timespec *` timeout instead of
2787    /// an int-milliseconds timeout; recent glibc implements epoll_wait/
2788    /// epoll_pwait via epoll_pwait2 when the kernel supports it. The pinned
2789    /// Reverie revision has no typed variant, so it arrives as a raw
2790    /// `Syscall::Other` and is dispatched here by Sysno. Detcore treats it
2791    /// like epoll_pwait: under record and replay a call that may wait waits
2792    /// outside the turn; under sequentialized threads it polls
2793    /// (`handle_internal_epoll_pwait2`); otherwise, and for a zero timeout, a
2794    /// scheduler yield point is followed by the raw call.
2795    // AUTONOMOUS-BOT-IMPLEMENTED
2796    // TODO-HUMAN-REVIEW(#773)
2797    pub async fn handle_epoll_pwait2<G: Guest<Self>>(
2798        &self,
2799        guest: &mut G,
2800        call: Syscall,
2801    ) -> Result<i64, Error> {
2802        // epoll_pwait2(epfd, events, maxevents, timeout, sigmask, sigsetsize)
2803        let (_, args) = call.into_parts();
2804        self.observe_under_temporary_mask(
2805            guest,
2806            Addr::<libc::sigset_t>::from_raw(args.arg4),
2807            args.arg5,
2808        )
2809        .await?;
2810        // A NULL timeout waits forever; a zero timespec cannot wait and keeps
2811        // the turn.
2812        let zero_timeout = args.arg3 != 0
2813            && Addr::<Timespec>::from_raw(args.arg3)
2814                .and_then(|timeout| guest.memory().read_value(timeout).ok())
2815                .is_some_and(|timeout: Timespec| timeout.tv_sec == 0 && timeout.tv_nsec == 0);
2816        // Under record and replay, a call that may wait does so outside the
2817        // scheduler turn, as epoll_pwait's does: unmasked through the logged
2818        // background path, masked as a kernel wait under a private copy of its
2819        // mask (`record_or_replay_masked_epoll_pwait2`).
2820        if self.cfg.recordreplay_modes {
2821            if !zero_timeout {
2822                return if args.arg4 != 0 {
2823                    self.record_or_replay_masked_epoll_pwait2(guest, args).await
2824                } else {
2825                    self.record_or_replay_blocking(guest, call).await
2826                };
2827            }
2828        } else if self.cfg.sequentialize_threads
2829            && !zero_timeout
2830            && (args.arg4 == 0 || self.cfg.backend.supports_blocked_wait_signal_interruption)
2831        {
2832            // With threads sequentialized, a call that may wait polls, as
2833            // epoll_pwait does, rather than waiting in the kernel inside the
2834            // turn, where no other guest thread could run
2835            // (https://github.com/rrnewton/hermit/issues/4228). A masked call
2836            // on a backend whose kernel does not report the guest's signal
2837            // state keeps the turn, as a masked epoll_pwait does there.
2838            return self.handle_internal_epoll_pwait2(guest, args).await;
2839        }
2840        let dettid = guest.thread_state().dettid;
2841        resource_request(guest, Resources::new(dettid)).await; // empty request
2842        // The raw call runs in this turn. A zero timeout only probes, once a
2843        // virtual timerfd is readable exactly when its deadline has passed;
2844        // any other wait here is in the host (`crate::syscalls::timerfd`).
2845        if zero_timeout {
2846            crate::syscalls::timerfd::publish_expired(guest).await;
2847        } else {
2848            crate::syscalls::timerfd::refuse_host_wait(guest, "epoll_pwait2 with a signal mask");
2849        }
2850        Ok(self.record_or_replay(guest, call).await?)
2851    }
2852
2853    /// An epoll_pwait2 that may wait, under sequentialized threads: it polls
2854    /// with zero-timeout probes, as epoll_pwait does. A probe is an
2855    /// epoll_pwait with no mask, whose answer for a zero timeout is the same
2856    /// as epoll_pwait2's. Linux copies and checks the timespec before the
2857    /// mask (`record_or_replay_masked_epoll_pwait2`), then the mask's size
2858    /// and the mask, before it looks at the epoll descriptor. An unmasked
2859    /// call waits as an unmasked epoll_pwait does
2860    /// (`handle_internal_epoll_pwait`), a masked one as a masked epoll_pwait
2861    /// does (`wait_on_masked_epoll`). It used to make the real call in the
2862    /// thread's turn, so it returned 0 at its timeout, or never, when only
2863    /// another guest thread could make an event ready
2864    /// (https://github.com/rrnewton/hermit/issues/4228).
2865    async fn handle_internal_epoll_pwait2<G: Guest<Self>>(
2866        &self,
2867        guest: &mut G,
2868        args: SyscallArgs,
2869    ) -> Result<i64, Error> {
2870        let deadline = match Addr::<Timespec>::from_raw(args.arg3) {
2871            Some(timeout) => {
2872                let timeout: Timespec = guest.memory().read_value(timeout)?;
2873                let timeout = ppoll_timeout_duration(timeout)?;
2874                // As for ppoll: `LogicalTime + Duration` saturates, where a
2875                // nanosecond count cast to u64 would wrap a 2^64 ns timeout to
2876                // none at all (Claude review of
2877                // https://github.com/rrnewton/hermit/pull/4235).
2878                Some(thread_observe_time(guest).await + timeout)
2879            }
2880            None => None,
2881        };
2882        let probe = syscalls::EpollPwait::new()
2883            .with_epfd(args.arg0 as i32)
2884            .with_events(AddrMut::from_raw(args.arg1))
2885            .with_maxevents(args.arg2 as i32)
2886            .with_timeout(0)
2887            .with_sigmask(None)
2888            .with_sigsetsize(args.arg5);
2889        if args.arg4 == 0 {
2890            let mut rsrc = Resources::new(guest.thread_state().dettid);
2891            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
2892            rsrc.fyi("epoll_pwait2");
2893            return retry_nonblocking_syscall_with_timeout(guest, probe, rsrc, deadline).await;
2894        }
2895        if args.arg5 != KERNEL_SIGSET_SIZE {
2896            return Err(Errno::EINVAL.into());
2897        }
2898        let mask_address = Addr::<libc::sigset_t>::from_raw(args.arg4).ok_or(Errno::EFAULT)?;
2899        let mask = read_kernel_sigset(guest, mask_address).await?;
2900        super::signal_shadow::note_wait_mask(guest, mask);
2901        // A pending real-time timer expiration that the mask lets the kernel
2902        // deliver or discard (https://github.com/rrnewton/hermit/issues/4089).
2903        observe_under_mask(guest, mask).await?;
2904        let mask = sanitize_ppoll_signal_mask(mask);
2905        self.wait_on_masked_epoll(guest, probe, mask, deadline, "epoll_pwait2")
2906            .await
2907    }
2908
2909    /// Before a call that sleeps or probes under the temporary mask at `mask`
2910    /// (`sigsetsize` bytes), refuse the run by name if the mask lets the kernel
2911    /// take a pending real-time timer expiration that every thread blocked when
2912    /// it expired, and discard the ones it lets the kernel discard
2913    /// (https://github.com/rrnewton/hermit/issues/4089). A mask the kernel would
2914    /// reject fails the call itself, which then observes nothing.
2915    async fn observe_under_temporary_mask<G: Guest<Self>>(
2916        &self,
2917        guest: &mut G,
2918        mask: Option<Addr<'_, libc::sigset_t>>,
2919        sigsetsize: usize,
2920    ) -> Result<(), Error> {
2921        let Some(mask) = mask else {
2922            return Ok(());
2923        };
2924        if sigsetsize != KERNEL_SIGSET_SIZE
2925            || !crate::scheduler::real_time_expiration_kept_pending()
2926        {
2927            return Ok(());
2928        }
2929        let Ok(mask) = read_kernel_sigset(guest, mask).await else {
2930            return Ok(());
2931        };
2932        observe_under_mask(guest, mask).await
2933    }
2934
2935    /// `record_or_replay_masked_epoll_pwait` for `epoll_pwait2`, whose mask
2936    /// pointer and size are its fifth and sixth arguments.
2937    async fn record_or_replay_masked_epoll_pwait2<G: Guest<Self>>(
2938        &self,
2939        guest: &mut G,
2940        args: SyscallArgs,
2941    ) -> Result<i64, Error> {
2942        // Linux copies and checks the timespec before the mask, so an
2943        // unreadable timeout is EFAULT and an invalid one EINVAL whatever the
2944        // mask and its size (Claude review of
2945        // https://github.com/rrnewton/hermit/pull/4128).
2946        if let Some(timeout) = Addr::<Timespec>::from_raw(args.arg3) {
2947            let timeout: Timespec = guest.memory().read_value(timeout)?;
2948            ppoll_timeout_duration(timeout)?;
2949        }
2950        if args.arg5 != KERNEL_SIGSET_SIZE {
2951            return Err(Errno::EINVAL.into());
2952        }
2953        let mask_address = Addr::<libc::sigset_t>::from_raw(args.arg4).ok_or(Errno::EFAULT)?;
2954        let mask = read_kernel_sigset(guest, mask_address).await?;
2955        super::signal_shadow::note_wait_mask(guest, mask);
2956        // The copy may go in the red zone on a stack with no scratch below it,
2957        // clear of the events buffer the kernel writes and of the timeout it
2958        // reads, as for epoll_pwait (`stage_private_cells`).
2959        let events_len = usize::try_from((args.arg2 as i32).max(0)).unwrap_or(0)
2960            * std::mem::size_of::<libc::epoll_event>();
2961        let live: Vec<std::ops::Range<usize>> = [
2962            (args.arg1, events_len),
2963            (args.arg3, std::mem::size_of::<Timespec>()),
2964        ]
2965        .into_iter()
2966        .filter(|&(start, _)| start != 0)
2967        .map(|(start, len)| start..start.saturating_add(len))
2968        .collect();
2969        let Some(staged) = stage_private_cells(guest, PrivateCells::Mask(mask), &live).await?
2970        else {
2971            return self.refuse_unstageable_epoll_pwait2_mask(guest, args).await;
2972        };
2973        let mut private = args;
2974        private.arg4 = staged.mask();
2975        let result = self
2976            .record_or_replay_blocking_with_unknown_mask(
2977                guest,
2978                Syscall::Other(Sysno::epoll_pwait2, private),
2979            )
2980            .await;
2981        staged.release(guest);
2982        if self.cfg.replaying && matches!(result, Err(Error::Errno(Errno::EINTR))) {
2983            end_replayed_pselect6_under_its_temporary_mask(guest, mask).await;
2984        }
2985        result
2986    }
2987
2988    /// `refuse_unstageable_epoll_pwait_mask` for `epoll_pwait2`, whose red
2989    /// zone the events buffer and the timeout fill.
2990    async fn refuse_unstageable_epoll_pwait2_mask<G: Guest<Self>>(
2991        &self,
2992        guest: &mut G,
2993        args: SyscallArgs,
2994    ) -> Result<i64, Error> {
2995        use std::io::Write as _;
2996        let message = "unsupported: epoll_pwait2 with a temporary signal mask, on a stack \
2997            with no room below its red zone whose red zone the call's events buffer and \
2998            timeout fill: Hermit has nowhere to put the private copy of the mask \
2999            (https://github.com/rrnewton/hermit/issues/4088)";
3000        tracing::error!("[tid {}] {message}", guest.tid());
3001        if self.cfg.panic_on_unsupported_syscalls {
3002            let _ = writeln!(crate::util::RetryingStderr, "{message}");
3003            return self
3004                .refuse_unserviceable_operation(guest, Sysno::epoll_pwait2, Errno::EFAULT)
3005                .await;
3006        }
3007        self.record_or_replay_blocking_with_unknown_mask(
3008            guest,
3009            Syscall::Other(Sysno::epoll_pwait2, args),
3010        )
3011        .await
3012    }
3013
3014    /// epoll_wait syscall (MAYHANG)
3015    pub async fn handle_epoll_wait<G: Guest<Self>>(
3016        &self,
3017        guest: &mut G,
3018        call: syscalls::EpollWait,
3019    ) -> Result<i64, Error> {
3020        if self.cfg.recordreplay_modes && call.timeout() == 0 {
3021            // This cannot block, but still yield a scheduler turn so a polling thread cannot
3022            // monopolize the guest between preemptions.
3023            resource_request(guest, Resources::new(guest.thread_state().dettid)).await;
3024            Ok(self.record_or_replay(guest, call).await?)
3025        } else if !self.cfg.sequentialize_threads || self.cfg.recordreplay_modes {
3026            Ok(self
3027                .record_or_replay_blocking(guest, Syscall::EpollWait(call))
3028                .await?)
3029        } else {
3030            self.handle_internal_epoll_wait(guest, call).await
3031        }
3032    }
3033
3034    /// Handle a guest-internal `epoll_wait` call that can be fully determinized.
3035    pub async fn handle_internal_epoll_wait<G: Guest<Self>>(
3036        &self,
3037        guest: &mut G,
3038        call: syscalls::EpollWait,
3039    ) -> Result<i64, Error> {
3040        let timeout_millis = call.timeout();
3041        if timeout_millis == 0 {
3042            crate::syscalls::timerfd::publish_expired(guest).await;
3043            Ok(guest.inject(call).await?) // Already non-blocking.
3044        } else {
3045            let maybe_timeout_ns = millis_duration_to_absolute_timeout(guest, timeout_millis).await;
3046            let mut rsrc = Resources::new(guest.thread_state().dettid);
3047            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
3048            rsrc.fyi("epoll_wait");
3049            retry_nonblocking_syscall_with_timeout(guest, call, rsrc, maybe_timeout_ns).await
3050        }
3051    }
3052
3053    /// Connect system call (MAYHANG)
3054    /// Note that connect waits until a TCP handshake but does not wait for accept() on the other end.
3055    /// Nevertheless, it can block for a long time while waiting for connection, unless the socket
3056    /// is already nonblocking.
3057    pub async fn handle_connect<G: Guest<Self>>(
3058        &self,
3059        guest: &mut G,
3060        call: syscalls::Connect,
3061    ) -> Result<i64, Error> {
3062        let fd = call.fd();
3063        let uservaddr = call.uservaddr();
3064        let addrlen = call.addrlen();
3065
3066        if guest.config().sched_heuristic == SchedHeuristic::ConnectBind {
3067            trace!("Scheduling heuristic: reprioritizing connect");
3068            let resource = ResourceID::PriorityChangePoint(
3069                FIRST_PRIORITY,
3070                guest.thread_state().thread_logical_time.as_nanos(),
3071                guest.thread_state().committed_clock_value,
3072                Vec::new(),
3073            );
3074            let req = guest.thread_state().mk_request(resource, Permission::W);
3075            resource_request(guest, req).await;
3076        }
3077
3078        let result = self.execute_nonblockable_fd_syscall(guest, call).await;
3079        if self.cfg.backend.loopback_pollers_yield_to_peers
3080            && connect_result_allows_peer_classification(&result)
3081        {
3082            // This metadata is a loopback-poll scheduling hint, not part of connect's semantics.
3083            // Let the kernel establish the authoritative result first, then classify the peer
3084            // best-effort so an invalid guest pointer or an untracked fd can never replace the
3085            // kernel's errno.
3086            let loopback_peer = (|| -> Result<Option<bool>, Error> {
3087                let Some(address) = uservaddr else {
3088                    return Ok(None);
3089                };
3090                let addrlen = usize::try_from(addrlen).unwrap_or(0);
3091                if addrlen < std::mem::size_of::<u16>() {
3092                    return Ok(None);
3093                }
3094                let family: u16 = guest.memory().read_value(address.cast())?;
3095                if family == libc::AF_INET as u16 {
3096                    if addrlen < std::mem::size_of::<libc::sockaddr_in>() {
3097                        return Ok(None);
3098                    }
3099                    let address: libc::sockaddr_in = guest.memory().read_value(address.cast())?;
3100                    Ok(Some(
3101                        Ipv4Addr::from(address.sin_addr.s_addr.to_ne_bytes()).is_loopback(),
3102                    ))
3103                } else if family == libc::AF_INET6 as u16 {
3104                    if addrlen < std::mem::size_of::<libc::sockaddr_in6>() {
3105                        return Ok(None);
3106                    }
3107                    let address: libc::sockaddr_in6 = guest.memory().read_value(address.cast())?;
3108                    Ok(Some(
3109                        Ipv6Addr::from(address.sin6_addr.s6_addr).is_loopback(),
3110                    ))
3111                } else {
3112                    // This includes a successful AF_UNSPEC disconnect and successful connects
3113                    // to non-IP families, neither of which has a loopback IP peer.
3114                    Ok(Some(false))
3115                }
3116            })()
3117            .ok()
3118            .flatten();
3119            if let Some(loopback_peer) = loopback_peer {
3120                let _ = guest
3121                    .thread_state()
3122                    .with_detfd(fd, |detfd| detfd.set_loopback_peer(loopback_peer));
3123            }
3124        }
3125
3126        result
3127    }
3128
3129    /// Handles sendto, sendmsg, and sendmmsg syscalls (MAYHANG).
3130    pub async fn handle_sendrecv<
3131        G: Guest<Self>,
3132        C: SyscallInfo + NonblockableSyscall + Into<Syscall>,
3133    >(
3134        &self,
3135        guest: &mut G,
3136        call: C,
3137    ) -> Result<i64, Error> {
3138        self.execute_nonblockable_fd_syscall(guest, call).await
3139    }
3140
3141    /// Sends one message and invalidates process-wide flock knowledge after success.
3142    ///
3143    /// The guest can mutate shared message and control memory while this helper
3144    /// deschedules. Parsing before the syscall would not prove which descriptors the
3145    /// kernel later transferred, so a successful unbound send conservatively makes
3146    /// every cached open-file-description lock mode unknown.
3147    pub async fn handle_sendmsg<G: Guest<Self>>(
3148        &self,
3149        guest: &mut G,
3150        call: syscalls::Sendmsg,
3151    ) -> Result<i64, Error> {
3152        if self.accept_in_turn_enabled() {
3153            let headers: Vec<usize> = call
3154                .msg()
3155                .map(|header| header.as_raw())
3156                .into_iter()
3157                .collect();
3158            self.mark_exported_listeners(guest, &headers);
3159        }
3160        let headers: Vec<usize> = call
3161            .msg()
3162            .map(|header| header.as_raw())
3163            .into_iter()
3164            .collect();
3165        self.refuse_sending_virtual_timerfds(guest, &headers);
3166        let result = self.execute_nonblockable_fd_syscall(guest, call).await?;
3167        guest.thread_state().forget_flock_modes();
3168        Ok(result)
3169    }
3170
3171    /// Mark every accept-in-turn listener (`DetFd::is_accept_in_turn_eligible`)
3172    /// these messages name in `SCM_RIGHTS` as exported, before they are sent
3173    /// and whatever the send returns: Linux may have queued the descriptor
3174    /// even when the call reports an error, and both phases must decide alike.
3175    /// `headers` are the guest addresses of the `msghdr`s: one for `sendmsg`,
3176    /// one per entry Linux could send for `sendmmsg`.
3177    ///
3178    /// An exported listener may be held by a process outside Detcore's view,
3179    /// so its accepts never take the temporary `O_NONBLOCK` again and keep the
3180    /// backgrounded path. An accept already waiting on it refuses at its next
3181    /// attempt (`ACCEPT_EXPORT_REFUSAL`). Both phases read the same guest
3182    /// memory here. When a header or control buffer cannot be read in full
3183    /// (Linux reads a write-only page, which Detcore cannot, and takes up to
3184    /// `optmem_max` bytes of control data, more than `MAX_CONTROL_BYTES`),
3185    /// every eligible listener in the table counts as exported. A thread that
3186    /// rewrites the control buffer while this one is descheduled can send a
3187    /// listener this did not see.
3188    // TODO-HUMAN-REVIEW(PR-3908)
3189    fn mark_exported_listeners<G: Guest<Self>>(&self, guest: &mut G, headers: &[usize]) {
3190        let (sent, unread) = sent_descriptors(guest, headers);
3191        if unread {
3192            // Linux can read memory Detcore cannot (a write-only page) and
3193            // accepts more control data than Detcore reads, so a message it
3194            // could not read may carry any listener.
3195            guest
3196                .thread_state()
3197                .mark_accept_in_turn_listeners_exported();
3198            return;
3199        }
3200        for fd in sent {
3201            let _ = guest.thread_state().with_detfd(fd, |detfd| {
3202                if detfd.is_accept_in_turn_eligible() {
3203                    detfd.set_exported();
3204                }
3205            });
3206        }
3207    }
3208
3209    /// Refuse the run, by name, before messages at `headers` pass a timerfd
3210    /// over `SCM_RIGHTS` while timerfds run on Detcore's virtual clock, armed
3211    /// or not (one armed after it is sent would be modelled only by the
3212    /// sender), or an epoll descriptor while this process holds an armed one
3213    /// (its set may include it). The receiving process keeps no model of the
3214    /// timer, so its probes would never make it readable and it would wait
3215    /// where Linux wakes (`crate::syscalls::timerfd`). A message whose control
3216    /// data Detcore cannot read refuses too while this process holds an armed
3217    /// timerfd.
3218    fn refuse_sending_virtual_timerfds<G: Guest<Self>>(&self, guest: &mut G, headers: &[usize]) {
3219        if !crate::syscalls::timerfd::enabled(guest) {
3220            return;
3221        }
3222        let holds_armed = crate::syscalls::timerfd::has_virtual_timerfds(guest);
3223        let (sent, unread) = sent_descriptors(guest, headers);
3224        if unread && holds_armed {
3225            crate::syscalls::timerfd::refuse(format_args!(
3226                "a message whose SCM_RIGHTS control data Detcore cannot read may pass a timerfd to another process"
3227            ));
3228        }
3229        for fd in sent {
3230            match guest.thread_state().with_detfd(fd, |detfd| detfd.ty()) {
3231                Ok(FdType::Timerfd) => crate::syscalls::timerfd::refuse(format_args!(
3232                    "a message passes timerfd {fd} over SCM_RIGHTS, and its receiver keeps no model of the timer"
3233                )),
3234                Ok(FdType::Epoll) if holds_armed => crate::syscalls::timerfd::refuse(format_args!(
3235                    "a message passes epoll descriptor {fd} over SCM_RIGHTS while this process holds a timerfd its set may include"
3236                )),
3237                _ => {}
3238            }
3239        }
3240    }
3241}
3242
3243/// The descriptors the messages at `headers` name in `SCM_RIGHTS`, and
3244/// whether a header or control buffer could not be read in full, in which case
3245/// the list may be incomplete (`mark_exported_listeners`).
3246fn sent_descriptors<T, G>(guest: &G, headers: &[usize]) -> (Vec<RawFd>, bool)
3247where
3248    T: RecordOrReplay,
3249    G: Guest<Detcore<T>>,
3250{
3251    let mut sent: Vec<RawFd> = Vec::new();
3252    let mut unread = false;
3253    for header in headers {
3254        // A null header or control buffer fails the call with EFAULT
3255        // before Linux reads any descriptor.
3256        let Some(header) = Addr::<libc::msghdr>::from_raw(*header) else {
3257            continue;
3258        };
3259        let Ok(header) = guest.memory().read_value::<_, libc::msghdr>(header) else {
3260            unread = true;
3261            continue;
3262        };
3263        let Some(control_address) = Addr::<u8>::from_raw(header.msg_control as usize) else {
3264            continue;
3265        };
3266        if header.msg_controllen > MAX_CONTROL_BYTES {
3267            unread = true;
3268            continue;
3269        }
3270        let mut control = vec![0; header.msg_controllen];
3271        if guest
3272            .memory()
3273            .read_exact(control_address, &mut control)
3274            .is_err()
3275        {
3276            unread = true;
3277            continue;
3278        }
3279        sent.extend(received_descriptors(&control));
3280    }
3281    (sent, unread)
3282}
3283
3284impl<T: RecordOrReplay> Detcore<T> {
3285    /// Sends a message batch and invalidates process-wide flock knowledge when the
3286    /// kernel reports at least one message sent. This intentionally includes
3287    /// descriptors named only by an unsent tail message: the mutable guest array is
3288    /// not stable across a possible deschedule, so narrower attribution is unsafe.
3289    pub async fn handle_sendmmsg<G: Guest<Self>>(
3290        &self,
3291        guest: &mut G,
3292        call: syscalls::Sendmmsg,
3293    ) -> Result<i64, Error> {
3294        if self.cfg.recordreplay_modes && is_accepted_connection(guest, call.sockfd()) {
3295            return self.refuse_log_served_mmsg(guest, Sysno::sendmmsg).await;
3296        }
3297        if self.accept_in_turn_enabled() {
3298            // Every entry Linux could send, sent or not: see `mark_exported_listeners`.
3299            // Reverie types the vector as `msghdr`s, but its entries are
3300            // `mmsghdr`s, each a `msghdr` followed by `msg_len`, so step by
3301            // the larger size.
3302            let headers: Vec<usize> = call.msgvec().map_or_else(Vec::new, |vector| {
3303                (0..call.vlen().min(libc::UIO_MAXIOV as u32) as usize)
3304                    .map(|index| vector.as_raw() + index * std::mem::size_of::<libc::mmsghdr>())
3305                    .collect()
3306            });
3307            self.mark_exported_listeners(guest, &headers);
3308        }
3309        // As for `sendmsg`: every entry Linux could send.
3310        let headers: Vec<usize> = call.msgvec().map_or_else(Vec::new, |vector| {
3311            (0..call.vlen().min(libc::UIO_MAXIOV as u32) as usize)
3312                .map(|index| vector.as_raw() + index * std::mem::size_of::<libc::mmsghdr>())
3313                .collect()
3314        });
3315        self.refuse_sending_virtual_timerfds(guest, &headers);
3316        let result = self.execute_nonblockable_fd_syscall(guest, call).await?;
3317        if result > 0 {
3318            guest.thread_state().forget_flock_modes();
3319        }
3320        Ok(result)
3321    }
3322
3323    /// Record and replay keep an accepted connection only in the log, and
3324    /// replay stands in an eventfd for it. Neither recorder nor replayer
3325    /// records the batched `sendmmsg` and `recvmmsg`, so replay would run them
3326    /// live against that eventfd and return something other than what the
3327    /// recording saw. Refuse them in both modes instead. On other sockets
3328    /// they still run live
3329    /// (https://github.com/rrnewton/hermit/issues/3883).
3330    // TODO-HUMAN-REVIEW(PR-3871): Refuse unrecorded batched I/O on accepted connections.
3331    async fn refuse_log_served_mmsg<G: Guest<Self>>(
3332        &self,
3333        guest: &mut G,
3334        sysno: Sysno,
3335    ) -> Result<i64, Error> {
3336        self.refuse_unserviceable_operation(guest, sysno, Errno::EOPNOTSUPP)
3337            .await
3338    }
3339
3340    // TODO-HUMAN-REVIEW(PR-912): Review receive-time capture across socket aliases.
3341    async fn observe_socket_receive<G: Guest<Self>>(
3342        &self,
3343        guest: &mut G,
3344        fd: i32,
3345    ) -> Result<LogicalTime, Error> {
3346        let timestamp = thread_observe_time(guest).await;
3347        guest.thread_state().with_detfd(fd, |detfd| {
3348            detfd.set_socket_receive_timestamp(timestamp);
3349        })?;
3350        Ok(timestamp)
3351    }
3352
3353    // AUTONOMOUS-BOT-IMPLEMENTED
3354    // TODO-HUMAN-REVIEW(PR-901)
3355    /// Receive one message and replace host socket timestamps with logical time.
3356    pub async fn handle_recvmsg<G: Guest<Self>>(
3357        &self,
3358        guest: &mut G,
3359        call: syscalls::Recvmsg,
3360    ) -> Result<i64, Error> {
3361        // NETLINK_SOCK_DIAG replies carry host-assigned socket identities in
3362        // their msg_iov payload (not msg_control). Canonicalize the supported
3363        // fields before the binary reply reaches the guest.
3364        // The predicate is shared with the read/readv/recvfrom/recvmmsg paths so
3365        // the five receive syscalls cannot drift apart again.
3366        if self.sock_diag_reply_fd(guest, call.sockfd()) {
3367            return self.handle_sock_diag_recvmsg(guest, call).await;
3368        }
3369
3370        if !self.cfg.virtualize_time {
3371            return self.execute_nonblockable_fd_syscall(guest, call).await;
3372        }
3373
3374        let Some(message_address) = call.msg() else {
3375            return self
3376                .handle_socket_receive(guest, call, call.sockfd(), true)
3377                .await;
3378        };
3379        // Snapshot every input field before the receive. Linux permits the
3380        // control buffer to overlap this header, so rereading it afterward can
3381        // turn a successful consuming receive into an artificial EFAULT.
3382        let message: libc::msghdr = guest.memory().read_value(message_address)?;
3383        if message.msg_control.is_null() || message.msg_controllen == 0 {
3384            return self
3385                .handle_socket_receive(guest, call, call.sockfd(), true)
3386                .await;
3387        }
3388        let control_len = message.msg_controllen.min(MAX_CONTROL_BYTES);
3389        let control_address: AddrMut<'_, u8> =
3390            AddrMut::from_raw(message.msg_control as usize).ok_or(Errno::EFAULT)?;
3391        let mut control = vec![0; control_len];
3392        // Validate the output region before consuming a datagram.
3393        guest.memory().read_exact(control_address, &mut control)?;
3394
3395        let result = self.execute_nonblockable_fd_syscall(guest, call).await?;
3396        let now = self.observe_socket_receive(guest, call.sockfd()).await?;
3397        let mut control = vec![0; control_len];
3398        guest.memory().read_exact(control_address, &mut control)?;
3399        // A descriptor received over `SCM_RIGHTS` that Detcore models (an
3400        // in-guest backend discovers it as it is used) joins this process's
3401        // table in `procfs::locks::LockLedger` with whatever OFD or flock
3402        // locks its description holds. One Detcore keeps no model of (ptrace)
3403        // is left out, so its locks are hidden once no modelled table names
3404        // the description (a named residual).
3405        for fd in received_descriptors(&control) {
3406            self.refresh_description_locks(guest, fd, super::files::LockCall::Recvmsg)
3407                .await?;
3408        }
3409        if socket_timestamp_messages(&control).is_empty() {
3410            return Ok(result);
3411        }
3412
3413        canonicalize_socket_timestamps(&mut control, now);
3414        guest.memory().write_exact(control_address, &control)?;
3415        Ok(result)
3416    }
3417
3418    // AUTONOMOUS-BOT-IMPLEMENTED
3419    // TODO-HUMAN-REVIEW(PR-1064)
3420    /// Whether replies received on `fd` must have their supported socket
3421    /// identities canonicalized.
3422    ///
3423    /// This is the single predicate every receive path consults. It exists as
3424    /// one function because the flag used to be tested inline in `recvmsg`
3425    /// alone, and four other receive syscalls reached the same dump without it
3426    /// (see [`Self::sanitize_sock_diag_segments`]).
3427    pub(crate) fn sock_diag_reply_fd<G: Guest<Self>>(&self, guest: &mut G, fd: RawFd) -> bool {
3428        self.cfg.virtualize_metadata
3429            && guest
3430                .thread_state()
3431                .with_detfd(fd, |detfd| detfd.is_sock_diag() || detfd.is_netlink_route())
3432                .unwrap_or(false)
3433    }
3434
3435    /// Whether this descriptor is specifically a `NETLINK_ROUTE` socket, which
3436    /// needs the link-counter sanitizer rather than the sock-diag one.
3437    fn netlink_route_reply_fd<G: Guest<Self>>(&self, guest: &mut G, fd: RawFd) -> bool {
3438        guest
3439            .thread_state()
3440            .with_detfd(fd, |detfd| detfd.is_netlink_route())
3441            .unwrap_or(false)
3442    }
3443
3444    /// Read an `iovec` array out of guest memory as plain `(address, capacity)`
3445    /// scalars, so no non-`Send` raw pointer is held across an await.
3446    fn read_iov_segments<G: Guest<Self>>(
3447        guest: &mut G,
3448        iov: usize,
3449        iovlen: usize,
3450    ) -> Result<Vec<(usize, usize)>, Error> {
3451        if iov == 0 || iovlen == 0 {
3452            return Ok(Vec::new());
3453        }
3454        let count = iovlen.min(libc::UIO_MAXIOV as usize);
3455        let address: AddrMut<'_, libc::iovec> = AddrMut::from_raw(iov).ok_or(Errno::EFAULT)?;
3456        // SAFETY: `iovec` is a plain C record; an all-zero value is a valid
3457        // staging value immediately overwritten by `read_values`.
3458        let mut iovecs: Vec<libc::iovec> =
3459            (0..count).map(|_| unsafe { std::mem::zeroed() }).collect();
3460        guest.memory().read_values(address.into(), &mut iovecs)?;
3461        Ok(iovecs
3462            .iter()
3463            .map(|iov| (iov.iov_base as usize, iov.iov_len))
3464            .collect())
3465    }
3466
3467    /// Canonicalize host-assigned identities in a `NETLINK_SOCK_DIAG` reply that
3468    /// the kernel has already written into guest memory.
3469    ///
3470    /// `segments` describes the destination buffers as `(address, capacity)` in
3471    /// the order the kernel filled them; `received` is the syscall's return
3472    /// value. The reply is gathered contiguously (it may be scattered across
3473    /// several buffers), sanitized via `crate::sock_diag` (fail-open,
3474    /// zero-only, never resizes), and written back preserving the original
3475    /// boundaries. Bounded by both each buffer's capacity and `received`, which
3476    /// under `MSG_TRUNC` can exceed the total capacity.
3477    ///
3478    /// Synchronous on purpose: every caller has already completed its receive,
3479    /// so nothing here awaits and no guest address outlives the borrow.
3480    fn sanitize_sock_diag_segments<G: Guest<Self>>(
3481        &self,
3482        guest: &mut G,
3483        fd: RawFd,
3484        segments: &[(usize, usize)],
3485        received: usize,
3486    ) -> Result<(), Error> {
3487        if received == 0 || segments.is_empty() {
3488            return Ok(());
3489        }
3490        let mut filled: Vec<(AddrMut<'_, u8>, usize)> = Vec::new();
3491        let mut buffer: Vec<u8> = Vec::with_capacity(received);
3492        let mut remaining = received;
3493        for &(base, capacity) in segments {
3494            if remaining == 0 {
3495                break;
3496            }
3497            if base == 0 || capacity == 0 {
3498                continue;
3499            }
3500            let take = capacity.min(remaining);
3501            let address: AddrMut<'_, u8> = AddrMut::from_raw(base).ok_or(Errno::EFAULT)?;
3502            let mut segment = vec![0u8; take];
3503            guest.memory().read_exact(address, &mut segment)?;
3504            buffer.extend_from_slice(&segment);
3505            filled.push((address, take));
3506            remaining -= take;
3507        }
3508
3509        // NETLINK_ROUTE and NETLINK_SOCK_DIAG replies need different
3510        // sanitizers: one zeroes live interface counters, the other determinizes
3511        // supported socket identities. The descriptor decides which, so a guest
3512        // holding both kinds of socket gets each handled correctly.
3513        let modified = if self.netlink_route_reply_fd(guest, fd) {
3514            crate::netlink_route::sanitize_route_link_stats(&mut buffer)
3515        } else {
3516            crate::sock_diag::sanitize_sock_diag_identities(&mut buffer)
3517        };
3518        if !modified {
3519            return Ok(());
3520        }
3521
3522        let mut offset = 0;
3523        for (address, len) in filled {
3524            guest
3525                .memory()
3526                .write_exact(address, &buffer[offset..offset + len])?;
3527            offset += len;
3528        }
3529        Ok(())
3530    }
3531
3532    /// `recvfrom` on a socket-diag descriptor: one destination buffer.
3533    ///
3534    /// `recv(2)` has no syscall of its own on x86_64 — glibc lowers it to
3535    /// `recvfrom` with a null address — so this covers `recv` as well, which is
3536    /// what Python's `socket.recv()` reaches.
3537    pub async fn handle_sock_diag_recvfrom<G: Guest<Self>>(
3538        &self,
3539        guest: &mut G,
3540        call: syscalls::Recvfrom,
3541    ) -> Result<i64, Error> {
3542        let fd = call.fd();
3543        let base = call.buf().map(|address| address.as_raw()).unwrap_or(0);
3544        let len = call.len();
3545        let result = self.handle_socket_receive(guest, call, fd, true).await?;
3546        let received = usize::try_from(result).unwrap_or(0);
3547        self.sanitize_sock_diag_segments(guest, fd, &[(base, len)], received)?;
3548        Ok(result)
3549    }
3550
3551    /// `read` on a socket-diag descriptor: one destination buffer.
3552    pub async fn handle_sock_diag_read<G: Guest<Self>>(
3553        &self,
3554        guest: &mut G,
3555        call: syscalls::Read,
3556    ) -> Result<i64, Error> {
3557        let fd = call.fd();
3558        let base = call.buf().map(|address| address.as_raw()).unwrap_or(0);
3559        let len = call.len();
3560        let result = self.handle_read(guest, call).await?;
3561        let received = usize::try_from(result).unwrap_or(0);
3562        self.sanitize_sock_diag_segments(guest, fd, &[(base, len)], received)?;
3563        Ok(result)
3564    }
3565
3566    /// Receive a `NETLINK_SOCK_DIAG` dump and zero the host-assigned socket
3567    /// inode numbers in the reply so `ss`-style enumeration is deterministic.
3568    ///
3569    /// The dump lands in `msg_iov` (netlink diag sockets carry no ancillary
3570    /// data), possibly scattered across several iovecs.
3571    async fn handle_sock_diag_recvmsg<G: Guest<Self>>(
3572        &self,
3573        guest: &mut G,
3574        call: syscalls::Recvmsg,
3575    ) -> Result<i64, Error> {
3576        let fd = call.sockfd();
3577        let Some(message_address) = call.msg() else {
3578            return self.handle_socket_receive(guest, call, fd, true).await;
3579        };
3580        // Snapshot the header's iovec pointer/count before the receive (they are
3581        // stable across it; the kernel fills the pointed-to buffers, not the
3582        // array). Scoped so the `msghdr`'s raw pointers are dropped before the
3583        // await below: holding one would make this future non-`Send`.
3584        let segments = {
3585            let message: libc::msghdr = guest.memory().read_value(message_address)?;
3586            Self::read_iov_segments(guest, message.msg_iov as usize, message.msg_iovlen)?
3587        };
3588
3589        let result = self.handle_socket_receive(guest, call, fd, true).await?;
3590        let received = usize::try_from(result).unwrap_or(0);
3591        self.sanitize_sock_diag_segments(guest, fd, &segments, received)?;
3592        Ok(result)
3593    }
3594
3595    /// `readv` on a socket-diag descriptor: an `iovec` array, no message header.
3596    pub async fn handle_sock_diag_readv<G: Guest<Self>>(
3597        &self,
3598        guest: &mut G,
3599        call: syscalls::Readv,
3600    ) -> Result<i64, Error> {
3601        let fd = call.fd();
3602        let iov = call.iov().map(|address| address.as_raw()).unwrap_or(0);
3603        let segments = Self::read_iov_segments(guest, iov, call.len())?;
3604        let result = self.handle_readv(guest, call).await?;
3605        let received = usize::try_from(result).unwrap_or(0);
3606        self.sanitize_sock_diag_segments(guest, fd, &segments, received)?;
3607        Ok(result)
3608    }
3609
3610    /// `recvmmsg` on a socket-diag descriptor.
3611    ///
3612    /// Each delivered `mmsghdr` is a separate datagram with its own byte count
3613    /// in `msg_len`, so each is gathered and sanitized independently; treating
3614    /// the batch as one buffer would let one message's length run into the
3615    /// next message's memory.
3616    pub async fn handle_sock_diag_recvmmsg<G: Guest<Self>>(
3617        &self,
3618        guest: &mut G,
3619        call: syscalls::Recvmmsg,
3620    ) -> Result<i64, Error> {
3621        let fd = call.fd();
3622        let Some(messages_address) = call.mmsg() else {
3623            return self.handle_recvmmsg(guest, call).await;
3624        };
3625        let vlen = call.vlen();
3626        if vlen == 0 || vlen > libc::UIO_MAXIOV as u32 {
3627            return self.handle_recvmmsg(guest, call).await;
3628        }
3629        let base = messages_address.as_raw();
3630
3631        // Snapshot each message's iovec geometry BEFORE the receive: the kernel
3632        // fills the pointed-to buffers and writes msg_len, but does not move the
3633        // iovec arrays themselves. Scoped, and reduced to plain scalars, so the
3634        // `mmsghdr` raw pointers are dropped before the await below: holding one
3635        // would make this future non-`Send`.
3636        let geometry: Vec<Vec<(usize, usize)>> = {
3637            // SAFETY: `mmsghdr` is a plain C record; an all-zero value is a
3638            // valid staging value immediately overwritten by `read_values`.
3639            let mut headers: Vec<libc::mmsghdr> = (0..vlen as usize)
3640                .map(|_| unsafe { std::mem::zeroed() })
3641                .collect();
3642            guest
3643                .memory()
3644                .read_values(messages_address.into(), &mut headers)?;
3645            let mut geometry = Vec::with_capacity(headers.len());
3646            for header in &headers {
3647                geometry.push(Self::read_iov_segments(
3648                    guest,
3649                    header.msg_hdr.msg_iov as usize,
3650                    header.msg_hdr.msg_iovlen,
3651                )?);
3652            }
3653            geometry
3654        };
3655
3656        let result = self.handle_recvmmsg(guest, call).await?;
3657        let delivered = usize::try_from(result).unwrap_or(0).min(geometry.len());
3658        if delivered == 0 {
3659            return Ok(result);
3660        }
3661
3662        // Re-read the array for the per-message byte counts the kernel just
3663        // wrote. Also scoped: nothing awaits past this point, but keeping the
3664        // raw pointers contained keeps the rule visible.
3665        let counts: Vec<usize> = {
3666            let address: AddrMut<'_, libc::mmsghdr> =
3667                AddrMut::from_raw(base).ok_or(Errno::EFAULT)?;
3668            // SAFETY: as above.
3669            let mut headers: Vec<libc::mmsghdr> = (0..vlen as usize)
3670                .map(|_| unsafe { std::mem::zeroed() })
3671                .collect();
3672            guest.memory().read_values(address.into(), &mut headers)?;
3673            headers.iter().map(|h| h.msg_len as usize).collect()
3674        };
3675        for (index, segments) in geometry.iter().enumerate().take(delivered) {
3676            self.sanitize_sock_diag_segments(guest, fd, segments, counts[index])?;
3677        }
3678        Ok(result)
3679    }
3680
3681    // TODO-HUMAN-REVIEW(PR-912): Review receive-time capture across socket aliases.
3682    /// Handle a socket receive and retain one timestamp for every alias of its open file.
3683    pub async fn handle_socket_receive<
3684        G: Guest<Self>,
3685        C: SyscallInfo + NonblockableSyscall + Into<Syscall>,
3686    >(
3687        &self,
3688        guest: &mut G,
3689        call: C,
3690        fd: i32,
3691        zero_delivers_packet: bool,
3692    ) -> Result<i64, Error> {
3693        let result = self.execute_nonblockable_fd_syscall(guest, call).await?;
3694        if self.cfg.virtualize_time && (result > 0 || (result == 0 && zero_delivers_packet)) {
3695            self.observe_socket_receive(guest, fd).await?;
3696        }
3697        Ok(result)
3698    }
3699
3700    // AUTONOMOUS-BOT-IMPLEMENTED
3701    // TODO-HUMAN-REVIEW(PR-901)
3702    /// Receive a message batch and replace every host socket timestamp with logical time.
3703    pub async fn handle_recvmmsg<G: Guest<Self>>(
3704        &self,
3705        guest: &mut G,
3706        call: syscalls::Recvmmsg,
3707    ) -> Result<i64, Error> {
3708        if self.cfg.recordreplay_modes && is_accepted_connection(guest, call.fd()) {
3709            return self.refuse_log_served_mmsg(guest, Sysno::recvmmsg).await;
3710        }
3711        if !self.cfg.virtualize_time || call.vlen() > libc::UIO_MAXIOV as u32 {
3712            return self.execute_nonblockable_fd_syscall(guest, call).await;
3713        }
3714
3715        let Some(messages_address) = call.mmsg() else {
3716            return self.execute_nonblockable_fd_syscall(guest, call).await;
3717        };
3718        let controls = {
3719            // SAFETY: `mmsghdr` is a plain C record and an all-zero value is a valid
3720            // initialized staging value that is immediately overwritten by `read_values`.
3721            let mut messages: Vec<libc::mmsghdr> = (0..call.vlen())
3722                .map(|_| unsafe { std::mem::zeroed() })
3723                .collect();
3724            guest
3725                .memory()
3726                .read_values(messages_address.into(), &mut messages)?;
3727
3728            let mut controls = Vec::with_capacity(messages.len());
3729            for message in &messages {
3730                let header = &message.msg_hdr;
3731                if header.msg_control.is_null() || header.msg_controllen == 0 {
3732                    controls.push(None);
3733                    continue;
3734                }
3735                controls.push(Some((
3736                    header.msg_control as usize,
3737                    header.msg_controllen.min(MAX_CONTROL_BYTES),
3738                )));
3739            }
3740            controls
3741        };
3742
3743        let result = self.execute_nonblockable_fd_syscall(guest, call).await?;
3744        let delivered = usize::try_from(result).unwrap_or(0).min(controls.len());
3745        if delivered == 0 {
3746            return Ok(result);
3747        }
3748        let now = self.observe_socket_receive(guest, call.fd()).await?;
3749        let mut timestamped = Vec::new();
3750        for (address, length) in controls.into_iter().take(delivered).flatten() {
3751            let address: AddrMut<'_, u8> = AddrMut::from_raw(address).ok_or(Errno::EFAULT)?;
3752            let mut bytes = vec![0; length];
3753            guest.memory().read_exact(address, &mut bytes)?;
3754            if !socket_timestamp_messages(&bytes).is_empty() {
3755                timestamped.push((address, bytes));
3756            }
3757        }
3758        if timestamped.is_empty() {
3759            return Ok(result);
3760        }
3761
3762        for (address, mut bytes) in timestamped {
3763            canonicalize_socket_timestamps(&mut bytes, now);
3764            guest.memory().write_exact(address, &bytes)?;
3765        }
3766        Ok(result)
3767    }
3768}
3769
3770#[cfg(test)]
3771mod tests {
3772    use super::*;
3773
3774    #[test]
3775    fn zero_timeout_socket_poll_requests_a_strong_one_turn_yield() {
3776        let request = zero_timeout_poll_request(DetTid::from_raw(17), true);
3777
3778        assert_eq!(request.resources.len(), 1);
3779        assert_eq!(
3780            request.resources.get(&ResourceID::SchedYield),
3781            Some(&Permission::W)
3782        );
3783        assert_eq!(request.fyi, LOOPBACK_POLL_YIELD_FYI);
3784    }
3785
3786    #[test]
3787    fn zero_timeout_non_socket_poll_keeps_the_existing_empty_turn() {
3788        let request = zero_timeout_poll_request(DetTid::from_raw(17), false);
3789
3790        assert!(request.resources.is_empty());
3791        assert!(request.fyi.is_empty());
3792    }
3793
3794    #[test]
3795    fn connect_peer_classification_never_overrides_kernel_errors() {
3796        assert!(connect_result_allows_peer_classification(&Ok(0)));
3797        assert!(connect_result_allows_peer_classification(&Err(
3798            Error::Errno(Errno::EINPROGRESS)
3799        )));
3800        assert!(!connect_result_allows_peer_classification(&Err(
3801            Error::Errno(Errno::EALREADY)
3802        )));
3803        assert!(!connect_result_allows_peer_classification(&Err(
3804            Error::Errno(Errno::EBADF)
3805        )));
3806        assert!(!connect_result_allows_peer_classification(&Err(
3807            Error::Errno(Errno::EFAULT)
3808        )));
3809    }
3810
3811    #[test]
3812    fn ppoll_timeout_uses_timespec_units() {
3813        assert_eq!(
3814            ppoll_timeout_duration(Timespec {
3815                tv_sec: 2,
3816                tv_nsec: 345_678_901,
3817            }),
3818            Ok(Duration::new(2, 345_678_901))
3819        );
3820        assert_eq!(
3821            timespec_from_duration(Duration::new(2, 345_678_901)),
3822            Timespec {
3823                tv_sec: 2,
3824                tv_nsec: 345_678_901,
3825            }
3826        );
3827    }
3828
3829    #[test]
3830    fn pselect6_fd_set_lengths_follow_the_raw_linux_abi() {
3831        assert_eq!(PSELECT6_INTERNAL_MAX_NFDS, 64);
3832        assert_eq!(pselect6_fd_set_len(-1), Err(Errno::EINVAL));
3833        assert_eq!(pselect6_fd_set_len(0), Ok(0));
3834        assert_eq!(pselect6_fd_set_len(1), Ok(8));
3835        assert_eq!(pselect6_fd_set_len(65), Ok(16));
3836        assert_eq!(pselect6_fd_set_len(libc::FD_SETSIZE as i32), Ok(128));
3837    }
3838
3839    #[test]
3840    fn pselect6_probe_result_maps_only_erestartsys_to_eintr() {
3841        assert_eq!(
3842            pselect6_probe_result(Err(Errno::ERESTARTSYS)),
3843            Err(Errno::EINTR)
3844        );
3845
3846        assert_eq!(pselect6_probe_result(Ok(0)), Ok(0));
3847        assert_eq!(pselect6_probe_result(Ok(1)), Ok(1));
3848        assert_eq!(pselect6_probe_result(Err(Errno::EBADF)), Err(Errno::EBADF));
3849        assert_eq!(
3850            pselect6_probe_result(Err(Errno::EINVAL)),
3851            Err(Errno::EINVAL)
3852        );
3853        assert_eq!(pselect6_probe_result(Err(Errno::EINTR)), Err(Errno::EINTR));
3854    }
3855
3856    #[test]
3857    fn select_timeout_folds_whole_seconds_out_of_microseconds() {
3858        let timeval = |tv_sec, tv_usec| libc::timeval { tv_sec, tv_usec };
3859        assert_eq!(
3860            select_timeout_duration(timeval(0, 1_500_000)),
3861            Ok(Duration::new(1, 500_000_000))
3862        );
3863        assert_eq!(
3864            select_timeout_duration(timeval(2, 3_000_001)),
3865            Ok(Duration::new(5, 1_000))
3866        );
3867        assert_eq!(
3868            select_timeout_duration(timeval(0, 999_999)),
3869            Ok(Duration::new(0, 999_999_000))
3870        );
3871        assert_eq!(select_timeout_duration(timeval(0, -1)), Err(Errno::EINVAL));
3872        assert_eq!(select_timeout_duration(timeval(-1, 0)), Err(Errno::EINVAL));
3873        // v7.1 refuses a negative field before normalizing, so neither mixed
3874        // sign is read as the 1 s it would sum to.
3875        assert_eq!(
3876            select_timeout_duration(timeval(2, -1_000_000)),
3877            Err(Errno::EINVAL)
3878        );
3879        assert_eq!(
3880            select_timeout_duration(timeval(-1, 2_000_000)),
3881            Err(Errno::EINVAL)
3882        );
3883        assert_eq!(select_timeout_duration(timeval(1, -1)), Err(Errno::EINVAL));
3884        assert_eq!(
3885            select_timeout_duration(timeval(libc::time_t::MAX, 1_000_000)),
3886            Err(Errno::EINVAL)
3887        );
3888    }
3889
3890    #[test]
3891    fn ppoll_signal_mask_keeps_reverie_preemption_unblocked() {
3892        let preemption_bit = 1_u64 << ((reverie::PERF_EVENT_SIGNAL as usize) - 1);
3893        assert_eq!(sanitize_ppoll_signal_mask(u64::MAX), !preemption_bit);
3894    }
3895
3896    #[test]
3897    fn ppoll_record_replay_waits_are_kernel_waits_and_run_mode_masked_waits_probe() {
3898        // Record/replay: the kernel owns the wait (issue 4042).
3899        assert!(ppoll_uses_kernel_wait(true, true));
3900        // A sequentialized run keeps the probe path.
3901        assert!(!ppoll_uses_kernel_wait(true, false));
3902        // Without sequentialization the kernel always owns it.
3903        assert!(ppoll_uses_kernel_wait(false, false));
3904        assert!(ppoll_uses_kernel_wait(false, true));
3905    }
3906
3907    #[test]
3908    fn ppoll_timeout_rejects_invalid_timespecs() {
3909        assert_eq!(
3910            ppoll_timeout_duration(Timespec {
3911                tv_sec: -1,
3912                tv_nsec: 0,
3913            }),
3914            Err(Errno::EINVAL)
3915        );
3916        assert_eq!(
3917            ppoll_timeout_duration(Timespec {
3918                tv_sec: 0,
3919                tv_nsec: 1_000_000_000,
3920            }),
3921            Err(Errno::EINVAL)
3922        );
3923    }
3924
3925    #[test]
3926    fn socket_timestamp_control_messages_use_logical_time() {
3927        let header_len = cmsg_align(std::mem::size_of::<libc::cmsghdr>());
3928        let timeval_len = std::mem::size_of::<libc::timeval>();
3929        let timespec_len = std::mem::size_of::<libc::timespec>();
3930        let first_len = header_len + timeval_len;
3931        let second_offset = cmsg_align(first_len);
3932        let second_len = header_len + timespec_len;
3933        let third_offset = second_offset + cmsg_align(second_len);
3934        let third_len = header_len + std::mem::size_of::<i32>();
3935        let mut control = vec![0; third_offset + cmsg_align(third_len)];
3936
3937        assert!(write_control_value(
3938            &mut control,
3939            libc::cmsghdr {
3940                cmsg_len: first_len,
3941                cmsg_level: libc::SOL_SOCKET,
3942                cmsg_type: SCM_TIMESTAMP_OLD,
3943            }
3944        ));
3945        assert!(write_control_value(
3946            &mut control[header_len..],
3947            libc::timeval {
3948                tv_sec: 99,
3949                tv_usec: 88,
3950            }
3951        ));
3952        assert!(write_control_value(
3953            &mut control[second_offset..],
3954            libc::cmsghdr {
3955                cmsg_len: second_len,
3956                cmsg_level: libc::SOL_SOCKET,
3957                cmsg_type: SCM_TIMESTAMPNS_OLD,
3958            }
3959        ));
3960        assert!(write_control_value(
3961            &mut control[second_offset + header_len..],
3962            libc::timespec {
3963                tv_sec: 77,
3964                tv_nsec: 66,
3965            }
3966        ));
3967        assert!(write_control_value(
3968            &mut control[third_offset..],
3969            libc::cmsghdr {
3970                cmsg_len: third_len,
3971                cmsg_level: libc::SOL_SOCKET,
3972                cmsg_type: libc::SCM_RIGHTS,
3973            }
3974        ));
3975        assert!(write_control_value(
3976            &mut control[third_offset + header_len..],
3977            42_i32
3978        ));
3979        let unrelated_message = control[third_offset..].to_vec();
3980
3981        assert_eq!(
3982            canonicalize_socket_timestamps(&mut control, LogicalTime::from_nanos(2_345_678_901)),
3983            2
3984        );
3985        let timeval = read_control_value::<libc::timeval>(&control[header_len..]).unwrap();
3986        assert_eq!(timeval.tv_sec, 2);
3987        assert_eq!(timeval.tv_usec, 345_678);
3988        let timespec =
3989            read_control_value::<libc::timespec>(&control[second_offset + header_len..]).unwrap();
3990        assert_eq!(timespec.tv_sec, 2);
3991        assert_eq!(timespec.tv_nsec, 345_678_901);
3992        assert_eq!(control[third_offset..], unrelated_message);
3993    }
3994
3995    #[test]
3996    fn truncated_timestamp_payload_prefix_is_rewritten() {
3997        let header_len = cmsg_align(std::mem::size_of::<libc::cmsghdr>());
3998        let full_len = header_len + std::mem::size_of::<libc::timeval>();
3999        let mut control = vec![0xaa; header_len + std::mem::size_of::<i32>()];
4000        assert!(write_control_value(
4001            &mut control,
4002            libc::cmsghdr {
4003                cmsg_len: full_len,
4004                cmsg_level: libc::SOL_SOCKET,
4005                cmsg_type: SCM_TIMESTAMP_OLD,
4006            }
4007        ));
4008
4009        assert_eq!(
4010            canonicalize_socket_timestamps(&mut control, LogicalTime::from_nanos(2_345_678_901)),
4011            1
4012        );
4013        assert_eq!(
4014            read_control_value::<i32>(&control[header_len..]),
4015            Some(2),
4016            "the visible timeval prefix must not retain host seconds"
4017        );
4018    }
4019
4020    #[test]
4021    fn timestamping_preserves_populated_source_slots() {
4022        let header_len = cmsg_align(std::mem::size_of::<libc::cmsghdr>());
4023        let timespec_len = std::mem::size_of::<libc::timespec>();
4024        let message_len = header_len + 3 * timespec_len;
4025        let mut control = vec![0; cmsg_align(message_len)];
4026        assert!(write_control_value(
4027            &mut control,
4028            libc::cmsghdr {
4029                cmsg_len: message_len,
4030                cmsg_level: libc::SOL_SOCKET,
4031                cmsg_type: SCM_TIMESTAMPING_OLD,
4032            }
4033        ));
4034        let zero = libc::timespec {
4035            tv_sec: 0,
4036            tv_nsec: 0,
4037        };
4038        let populated = libc::timespec {
4039            tv_sec: 99,
4040            tv_nsec: 88,
4041        };
4042        assert!(write_control_value(&mut control[header_len..], zero));
4043        assert!(write_control_value(
4044            &mut control[header_len + timespec_len..],
4045            populated
4046        ));
4047        assert!(write_control_value(
4048            &mut control[header_len + 2 * timespec_len..],
4049            populated
4050        ));
4051
4052        assert_eq!(
4053            canonicalize_socket_timestamps(&mut control, LogicalTime::from_nanos(2_345_678_901)),
4054            1
4055        );
4056        let first = read_control_value::<libc::timespec>(&control[header_len..]).unwrap();
4057        let second =
4058            read_control_value::<libc::timespec>(&control[header_len + timespec_len..]).unwrap();
4059        let third = read_control_value::<libc::timespec>(&control[header_len + 2 * timespec_len..])
4060            .unwrap();
4061        assert_eq!((first.tv_sec, first.tv_nsec), (0, 0));
4062        assert_eq!((second.tv_sec, second.tv_nsec), (2, 345_678_901));
4063        assert_eq!((third.tv_sec, third.tv_nsec), (2, 345_678_901));
4064    }
4065}