air_sys_syscall/

ipc.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 `ipc` — eventfd, pipe, opérations zero-copy.
//!
//! Cf. `docs/specs/layer-0/family-ipc.md`.

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

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

use air_sys_types::Errno;
use air_sys_types::ipc::{EventFdFlags, PipeFlags, SpliceFlags};
use air_sys_types::net::IoSlice;

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

// ─────────────────────────────────────────────────────────────────────────
// EventFd — compteur kernel exposé comme FD.
// ─────────────────────────────────────────────────────────────────────────

/// FD `eventfd` (cf. `eventfd2(2)`).
///
/// Encapsule un compteur kernel 64 bits exposé comme descripteur de
/// fichier. Pattern privilégié pour les notifications légères
/// inter-threads ou inter-processus, et pour l'intégration avec
/// io_uring (wakeup du reactor).
///
/// La fermeture du FD est automatique à la destruction (RAII via
/// [`OwnedFd`]).
#[derive(Debug)]
pub struct EventFd(OwnedFd);

impl EventFd {
    /// Vue empruntée du FD sous-jacent.
    ///
    /// Utile pour passer le FD à d'autres syscalls (poll, io_uring…)
    /// sans transférer l'ownership.
    #[must_use]
    pub fn as_fd(&self) -> BorrowedFd<'_> {
        self.0.as_fd()
    }

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

    /// Lit la valeur courante du compteur.
    ///
    /// **Mode normal** (sans `SEMAPHORE`) : retourne la valeur courante et
    /// remet le compteur à zéro. Bloque si le compteur est zéro (sauf
    /// si `NONBLOCK` est positionné).
    ///
    /// **Mode sémaphore** (avec `SEMAPHORE`) : retourne 1 et décrémente
    /// de 1. Bloque si le compteur est zéro.
    ///
    /// # Errors
    ///
    /// - `EAGAIN` : compteur à zéro et le FD est en mode non-bloquant.
    /// - `EINTR` : interrompu par un signal (ADR-021 convention 2 :
    ///   pas de retry automatique).
    /// - `EBADF` : FD invalide (ne se produit pas si `EventFd` bien formé).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use air_sys_syscall::ipc::eventfd2;
    /// use air_sys_types::EventFdFlags;
    ///
    /// let efd = eventfd2(0, EventFdFlags::empty()).expect("eventfd2");
    /// efd.write(5).expect("write");
    /// let val = efd.read().expect("read");
    /// assert_eq!(val, 5);
    /// ```
    pub fn read(&self) -> Result<u64, Errno> {
        let mut buffer: u64 = 0;
        let buf_ptr: *mut u64 = &mut buffer;
        // SAFETY:
        // - SYS_read sur un eventfd lit exactement 8 octets dans `*buf_ptr`.
        // - `buffer` est local valide pour toute la durée du syscall.
        // - Le FD est garanti ouvert (EventFd possède un OwnedFd valide).
        let ret = unsafe {
            raw_syscall_read(
                self.0.as_raw_fd(),
                buf_ptr as u64,
                core::mem::size_of::<u64>(),
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(buffer)
    }

    /// Incrémente le compteur de `value`.
    ///
    /// Bloque si le compteur atteindrait `u64::MAX - 1` (espace épuisé).
    /// Retourne immédiatement `EAGAIN` si non-bloquant.
    ///
    /// # Parameters
    ///
    /// - `value` : incrément. La valeur maximale autorisée par incrémentation
    ///   est `u64::MAX - 1` ; `u64::MAX` est interdit par le kernel.
    ///
    /// # Errors
    ///
    /// - `EINVAL` : `value` == `u64::MAX` (débordement interdit).
    /// - `EAGAIN` : le FD est non-bloquant et l'incrément bloquerait.
    /// - `EINTR` : interrompu par un signal (pas de retry automatique).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use air_sys_syscall::ipc::eventfd2;
    /// use air_sys_types::EventFdFlags;
    ///
    /// let efd = eventfd2(0, EventFdFlags::empty()).expect("eventfd2");
    /// efd.write(1).expect("write notification");
    /// ```
    pub fn write(&self, value: u64) -> Result<(), Errno> {
        let buf_ptr: *const u64 = &value;
        // SAFETY:
        // - SYS_write sur un eventfd lit exactement 8 octets depuis `*buf_ptr`.
        // - `value` est local valide pour toute la durée du syscall.
        // - Le FD est garanti ouvert (EventFd possède un OwnedFd valide).
        let ret = unsafe {
            raw_syscall_write(
                self.0.as_raw_fd(),
                buf_ptr as u64,
                core::mem::size_of::<u64>(),
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Fonctions publiques
// ─────────────────────────────────────────────────────────────────────────

/// Crée un `eventfd` avec compteur initial et flags.
///
/// Wrappeur de `eventfd2(2)` (Linux 2.6.27+, numéro x86_64: 290,
/// aarch64: 19). `CLOEXEC` n'est **pas** ajouté automatiquement : l'appelant
/// doit l'inclure dans `flags` si désiré (comportement recommandé).
///
/// # Parameters
///
/// - `initial` : valeur initiale du compteur (typiquement 0).
/// - `flags` : combinaison de [`EventFdFlags`].
///
/// # Errors
///
/// - `EINVAL` : flags invalides.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
/// - `ENODEV` : impossible de monter le pseudo-périphérique anonyme.
/// - `ENOMEM` : mémoire kernel insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::ipc::eventfd2;
/// use air_sys_types::EventFdFlags;
///
/// let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2");
/// ```
pub fn eventfd2(initial: u64, flags: EventFdFlags) -> Result<EventFd, Errno> {
    // Le kernel eventfd2 prend un u32 : les bits hauts de `initial` sont
    // ignorés par l'ABI kernel ; on passe les 32 bits bas.
    #[allow(clippy::cast_possible_truncation)]
    let initial_u32 = initial as u32;
    // SAFETY: eventfd2(2) ne lit ni n'écrit aucune mémoire utilisateur ;
    // il prend deux scalaires (u32 initial, i32 flags) et retourne un fd.
    let ret = unsafe { raw_syscall_eventfd2(initial_u32, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // Linux borne les fd à i32::MAX ; la troncature est exacte.
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = ret as i32;
    // SAFETY: le kernel vient d'allouer un fd valide et nous en a transféré
    // la propriété ; Air le wrappe immédiatement dans OwnedFd. Drop fermera.
    let owned = unsafe { OwnedFd::from_raw_fd(raw_fd) };
    Ok(EventFd(owned))
}

/// Crée un pipe unidirectionnel et retourne `(read_end, write_end)`.
///
/// Wrappeur de `pipe2(2)` (Linux 2.6.27+). Retourne deux [`OwnedFd`] :
/// le premier est le côté lecture, le second le côté écriture.
///
/// `CLOEXEC` est **fortement recommandé** pour éviter la fuite du pipe
/// vers les processus fils après `exec`. Air n'impose pas `CLOEXEC`
/// automatiquement car certains usages légitimes (héritage volontaire
/// vers un enfant) en ont besoin.
///
/// # Parameters
///
/// - `flags` : combinaison de [`PipeFlags`].
///
/// # Errors
///
/// - `EFAULT` : pointeur interne invalide (ne se produit pas via cette API).
/// - `EINVAL` : flags invalides.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::ipc::pipe2;
/// use air_sys_types::PipeFlags;
///
/// let (read_fd, write_fd) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
/// ```
pub fn pipe2(flags: PipeFlags) -> Result<(OwnedFd, OwnedFd), Errno> {
    // Le kernel pipe2 écrit deux fd dans un tableau int[2] (= [i32; 2]).
    let mut fds: [i32; 2] = [-1, -1];
    let fds_ptr: *mut [i32; 2] = &mut fds;
    // SAFETY:
    // - pipe2(2) écrit exactement 2 × sizeof(int) = 8 octets à `fds_ptr`.
    // - `fds` est local valide pour toute la durée du syscall.
    let ret = unsafe { raw_syscall_pipe2(fds_ptr as u64, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // SAFETY: le kernel a écrit deux fd valides dans `fds` ; Air en prend
    // la propriété. Drop fermera chacun.
    let read_end = unsafe { OwnedFd::from_raw_fd(fds[0]) };
    let write_end = unsafe { OwnedFd::from_raw_fd(fds[1]) };
    Ok((read_end, write_end))
}

/// Transfère jusqu'à `length` octets de `fd_in` vers `fd_out` sans copie
/// userspace (zero-copy).
///
/// Wrappeur de `splice(2)` (Linux 2.6.17+). **Au moins un** des deux FDs
/// doit être un pipe ; sinon le kernel retourne `EINVAL`.
///
/// Si `offset_in` / `offset_out` est `None`, la position courante du FD est
/// utilisée et avancée. Si `Some`, la position donnée est utilisée sans
/// modifier la position courante du FD.
///
/// # Parameters
///
/// - `fd_in` : FD source.
/// - `offset_in` : offset dans `fd_in`, ou `None` pour la position courante.
/// - `fd_out` : FD destination.
/// - `offset_out` : offset dans `fd_out`, ou `None` pour la position courante.
/// - `length` : nombre maximum d'octets à transférer.
/// - `flags` : drapeaux [`SpliceFlags`].
///
/// # Errors
///
/// - `EINVAL` : ni `fd_in` ni `fd_out` n'est un pipe, ou flags invalides.
/// - `EAGAIN` : mode `NONBLOCK` et l'opération bloquerait.
/// - `EINTR` : interrompu par un signal (pas de retry automatique).
/// - `EBADF` : FD invalide ou mode d'accès incorrect.
/// - `ESPIPE` : `offset_in` non-nul sur un pipe (les pipes ne sont pas seekables).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::ipc::{pipe2, splice};
/// use air_sys_types::{PipeFlags, SpliceFlags};
/// use air_sys_types::fd::AsFd;
///
/// let (read_fd, write_fd) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
/// // Connecter un fichier source au pipe...
/// let _ = splice(
///     read_fd.as_fd(), None,
///     write_fd.as_fd(), None,
///     4096,
///     SpliceFlags::empty(),
/// );
/// ```
pub fn splice(
    fd_in: BorrowedFd<'_>,
    offset_in: Option<&mut u64>,
    fd_out: BorrowedFd<'_>,
    offset_out: Option<&mut u64>,
    length: usize,
    flags: SpliceFlags,
) -> Result<usize, Errno> {
    // `None` → NULL pointer (0) ; `Some` → adresse du u64 mutable.
    let off_in_ptr: u64 = match offset_in {
        None => 0,
        Some(p) => {
            let raw: *mut u64 = p;
            raw as u64
        }
    };
    let off_out_ptr: u64 = match offset_out {
        None => 0,
        Some(p) => {
            let raw: *mut u64 = p;
            raw as u64
        }
    };
    // SAFETY:
    // - splice(2) lit/écrit optionnellement via `off_in_ptr`/`off_out_ptr`
    //   si non nuls ; les pointeurs sont valides (locaux à l'appelant, via
    //   `Option<&mut u64>`).
    // - fd_in et fd_out sont garantis ouverts par BorrowedFd.
    let ret = unsafe {
        raw_syscall_splice(
            fd_in.as_raw_fd(),
            off_in_ptr,
            fd_out.as_raw_fd(),
            off_out_ptr,
            length,
            flags.bits(),
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // splice retourne le nombre d'octets transférés : non négatif, ≤ length
    // (qui est un usize). La troncature de i64 → usize est exacte sur LP64.
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Duplique le contenu d'un pipe source dans un pipe destination sans
/// consommer les données de la source.
///
/// Wrappeur de `tee(2)` (Linux 2.6.17+). Les deux FDs **doivent** être
/// des pipes. Contrairement à `splice`, les données restent disponibles
/// dans `fd_in` après l'opération.
///
/// # Parameters
///
/// - `fd_in` : pipe source.
/// - `fd_out` : pipe destination.
/// - `length` : nombre maximum d'octets à dupliquer.
/// - `flags` : drapeaux [`SpliceFlags`] (typiquement `NONBLOCK`).
///
/// # Errors
///
/// - `EINVAL` : `fd_in` ou `fd_out` n'est pas un pipe.
/// - `EAGAIN` : mode `NONBLOCK` et l'opération bloquerait.
/// - `EINTR` : interrompu par un signal.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::ipc::{pipe2, tee};
/// use air_sys_types::{PipeFlags, SpliceFlags};
/// use air_sys_types::fd::AsFd;
///
/// let (r1, w1) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
/// let (r2, w2) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
/// let _ = tee(r1.as_fd(), w2.as_fd(), 4096, SpliceFlags::empty());
/// ```
pub fn tee(
    fd_in: BorrowedFd<'_>,
    fd_out: BorrowedFd<'_>,
    length: usize,
    flags: SpliceFlags,
) -> Result<usize, Errno> {
    // SAFETY: tee(2) ne touche aucune mémoire utilisateur ; il opère
    // uniquement sur les pipe buffers internes au kernel.
    // fd_in et fd_out sont garantis ouverts par BorrowedFd.
    let ret =
        unsafe { raw_syscall_tee(fd_in.as_raw_fd(), fd_out.as_raw_fd(), length, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Transfère des buffers userspace vers un pipe sans copie intermédiaire.
///
/// Wrappeur de `vmsplice(2)` (Linux 2.6.17+). `fd` doit être un pipe.
///
/// **Mode GIFT (dangereux) :** si [`SpliceFlags::GIFT`] est positionné,
/// les pages userspace sont données au kernel. Les régions décrites par
/// `iov` **ne doivent plus jamais être modifiées** après l'appel —
/// violation d'invariant = corruption mémoire silencieuse.
///
/// # Parameters
///
/// - `fd` : pipe destination.
/// - `iov` : slices de buffers userspace à transférer.
/// - `flags` : drapeaux [`SpliceFlags`].
///
/// # Safety
///
/// Si [`SpliceFlags::GIFT`] est utilisé, l'appelant doit garantir que
/// les pages décrites par `iov` ne sont plus modifiées après l'appel.
/// Modifier ces pages après un `vmsplice GIFT` produit un comportement
/// indéfini.
///
/// # Errors
///
/// - `EINVAL` : `fd` n'est pas un pipe, ou `iov` dépasse `UIO_MAXIOV`.
/// - `EAGAIN` : mode `NONBLOCK` et le pipe est plein.
/// - `EINTR` : interrompu par un signal.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::ipc::{pipe2, vmsplice};
/// use air_sys_types::{PipeFlags, SpliceFlags};
/// use air_sys_types::net::IoSlice;
/// use air_sys_types::fd::AsFd;
///
/// let data = b"hello, world";
/// let iov = [IoSlice::new(data)];
/// let (_r, w) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
/// let _ = vmsplice(w.as_fd(), &iov, SpliceFlags::empty());
/// ```
pub fn vmsplice(
    fd: BorrowedFd<'_>,
    iov: &[IoSlice<'_>],
    flags: SpliceFlags,
) -> Result<usize, Errno> {
    let iov_ptr: *const IoSlice<'_> = iov.as_ptr();
    // SAFETY:
    // - vmsplice(2) lit les iovec décrits par `iov_ptr`/`iov_len` pour
    //   transférer des données userspace dans un pipe kernel.
    // - Chaque IoSlice est #[repr(C)] compatible avec `struct iovec` Linux.
    // - Les buffers pointés par les IoSlice doivent rester valides et
    //   immuables pour la durée du syscall (garantit par la durée de vie
    //   de la référence &[IoSlice<'_>]).
    // - fd est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_vmsplice(fd.as_raw_fd(), iov_ptr as u64, iov.len(), flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts : read / write (pour eventfd)
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_read(fd: i32, buffer: u64, count: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (x86_64 = 0). Le kernel écrit `count` octets à
    // l'adresse `buffer`. L'appelant garantit que `buffer` est valide pour
    // `count` octets en écriture. Clobbers RCX + R11 (ABI syscall x86_64).
    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_read(fd: i32, buffer: u64, count: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (aarch64 = 63). Numéro en X8, args en X0..X2, retour en X0.
    // Le kernel écrit `count` octets à `buffer`.
    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(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_write(fd: i32, buffer: u64, count: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_write (x86_64 = 1). Le kernel lit `count` octets depuis
    // l'adresse `buffer`. L'appelant garantit que `buffer` est valide pour
    // `count` octets en lecture. `readonly` serait incorrect (le syscall
    // avance la position du fd côté kernel), donc on n'utilise pas `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 1_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_write(fd: i32, buffer: u64, count: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_write (aarch64 = 64). Numéro en X8, args en X0..X2, retour en X0.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 64_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") count,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts : eventfd2, pipe2, splice, tee, vmsplice
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_eventfd2(initial: u32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_eventfd2 (x86_64 = 290). Scalaires seulement ; pas
    // d'accès mémoire utilisateur. `readonly` correct.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 290_i64,
            in("rdi") i64::from(initial),
            in("rsi") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_eventfd2(initial: u32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_eventfd2 (aarch64 = 19). Scalaires ; `readonly` correct.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 19_i64,
            inout("x0") i64::from(initial) => ret,
            in("x1") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_pipe2(fds_ptr: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_pipe2 (x86_64 = 293). Le kernel écrit 2 × sizeof(int)
    // octets à `fds_ptr`. L'appelant garantit la validité du pointeur.
    // **Pas de `readonly`** : le kernel écrit dans la mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 293_i64,
            in("rdi") fds_ptr,
            in("rsi") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_pipe2(fds_ptr: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_pipe2 (aarch64 = 59). Le kernel écrit les deux fd à `fds_ptr`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 59_i64,
            inout("x0") fds_ptr => ret,
            in("x1") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_splice(
    fd_in: i32,
    offset_in: u64,
    fd_out: i32,
    offset_out: u64,
    length: usize,
    flags: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_splice (x86_64 = 275). Le kernel peut lire/écrire
    // optionnellement via `offset_in`/`offset_out` si non nuls.
    // **Pas de `readonly`** : le kernel peut modifier les offsets.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 275_i64,
            in("rdi") i64::from(fd_in),
            in("rsi") offset_in,
            in("rdx") i64::from(fd_out),
            in("r10") offset_out,
            in("r8") length,
            in("r9") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_splice(
    fd_in: i32,
    offset_in: u64,
    fd_out: i32,
    offset_out: u64,
    length: usize,
    flags: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_splice (aarch64 = 76). Args en X0..X5.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 76_i64,
            inout("x0") i64::from(fd_in) => ret,
            in("x1") offset_in,
            in("x2") i64::from(fd_out),
            in("x3") offset_out,
            in("x4") length,
            in("x5") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_tee(fd_in: i32, fd_out: i32, length: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tee (x86_64 = 276). Opère uniquement sur les pipe
    // buffers kernel ; pas d'accès mémoire utilisateur.
    // `readonly` serait inexact (modifie l'état interne des pipes).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 276_i64,
            in("rdi") i64::from(fd_in),
            in("rsi") i64::from(fd_out),
            in("rdx") length,
            in("r10") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_tee(fd_in: i32, fd_out: i32, length: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tee (aarch64 = 77). Args en X0..X3.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 77_i64,
            inout("x0") i64::from(fd_in) => ret,
            in("x1") i64::from(fd_out),
            in("x2") length,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_vmsplice(fd: i32, iov: u64, iov_len: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_vmsplice (x86_64 = 278). Le kernel lit les iovec à
    // `iov` pour transférer des données userspace dans le pipe.
    // **Pas de `readonly`** : les données peuvent être consommées (mode
    // GIFT donne la propriété des pages au kernel).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 278_i64,
            in("rdi") i64::from(fd),
            in("rsi") iov,
            in("rdx") iov_len,
            in("r10") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_vmsplice(fd: i32, iov: u64, iov_len: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_vmsplice (aarch64 = 75). Args en X0..X3.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 75_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") iov,
            in("x2") iov_len,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────

#[cfg(test)]
#[cfg(target_os = "linux")]
mod tests {
    use super::*;

    /// `eventfd2` crée un FD avec CLOEXEC sans paniquer.
    #[test]
    fn eventfd2_cloexec_creates_fd() {
        let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2 avec CLOEXEC");
        // Le FD est valide si on peut en obtenir une vue empruntée.
        let _borrowed = efd.as_fd();
    }

    /// `EventFd::write` puis `EventFd::read` retournent la même valeur.
    #[test]
    fn eventfd_write_read_roundtrip() {
        let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2");
        efd.write(42).expect("write 42");
        let val = efd.read().expect("read");
        assert_eq!(val, 42, "la valeur lue doit être 42");
    }

    /// Plusieurs écritures s'accumulent : le compteur est additif.
    #[test]
    fn eventfd_write_accumulates() {
        let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2");
        efd.write(10).expect("write 10");
        efd.write(5).expect("write 5");
        let val = efd.read().expect("read");
        // En mode normal, read retourne la somme et remet à 0.
        assert_eq!(val, 15, "compteur doit être 15 (10+5)");
    }

    /// `eventfd2` avec valeur initiale non nulle.
    #[test]
    fn eventfd2_initial_value() {
        let efd = eventfd2(7, EventFdFlags::CLOEXEC).expect("eventfd2 avec initial=7");
        let val = efd.read().expect("read");
        assert_eq!(val, 7, "valeur initiale doit être 7");
    }

    /// `EventFd::into_fd` transfère bien l'ownership.
    #[test]
    fn eventfd_into_fd_transfers_ownership() {
        let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2");
        let _owned: OwnedFd = efd.into_fd();
        // `efd` est consommé ; `_owned` sera fermé à la fin du scope.
    }

    /// `pipe2` crée deux FDs valides.
    #[test]
    fn pipe2_creates_valid_fds() {
        let (read_fd, write_fd) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
        // Les FDs sont valides si les BorrowedFd sont obtenables.
        let _r = read_fd.as_fd();
        let _w = write_fd.as_fd();
    }

    /// `splice` transfère des données de pipe à pipe.
    #[test]
    fn splice_pipe_to_pipe() {
        let (r1, w1) = pipe2(PipeFlags::CLOEXEC).expect("pipe2 source");
        let (r2, w2) = pipe2(PipeFlags::CLOEXEC).expect("pipe2 dest");

        // Écrit "hello" dans w1 via vmsplice.
        let data = b"hello";
        let iov = [IoSlice::new(data)];
        let written = vmsplice(w1.as_fd(), &iov, SpliceFlags::empty()).expect("vmsplice");
        assert_eq!(written, 5, "vmsplice doit transférer 5 octets");

        // splice de r1 vers w2.
        let transferred =
            splice(r1.as_fd(), None, w2.as_fd(), None, 5, SpliceFlags::empty()).expect("splice");
        assert_eq!(transferred, 5, "splice doit transférer 5 octets");

        // Lit le résultat depuis r2 via read(2) direct.
        let mut buffer = [0u8; 5];
        let buf_ptr: *mut u8 = buffer.as_mut_ptr();
        // SAFETY: buffer est local valide pour 5 octets.
        let n = unsafe { raw_syscall_read(r2.as_raw_fd(), buf_ptr as u64, 5) };
        assert_eq!(n, 5);
        assert_eq!(&buffer, b"hello");
    }

    /// `tee` copie sans consommer les données source.
    #[test]
    fn tee_copies_without_consuming() {
        let (r1, w1) = pipe2(PipeFlags::CLOEXEC).expect("pipe2 source");
        let (r2, w2) = pipe2(PipeFlags::CLOEXEC).expect("pipe2 dest");

        // Écrit "world" dans w1.
        let data = b"world";
        let iov = [IoSlice::new(data)];
        let written = vmsplice(w1.as_fd(), &iov, SpliceFlags::empty()).expect("vmsplice");
        assert_eq!(written, 5);

        // tee de r1 vers w2 : copie sans consommer.
        let copied = tee(r1.as_fd(), w2.as_fd(), 5, SpliceFlags::empty()).expect("tee");
        assert_eq!(copied, 5, "tee doit copier 5 octets");

        // Les données sont disponibles dans r2.
        let mut buf2 = [0u8; 5];
        // SAFETY: `buf2` est un tableau local de 5 octets ; on passe son pointeur et
        // la taille exacte (5) — le kernel y écrit au plus 5 octets.
        let n2 = unsafe { raw_syscall_read(r2.as_raw_fd(), buf2.as_mut_ptr() as u64, 5) };
        assert_eq!(n2, 5);
        assert_eq!(&buf2, b"world");

        // Et encore disponibles dans r1 (tee ne consomme pas).
        let mut buf1 = [0u8; 5];
        // SAFETY: `buf1` est un tableau local de 5 octets ; on passe son pointeur et
        // la taille exacte (5) — le kernel y écrit au plus 5 octets.
        let n1 = unsafe { raw_syscall_read(r1.as_raw_fd(), buf1.as_mut_ptr() as u64, 5) };
        assert_eq!(n1, 5);
        assert_eq!(&buf1, b"world");
    }

    /// `vmsplice` écrit dans un pipe et les données sont lisibles.
    #[test]
    fn vmsplice_writes_to_pipe() {
        let (r, w) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
        let data = b"vmsplice-test";
        let iov = [IoSlice::new(data)];

        let written = vmsplice(w.as_fd(), &iov, SpliceFlags::empty()).expect("vmsplice");
        assert_eq!(written, data.len(), "vmsplice doit écrire tous les octets");

        let mut buffer = [0u8; 13];
        // SAFETY: `buffer` est un tableau local de 13 octets ; on passe son pointeur
        // et la taille exacte (13) — le kernel y écrit au plus 13 octets.
        let n = unsafe { raw_syscall_read(r.as_raw_fd(), buffer.as_mut_ptr() as u64, 13) };
        assert_eq!(n, 13);
        assert_eq!(&buffer, b"vmsplice-test");
    }

    /// `vmsplice` avec plusieurs iovec.
    #[test]
    fn vmsplice_multiple_iov() {
        let (r, w) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
        let a = b"foo";
        let b_data = b"bar";
        let iov = [IoSlice::new(a), IoSlice::new(b_data)];

        let written = vmsplice(w.as_fd(), &iov, SpliceFlags::empty()).expect("vmsplice multi");
        assert_eq!(written, 6, "6 octets en tout");

        let mut buffer = [0u8; 6];
        // SAFETY: `buffer` est un tableau local de 6 octets ; on passe son pointeur
        // et la taille exacte (6) — le kernel y écrit au plus 6 octets.
        let n = unsafe { raw_syscall_read(r.as_raw_fd(), buffer.as_mut_ptr() as u64, 6) };
        assert_eq!(n, 6);
        assert_eq!(&buffer, b"foobar");
    }

    // Les bras `Some(p)` des offsets de `splice` sont couverts de façon
    // déterministe par `splice_with_some_offsets_on_invalid_fds_returns_ebadf`
    // (ci-dessus) ; le chemin succès (offset `None`) l'est par
    // `splice_pipe_to_pipe`. Pas besoin d'un test memfd conditionnel.

    /// Helper interne pour memfd_create dans les tests (distinct de raw_syscall_*
    /// du module parent, qui n'est pas `pub` mais accessible dans ce sous-module).
    #[cfg(target_arch = "x86_64")]
    unsafe fn test_memfd_create(nr: i64, name: u64, flags: u64) -> i64 {
        let ret: i64;
        // SAFETY: memfd_create (numéro `nr`). `name` pointe une chaîne C valide et
        // NUL-terminée (lue par le kernel) ; retourne un FD ≥ 0 ou un errno négatif.
        unsafe {
            core::arch::asm!(
                "syscall",
                in("rax") nr,
                in("rdi") name,
                in("rsi") flags,
                lateout("rax") ret,
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    #[cfg(target_arch = "aarch64")]
    unsafe fn test_memfd_create(nr: i64, name: u64, flags: u64) -> i64 {
        let ret: i64;
        // SAFETY: memfd_create (numéro `nr`). `name` pointe une chaîne C valide et
        // NUL-terminée (lue par le kernel) ; retourne un FD ≥ 0 ou un errno négatif.
        unsafe {
            core::arch::asm!(
                "svc 0",
                in("x8") nr,
                inout("x0") name => ret,
                in("x1") flags,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    // ── eventfd error path ─────────────────────────────────────────────────

    #[test]
    fn eventfd2_read_empty_nonblocking_returns_eagain() {
        use air_sys_types::Errno;
        // Couvre la branche d'erreur (`ret < 0`) de `EventFd::read` sans fd
        // invalide : un eventfd non bloquant au compteur 0 renvoie `EAGAIN`
        // (la lecture bloquerait). FD valide → pas de double close ni de
        // course de réutilisation de fd entre threads de test.
        let efd = eventfd2(0, EventFdFlags::CLOEXEC | EventFdFlags::NONBLOCK).expect("eventfd2");
        let err = efd.read().unwrap_err();
        assert_eq!(err, Errno::EAGAIN);
    }

    #[test]
    fn eventfd_write_u64_max_returns_einval() {
        // Couvre la branche d'erreur (`ret < 0`) de `EventFd::write` : la
        // valeur sentinelle `u64::MAX` (débordement) est rejetée par le
        // kernel avec EINVAL (cf. man eventfd(2)).
        let efd = eventfd2(0, EventFdFlags::CLOEXEC).expect("eventfd2");
        let err = efd.write(u64::MAX).unwrap_err();
        assert_eq!(err, Errno::EINVAL);
    }

    #[test]
    fn splice_with_some_offsets_on_invalid_fds_returns_ebadf() {
        // Couvre les bras `Some(p)` des match `offset_in`/`offset_out` de `splice`
        // (évalués AVANT le syscall, donc atteints même si l'appel échoue).
        // Deux fd au-delà de toute table de fd → EBADF déterministe, sans
        // dépendre de `memfd_create`.
        let mut offset_in: u64 = 0;
        let mut offset_out: u64 = 0;
        // SAFETY: borrow_raw ne crée que des vues ; aucun fd n'est fermé.
        let fin = unsafe { BorrowedFd::borrow_raw(i32::MAX) };
        let fout = unsafe { BorrowedFd::borrow_raw(i32::MAX) };
        let err = splice(
            fin,
            Some(&mut offset_in),
            fout,
            Some(&mut offset_out),
            4,
            SpliceFlags::empty(),
        )
        .unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn vmsplice_on_invalid_fd_returns_ebadf() {
        // Couvre la branche d'erreur (`ret < 0`) de `vmsplice` : un fd
        // au-delà de toute limite (`i32::MAX`) n'est pas ouvert → EBADF.
        let data = [b'x'];
        let iov = [IoSlice::new(&data)];
        // SAFETY: borrow_raw ne crée qu'une vue ; aucun fd n'est fermé. Le
        // fd i32::MAX dépasse toute table de fd → EBADF déterministe.
        let fd = unsafe { BorrowedFd::borrow_raw(i32::MAX) };
        let err = vmsplice(fd, &iov, SpliceFlags::empty()).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    // 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 _ = 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 _ = errno_from_negative_syscall_ret(-5000);
    }

    // ── tee error path ────────────────────────────────────────────────────

    #[test]
    fn tee_einval_on_non_pipe() {
        use air_sys_types::Errno;
        #[cfg(target_arch = "x86_64")]
        let nr_memfd: i64 = 319;
        #[cfg(target_arch = "aarch64")]
        let nr_memfd: i64 = 279;
        let name = c"ipc-tee-test";
        // SAFETY: `name` est une chaîne C statique valide et NUL-terminée ; le helper
        // `test_memfd_create` ne lit que ce pointeur (aucune écriture mémoire).
        let ret = unsafe { test_memfd_create(nr_memfd, name.as_ptr() as u64, 1) };
        if ret < 0 {
            return;
        }
        #[allow(clippy::cast_possible_truncation)]
        // SAFETY: `ret >= 0` ici, donc c'est un FD fraîchement créé par memfd_create,
        // non possédé ailleurs : on en prend la propriété exclusive.
        let fd = unsafe { OwnedFd::from_raw_fd(ret as i32) };

        let (_, w) = pipe2(PipeFlags::CLOEXEC).expect("pipe2");
        // tee avec un non-pipe comme source doit retourner EINVAL.
        let err = tee(fd.as_fd(), w.as_fd(), 4, SpliceFlags::empty()).unwrap_err();
        assert_eq!(err, Errno::EINVAL);
    }
}