air_sys_syscall/

signal.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 `signal`.
//!
//! Cf. `docs/specs/layer-0/family-signal.md` et `ADR-020-strategie-signaux`.
//!
//! Périmètre :
//! - Sous-section 1 (signalfd + masques) : [`signalfd_create`],
//!   [`signalfd_create_blocking`], [`SignalFd::read`],
//!   [`SignalFd::update_mask`], [`block_signals`], [`unblock_signals`],
//!   [`set_signal_mask`], [`current_signal_mask`], [`wait_for_signal`].
//! - Sous-section 2 (envoi) : [`kill`], [`tgkill`], [`rt_sigqueueinfo`].
//! - Sous-section 3 (sigaction restreint FAUTES) : sous-module
//!   [`synchronous_handler`] avec [`synchronous_handler::install_fatal_handler`]
//!   et [`synchronous_handler::restore_handler`] (handler **inerte** ; le noyau
//!   force l'action par défaut sur les 4 fautes, ADR-020).
//! - Sous-section 4 (sigaction async NON-faute, ADR-066) : sous-module
//!   [`async_handler`] avec [`async_handler::install`]/[`async_handler::restore`]
//!   (handler **réellement installé** — le noyau appelle le handler C à la
//!   délivrance d'un signal gérable ; trampoline `rt_sigreturn` fourni sur
//!   x86_64), et [`rt_sigpending`] (ensemble des signaux pendants).

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

use air_sys_types::{
    AltStack, Errno, Pid, Signal, SignalFdFlags, SignalFdInfo, SignalInfo, SignalMask, Tid,
};

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

// ─────────────────────────────────────────────────────────────────────────
// SignalFd — wrapper RAII opaque autour d'un signalfd kernel.
// ─────────────────────────────────────────────────────────────────────────

/// FD `signalfd` (cf. `signalfd4(2)`). Drop ferme le FD via [`OwnedFd`].
#[derive(Debug)]
pub struct SignalFd(OwnedFd);

impl SignalFd {
    /// Construit depuis un `OwnedFd` déjà ouvert sur un signalfd.
    #[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`.
    #[must_use]
    pub fn into_fd(self) -> OwnedFd {
        self.0
    }

    /// Lit le prochain événement signal disponible sur le `signalfd`.
    ///
    /// Bloque si le FD est en mode bloquant (par défaut) et qu'aucun
    /// signal n'est pendant ; retourne immédiatement avec
    /// [`Errno::EAGAIN`] si le FD est en mode `NONBLOCK` et aucun
    /// signal n'est disponible.
    ///
    /// # Errors
    ///
    /// - [`Errno::EAGAIN`] : mode non-bloquant, aucun signal pendant.
    /// - [`Errno::EINTR`] : interrompu par un signal (remonté tel quel
    ///   per convention 2 ADR-021).
    pub fn read(&self) -> Result<SignalFdInfo, Errno> {
        let mut buffer = [0_u8; SIGNALFD_SIGINFO_SIZE];
        let ptr: *mut u8 = buffer.as_mut_ptr();
        let length = u64::try_from(SIGNALFD_SIGINFO_SIZE)
            .expect("buffer fixe SIGNALFD_SIGINFO_SIZE tient en u64");
        // SAFETY:
        // - SYS_read sur un signalfd valide écrit exactement 128 octets
        //   dans `buffer` (taille du `signalfd_siginfo`) ou retourne une
        //   erreur. `buffer` est local valide pour la durée du syscall.
        let ret = unsafe { raw_syscall_read(self.0.as_raw_fd(), ptr as u64, length) };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        // Lecture partielle d'un signalfd impossible (atomique côté kernel) ;
        // ret == 128 ou erreur.
        debug_assert_eq!(ret, i64::from(SIGNALFD_SIGINFO_SIZE_I32));
        Ok(parse_signalfd_siginfo(&buffer))
    }

    /// Met à jour le mask de signaux capturés par ce `signalfd`.
    ///
    /// Équivalent à un nouvel appel `signalfd4(self, &mask, ...)` qui
    /// remplace atomiquement le mask interne du FD.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : mask invalide.
    pub fn update_mask(&mut self, mask: &SignalMask) -> Result<(), Errno> {
        let bits = mask.bits();
        let mask_ptr: *const u64 = &bits;
        // SAFETY: signalfd4(fd_existant, &mask, sizeof(u64), 0). Le
        // kernel lit 8 octets à mask_ptr (sigset_t kernel = 1 mot sur
        // archs où _NSIG = 64). Flags=0 préserve les flags existants
        // (NONBLOCK/CLOEXEC) du FD.
        let ret = unsafe {
            raw_syscall_signalfd4(self.0.as_raw_fd(), mask_ptr as u64, SIGSET_SIZE_U64, 0_i32)
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }
}

// ─────────────────────────────────────────────────────────────────────────
// signalfd_create / signalfd_create_blocking.
// ─────────────────────────────────────────────────────────────────────────

/// Crée un `signalfd` pour les signaux du `mask`.
///
/// Le drapeau `CLOEXEC` est **toujours** ajouté par le wrapper (cf.
/// discipline universelle couche 0 : tous les FDs créés par Air sont
/// `O_CLOEXEC`).
///
/// **Important.** Créer un signalfd ne suffit pas à empêcher la
/// délivrance normale des signaux du `mask` (handler ou comportement
/// par défaut). Il faut **aussi** bloquer ces signaux dans le mask du
/// thread via [`block_signals`]. Le helper [`signalfd_create_blocking`]
/// combine les deux étapes.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : mask invalide.
/// - `EMFILE`/`ENFILE` (stub Errno) : limites de FDs atteintes.
pub fn signalfd_create(mask: &SignalMask, flags: SignalFdFlags) -> Result<SignalFd, Errno> {
    let bits = mask.bits();
    let mask_ptr: *const u64 = &bits;
    let kernel_flags = flags.bits() | SignalFdFlags::CLOEXEC.bits();
    // SAFETY: signalfd4(-1, &mask, sizeof(u64), flags) crée un nouveau
    // FD ; le kernel lit 8 octets à mask_ptr. Pas d'écriture en mémoire
    // utilisateur. -1 = créer un nouveau (vs réutiliser un existant).
    let ret =
        unsafe { raw_syscall_signalfd4(-1_i32, mask_ptr as u64, SIGSET_SIZE_U64, kernel_flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let new_fd = ret as i32;
    // SAFETY: kernel vient de transférer la propriété d'un fd valide.
    let owned = unsafe { OwnedFd::from_raw_fd(new_fd) };
    Ok(SignalFd::from_owned_fd(owned))
}

/// Helper canonique : bloque les signaux du `mask` dans le thread
/// appelant **puis** crée un `signalfd` pour ces mêmes signaux.
///
/// Pattern recommandé par `family-signal.md` et ADR-020.
///
/// **Note.** Le blocage est PER-THREAD ; il s'applique au thread qui
/// appelle cette fonction. À combiner avec un `MaskGuard` RAII dans le
/// code de test pour ne pas contaminer les threads/tests suivants.
///
/// # Errors
///
/// - Toutes les erreurs de [`block_signals`] et [`signalfd_create`].
pub fn signalfd_create_blocking(
    mask: &SignalMask,
    flags: SignalFdFlags,
) -> Result<SignalFd, Errno> {
    let _ = block_signals(mask)?;
    signalfd_create(mask, flags)
}

// ─────────────────────────────────────────────────────────────────────────
// Masques de signaux : rt_sigprocmask wrappers.
// ─────────────────────────────────────────────────────────────────────────

const SIG_BLOCK: i32 = 0;
const SIG_UNBLOCK: i32 = 1;
const SIG_SETMASK: i32 = 2;
const SIGSET_SIZE_U64: u64 = 8;

/// Bloque les signaux du `mask` dans le mask courant du thread (union).
/// Retourne l'ancien mask (avant modification).
///
/// `SIGKILL` et `SIGSTOP` sont silencieusement ignorés par le kernel
/// (non bloquables).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn block_signals(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_BLOCK, Some(mask))
}

/// Déblocque les signaux du `mask` dans le mask courant du thread
/// (différence). Retourne l'ancien mask.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn unblock_signals(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_UNBLOCK, Some(mask))
}

/// Remplace **totalement** le mask de signaux du thread par `mask`.
/// Retourne l'ancien mask.
///
/// Usage typique : restauration du mask original via un guard RAII.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn set_signal_mask(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_SETMASK, Some(mask))
}

/// Lit le mask de signaux courant sans modification.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : ne se produit pas en pratique.
pub fn current_signal_mask() -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_SETMASK, None)
}

/// Helper interne : encapsule l'appel `rt_sigprocmask` quelle que soit
/// l'opération (SIG_BLOCK/UNBLOCK/SETMASK). `set = None` signifie
/// « lecture seule ».
fn rt_sigprocmask(how: i32, set: Option<&SignalMask>) -> Result<SignalMask, Errno> {
    let set_bits: u64 = set.map_or(0, |m| m.bits());
    let set_ptr: u64 = match set {
        Some(_) => {
            let p: *const u64 = &set_bits;
            p as u64
        }
        None => 0,
    };
    let mut old_bits: u64 = 0;
    let old_ptr: *mut u64 = &mut old_bits;
    // SAFETY: rt_sigprocmask lit `set` si non-null (8 octets), écrit
    // `oldset` (8 octets). Les deux pointeurs sont locaux ; sigsetsize=8
    // correspond à la taille kernel `sigset_t` sur x86_64/aarch64.
    let ret = unsafe { raw_syscall_rt_sigprocmask(how, set_ptr, old_ptr as u64, SIGSET_SIZE_U64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(SignalMask::from_bits(old_bits))
}

/// Lit l'ensemble des signaux **pendants** (`rt_sigpending(2)`).
///
/// Retourne le [`SignalMask`] des signaux **en attente** de délivrance pour le
/// thread appelant (union des pendants par-thread et par-process), c.-à-d.
/// générés mais pas encore délivrés — typiquement parce qu'ils sont **bloqués**
/// dans le masque courant. Brique de `sigpending(3)` de la libc (via la couche 1
/// `air-signal`).
///
/// **Kernel = bible** : cette fonction **expose** l'état pendant du noyau, elle
/// n'en maintient aucun (ADR-064 §6).
///
/// # Errors
///
/// - [`Errno::EFAULT`] : inatteignable via cette API (le buffer est un local
///   vivant). En pratique `rt_sigpending` ne peut pas échouer avec un
///   `sigsetsize` correct (fixé à 8 par le wrapper).
pub fn rt_sigpending() -> Result<SignalMask, Errno> {
    let mut pending_bits: u64 = 0;
    let set_ptr: *mut u64 = &mut pending_bits;
    // SAFETY: rt_sigpending écrit 8 octets (sigset_t kernel = 1 mot sur
    // x86_64/aarch64) à `set_ptr`, local vivant pour la durée de l'appel.
    // sigsetsize=8 correspond à la taille kernel `sigset_t`.
    let ret = unsafe { raw_syscall_rt_sigpending(set_ptr as u64, SIGSET_SIZE_U64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(SignalMask::from_bits(pending_bits))
}

// ─────────────────────────────────────────────────────────────────────────
// wait_for_signal — helper signalfd temporaire.
// ─────────────────────────────────────────────────────────────────────────

/// Attend l'arrivée d'un signal du `mask`, avec timeout optionnel.
///
/// Implémentation : crée un `signalfd` temporaire pour `mask`, bloque
/// ces signaux dans le thread, lit l'événement (bloquant ou avec
/// timeout via `ppoll`).
///
/// **Note périmètre.** Cette PR n'implémente que la variante
/// `timeout = None` (lecture bloquante via `read` sur le signalfd) ;
/// la variante `Some(duration)` nécessite `ppoll` qui sera ajouté dans
/// la PR `family-time` (timers). En `Some(_)`, retourne actuellement
/// [`Errno::EINVAL`] — l'API publique reste conforme spec mais la
/// branche timeout est documentée comme TODO.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `timeout.is_some()` (non encore implémenté
///   sans wrapper `ppoll`).
/// - Toutes les erreurs de [`signalfd_create_blocking`] et de
///   [`SignalFd::read`].
pub fn wait_for_signal(
    mask: &SignalMask,
    timeout: Option<Duration>,
) -> Result<SignalFdInfo, Errno> {
    if timeout.is_some() {
        return Err(Errno::EINVAL);
    }
    let sfd = signalfd_create_blocking(mask, SignalFdFlags::empty())?;
    sfd.read()
}

// ─────────────────────────────────────────────────────────────────────────
// Envoi de signaux : kill, tgkill, rt_sigqueueinfo.
// ─────────────────────────────────────────────────────────────────────────

/// Envoie `signal` au processus `pid`.
///
/// `signal = None` correspond au "signal 0" Linux : test d'existence du
/// processus sans envoyer de signal effectif (cf. convention 1
/// ADR-021).
///
/// **Recommandation Air.** Pour un processus enfant dont on possède un
/// `PidFd`, préférer [`pidfd_send_signal`](crate::process::pidfd_send_signal)
/// — pas de race sur le PID recyclé.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : signal invalide.
/// - [`Errno::EPERM`] : permissions insuffisantes.
/// - [`Errno::ESRCH`] : processus inexistant.
pub fn kill(pid: Pid, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // SAFETY: kill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_kill(pid.as_raw(), sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` à **tout un groupe de processus** (`kill(2)` avec un `pid` négatif) —
/// **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc `killpg` (le type positif-seul [`Pid`] interdit d'exprimer le `pid`
/// négatif « groupe » via [`kill`]). `group = None` cible le **groupe de l'appelant**
/// (sentinelle kernel `0` typée en `Option`, ADR-021 conv. 1) ; `Some(g)` cible le groupe
/// `g` (le kernel reçoit `-g`). `signal = None` = test d'existence.
pub fn kill_process_group(group: Option<Pid>, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // `None` ⇒ `0` (groupe de l'appelant) ; `Some(g)` ⇒ `-g` (g > 0 ⇒ pas de débordement).
    let target = group.map_or(0_i32, |g| g.as_raw().wrapping_neg());
    // SAFETY: kill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_kill(target, sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Installe (`new`) et/ou interroge (`old`) la **pile de signal alternative** du thread
/// (`sigaltstack(2)`) — **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc. `new = None` ne change rien ; `old = None` ne rapporte rien.
/// Requis par `std` (traitement d'un `SIGSEGV` de débordement de pile sur pile dédiée).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `new.flags` invalide, ou `new.size < MINSIGSTKSZ`.
/// - [`Errno::EPERM`] : tentative de désactivation alors que le thread est **sur** la pile
///   alternative (`SS_ONSTACK`).
/// - [`Errno::EFAULT`] : `new`/`old` hors de l'espace adressable (impossible via `&`).
pub fn sigaltstack(new: Option<&AltStack>, old: Option<&mut AltStack>) -> Result<(), Errno> {
    let new_ptr = new.map_or(0_u64, |stack| core::ptr::from_ref(stack) as u64);
    let old_ptr = old.map_or(0_u64, |stack| core::ptr::from_mut(stack) as u64);
    // SAFETY: le kernel **lit** `*new` (24 octets, `stack_t`) si `new_ptr != 0`, et
    // **écrit** `*old` (24 octets) si `old_ptr != 0` ; les deux proviennent de références
    // Rust valides et correctement dimensionnées (`AltStack` est `#[repr(C)]` = `stack_t`).
    let ret = unsafe { raw_syscall_sigaltstack(new_ptr, old_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` au thread `tid` du process `tgid`.
///
/// Plus précis que [`kill`] : cible un thread spécifique d'un processus
/// multi-thread. Indispensable pour les patterns de signaling
/// intra-process déterministes (notamment dans les tests qui veulent
/// délivrer un signal à un thread précis sans contaminer les autres
/// workers).
///
/// `signal = None` : test d'existence (convention 1 ADR-021).
///
/// # Errors
///
/// - Mêmes que [`kill`].
pub fn tgkill(tgid: Pid, tid: Tid, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // SAFETY: tgkill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_tgkill(tgid.as_raw(), tid.as_raw(), sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` au processus `pid` avec un payload `siginfo_t`
/// (pattern SI_QUEUE — `sigqueue(3)` côté userspace).
///
/// `info` est construit côté appelant via
/// [`SignalInfo::new_queue`](air_sys_types::SignalInfo::new_queue). Le
/// kernel écrase `si_signo` avec `signal` à la délivrance.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : signal invalide.
/// - [`Errno::EPERM`] : tentative d'envoi cross-process avec un
///   `si_code` non autorisé (impossible via notre constructeur qui
///   fixe `si_code = SI_QUEUE`).
/// - [`Errno::ESRCH`] : processus inexistant.
pub fn rt_sigqueueinfo(pid: Pid, signal: Signal, info: &SignalInfo) -> Result<(), Errno> {
    let info_ptr: *const u8 = info.as_bytes().as_ptr();
    // SAFETY: rt_sigqueueinfo(2) lit 128 octets à `info_ptr` (taille
    // siginfo_t Linux côté x86_64/aarch64). Pas d'écriture user.
    let ret =
        unsafe { raw_syscall_rt_sigqueueinfo(pid.as_raw(), signal.as_raw(), info_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// signalfd_siginfo : parsing du buffer kernel vers SignalFdInfo.
// ─────────────────────────────────────────────────────────────────────────

const SIGNALFD_SIGINFO_SIZE: usize = 128;
const SIGNALFD_SIGINFO_SIZE_I32: i32 = 128;

// Offsets dans `struct signalfd_siginfo` (uapi/linux/signalfd.h).
// Identiques x86_64/aarch64.
const SFI_SSI_SIGNO: usize = 0;
const SFI_SSI_ERRNO: usize = 4;
const SFI_SSI_CODE: usize = 8;
const SFI_SSI_PID: usize = 12;
const SFI_SSI_UID: usize = 16;
const SFI_SSI_FD: usize = 20;
const SFI_SSI_TID: usize = 24;
const SFI_SSI_BAND: usize = 28;
const SFI_SSI_OVERRUN: usize = 32;
const SFI_SSI_TRAPNO: usize = 36;
const SFI_SSI_STATUS: usize = 40;
const SFI_SSI_INT: usize = 44;
const SFI_SSI_PTR: usize = 48;
const SFI_SSI_UTIME: usize = 56;
const SFI_SSI_STIME: usize = 64;
const SFI_SSI_ADDR: usize = 72;

fn read_u32(buffer: &[u8], offset: usize) -> u32 {
    u32::from_ne_bytes(
        buffer[offset..offset.saturating_add(4)]
            .try_into()
            .expect("4 octets"),
    )
}

fn read_i32(buffer: &[u8], offset: usize) -> i32 {
    i32::from_ne_bytes(
        buffer[offset..offset.saturating_add(4)]
            .try_into()
            .expect("4 octets"),
    )
}

fn read_u64(buffer: &[u8], offset: usize) -> u64 {
    u64::from_ne_bytes(
        buffer[offset..offset.saturating_add(8)]
            .try_into()
            .expect("8 octets"),
    )
}

fn parse_signalfd_siginfo(buffer: &[u8; SIGNALFD_SIGINFO_SIZE]) -> SignalFdInfo {
    let signo = read_u32(buffer, SFI_SSI_SIGNO);
    // Le kernel garantit `signo` > 0 pour tout événement signalfd réel.
    let signal = Signal::try_from_raw(i32::try_from(signo).expect("ssi_signo fit en i32"))
        .expect("kernel : signalfd événement avec signo > 0");

    let pid_raw = read_u32(buffer, SFI_SSI_PID);
    // `ssi_pid == 0` quand le signal vient du kernel (SI_KERNEL) ; on
    // applique la convention 1 ADR-021 et retourne `None` dans ce cas.
    let pid = if pid_raw == 0 {
        None
    } else {
        Some(
            Pid::try_from_raw(i32::try_from(pid_raw).expect("ssi_pid fit en i32"))
                .expect("ssi_pid > 0 ici"),
        )
    };

    SignalFdInfo {
        signal,
        errno: read_i32(buffer, SFI_SSI_ERRNO),
        code: read_i32(buffer, SFI_SSI_CODE),
        pid,
        uid: read_u32(buffer, SFI_SSI_UID),
        fd: read_i32(buffer, SFI_SSI_FD),
        timer_id: read_u32(buffer, SFI_SSI_TID),
        band: read_u32(buffer, SFI_SSI_BAND),
        overrun: read_u32(buffer, SFI_SSI_OVERRUN),
        trap_no: read_u32(buffer, SFI_SSI_TRAPNO),
        status: read_i32(buffer, SFI_SSI_STATUS),
        int: read_i32(buffer, SFI_SSI_INT),
        ptr: read_u64(buffer, SFI_SSI_PTR),
        utime: read_u64(buffer, SFI_SSI_UTIME),
        stime: read_u64(buffer, SFI_SSI_STIME),
        addr: read_u64(buffer, SFI_SSI_ADDR),
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Sous-module synchronous_handler : sigaction restreint (cf. ADR-020).
// ─────────────────────────────────────────────────────────────────────────

pub mod synchronous_handler {
    //! Wrappers `sigaction` **restreints aux 4 signaux synchrones fatals**
    //! (cf. ADR-020).
    //!
    //! L'API entière est `unsafe` : l'appelant doit garantir que le
    //! handler installé respecte la contrainte async-signal-safe
    //! (cf. `man 7 signal-safety`).

    use air_sys_types::Errno;
    use air_sys_types::signal::synchronous_handler::{FatalHandler, FatalSignal, PreviousHandler};

    use super::{SIGSET_SIZE_U64, errno_from_negative_syscall_ret};

    // SA_SIGINFO = 4 (constant ABI Linux, identique x86_64/aarch64).
    const SA_SIGINFO: u64 = 4;

    /// Installe `handler` comme handler du signal fatal `signal`.
    /// Retourne l'ancien handler dans `PreviousHandler` pour pouvoir
    /// restaurer via [`restore_handler`].
    ///
    /// # Safety
    ///
    /// L'appelant doit garantir que `handler` est **async-signal-safe**
    /// (cf. `man 7 signal-safety`). Concrètement : pas de `malloc`, pas
    /// de `printf`, pas de mutex, pas de `Mutex` Rust, pas d'allocations
    /// indirectes (incluant les `format!`). Les appels typiques admis :
    /// `write(STDERR_FILENO, ...)`, opérations `core::sync::atomic`,
    /// `_exit(N)`. Voir l'ADR-020 pour les patterns de crash reporter.
    pub unsafe fn install_fatal_handler(
        signal: FatalSignal,
        handler: FatalHandler,
    ) -> Result<PreviousHandler, Errno> {
        let mut new_sa = KernelSigaction::zeroed();
        new_sa.sa_handler = handler as usize as u64;
        new_sa.sa_flags = SA_SIGINFO;
        // sa_mask = 0 (aucun signal additionnel bloqué pendant le
        // handler). sa_restorer = 0 sur x86_64 → kernel utilise le
        // trampoline VDSO ; absent sur aarch64.

        let mut previous = PreviousHandler::zeroed();
        let new_ptr: *const KernelSigaction = &new_sa;
        let old_ptr: *mut [u8; 32] = previous.as_bytes_mut();

        // SAFETY: rt_sigaction(2). Le kernel lit `new_sa`
        // (KernelSigaction valide, locale) et écrit jusqu'à 32 octets à
        // `old_ptr` (capacité de `PreviousHandler`). sigsetsize=8
        // correspond à la taille kernel `sigset_t`.
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_signal().as_raw(),
                new_ptr as u64,
                old_ptr as u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(previous)
    }

    /// Restaure le handler `previous` pour le signal `signal`.
    ///
    /// # Safety
    ///
    /// `previous` doit avoir été obtenu par un appel précédent à
    /// [`install_fatal_handler`] sur le **même** `signal`. Restaurer un
    /// `PreviousHandler` qui ne provient pas du même signal est
    /// undefined behavior côté kernel.
    pub unsafe fn restore_handler(
        signal: FatalSignal,
        previous: PreviousHandler,
    ) -> Result<(), Errno> {
        let prev_ptr: *const [u8; 32] = previous.as_bytes();
        // SAFETY: rt_sigaction(2). Le kernel lit jusqu'à 32 octets à
        // `prev_ptr` (KernelSigaction est ≤ 32 octets sur x86_64/aarch64).
        // Pas d'écriture (oldset=NULL).
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_signal().as_raw(),
                prev_ptr as u64,
                0_u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// Représentation interne du `struct sigaction` kernel.
    ///
    /// Layout :
    /// - offset 0  : `sa_handler` (pointer, 8 octets)
    /// - offset 8  : `sa_flags` (unsigned long, 8 octets)
    /// - offset 16 : `sa_restorer` (x86_64 uniquement, 8 octets)
    /// - offset 24 (x86_64) ou 16 (aarch64) : `sa_mask` (sigset_t, 8 octets)
    ///
    /// Sur aarch64, `sa_restorer` est absent (le kernel utilise VDSO
    /// pour le retour). On utilise donc deux layouts compatibles avec
    /// le syscall :
    /// - x86_64 : 32 octets.
    /// - aarch64 : 24 octets, paddé à 32 pour uniformiser le buffer
    ///   `PreviousHandler` (les 8 derniers octets sont ignorés par le
    ///   kernel sur aarch64).
    #[repr(C)]
    #[cfg(target_arch = "x86_64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_restorer: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "x86_64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_restorer: 0,
                sa_mask: 0,
            }
        }
    }

    #[repr(C)]
    #[cfg(target_arch = "aarch64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "aarch64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_mask: 0,
            }
        }
    }

    #[cfg(target_arch = "x86_64")]
    #[inline]
    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 `new_sa`
        // (KernelSigaction, 32 octets), écrit `old_sa` (32 octets) si
        // non-null. ABI standard ; pas de `readonly` (écriture sur
        // `*old_sa`).
        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")]
    #[inline]
    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).
        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
    }

    /// Test : KernelSigaction tient dans le buffer 32 octets de
    /// PreviousHandler.
    const _: () = {
        assert!(core::mem::size_of::<KernelSigaction>() <= 32);
    };

    /// Fonction `c_int` utilitaire pour les tests : ne fait rien (handler
    /// vide), mais respecte la signature `FatalHandler`.
    ///
    /// Used by tests. Marked async-signal-safe (no allocation, no I/O,
    /// just returns).
    ///
    /// # Safety
    ///
    /// Trivially safe : no operations.
    #[cfg(test)]
    pub(super) unsafe extern "C" fn noop_handler(
        _signum: core::ffi::c_int,
        _info: *mut air_sys_types::signal::synchronous_handler::SignalInfo,
        _context: *mut core::ffi::c_void,
    ) {
        // Vide. Trivially async-signal-safe.
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Sous-module async_handler : rt_sigaction NON-faute réel (cf. ADR-066).
// ─────────────────────────────────────────────────────────────────────────

// Trampoline `rt_sigreturn` pour x86_64. À la fin d'un handler **non-faute**, le
// noyau ne revient PAS directement au code interrompu : il saute à l'adresse
// `sa_restorer`, dont la seule mission est d'invoquer `rt_sigreturn` (NR 15) pour
// restaurer le contexte pré-signal empilé par le noyau (sigframe). Sur x86_64 la
// libc/`std` fournit ce trampoline ; sans libc (Air), on le fournit nous-mêmes.
// Sur aarch64, le noyau route le retour par le VDSO — **aucun** `sa_restorer`.
//
// SAFETY: le corps asm n'est **jamais** appelé depuis Rust ; c'est le **noyau**
// qui y saute à la fin du handler, avec `%rsp` pointant sur le sigframe. Il ne
// fait qu'exécuter `rt_sigreturn` (`mov $15, %rax; syscall`), syscall qui ne
// retourne pas (il restaure le contexte). Aucun prologue/épilogue (pas de cadre
// de pile), aucun accès mémoire propre : conforme au contrat ABI de `sa_restorer`.
// Liaison **`.weak`** (et non `.globl`) : sur la cible `*-unknown-linux-air`
// (std sur PAL safe, `-Z build-std`), `air-sys-syscall` est compilé **deux fois**
// dans un même exécutable — une instance tirée DANS `std` (le PAL couche 1 via
// `rustc-dep-of-std`) et une instance de l'arbre applicatif (ex. `air-account` →
// `air-filesystem` → `air-sys-syscall`). Un symbole à **nom fixe** (`#[no_mangle]`/
// `global_asm`) serait alors **défini deux fois** ⇒ `rust-lld: duplicate symbol`.
// `.weak` autorise la **coalescence** : les deux définitions étant **identiques**
// (même corps asm), l'éditeur de liens en garde une, sans ambiguïté. Sur les cibles
// mono-instance (`*-linux-gnu`, barrière/CI) il n'y a **qu'une** définition ⇒
// comportement **inchangé** (un symbole faible référencé n'est jamais éliminé).
#[cfg(target_arch = "x86_64")]
core::arch::global_asm!(
    ".p2align 4",
    ".weak __air_rt_sigreturn_trampoline",
    ".hidden __air_rt_sigreturn_trampoline",
    "__air_rt_sigreturn_trampoline:",
    "mov rax, 15", // __NR_rt_sigreturn (x86_64)
    "syscall",
);

#[cfg(target_arch = "x86_64")]
unsafe extern "C" {
    /// Symbole du trampoline `rt_sigreturn` défini par le `global_asm!`
    /// ci-dessus. Jamais appelé depuis Rust — seule son **adresse** est posée
    /// dans `sa_restorer`.
    fn __air_rt_sigreturn_trampoline();
}

pub mod async_handler {
    //! Wrappers `rt_sigaction` pour les signaux **non-faute** — handler
    //! **réellement installé** (cf. ADR-064 : délivrance async réelle ; ADR-066 :
    //! descellement additif couche 0).
    //!
    //! Contrairement à [`synchronous_handler`](super::synchronous_handler)
    //! (restreint aux 4 fautes, handler **inerte** — le noyau force l'action par
    //! défaut), ce sous-module installe un `rt_sigaction` **effectif** : le noyau
    //! détourne le thread vers le handler C à la délivrance d'un signal
    //! **gérable**. C'est la **fondation dual-face** que la libc (`sigaction`) et
    //! le PAL consomment via la couche 1 `air-signal`.
    //!
    //! **API entièrement `unsafe`** : l'appelant garantit que le handler est
    //! **async-signal-safe** (`man 7 signal-safety`) — précondition invérifiable
    //! par le compilateur, portée par l'appelant (identique à
    //! `synchronous_handler`).

    use air_sys_types::Errno;
    use air_sys_types::signal::async_handler::{PreviousDisposition, SigActionFlags};
    use air_sys_types::{Signal, SignalMask};

    use super::{SIGSET_SIZE_U64, errno_from_negative_syscall_ret};

    /// `SA_RESTORER` (`0x0400_0000`) — **x86_64 uniquement**. Signale au noyau que
    /// `sa_restorer` porte l'adresse du trampoline de retour de handler.
    #[cfg(target_arch = "x86_64")]
    const SA_RESTORER: u64 = 0x0400_0000;

    /// Valeur `sa_handler` = `SIG_DFL` (action par défaut du noyau).
    pub const SIG_DFL: usize = 0;
    /// Valeur `sa_handler` = `SIG_IGN` (signal ignoré). **Sûr** (constante noyau,
    /// aucun code utilisateur) — cf. ADR-064 §2.
    pub const SIG_IGN: usize = 1;

    /// Installe une disposition pour le signal **non-faute** `signal` via
    /// `rt_sigaction(2)`, et rend la disposition **précédente** (pour
    /// [`restore`]).
    ///
    /// - `handler_sa` : valeur brute de `sa_handler` — [`SIG_DFL`] (`0`),
    ///   [`SIG_IGN`] (`1`), ou l'**adresse** d'une fonction handler
    ///   `extern "C"` (cast `usize`). C'est la couche 1 (`air-signal`) qui
    ///   fournit le type de handler ; la couche 0 reste agnostique (adresse
    ///   brute).
    /// - `flags` : [`SigActionFlags`] (`SA_SIGINFO`/`SA_RESTART`/…). Sur x86_64,
    ///   le wrapper **ajoute** `SA_RESTORER` et pose `sa_restorer` sur le
    ///   trampoline `rt_sigreturn` d'Air (obligatoire sans libc). Sur aarch64, le
    ///   retour passe par le VDSO — aucun `sa_restorer`.
    /// - `mask` : signaux **additionnels** bloqués pendant l'exécution du handler.
    ///
    /// # Safety
    ///
    /// Si `handler_sa` désigne une fonction (≠ [`SIG_DFL`]/[`SIG_IGN`]), l'appelant
    /// doit garantir qu'elle est **async-signal-safe** (`man 7 signal-safety`) :
    /// pas de `malloc`, pas de verrou, pas d'I/O bufferisée, etc. Le noyau peut
    /// l'invoquer à un point **arbitraire** du programme. Poser [`SIG_DFL`] ou
    /// [`SIG_IGN`] est en soi sûr (aucun code utilisateur), mais l'API reste
    /// `unsafe` pour une frontière uniforme.
    ///
    /// Ce wrapper est réservé aux signaux **non-faute** : installer un handler
    /// pour `SIGSEGV`/`SIGBUS`/`SIGFPE`/`SIGILL` est le domaine (inerte) de
    /// [`synchronous_handler`](super::synchronous_handler) (ADR-020/ADR-064).
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : `signal` non-catchable (`SIGKILL`/`SIGSTOP`).
    pub unsafe fn install(
        signal: Signal,
        handler_sa: usize,
        flags: SigActionFlags,
        mask: SignalMask,
    ) -> Result<PreviousDisposition, Errno> {
        let mut new_sa = KernelSigaction::zeroed();
        // `usize → u64` : Air ne cible que des arches 64 bits (ADR-014) — même
        // idiome que `synchronous_handler::install_fatal_handler`
        // (`handler as usize as u64`), lossless, sans conversion faillible.
        new_sa.sa_handler = handler_sa as u64;
        new_sa.sa_mask = mask.bits();

        // Drapeaux : ceux de l'appelant, plus `SA_RESTORER` sur x86_64 (le noyau
        // a besoin d'un trampoline de retour ; sans libc, Air le fournit).
        let kernel_flags = flags.bits();
        #[cfg(target_arch = "x86_64")]
        {
            new_sa.sa_flags = kernel_flags | SA_RESTORER;
            // Adresse du trampoline `rt_sigreturn` (fn item → usize → u64,
            // 64 bits : lossless).
            new_sa.sa_restorer = super::__air_rt_sigreturn_trampoline as *const () as usize as u64;
        }
        #[cfg(target_arch = "aarch64")]
        {
            new_sa.sa_flags = kernel_flags;
        }

        let mut previous = PreviousDisposition::zeroed();
        let new_ptr: *const KernelSigaction = &new_sa;
        let old_ptr: *mut u8 = previous.as_bytes_mut().as_mut_ptr();

        // SAFETY: rt_sigaction(2). Le kernel lit `new_sa` (KernelSigaction valide,
        // locale) et écrit jusqu'à 32 octets à `old_ptr` (capacité de
        // `PreviousDisposition`). sigsetsize=8 = taille kernel `sigset_t`. Le
        // handler éventuel respecte l'async-signal-safety par contrat `unsafe`.
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_raw(),
                new_ptr as u64,
                old_ptr as u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(previous)
    }

    /// Restaure la disposition `previous` pour le signal `signal`.
    ///
    /// # Safety
    ///
    /// `previous` doit provenir d'un [`install`] précédent sur le **même**
    /// `signal`. Restaurer une disposition d'un autre signal est un comportement
    /// indéfini côté noyau.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : `signal` non-catchable (ne se produit pas si
    ///   `previous` vient d'un `install` réussi sur ce signal).
    pub unsafe fn restore(signal: Signal, previous: PreviousDisposition) -> Result<(), Errno> {
        let prev_ptr: *const u8 = previous.as_bytes().as_ptr();
        // SAFETY: rt_sigaction(2). Le kernel lit jusqu'à 32 octets à `prev_ptr`
        // (KernelSigaction ≤ 32 octets). Pas d'écriture (oldset=NULL).
        let ret = unsafe {
            raw_syscall_rt_sigaction(signal.as_raw(), prev_ptr as u64, 0_u64, SIGSET_SIZE_U64)
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// Représentation interne du `struct sigaction` kernel (cf.
    /// [`synchronous_handler`](super::synchronous_handler) — même layout ABI,
    /// dupliqué pour ne PAS toucher au sous-module des fautes).
    ///
    /// - offset 0  : `sa_handler` (8) ; offset 8 : `sa_flags` (8) ;
    /// - x86_64 : offset 16 `sa_restorer` (8), offset 24 `sa_mask` (8) — 32 octets ;
    /// - aarch64 : offset 16 `sa_mask` (8), **pas** de `sa_restorer` — 24 octets.
    #[repr(C)]
    #[cfg(target_arch = "x86_64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_restorer: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "x86_64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_restorer: 0,
                sa_mask: 0,
            }
        }
    }

    #[repr(C)]
    #[cfg(target_arch = "aarch64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "aarch64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_mask: 0,
            }
        }
    }

    /// `KernelSigaction` tient dans le buffer 32 octets de `PreviousDisposition`.
    const _: () = {
        assert!(core::mem::size_of::<KernelSigaction>() <= 32);
    };

    #[cfg(target_arch = "x86_64")]
    #[inline]
    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 `new_sa`
        // (KernelSigaction, 32 octets), écrit `old_sa` (32 octets) si non-null.
        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")]
    #[inline]
    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).
        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
    }
}

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

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_signalfd4(fd: i32, mask: u64, sigsetsize: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_signalfd4 (x86_64 = 289). Le kernel lit `*mask` (8
    // octets) ; pas d'écriture en mémoire utilisateur (`readonly` OK).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 289_i64,
            in("rdi") i64::from(fd),
            in("rsi") mask,
            in("rdx") sigsetsize,
            in("r10") 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_signalfd4(fd: i32, mask: u64, sigsetsize: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_signalfd4 (aarch64 = 74).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 74_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") mask,
            in("x2") sigsetsize,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigprocmask(how: i32, set: u64, oldset: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigprocmask (x86_64 = 14). Le kernel lit `*set` si
    // non-null (8 octets) ; écrit `*oldset` si non-null (8 octets). Pas
    // de `readonly` (écriture sur oldset).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 14_i64,
            in("rdi") i64::from(how),
            in("rsi") set,
            in("rdx") oldset,
            in("r10") sigsetsize,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigprocmask(how: i32, set: u64, oldset: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigprocmask (aarch64 = 135).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 135_i64,
            inout("x0") i64::from(how) => ret,
            in("x1") set,
            in("x2") oldset,
            in("x3") sigsetsize,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sigaltstack(new: u64, old: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sigaltstack (x86_64 = 131). Le kernel **lit** `*new` (24 octets) si
    // `new != 0` et **écrit** `*old` (24 octets) si `old != 0` — pas de `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 131_i64,
            in("rdi") new,
            in("rsi") old,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sigaltstack(new: u64, old: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sigaltstack (aarch64 = 132). Mêmes contrats mémoire que x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 132_i64,
            inout("x0") new => ret,
            in("x1") old,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigpending(set: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigpending (x86_64 = 127). Le kernel **écrit** 8 octets à
    // `set` (sigset_t) ; pas de `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 127_i64,
            in("rdi") set,
            in("rsi") sigsetsize,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigpending(set: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigpending (aarch64 = 136).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 136_i64,
            inout("x0") set => ret,
            in("x1") sigsetsize,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_kill(pid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_kill (x86_64 = 62). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 62_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(sig),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_kill(pid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_kill (aarch64 = 129).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 129_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(sig),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_tgkill(tgid: i32, tid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tgkill (x86_64 = 234). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 234_i64,
            in("rdi") i64::from(tgid),
            in("rsi") i64::from(tid),
            in("rdx") i64::from(sig),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_tgkill(tgid: i32, tid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tgkill (aarch64 = 131).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 131_i64,
            inout("x0") i64::from(tgid) => ret,
            in("x1") i64::from(tid),
            in("x2") i64::from(sig),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigqueueinfo(pid: i32, sig: i32, info: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigqueueinfo (x86_64 = 129). Le kernel lit 128
    // octets à `info` (siginfo_t). Pas d'écriture user (`readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 129_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(sig),
            in("rdx") info,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigqueueinfo(pid: i32, sig: i32, info: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigqueueinfo (aarch64 = 138).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 138_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(sig),
            in("x2") info,
            options(nostack, preserves_flags, readonly),
        );
    }
    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 à `buffer`. Pour signalfd, exactement 128 octets pour un
    // événement complet.
    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: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (aarch64 = 63).
    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
}

// ─────────────────────────────────────────────────────────────────────────
// Helper de conversion errno (réplique de celui de process.rs ; un
// futur refactor pourra centraliser).
// ─────────────────────────────────────────────────────────────────────────

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

// ─────────────────────────────────────────────────────────────────────────
// Tests.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests;