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