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;