air_sys_syscall/

poll.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Famille `poll` — attente synchrone bornée et interruptible (`ppoll(2)`).
//!
//! Ajoutée par **ADR-044** (RFC d'extension d'une couche scellée, re-sceau
//! `couche-0-v1.5`) pour débloquer l'attente bornée/interruptible de
//! `air-process` **sans tirer io_uring** dans la couche 1. Cf.
//! `docs/specs/layer-0/family-poll.md`.
//!
//! Caractéristiques (doctrine « kernel = bible ») :
//!
//! - **`ppoll` uniquement** : précision nanoseconde (aligne [`Duration`]),
//!   `timeout` non muté au retour, masque de signaux atomique — la variante
//!   moderne (ADR-021).
//! - **`EINTR` remonté, jamais de retry** (ADR-021 §2) : la reprise (échéance
//!   recalculée) vit en couche 1.
//! - **`PollFd` emprunté (+0)** : la slice de l'appelant est passée au kernel
//!   sans copie ni allocation (Principe 4) ; les `revents` sont restitués
//!   intégralement (ADR-032).
//! - **Conversion d'échéance défensive** (Principe 2) : `tv_sec` clampé à
//!   `i64::MAX` en cas de débordement, jamais d'`as` lossy.

use core::num::NonZeroI32;
use core::time::Duration;

use air_sys_types::{Errno, PollFd, SignalMask};

/// Taille du `sigset_t` kernel (1 mot de 64 bits sur x86_64/aarch64, `_NSIG = 64`).
const SIGSET_SIZE_U64: u64 = 8;

/// Miroir `#[repr(C)]` de `struct timespec` kernel (`__kernel_timespec`).
///
/// `pub(crate)` : **réutilisé tel quel** par la famille `futex` (ADR-048) pour le
/// timeout relatif de `futex_wait` — même `repr`, même conversion défensive.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub(crate) struct KernelTimespec {
    tv_sec: i64,
    tv_nsec: i64,
}

/// `ppoll(2)`. Attend un événement sur l'un des `fds` jusqu'à `timeout`.
///
/// - `timeout = None`     → attente **indéfinie** (timespec `NULL`).
/// - `timeout = Some(d)`  → attente bornée ; [`Duration::ZERO`] = **sondage** non
///   bloquant.
/// - `sigmask = None`     → `NULL` (aucune substitution de masque ; réservé à un
///   usage futur).
///
/// Au retour, chaque [`PollFd`] de `fds` porte ses `revents` remplis par le
/// kernel (vide si le descripteur n'est pas prêt).
///
/// Retour : **nombre de fd** dont `revents` est non vide ; **`0` = expiration**.
///
/// # Errors
///
/// - [`Errno::EINTR`] : un signal a interrompu l'attente — **remonté tel quel**
///   (ADR-021 §2), aucune reprise automatique en couche 0.
/// - [`Errno::EINVAL`] : `timespec` invalide — impossible via la conversion
///   défensive interne (`tv_nsec < 1e9`, `tv_sec ≥ 0`).
/// - [`Errno::EFAULT`] : pointeur invalide — inatteignable via cette API safe
///   (la slice et le masque proviennent de références vivantes).
pub fn ppoll(
    fds: &mut [PollFd<'_>],
    timeout: Option<Duration>,
    sigmask: Option<&SignalMask>,
) -> Result<usize, Errno> {
    // Échéance : `None` → pointeur NULL (attente infinie) ; `Some` → adresse d'un
    // `KernelTimespec` local vivant pour toute la durée de l'appel.
    let ts = timeout.map(kernel_timespec_from_duration_clamped);
    let timeout_ptr: u64 = match &ts {
        Some(t) => {
            let p: *const KernelTimespec = t;
            p as u64
        }
        None => 0,
    };

    // Masque de signaux : `None` → NULL ; `Some` → adresse d'un mot `u64` local.
    let mask_bits: u64 = sigmask.map_or(0, |m| m.bits());
    let mask_ptr: u64 = match sigmask {
        Some(_) => {
            let p: *const u64 = &mask_bits;
            p as u64
        }
        None => 0,
    };

    let nfds = fds.len() as u64;
    let fds_ptr = fds.as_mut_ptr() as u64;

    // SAFETY: `fds` est une slice vivante de `PollFd` (`#[repr(C)]` bit-pour-bit
    // `struct pollfd`) ; le kernel lit `fd`/`events` et écrit `revents` de chacune
    // des `nfds` entrées — accès borné à la slice possédée par l'appelant.
    // `timeout_ptr` pointe un `KernelTimespec` local vivant (ou NULL) ; `mask_ptr`
    // pointe un `u64` local vivant (ou NULL), `sigsetsize = 8` = taille kernel du
    // `sigset_t`. Aucun pointeur ne survit à l'appel.
    let ret = unsafe { raw_syscall_ppoll(fds_ptr, nfds, timeout_ptr, mask_ptr, SIGSET_SIZE_U64) };

    // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md, section
    // `poll`). Le bras d'erreur n'est atteignable que par `EINTR` (signal pendant
    // l'attente — non injectable de façon déterministe en CI, comme le précédent
    // `waitid`), `EFAULT` (pointeur invalide — exclu : slice/masque vivants par
    // construction) ou `EINVAL` (timespec invalide — exclu par la conversion
    // défensive : `tv_nsec < 1e9`, `tv_sec ≥ 0`). Le décodage d'errno lui-même est
    // couvert par `errno_from_negative_syscall_ret_maps_eintr`.
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `ret ≥ 0` est le nombre de fd prêts (≤ nfds) : conversion `i64 → usize`
    // défensive (Principe 2, pas d'`as`). Inatteignable en erreur : `ret` est
    // borné par `nfds` qui provient d'un `usize`.
    usize::try_from(ret).map_err(|_| Errno::EINVAL)
}

/// Conversion `Duration` → `KernelTimespec` **défensive** (Principe 2).
///
/// - `tv_sec` = `i64::try_from(d.as_secs())`, **clampé à `i64::MAX`** en cas de
///   débordement (« ~infini borné », ≈ 292 milliards d'années) — jamais d'`as`,
///   jamais de troncature silencieuse.
/// - `tv_nsec` = `d.subsec_nanos()` (`< 1e9`, conversion `u32 → i64` sûre via
///   `i64::from`).
/// - `Duration::ZERO` → `{0, 0}` → sondage immédiat.
///
/// `pub(crate)` : **réutilisé tel quel** par la famille `futex` (ADR-048).
pub(crate) fn kernel_timespec_from_duration_clamped(d: Duration) -> KernelTimespec {
    let tv_sec = i64::try_from(d.as_secs()).unwrap_or(i64::MAX);
    KernelTimespec {
        tv_sec,
        tv_nsec: i64::from(d.subsec_nanos()),
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Helper commun : conversion d'une valeur de retour syscall négative en Errno.
// ─────────────────────────────────────────────────────────────────────────

fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret.wrapping_neg() as i32;
    let nz = NonZeroI32::new(raw).expect("errno strictement positif par construction");
    Errno::from_nonzero(nz)
}

// ─────────────────────────────────────────────────────────────────────────
// asm! wrappers x86_64 / aarch64.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_ppoll(
    fds: u64,
    nfds: u64,
    timeout: u64,
    sigmask: u64,
    sigsetsize: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_ppoll (x86_64 = 271). Le kernel lit `*fds` (nfds × `struct
    // pollfd`) et y écrit les `revents` ; lit `*timeout` si non-null (16 octets),
    // lit `*sigmask` si non-null (8 octets). Pas de `readonly` (écriture sur
    // `fds`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 271_i64,
            in("rdi") fds,
            in("rsi") nfds,
            in("rdx") timeout,
            in("r10") sigmask,
            in("r8") sigsetsize,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_ppoll(
    fds: u64,
    nfds: u64,
    timeout: u64,
    sigmask: u64,
    sigsetsize: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_ppoll (aarch64 = 73). Mêmes accès mémoire que sur x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 73_i64,
            inout("x0") fds => ret,
            in("x1") nfds,
            in("x2") timeout,
            in("x3") sigmask,
            in("x4") sigsetsize,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(all(test, target_os = "linux", not(loom)))]
mod tests {
    use super::{KernelTimespec, kernel_timespec_from_duration_clamped, ppoll};
    use crate::ipc::pipe2;
    use air_sys_types::fd::{AsFd, OwnedFd};
    use air_sys_types::{Errno, PipeFlags, PollEvents, PollFd, SignalMask};
    use core::num::NonZeroI32;
    use core::time::Duration;

    /// Crée un pipe `(lecteur, écrivain)` via le wrapper couche 0 `ipc::pipe2`.
    /// Les `OwnedFd` ferment leurs descripteurs à `Drop` (RAII).
    fn make_pipe() -> (OwnedFd, OwnedFd) {
        pipe2(PipeFlags::CLOEXEC).expect("pipe2")
    }

    /// Écrit un octet sur l'extrémité écriture d'un pipe (réveille `POLLIN`).
    fn poke(writer: &OwnedFd) {
        use air_sys_types::fd::AsFd;
        // Écrit via le wrapper couche 0 (FD emprunté Air) — pas de pont std.
        crate::fs::write(writer.as_fd(), b"x").expect("write pipe");
    }

    #[test]
    fn ppoll_reports_pollin_after_write() {
        let (reader, writer) = make_pipe();
        poke(&writer);
        let mut fds = [PollFd::new(reader.as_fd(), PollEvents::IN)];
        // Échéance large : le fd est déjà prêt, l'appel revient immédiatement.
        let n = ppoll(&mut fds, Some(Duration::from_secs(5)), None).expect("ppoll");
        assert_eq!(n, 1);
        assert!(fds[0].revents().contains(PollEvents::IN));
    }

    #[test]
    fn ppoll_infinite_timeout_returns_on_ready_fd() {
        // `timeout = None` ⇒ timespec NULL (attente indéfinie). On rend le fd prêt
        // AVANT l'appel : ppoll revient immédiatement, sans bloquer — ce qui
        // exerce le bras `None` (pointeur NULL) de façon déterministe.
        let (reader, writer) = make_pipe();
        poke(&writer);
        let mut fds = [PollFd::new(reader.as_fd(), PollEvents::IN)];
        let n = ppoll(&mut fds, None, None).expect("ppoll");
        assert_eq!(n, 1);
        assert!(fds[0].revents().contains(PollEvents::IN));
    }

    #[test]
    fn ppoll_times_out_on_silent_pipe() {
        let (reader, _writer) = make_pipe();
        let mut fds = [PollFd::new(reader.as_fd(), PollEvents::IN)];
        // Pipe muet, timeout court : expiration → Ok(0), aucun revents.
        let n = ppoll(&mut fds, Some(Duration::from_millis(10)), None).expect("ppoll");
        assert_eq!(n, 0);
        assert_eq!(fds[0].revents(), PollEvents::empty());
    }

    #[test]
    fn ppoll_zero_timeout_is_nonblocking_poll() {
        let (reader, _writer) = make_pipe();
        let mut fds = [PollFd::new(reader.as_fd(), PollEvents::IN)];
        // Sondage non bloquant sur un pipe muet : revient aussitôt avec Ok(0).
        let n = ppoll(&mut fds, Some(Duration::ZERO), None).expect("ppoll");
        assert_eq!(n, 0);
    }

    #[test]
    fn ppoll_multi_fd_only_ready_one_carries_revents() {
        let (ready_reader, ready_writer) = make_pipe();
        let (idle_reader, _idle_writer) = make_pipe();
        poke(&ready_writer);
        let mut fds = [
            PollFd::new(idle_reader.as_fd(), PollEvents::IN),
            PollFd::new(ready_reader.as_fd(), PollEvents::IN),
        ];
        let n = ppoll(&mut fds, Some(Duration::from_secs(5)), None).expect("ppoll");
        assert_eq!(n, 1, "un seul fd est prêt");
        // Seul le fd écrit porte un revents non vide (info kernel non masquée).
        assert_eq!(fds[0].revents(), PollEvents::empty());
        assert!(fds[1].revents().contains(PollEvents::IN));
    }

    #[test]
    fn ppoll_empty_slice_times_out() {
        // Slice vide (`nfds = 0`) : ppoll dégénère en simple sommeil borné → Ok(0).
        let mut fds: [PollFd<'_>; 0] = [];
        let n = ppoll(&mut fds, Some(Duration::ZERO), None).expect("ppoll");
        assert_eq!(n, 0);
    }

    #[test]
    fn ppoll_with_empty_sigmask_still_polls() {
        // Exerce la branche `sigmask = Some(_)` (pointeur non-null) : un masque
        // vide ne bloque aucun signal et ne change pas le résultat.
        let (reader, writer) = make_pipe();
        poke(&writer);
        let mut fds = [PollFd::new(reader.as_fd(), PollEvents::IN)];
        let mask = SignalMask::empty();
        let n = ppoll(&mut fds, Some(Duration::from_secs(5)), Some(&mask)).expect("ppoll");
        assert_eq!(n, 1);
        assert!(fds[0].revents().contains(PollEvents::IN));
    }

    #[test]
    fn timespec_conversion_zero_is_immediate() {
        let ts = kernel_timespec_from_duration_clamped(Duration::ZERO);
        assert_eq!(ts.tv_sec, 0);
        assert_eq!(ts.tv_nsec, 0);
    }

    #[test]
    fn timespec_conversion_clamps_giant_seconds_to_i64_max() {
        // `Duration` géante (secondes > i64::MAX) → clamp à i64::MAX, jamais d'`as`.
        let giant = Duration::new(u64::MAX, 999_999_999);
        let ts = kernel_timespec_from_duration_clamped(giant);
        assert_eq!(ts.tv_sec, i64::MAX);
        assert_eq!(ts.tv_nsec, 999_999_999);
    }

    #[test]
    fn timespec_conversion_preserves_small_values() {
        let ts = kernel_timespec_from_duration_clamped(Duration::new(3, 250));
        assert_eq!(ts.tv_sec, 3);
        assert_eq!(ts.tv_nsec, 250);
    }

    #[test]
    fn errno_from_negative_syscall_ret_maps_eintr() {
        assert_eq!(super::errno_from_negative_syscall_ret(-4), Errno::EINTR);
        // Cohérence du décodage : -EINVAL (22) → Errno::EINVAL.
        let nz = NonZeroI32::new(22).unwrap();
        assert_eq!(Errno::from_nonzero(nz), Errno::EINVAL);
    }

    // Couvrent les deux opérandes du `debug_assert!(ret < 0 && ret > -4096)`
    // de `errno_from_negative_syscall_ret` (`ret = 0` ; `ret = -5000`).
    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_on_non_negative() {
        let _ = super::errno_from_negative_syscall_ret(0);
    }

    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_below_errno_range() {
        let _ = super::errno_from_negative_syscall_ret(-5000);
    }

    proptest::proptest! {
        /// Property : la conversion `Duration → timespec` ne panique jamais,
        /// `tv_nsec` reste dans `[0, 1e9)` et `tv_sec` est clampé à `i64::MAX`.
        #[test]
        fn timespec_conversion_is_total(secs in 0_u64..=u64::MAX, nanos in 0_u32..1_000_000_000) {
            let d = Duration::new(secs, nanos);
            let ts = kernel_timespec_from_duration_clamped(d);
            proptest::prop_assert!(ts.tv_nsec >= 0 && ts.tv_nsec < 1_000_000_000);
            proptest::prop_assert_eq!(ts.tv_nsec, i64::from(nanos));
            let expected = i64::try_from(secs).unwrap_or(i64::MAX);
            proptest::prop_assert_eq!(ts.tv_sec, expected);
        }
    }

    /// `KernelTimespec` est `#[repr(C)]` de 16 octets (`__kernel_timespec`).
    #[test]
    fn kernel_timespec_layout() {
        assert_eq!(core::mem::size_of::<KernelTimespec>(), 16);
        let ts = KernelTimespec {
            tv_sec: 1,
            tv_nsec: 2,
        };
        let _ = format!("{ts:?}");
        let copy = ts;
        assert_eq!(copy.tv_sec, 1);
    }
}