air_sys_syscall/

time.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/.

//! Wrappers de la famille `time`.
//!
//! Cf. `docs/specs/layer-0/family-time.md`.

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use core::num::NonZeroI32;
use core::time::Duration;

use air_sys_types::{
    Clock, Errno, Instant, SleepDeadline, SleepError, TimerFdFlags, TimerFdSpecification,
    TimerSetFlags,
};

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::time supporte uniquement x86_64 et aarch64 (ADR-014).");

const NANOS_PER_SECOND_U32: u32 = 1_000_000_000;
const TIMER_ABSTIME: i32 = 1;

#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
struct KernelTimespec {
    tv_sec: i64,
    tv_nsec: i64,
}

#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
struct KernelItimerspec {
    it_interval: KernelTimespec,
    it_value: KernelTimespec,
}

/// FD `timerfd` (cf. `timerfd_create(2)`).
#[derive(Debug)]
pub struct TimerFd(OwnedFd);

impl TimerFd {
    /// Construit depuis un `OwnedFd` déjà ouvert sur un timerfd.
    #[must_use]
    #[inline]
    pub const fn from_owned_fd(fd: OwnedFd) -> Self {
        Self(fd)
    }

    /// Vue empruntée du FD sous-jacent.
    #[must_use]
    pub fn as_fd(&self) -> BorrowedFd<'_> {
        use air_sys_types::fd::AsFd;
        self.0.as_fd()
    }

    /// Consomme et restitue le `OwnedFd` sous-jacent.
    #[must_use]
    pub fn into_fd(self) -> OwnedFd {
        self.0
    }

    /// Arme le timer et retourne l'ancienne spécification.
    ///
    /// # Errors
    ///
    /// - `EINVAL` : durée hors-plage (dépassement `i64` lors de la conversion
    ///   en `KernelTimespec`), ou combinaison de `flags` refusée par le kernel.
    /// - `EBADF` : le FD sous-jacent n'est pas un timerfd valide.
    pub fn arm(
        &self,
        spec: &TimerFdSpecification,
        flags: TimerSetFlags,
    ) -> Result<TimerFdSpecification, Errno> {
        let new_value = kernel_itimerspec_from_spec(*spec)?;
        let mut old_value = KernelItimerspec::default();
        // SAFETY: `new_value` et `old_value` sont des `KernelItimerspec` locaux
        // vivants ; on passe leurs adresses (lecture pour `new_value`, écriture pour
        // `old_value`) — préconditions de `raw_syscall_timerfd_settime` satisfaites.
        let ret = unsafe {
            raw_syscall_timerfd_settime(
                self.0.as_raw_fd(),
                flags.bits(),
                (&new_value as *const KernelItimerspec) as u64,
                (&mut old_value as *mut KernelItimerspec) as u64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        kernel_itimerspec_to_spec(old_value)
    }

    /// Désarme le timer et retourne l'ancienne spécification.
    ///
    /// # Errors
    ///
    /// Délègue à [`TimerFd::arm`] avec une spécification nulle — seul `EBADF`
    /// peut survenir. `EINVAL` ne peut pas survenir ici car la spécification
    /// `Duration::ZERO` est toujours valide.
    pub fn disarm(&self) -> Result<TimerFdSpecification, Errno> {
        self.arm(
            &TimerFdSpecification {
                initial: Duration::ZERO,
                interval: Duration::ZERO,
            },
            TimerSetFlags::empty(),
        )
    }

    /// Lit l'état courant du timer.
    ///
    /// # Errors
    ///
    /// - `EBADF` : le FD sous-jacent n'est pas un timerfd valide.
    /// - `EINVAL` : valeur renvoyée par le kernel hors-plage (ne devrait pas
    ///   survenir sur un timerfd bien formé).
    pub fn current(&self) -> Result<TimerFdSpecification, Errno> {
        let mut current = KernelItimerspec::default();
        // SAFETY: `current` est un `KernelItimerspec` local vivant ; on passe son
        // adresse au kernel qui y écrit l'échéance courante — précondition de
        // `raw_syscall_timerfd_gettime` satisfaite.
        let ret = unsafe {
            raw_syscall_timerfd_gettime(
                self.0.as_raw_fd(),
                (&mut current as *mut KernelItimerspec) as u64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        kernel_itimerspec_to_spec(current)
    }

    /// Lit le nombre d'expirations accumulées.
    ///
    /// # Errors
    ///
    /// - `EAGAIN` : aucune expiration disponible et le FD a été créé avec
    ///   `TFD_NONBLOCK` (cf. test `timerfd_nonblocking_read_without_expiration_returns_eagain`).
    /// - `EINTR` : interrompu par un signal avant toute expiration. Conforme
    ///   à la politique EINTR de la couche 0 : l'appelant doit retry
    ///   explicitement s'il le souhaite.
    /// - `EBADF` : le FD sous-jacent n'est pas un timerfd valide.
    /// - `ECANCELED` : l'horloge `CLOCK_REALTIME` (ou `CLOCK_REALTIME_ALARM`) a
    ///   subi un changement discontinu alors que le timer absolu avait été armé
    ///   avec `TFD_TIMER_CANCEL_ON_SET` (cf. `man 2 timerfd_create`).
    pub fn read(&self) -> Result<u64, Errno> {
        let mut count = 0_u64;
        // SAFETY: `count` est un `u64` local vivant ; on passe son adresse et la
        // taille exacte (`size_of::<u64>()`) — le kernel y écrit au plus 8 octets,
        // précondition de `raw_syscall_read` satisfaite.
        let ret = unsafe {
            raw_syscall_read(
                self.0.as_raw_fd(),
                (&mut count as *mut u64) as u64,
                u64::try_from(core::mem::size_of::<u64>()).expect("u64 size fits in u64"),
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        debug_assert_eq!(ret, 8);
        Ok(count)
    }
}

/// Lit le temps courant pour l'horloge ciblée.
///
/// # Errors
///
/// - `EINVAL` : identifiant d'horloge inconnu du kernel, ou valeur renvoyée
///   hors-plage (nanoseconde négative ou ≥ 10⁹).
pub fn clock_gettime(clock: Clock) -> Result<Instant, Errno> {
    let ts = syscall_clock_gettime(clock.as_raw())?;
    kernel_timespec_to_instant(clock, ts)
}

/// Modifie le temps courant d'une horloge ajustable.
///
/// # Errors
///
/// - `EINVAL` : `instant.clock() != clock` (vérifié avant l'appel syscall),
///   ou identifiant d'horloge refusé par le kernel.
/// - `EPERM` : `CAP_SYS_TIME` manquante. Échoue systématiquement en
///   environnement non privilégié (cf. test `clock_settime_realtime_current_time_is_ok_or_eperm`).
pub fn clock_settime(clock: Clock, instant: Instant) -> Result<(), Errno> {
    if instant.clock() != clock {
        return Err(Errno::EINVAL);
    }
    let ts = kernel_timespec_from_instant(instant);
    // Note coverage:
    // - Le chemin `Ok(())` de `clock_settime` n'est généralement pas couvrable
    //   en CI ni en développement courant, car `clock_settime(2)` exige des
    //   privilèges élevés (`CAP_SYS_TIME`) pour réussir sur les horloges
    //   ajustables.
    // - Nous savons donc que la branche succès peut rester non couverte sur un
    //   environnement non privilégié, même si le wrapper est correct.
    // - Une manière d'atteindre artificiellement 100 % ici serait
    //   d'introduire un point d'injection / seam test-only pour simuler un
    //   succès du syscall. Ce choix est refusé dans Air : on n'ouvre pas de
    //   brèche structurelle dans le code de production uniquement pour flatter
    //   la couverture. Le projet vise une couverture maximale, mais reste
    //   pragmatique plutôt que paranoïaque.
    // SAFETY: `ts` est un `KernelTimespec` local vivant ; on passe son adresse en
    // lecture seule — précondition de `raw_syscall_clock_settime` satisfaite.
    let ret =
        unsafe { raw_syscall_clock_settime(clock.as_raw(), (&ts as *const KernelTimespec) as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Résolution de l'horloge ciblée.
///
/// # Errors
///
/// - `EINVAL` : identifiant d'horloge inconnu du kernel.
pub fn clock_getres(clock: Clock) -> Result<Duration, Errno> {
    let ts = syscall_clock_getres(clock.as_raw())?;
    kernel_timespec_to_duration(ts)
}

/// Endort le thread appelant jusqu'à l'échéance demandée.
pub fn clock_nanosleep(clock: Clock, deadline: SleepDeadline) -> Result<(), SleepError> {
    let mut rem = KernelTimespec::default();
    let (flags, req, rem_ptr) = match deadline {
        SleepDeadline::Relative(duration) => {
            let req = match kernel_timespec_from_duration(duration) {
                Ok(req) => req,
                Err(err) => return Err(SleepError::Other(err)),
            };
            (0_i32, req, (&mut rem as *mut KernelTimespec) as u64)
        }
        SleepDeadline::AbsoluteInstant(instant) => {
            if instant.clock() != clock {
                return Err(SleepError::Other(Errno::EINVAL));
            }
            (TIMER_ABSTIME, kernel_timespec_from_instant(instant), 0_u64)
        }
    };

    // SAFETY: `req` est un `KernelTimespec` local vivant (lecture) ; `rem_ptr` est
    // soit nul (sommeil absolu), soit l'adresse du `rem` local vivant (écriture du
    // reste) — préconditions de `raw_syscall_clock_nanosleep` satisfaites.
    let ret = unsafe {
        raw_syscall_clock_nanosleep(
            clock.as_raw(),
            flags,
            (&req as *const KernelTimespec) as u64,
            rem_ptr,
        )
    };
    decode_clock_nanosleep_result(deadline, rem, ret)
}

/// Crée un `timerfd` pour l'horloge ciblée.
///
/// `TFD_CLOEXEC` est toujours positionné en interne, quelle que soit la valeur
/// de `flags` (sécurité par défaut).
///
/// # Errors
///
/// - `EINVAL` : identifiant d'horloge non supporté par `timerfd`, ou
///   combinaison de `flags` invalide.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
/// - `ENOMEM` : mémoire kernel insuffisante.
/// - `ENODEV` : impossible de monter le pseudo-périphérique anonyme interne.
pub fn timerfd_create(clock: Clock, flags: TimerFdFlags) -> Result<TimerFd, Errno> {
    let kernel_flags = flags.bits() | TimerFdFlags::CLOEXEC.bits();
    let owned = syscall_timerfd_create(clock.as_raw(), kernel_flags)?;
    Ok(TimerFd::from_owned_fd(owned))
}

fn syscall_clock_gettime(clock: i32) -> Result<KernelTimespec, Errno> {
    let mut ts = KernelTimespec::default();
    // SAFETY: `ts` est un `KernelTimespec` local vivant ; on passe son adresse en
    // écriture — précondition de `raw_syscall_clock_gettime` satisfaite.
    let ret = unsafe { raw_syscall_clock_gettime(clock, (&mut ts as *mut KernelTimespec) as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ts)
}

fn syscall_clock_getres(clock: i32) -> Result<KernelTimespec, Errno> {
    let mut ts = KernelTimespec::default();
    // SAFETY: `ts` est un `KernelTimespec` local vivant ; on passe son adresse en
    // écriture — précondition de `raw_syscall_clock_getres` satisfaite.
    let ret = unsafe { raw_syscall_clock_getres(clock, (&mut ts as *mut KernelTimespec) as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ts)
}

fn syscall_timerfd_create(clock: i32, flags: i32) -> Result<OwnedFd, Errno> {
    // SAFETY: `raw_syscall_timerfd_create` ne prend que des scalaires et ne touche
    // à aucune mémoire utilisateur — aucune précondition de pointeur à honorer.
    let ret = unsafe { raw_syscall_timerfd_create(clock, flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let fd = ret as i32;
    // SAFETY: `ret >= 0` ici, donc `fd` est un descripteur fraîchement créé par
    // `timerfd_create`, non possédé ailleurs : on en prend la propriété exclusive.
    let owned = unsafe { OwnedFd::from_raw_fd(fd) };
    Ok(owned)
}

fn decode_clock_nanosleep_result(
    deadline: SleepDeadline,
    rem: KernelTimespec,
    ret: i64,
) -> Result<(), SleepError> {
    if ret == 0 {
        return Ok(());
    }
    let errno = errno_from_negative_syscall_ret(ret);
    if errno == Errno::EINTR
        && let SleepDeadline::Relative(_) = deadline
    {
        let remaining = kernel_timespec_to_duration(rem).map_err(SleepError::Other)?;
        return Err(SleepError::Interrupted { remaining });
    }
    Err(SleepError::Other(errno))
}

fn kernel_timespec_from_duration(duration: Duration) -> Result<KernelTimespec, Errno> {
    let secs = i64::try_from(duration.as_secs()).map_err(|_| Errno::EINVAL)?;
    Ok(KernelTimespec {
        tv_sec: secs,
        tv_nsec: i64::from(duration.subsec_nanos()),
    })
}

fn kernel_timespec_to_duration(ts: KernelTimespec) -> Result<Duration, Errno> {
    if ts.tv_sec < 0 || ts.tv_nsec < 0 || ts.tv_nsec >= i64::from(NANOS_PER_SECOND_U32) {
        return Err(Errno::EINVAL);
    }
    let secs = u64::try_from(ts.tv_sec).map_err(|_| Errno::EINVAL)?;
    let nanos = u32::try_from(ts.tv_nsec).map_err(|_| Errno::EINVAL)?;
    Ok(Duration::new(secs, nanos))
}

fn kernel_timespec_from_instant(instant: Instant) -> KernelTimespec {
    KernelTimespec {
        tv_sec: instant.seconds(),
        tv_nsec: i64::from(instant.nanoseconds()),
    }
}

fn kernel_timespec_to_instant(clock: Clock, ts: KernelTimespec) -> Result<Instant, Errno> {
    if ts.tv_nsec < 0 || ts.tv_nsec >= i64::from(NANOS_PER_SECOND_U32) {
        return Err(Errno::EINVAL);
    }
    let nanos = u32::try_from(ts.tv_nsec).map_err(|_| Errno::EINVAL)?;
    Instant::try_new(clock, ts.tv_sec, nanos).ok_or(Errno::EINVAL)
}

fn kernel_itimerspec_from_spec(spec: TimerFdSpecification) -> Result<KernelItimerspec, Errno> {
    Ok(KernelItimerspec {
        it_interval: kernel_timespec_from_duration(spec.interval)?,
        it_value: kernel_timespec_from_duration(spec.initial)?,
    })
}

fn kernel_itimerspec_to_spec(spec: KernelItimerspec) -> Result<TimerFdSpecification, Errno> {
    Ok(TimerFdSpecification {
        interval: kernel_timespec_to_duration(spec.it_interval)?,
        initial: kernel_timespec_to_duration(spec.it_value)?,
    })
}

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)
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clock_gettime(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_gettime (x86_64 = 228). Le kernel écrit l'instant courant
    // à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide et inscriptible
    // pour la durée de l'appel (précondition de cette fn unsafe, tenue par l'appelant).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 228_i64,
            in("rdi") i64::from(clock),
            in("rsi") ts,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clock_settime(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_settime (x86_64 = 227). Le kernel lit l'instant à poser
    // à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide pour la durée
    // de l'appel. `readonly` : aucune mémoire utilisateur n'est écrite.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 227_i64,
            in("rdi") i64::from(clock),
            in("rsi") ts,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clock_getres(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_getres (x86_64 = 229). Le kernel écrit la résolution de
    // l'horloge à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide et
    // inscriptible pour la durée de l'appel (précondition de cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 229_i64,
            in("rdi") i64::from(clock),
            in("rsi") ts,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clock_nanosleep(clock: i32, flags: i32, req: u64, rem: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_nanosleep (x86_64 = 230). Le kernel lit la durée demandée
    // à l'adresse `req` et, en cas d'interruption d'un sommeil relatif, écrit le
    // reste à l'adresse `rem`. `req` doit pointer un `KernelTimespec` valide ; `rem`
    // doit être nul ou pointer un `KernelTimespec` inscriptible (préconditions de
    // cette fn unsafe, tenues par l'appelant).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 230_i64,
            in("rdi") i64::from(clock),
            in("rsi") i64::from(flags),
            in("rdx") req,
            in("r10") rem,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_timerfd_create(clock: i32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_create (x86_64 = 283). Ne prend que des scalaires (clock,
    // flags) et ne touche à aucune mémoire utilisateur ; retourne un FD ≥ 0 ou un
    // errno négatif. `readonly` : aucune écriture mémoire.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 283_i64,
            in("rdi") i64::from(clock),
            in("rsi") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_timerfd_settime(fd: i32, flags: i32, new_value: u64, old_value: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_settime (x86_64 = 286). Le kernel lit la nouvelle
    // échéance à l'adresse `new_value` et, si `old_value` est non nul, y écrit
    // l'ancienne. `new_value` doit pointer un `KernelItimerspec` valide ; `old_value`
    // doit être nul ou pointer un `KernelItimerspec` inscriptible (préconditions de
    // cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 286_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(flags),
            in("rdx") new_value,
            in("r10") old_value,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_timerfd_gettime(fd: i32, curr_value: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_gettime (x86_64 = 287). Le kernel écrit l'échéance
    // courante à l'adresse `curr_value`, qui doit pointer un `KernelItimerspec`
    // valide et inscriptible pour la durée de l'appel (précondition de cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 287_i64,
            in("rdi") i64::from(fd),
            in("rsi") curr_value,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_read(fd: i32, buffer: u64, count: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (x86_64 = 0). Le kernel écrit jusqu'à `count` octets à
    // l'adresse `buffer`, qui doit pointer une zone valide et inscriptible d'au
    // moins `count` octets (précondition de cette fn unsafe, tenue par l'appelant).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 0_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") count,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clock_gettime(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_gettime (aarch64 = 113). Le kernel écrit l'instant courant
    // à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide et inscriptible
    // pour la durée de l'appel (précondition de cette fn unsafe, tenue par l'appelant).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 113_i64,
            inout("x0") i64::from(clock) => ret,
            in("x1") ts,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clock_settime(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_settime (aarch64 = 112). Le kernel lit l'instant à poser
    // à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide pour la durée
    // de l'appel. `readonly` : aucune mémoire utilisateur n'est écrite.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 112_i64,
            inout("x0") i64::from(clock) => ret,
            in("x1") ts,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clock_getres(clock: i32, ts: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_getres (aarch64 = 114). Le kernel écrit la résolution de
    // l'horloge à l'adresse `ts`, qui doit pointer un `KernelTimespec` valide et
    // inscriptible pour la durée de l'appel (précondition de cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 114_i64,
            inout("x0") i64::from(clock) => ret,
            in("x1") ts,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clock_nanosleep(clock: i32, flags: i32, req: u64, rem: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_clock_nanosleep (aarch64 = 115). Le kernel lit la durée demandée
    // à l'adresse `req` et, en cas d'interruption d'un sommeil relatif, écrit le
    // reste à l'adresse `rem`. `req` doit pointer un `KernelTimespec` valide ; `rem`
    // doit être nul ou pointer un `KernelTimespec` inscriptible (préconditions de
    // cette fn unsafe, tenues par l'appelant).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 115_i64,
            inout("x0") i64::from(clock) => ret,
            in("x1") i64::from(flags),
            in("x2") req,
            in("x3") rem,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_timerfd_create(clock: i32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_create (aarch64 = 85). Ne prend que des scalaires (clock,
    // flags) et ne touche à aucune mémoire utilisateur ; retourne un FD ≥ 0 ou un
    // errno négatif. `readonly` : aucune écriture mémoire.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 85_i64,
            inout("x0") i64::from(clock) => ret,
            in("x1") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_timerfd_settime(fd: i32, flags: i32, new_value: u64, old_value: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_settime (aarch64 = 86). Le kernel lit la nouvelle
    // échéance à l'adresse `new_value` et, si `old_value` est non nul, y écrit
    // l'ancienne. `new_value` doit pointer un `KernelItimerspec` valide ; `old_value`
    // doit être nul ou pointer un `KernelItimerspec` inscriptible (préconditions de
    // cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 86_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(flags),
            in("x2") new_value,
            in("x3") old_value,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_timerfd_gettime(fd: i32, curr_value: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_timerfd_gettime (aarch64 = 87). Le kernel écrit l'échéance
    // courante à l'adresse `curr_value`, qui doit pointer un `KernelItimerspec`
    // valide et inscriptible pour la durée de l'appel (précondition de cette fn unsafe).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 87_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") curr_value,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_read(fd: i32, buffer: u64, count: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (aarch64 = 63). Le kernel écrit jusqu'à `count` octets à
    // l'adresse `buffer`, qui doit pointer une zone valide et inscriptible d'au
    // moins `count` octets (précondition de cette fn unsafe, tenue par l'appelant).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 63_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") count,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::process::{getpid, gettid};
    use crate::signal::tgkill;
    use crate::test_support::sown;
    use air_sys_types::Signal;
    use air_sys_types::fd::{AsFd, AsRawFd};
    use std::os::unix::net::UnixStream;
    use std::thread;

    #[test]
    fn clock_gettime_monotonic_is_non_decreasing() {
        let t1 = clock_gettime(Clock::Monotonic).expect("clock_gettime monotonic doit réussir");
        let t2 = clock_gettime(Clock::Monotonic).expect("clock_gettime monotonic doit réussir");
        assert!(t2.saturating_duration_since(t1) <= Duration::from_secs(1));
    }

    #[test]
    fn clock_gettime_realtime_is_positive() {
        let t = clock_gettime(Clock::Realtime).expect("clock_gettime Realtime");
        // Unix epoch > 0 (valeur post-2000).
        assert!(t.seconds() > 0);
    }

    #[test]
    fn clock_gettime_process_cpu_succeeds() {
        let _ = clock_gettime(Clock::ProcessCpuTime).expect("clock_gettime ProcessCpuTime");
    }

    #[test]
    fn clock_getres_realtime_is_reasonable() {
        let res = clock_getres(Clock::Realtime).expect("clock_getres Realtime");
        assert!(res < Duration::from_secs(1));
    }

    #[test]
    fn clock_getres_monotonic_is_reasonable() {
        let res = clock_getres(Clock::Monotonic).expect("clock_getres doit réussir");
        assert!(res < Duration::from_secs(1));
    }

    #[test]
    fn clock_nanosleep_relative_waits_at_least_requested_duration() {
        let start = std::time::Instant::now();
        clock_nanosleep(
            Clock::Monotonic,
            SleepDeadline::Relative(Duration::from_millis(20)),
        )
        .expect("clock_nanosleep relatif doit réussir");
        assert!(start.elapsed() >= Duration::from_millis(15));
    }

    #[test]
    fn clock_nanosleep_absolute_rejects_cross_clock_deadline() {
        let deadline = Instant::try_new(Clock::Realtime, 1, 0).expect("valid instant");
        let err = clock_nanosleep(Clock::Monotonic, SleepDeadline::AbsoluteInstant(deadline))
            .expect_err("cross-clock deadline must be rejected");
        assert_eq!(err, SleepError::Other(Errno::EINVAL));
    }

    #[test]
    fn clock_nanosleep_relative_rejects_duration_overflow() {
        let err = clock_nanosleep(
            Clock::Monotonic,
            SleepDeadline::Relative(Duration::from_secs(u64::MAX)),
        )
        .expect_err("overflowing duration must be rejected");
        assert_eq!(err, SleepError::Other(Errno::EINVAL));
    }

    #[test]
    fn clock_nanosleep_absolute_waits_until_deadline() {
        let start = clock_gettime(Clock::Monotonic).expect("clock_gettime monotonic");
        let target = Duration::from_millis(15);
        let total_nanos = u64::from(start.nanoseconds()) + u64::from(target.subsec_nanos());
        let carry_secs = total_nanos / 1_000_000_000;
        let nanos =
            u32::try_from(total_nanos % 1_000_000_000).expect("normalized nanos fit in u32");
        let deadline = Instant::try_new(
            Clock::Monotonic,
            start.seconds()
                + i64::try_from(target.as_secs()).expect("short duration seconds fit in i64")
                + i64::try_from(carry_secs).expect("carry fits in i64"),
            nanos,
        )
        .expect("normalized absolute deadline");
        let wall_start = std::time::Instant::now();
        clock_nanosleep(Clock::Monotonic, SleepDeadline::AbsoluteInstant(deadline))
            .expect("absolute sleep must succeed");
        assert!(wall_start.elapsed() >= Duration::from_millis(10));
    }

    #[test]
    fn timerfd_nonblocking_read_without_expiration_returns_eagain() {
        let tfd = timerfd_create(Clock::Monotonic, TimerFdFlags::NONBLOCK)
            .expect("timerfd_create doit réussir");
        let err = tfd
            .read()
            .expect_err("read sans expiration doit échouer en EAGAIN");
        assert_eq!(err, Errno::EAGAIN);
    }

    #[test]
    fn timerfd_one_shot_arm_then_read_returns_one_expiration() {
        let tfd = timerfd_create(Clock::Monotonic, TimerFdFlags::empty())
            .expect("timerfd_create doit réussir");
        let previous = tfd
            .arm(
                &TimerFdSpecification {
                    initial: Duration::from_millis(10),
                    interval: Duration::ZERO,
                },
                TimerSetFlags::empty(),
            )
            .expect("arm doit réussir");
        assert_eq!(previous.initial, Duration::ZERO);
        assert_eq!(previous.interval, Duration::ZERO);
        let expirations = tfd.read().expect("read doit réussir après expiration");
        assert_eq!(expirations, 1);
    }

    #[test]
    fn timerfd_current_and_disarm_roundtrip() {
        let tfd = timerfd_create(Clock::Monotonic, TimerFdFlags::empty())
            .expect("timerfd_create doit réussir");
        let spec = TimerFdSpecification {
            initial: Duration::from_millis(50),
            interval: Duration::from_millis(20),
        };
        let _ = tfd
            .arm(&spec, TimerSetFlags::empty())
            .expect("arm doit réussir");
        let current = tfd.current().expect("current doit réussir");
        assert_eq!(current.interval, Duration::from_millis(20));
        assert!(current.initial <= Duration::from_millis(50));
        let previous = tfd.disarm().expect("disarm doit réussir");
        assert_eq!(previous.interval, Duration::from_millis(20));
        let now = tfd.current().expect("current disarmed doit réussir");
        assert_eq!(now.initial, Duration::ZERO);
        assert_eq!(now.interval, Duration::ZERO);
    }

    #[test]
    fn errno_from_negative_syscall_ret_maps_eagain() {
        assert_eq!(errno_from_negative_syscall_ret(-11), Errno::EAGAIN);
    }

    #[test]
    fn timerfd_fd_accessors_roundtrip() {
        let tfd = timerfd_create(Clock::Monotonic, TimerFdFlags::NONBLOCK)
            .expect("timerfd_create doit réussir");
        let borrowed_raw = tfd.as_fd().as_raw_fd();
        let borrowed_raw_via_inner = tfd.as_fd().as_fd().as_raw_fd();
        assert_eq!(borrowed_raw, borrowed_raw_via_inner);

        let owned = tfd.into_fd();
        assert_eq!(borrowed_raw, owned.as_raw_fd());
    }

    #[test]
    fn timerfd_methods_reject_non_timerfd_fd() {
        let (stream, _peer) = UnixStream::pair().expect("unix stream pair");
        let owned: OwnedFd = sown(stream);
        let timer = TimerFd::from_owned_fd(owned);

        assert!(timer.current().is_err());
        assert!(
            timer
                .arm(
                    &TimerFdSpecification {
                        initial: Duration::from_millis(1),
                        interval: Duration::ZERO,
                    },
                    TimerSetFlags::empty(),
                )
                .is_err()
        );
    }

    #[test]
    fn clock_settime_rejects_cross_clock_instant() {
        let instant = Instant::try_new(Clock::Realtime, 1, 0).expect("valid instant");
        let err = clock_settime(Clock::Monotonic, instant)
            .expect_err("cross-clock instant must be rejected");
        assert_eq!(err, Errno::EINVAL);
    }

    #[test]
    fn clock_settime_realtime_current_time_is_ok_or_eperm() {
        let now = clock_gettime(Clock::Realtime).expect("clock_gettime realtime");
        let result = clock_settime(Clock::Realtime, now);
        assert!(matches!(result, Ok(()) | Err(Errno::EPERM)));
    }

    #[test]
    fn raw_clock_helpers_reject_invalid_clock() {
        let ts = KernelTimespec {
            tv_sec: 1,
            tv_nsec: 0,
        };

        assert_eq!(syscall_clock_gettime(-1), Err(Errno::EINVAL));
        assert_eq!(syscall_clock_getres(-1), Err(Errno::EINVAL));
        // SAFETY: `ts` est un `KernelTimespec` local vivant ; on passe son adresse
        // en lecture seule (`clock = -1` invalide ⇒ EINVAL avant toute lecture
        // effective) — précondition de `raw_syscall_clock_settime` satisfaite.
        let settime_ret =
            unsafe { raw_syscall_clock_settime(-1, (&ts as *const KernelTimespec) as u64) };
        assert_eq!(errno_from_negative_syscall_ret(settime_ret), Errno::EINVAL);
        assert!(matches!(
            syscall_timerfd_create(-1, TimerFdFlags::CLOEXEC.bits()),
            Err(Errno::EINVAL)
        ));
    }

    #[test]
    fn decode_clock_nanosleep_result_covers_eintr_paths() {
        let interrupted = decode_clock_nanosleep_result(
            SleepDeadline::Relative(Duration::from_secs(1)),
            KernelTimespec {
                tv_sec: 0,
                tv_nsec: 500_000_000,
            },
            -i64::from(Errno::EINTR.as_raw()),
        )
        .expect_err("relative EINTR must map to Interrupted");
        assert_eq!(
            interrupted,
            SleepError::Interrupted {
                remaining: Duration::from_millis(500)
            }
        );

        let absolute = decode_clock_nanosleep_result(
            SleepDeadline::AbsoluteInstant(
                Instant::try_new(Clock::Monotonic, 1, 0).expect("valid instant"),
            ),
            KernelTimespec::default(),
            -i64::from(Errno::EINTR.as_raw()),
        )
        .expect_err("absolute EINTR stays as Other");
        assert_eq!(absolute, SleepError::Other(Errno::EINTR));

        // errno non-EINTR : couvre le côté faux de la condition `errno == EINTR`
        // (la branche tombe directement sur `SleepError::Other`).
        let other = decode_clock_nanosleep_result(
            SleepDeadline::Relative(Duration::from_secs(1)),
            KernelTimespec::default(),
            -i64::from(Errno::EINVAL.as_raw()),
        )
        .expect_err("non-EINTR error stays as Other");
        assert_eq!(other, SleepError::Other(Errno::EINVAL));
    }

    // Couvre les deux côtés faux du `debug_assert!(ret < 0 && ret > -4096)` de
    // `errno_from_negative_syscall_ret` (garde de défense en profondeur).
    #[test]
    #[should_panic(expected = "ret < 0")]
    fn errno_from_negative_syscall_ret_panics_on_non_negative() {
        let _ = errno_from_negative_syscall_ret(0);
    }

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

    #[test]
    fn decode_clock_nanosleep_result_rejects_invalid_remaining_timespec() {
        let err = decode_clock_nanosleep_result(
            SleepDeadline::Relative(Duration::from_secs(1)),
            KernelTimespec {
                tv_sec: -1,
                tv_nsec: 0,
            },
            -i64::from(Errno::EINTR.as_raw()),
        )
        .expect_err("invalid remainder must map to EINVAL");
        assert_eq!(err, SleepError::Other(Errno::EINVAL));
    }

    #[test]
    fn helper_conversions_validate_bounds() {
        assert_eq!(
            kernel_timespec_from_duration(Duration::from_secs(u64::MAX)),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_timespec_to_duration(KernelTimespec {
                tv_sec: -1,
                tv_nsec: 0,
            }),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_timespec_to_duration(KernelTimespec {
                tv_sec: 0,
                tv_nsec: 1_000_000_000,
            }),
            Err(Errno::EINVAL)
        );
        // `tv_nsec` négatif : opérande médian de la disjonction de
        // `kernel_timespec_to_duration` (jamais pris autrement).
        assert_eq!(
            kernel_timespec_to_duration(KernelTimespec {
                tv_sec: 0,
                tv_nsec: -1,
            }),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_timespec_to_instant(
                Clock::Monotonic,
                KernelTimespec {
                    tv_sec: 0,
                    tv_nsec: 1_000_000_000,
                },
            ),
            Err(Errno::EINVAL)
        );
        // `tv_nsec` négatif : premier opérande de la disjonction de
        // `kernel_timespec_to_instant`.
        assert_eq!(
            kernel_timespec_to_instant(
                Clock::Monotonic,
                KernelTimespec {
                    tv_sec: 0,
                    tv_nsec: -1,
                },
            ),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_itimerspec_from_spec(TimerFdSpecification {
                initial: Duration::ZERO,
                interval: Duration::from_secs(u64::MAX),
            }),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_itimerspec_from_spec(TimerFdSpecification {
                initial: Duration::from_secs(u64::MAX),
                interval: Duration::ZERO,
            }),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_itimerspec_to_spec(KernelItimerspec {
                it_interval: KernelTimespec {
                    tv_sec: -1,
                    tv_nsec: 0,
                },
                it_value: KernelTimespec {
                    tv_sec: 0,
                    tv_nsec: 0,
                },
            }),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            kernel_itimerspec_to_spec(KernelItimerspec {
                it_interval: KernelTimespec {
                    tv_sec: 0,
                    tv_nsec: 0,
                },
                it_value: KernelTimespec {
                    tv_sec: -1,
                    tv_nsec: 0,
                },
            }),
            Err(Errno::EINVAL)
        );
    }

    #[test]
    fn clock_nanosleep_relative_is_interruptible_by_signal() {
        let handler = TestSignalHandler::install(Signal::SIGUSR1).expect("install SIGUSR1 handler");
        let pid = getpid();
        let tid = gettid();
        let sender = thread::spawn(move || {
            thread::sleep(Duration::from_millis(10));
            tgkill(pid, tid, Some(Signal::SIGUSR1)).expect("tgkill SIGUSR1");
        });

        let err = clock_nanosleep(
            Clock::Monotonic,
            SleepDeadline::Relative(Duration::from_millis(100)),
        )
        .expect_err("sleep should be interrupted");
        sender.join().expect("signal sender thread join");
        drop(handler);

        // On prouve seulement la variante : un `if let` laisserait une
        // branche « else » morte. La valeur exacte de `remaining` (et ses
        // bornes) est vérifiée de façon déterministe dans
        // `decode_clock_nanosleep_result_covers_eintr_paths`.
        assert!(matches!(err, SleepError::Interrupted { .. }));
    }

    #[test]
    fn timerfd_arm_rejects_overflowing_initial_spec() {
        let tfd = timerfd_create(Clock::Monotonic, TimerFdFlags::NONBLOCK)
            .expect("timerfd_create doit réussir");
        let err = tfd
            .arm(
                &TimerFdSpecification {
                    initial: Duration::from_secs(u64::MAX),
                    interval: Duration::ZERO,
                },
                TimerSetFlags::empty(),
            )
            .expect_err("overflowing initial spec must be rejected");
        assert_eq!(err, Errno::EINVAL);
    }

    struct TestSignalHandler {
        signal: Signal,
        previous: KernelSigaction,
    }

    impl TestSignalHandler {
        fn install(signal: Signal) -> Result<Self, Errno> {
            Self::install_raw(signal.as_raw())
        }

        fn install_raw(signum: i32) -> Result<Self, Errno> {
            let new_action = KernelSigaction::handler_only(test_noop_signal_handler);
            let mut previous = KernelSigaction::default();
            // SAFETY:
            // - `new_action` et `previous` pointent sur des buffers locaux valides.
            // - `signum` est soit un signal valide du test, soit une valeur invalide
            //   exercée explicitement pour couvrir le chemin d'erreur.
            // - `sigsetsize = 8` correspond au `kernel_sigset_t` 64-bit visé par Air.
            let ret = unsafe {
                raw_syscall_rt_sigaction(
                    signum,
                    (&new_action as *const KernelSigaction) as u64,
                    (&mut previous as *mut KernelSigaction) as u64,
                    8,
                )
            };
            if ret < 0 {
                return Err(errno_from_negative_syscall_ret(ret));
            }
            let signal = Signal::try_from_raw(signum).expect("valid signum on success");
            Ok(Self { signal, previous })
        }
    }

    impl Drop for TestSignalHandler {
        fn drop(&mut self) {
            // SAFETY: on restaure la disposition sauvegardée `self.previous` (buffer
            // local vivant, lecture seule) ; `old_sa = 0` (aucune ancienne à écrire),
            // `sigsetsize = 8` pour le `kernel_sigset_t` 64-bit visé par Air —
            // préconditions de `raw_syscall_rt_sigaction` satisfaites.
            let _ = unsafe {
                raw_syscall_rt_sigaction(
                    self.signal.as_raw(),
                    (&self.previous as *const KernelSigaction) as u64,
                    0,
                    8,
                )
            };
        }
    }

    #[repr(C)]
    #[derive(Clone, Copy, Default)]
    struct KernelSigaction {
        sa_handler: usize,
        sa_flags: usize,
        sa_restorer: usize,
        sa_mask: u64,
    }

    impl KernelSigaction {
        fn handler_only(handler: extern "C" fn(i32)) -> Self {
            Self {
                sa_handler: handler as usize,
                sa_flags: 0,
                sa_restorer: 0,
                sa_mask: 0,
            }
        }
    }

    extern "C" fn test_noop_signal_handler(_: i32) {}

    #[test]
    fn test_signal_handler_install_rejects_invalid_signal_number() {
        // `.err().expect(...)` au lieu d'un `match { Ok => panic }` : ce
        // dernier laisserait le bras `Ok` comme branche morte. `.err()` évite
        // d'exiger `Debug` sur `TestSignalHandler` (que `expect_err` réclame).
        let err = TestSignalHandler::install_raw(-1)
            .err()
            .expect("invalid signal number should fail");
        assert_eq!(err, Errno::EINVAL);
    }

    #[test]
    fn test_noop_signal_handler_is_callable() {
        test_noop_signal_handler(0);
    }

    #[cfg(target_arch = "x86_64")]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (x86_64 = 13). Le kernel lit la nouvelle
        // disposition à l'adresse `new_sa` (si non nulle) et écrit l'ancienne à
        // `old_sa` (si non nulle) ; `sigsetsize` borne la taille du masque. Chaque
        // pointeur non nul doit viser un `KernelSigaction` valide (resp. inscriptible
        // pour `old_sa`) — préconditions de cette fn unsafe, tenues par l'appelant.
        unsafe {
            core::arch::asm!(
                "syscall",
                in("rax") 13_i64,
                in("rdi") i64::from(signum),
                in("rsi") new_sa,
                in("rdx") old_sa,
                in("r10") sigsetsize,
                lateout("rax") ret,
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    #[cfg(target_arch = "aarch64")]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (aarch64 = 134). Le kernel lit la nouvelle
        // disposition à l'adresse `new_sa` (si non nulle) et écrit l'ancienne à
        // `old_sa` (si non nulle) ; `sigsetsize` borne la taille du masque. Chaque
        // pointeur non nul doit viser un `KernelSigaction` valide (resp. inscriptible
        // pour `old_sa`) — préconditions de cette fn unsafe, tenues par l'appelant.
        unsafe {
            core::arch::asm!(
                "svc 0",
                in("x8") 134_i64,
                inout("x0") i64::from(signum) => ret,
                in("x1") new_sa,
                in("x2") old_sa,
                in("x3") sigsetsize,
                options(nostack, preserves_flags),
            );
        }
        ret
    }
}