air_sys_syscall/

mem.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 `mem` — mappings, protection, memfd, etc.
//!
//! Cf. `docs/specs/layer-0/family-mem.md`.

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

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use core::ffi::CStr;
use core::num::NonZeroI32;
use core::ptr::NonNull;
use core::sync::atomic::AtomicU32;

// `MmapRegion` partage sa durée de vie via `Arc` (un seul compte fort par
// mapping). Sous `--cfg loom`, on bascule sur l'`Arc` modélisé par loom pour
// **prouver** le protocole de refcount (clones/drops concurrents de la garde
// de vivacité) ; sinon `std::sync::Arc`. Même schéma que le protocole d'anneau
// io_uring (`io_uring::ring`).
#[cfg(not(loom))]
use alloc::sync::Arc;
#[cfg(loom)]
use loom::sync::Arc;

use air_sys_types::mem::{
    MadviseAdvice, MapFlags, MappingPointer, MemfdFlags, MlockFlags, MlockallFlags, MremapFlags,
    MsyncFlags, ProtectionFlags, RemoteIoSlice,
};
use air_sys_types::net::{IoSlice, IoSliceMut};
use air_sys_types::{Errno, Pid};

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

// ─────────────────────────────────────────────────────────────────────────
// Mapping — type RAII wrappant une plage mémoire mappée.
//
// Note d'architecture : `Mapping` est placé dans `air-sys-syscall::mem`
// et non dans `air-sys-types`, contrairement à ce qu'indique la spec,
// car son `Drop` doit appeler `munmap` (un syscall). Placer un appel
// syscall dans `air-sys-types` violerait l'invariant d'architecture
// « les types ne font pas de syscalls ». Voir QUESTIONS-implementation.md.
// ─────────────────────────────────────────────────────────────────────────

/// Mapping mémoire RAII.
///
/// Crée automatiquement par [`mmap_anonymous`], [`mmap_file`] et
/// retourné par [`mremap`]. Appelle `munmap(2)` automatiquement à la
/// destruction pour éviter tout fuite de mémoire mappée.
///
/// Contrairement à un [`MappingPointer`] brut, ce type garantit que
/// `munmap` sera appelé exactement une fois, même en cas de panique.
///
/// Le `Drop` automatique ignore l'erreur de `munmap` (cas extrêmement
/// rare sur Linux moderne). Pour récupérer une éventuelle erreur,
/// utiliser [`munmap`] qui consomme le `Mapping` explicitement.
#[derive(Debug)]
pub struct Mapping {
    addr: NonNull<u8>,
    len: usize,
}

// SAFETY: voir MappingPointer — la synchronisation est à la charge de l'appelant.
unsafe impl Send for Mapping {}
// SAFETY: `&Mapping` ne donne que l'adresse et la longueur ; lire ou écrire la mémoire
// désignée passe par du code `unsafe`, dont l'appelant porte la synchronisation.
unsafe impl Sync for Mapping {}

impl Mapping {
    /// Retourne un pointeur constant vers le début du mapping.
    #[must_use]
    pub fn as_ptr(&self) -> *const u8 {
        self.addr.as_ptr()
    }

    /// Retourne un pointeur mutable vers le début du mapping.
    #[must_use]
    pub fn as_mut_ptr(&mut self) -> *mut u8 {
        self.addr.as_ptr()
    }

    /// Longueur du mapping en octets.
    #[must_use]
    pub fn len(&self) -> usize {
        self.len
    }

    /// Retourne `true` si la longueur est zéro (mapping vide).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Vue en lecture du mapping sous forme de slice d'octets.
    ///
    /// # Safety
    ///
    /// Le mapping doit être lisible (au moins `ProtectionFlags::READ`) et le
    /// contenu doit être valide pour la durée de vie de la référence
    /// retournée.
    #[must_use]
    pub fn as_slice(&self) -> &[u8] {
        // SAFETY: address est NonNull, length est la taille du mapping, et
        // la durée de vie est liée à &self.
        unsafe { core::slice::from_raw_parts(self.addr.as_ptr(), self.len) }
    }

    /// Vue en écriture du mapping sous forme de slice d'octets.
    ///
    /// # Safety
    ///
    /// Le mapping doit être accessible en écriture (au moins
    /// `ProtectionFlags::WRITE`). L'appelant est responsable de ne pas créer
    /// de références Rust aliasées sur la même plage mémoire.
    pub unsafe fn as_mut_slice(&mut self) -> &mut [u8] {
        // SAFETY: préconditions documentées dans la section # Safety.
        unsafe { core::slice::from_raw_parts_mut(self.addr.as_ptr(), self.len) }
    }
}

impl Drop for Mapping {
    fn drop(&mut self) {
        // Appel munmap en ignorant l'erreur (rare sur Linux moderne).
        // Pour récupérer l'erreur, utiliser munmap() explicite.
        let _ = raw_munmap(self.addr.as_ptr(), self.len);
    }
}

/// Appel syscall munmap brut, partagé entre Mapping::drop et munmap().
fn raw_munmap(address: *mut u8, length: usize) -> Result<(), Errno> {
    // SAFETY: munmap(2) ne lit ni n'écrit de mémoire utilisateur (il
    // libère le mapping). address et length sont fournis tels quels au kernel.
    let ret = unsafe { raw_syscall_munmap(address as u64, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Helper interne : appel mmap brut commun.
// ─────────────────────────────────────────────────────────────────────────

/// Appel mmap brut partagé par mmap_anonymous, mmap_file et mmap_fixed.
///
/// # Safety
///
/// L'appelant doit fournir des arguments valides pour le syscall mmap(2).
/// En particulier :
/// - `fd` doit être -1 pour les mappings anonymes, ou un fd ouvert valide.
/// - `offset` doit être aligné sur la page size.
/// - Si `flags` contient `MAP_FIXED`, `address` peut écraser des mappings existants.
unsafe fn raw_mmap(
    address: u64,
    length: usize,
    prot: i32,
    flags: i32,
    fd: i64,
    offset: u64,
) -> Result<NonNull<u8>, Errno> {
    // SAFETY: mmap(2) mappe de la mémoire ; l'appelant garantit les préconditions.
    let ret = unsafe { raw_syscall_mmap(address, length, prot, flags, fd, offset) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // ret est l'adresse du mapping (i64 positif, jamais 0 sur Linux).
    #[allow(clippy::cast_sign_loss)]
    let addr_raw = ret as u64 as *mut u8;
    let address = NonNull::new(addr_raw).expect("mmap returned NULL (impossible)");
    Ok(address)
}

// ─────────────────────────────────────────────────────────────────────────
// Fonctions publiques — Mappings
// ─────────────────────────────────────────────────────────────────────────

/// Crée un mapping mémoire anonyme (sans fichier sous-jacent).
///
/// Wrappeur de `mmap(2)` avec `MAP_ANONYMOUS | MAP_PRIVATE` ajoutés
/// automatiquement par le wrapper. Le flag [`MapFlags::ANONYMOUS`] est
/// toujours positionné en interne — l'appelant n'a pas besoin de le
/// passer dans `flags`.
///
/// La durée de vie du mapping est gérée par le [`Mapping`] retourné :
/// `munmap` est appelé automatiquement à la destruction.
///
/// # Parameters
///
/// - `length` : taille souhaitée en octets. Le kernel arrondit à la page
///   supérieure ; la taille effective est accessible via `Mapping::length()`.
/// - `prot` : protections d'accès initiales.
/// - `flags` : flags de comportement (sans `ANONYMOUS` ni `PRIVATE`, ajoutés
///   automatiquement).
///
/// # Errors
///
/// - `EINVAL` : `length` est zéro, ou flags incompatibles (`SHARED | PRIVATE`).
/// - `ENOMEM` : mémoire virtuelle ou physique insuffisante.
/// - `EACCES` : permissions refusées par le kernel.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::mmap_anonymous;
/// use air_sys_types::mem::{MapFlags, ProtectionFlags};
///
/// let mut m = mmap_anonymous(
///     4096,
///     ProtectionFlags::READ | ProtectionFlags::WRITE,
///     MapFlags::PRIVATE,
/// ).expect("mmap_anonymous");
/// // munmap appelé automatiquement à la fin du scope
/// ```
pub fn mmap_anonymous(
    length: usize,
    prot: ProtectionFlags,
    flags: MapFlags,
) -> Result<Mapping, Errno> {
    // MAP_ANONYMOUS | MAP_PRIVATE ajoutés systématiquement.
    let effective_flags = (flags | MapFlags::ANONYMOUS | MapFlags::PRIVATE).bits();
    // SAFETY: mmap anonyme — fd=-1, offset=0, address=0 (any). Pas d'accès
    // à de la mémoire utilisateur existante.
    let address = unsafe { raw_mmap(0, length, prot.bits(), effective_flags, -1, 0) }?;
    Ok(Mapping {
        addr: address,
        len: length,
    })
}

/// Crée un mapping de fichier.
///
/// Wrappeur de `mmap(2)` avec un FD fichier. `offset` doit être aligné
/// sur la page size (vérification effectuée par le kernel).
///
/// # Parameters
///
/// - `fd` : FD du fichier à mapper.
/// - `length` : longueur du mapping en octets.
/// - `offset` : offset dans le fichier (doit être aligné sur la page size).
/// - `prot` : protections d'accès.
/// - `flags` : flags de mapping (`SHARED` ou `PRIVATE` obligatoire).
///
/// # Errors
///
/// - `EINVAL` : `offset` non aligné, `length` zéro, ou flags invalides.
/// - `EACCES` : `prot` incompatible avec les permissions du FD.
/// - `ENOMEM` : mémoire virtuelle insuffisante.
/// - `ENODEV` : le FD référence un type de fichier non mappable.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::mmap_file;
/// use air_sys_types::mem::{MapFlags, ProtectionFlags};
/// use air_sys_types::fd::BorrowedFd;
///
/// // fd = FD d'un fichier de 4096 octets déjà ouvert
/// # fn example(fd: BorrowedFd<'_>) {
/// let m = mmap_file(fd, 4096, 0, ProtectionFlags::READ, MapFlags::PRIVATE)
///     .expect("mmap_file");
/// let _data: &[u8] = m.as_slice();
/// # }
/// ```
pub fn mmap_file(
    fd: BorrowedFd<'_>,
    length: usize,
    offset: u64,
    prot: ProtectionFlags,
    flags: MapFlags,
) -> Result<Mapping, Errno> {
    let raw_fd = i64::from(fd.as_raw_fd());
    // SAFETY: fd est un BorrowedFd valide, donc le fd numérique est ouvert
    // pour la durée de l'appel. offset est passé tel quel au kernel.
    let address = unsafe { raw_mmap(0, length, prot.bits(), flags.bits(), raw_fd, offset) }?;
    Ok(Mapping {
        addr: address,
        len: length,
    })
}

/// Mappe à une adresse spécifique.
///
/// Wrappeur de `mmap(2)` avec `MAP_FIXED` ou `MAP_FIXED_NOREPLACE`.
/// `unsafe` car peut écraser des mappings existants si `MAP_FIXED`
/// est utilisé sans `FIXED_NOREPLACE`.
///
/// # Safety
///
/// L'appelant doit garantir que :
/// 1. `address` est aligné sur la page size.
/// 2. Si `MapFlags::FIXED` est dans `flags`, les mappings existants à
///    cette adresse peuvent être détruits.
/// 3. Préférer `MapFlags::FIXED_NOREPLACE` pour obtenir `EEXIST` en cas
///    de collision plutôt que d'écraser silencieusement.
///
/// # Parameters
///
/// - `address` : adresse de base souhaitée.
/// - `length` : longueur en octets.
/// - `prot` : protections.
/// - `flags` : flags de mapping (doit contenir `FIXED` ou `FIXED_NOREPLACE`).
/// - `fd` : FD fichier optionnel (`None` pour mapping anonyme).
/// - `offset` : offset dans le fichier (0 pour mapping anonyme).
///
/// # Errors
///
/// - `EINVAL` : adresse non alignée ou flags invalides.
/// - `EEXIST` : adresse occupée et `FIXED_NOREPLACE` est utilisé.
/// - `ENOMEM` : mémoire insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::mmap_fixed;
/// use air_sys_types::mem::{MapFlags, MappingPointer, ProtectionFlags};
/// use core::ptr::NonNull;
///
/// # fn example(address: NonNull<u8>) {
/// // unsafe : peut écraser des mappings existants si MAP_FIXED utilisé
/// let ptr = unsafe {
///     mmap_fixed(
///         address,
///         4096,
///         ProtectionFlags::READ | ProtectionFlags::WRITE,
///         MapFlags::FIXED_NOREPLACE | MapFlags::PRIVATE | MapFlags::ANONYMOUS,
///         None,
///         0,
///     )
/// }.expect("mmap_fixed");
/// # }
/// ```
pub unsafe fn mmap_fixed(
    address: NonNull<u8>,
    length: usize,
    prot: ProtectionFlags,
    flags: MapFlags,
    fd: Option<BorrowedFd<'_>>,
    offset: u64,
) -> Result<MappingPointer, Errno> {
    let raw_fd: i64 = match fd {
        Some(f) => i64::from(f.as_raw_fd()),
        None => -1,
    };
    // Pour mapping anonyme sans fd, on ajoute MAP_ANONYMOUS.
    let effective_flags = if fd.is_none() {
        (flags | MapFlags::ANONYMOUS).bits()
    } else {
        flags.bits()
    };
    // SAFETY: l'appelant garantit que address est aligné sur la page size
    // et que MAP_FIXED / MAP_FIXED_NOREPLACE est positionné.
    let mapped_addr = unsafe {
        raw_mmap(
            address.as_ptr() as u64,
            length,
            prot.bits(),
            effective_flags,
            raw_fd,
            offset,
        )
    }?;
    Ok(MappingPointer {
        address: mapped_addr,
        length,
    })
}

// ─────────────────────────────────────────────────────────────────────────
// MmapRegion — mapping partageable, compatible avec l'asynchronie io_uring.
//
// Cf. docs/specs/layer-0/family-mem-mmap-region.md.
//
// `MmapRegion` (`Arc<MmapRegionInner>`) est l'**opt-in partageable** : à la
// différence de `Mapping` (RAII unique, zéro-coût, **inchangé**), sa durée de
// vie peut être partagée avec le slot S1 d'une opération io_uring en vol
// (`madvise`, `futex_*`) via une `MmapRegionLiveness`. Le kernel lit la
// mémoire de la région **de façon asynchrone**, jusqu'à la complétion ; la
// garde garée dans le slot empêche `munmap` tant que l'op est en vol. `munmap`
// n'a lieu qu'au **dernier** drop (région utilisateur ET toutes les gardes) →
// **ni use-after-unmap, ni fuite**.
//
// **Exception ADR-021 c.4 (« pas d'alloc dans le happy path »), documentée :**
// `MmapRegion` fait **une** allocation (l'`Arc` inner). C'est admis car (1)
// opt-in — `Mapping` reste zéro-coût ; (2) négligeable et amorti devant le
// syscall `mmap` qui crée la région ; (3) le partage de durée de vie est
// **intrinsèquement nécessaire** à la sûreté de l'usage asynchrone (clause
// « nécessité documentée » d'ADR-021 c.4).
// ─────────────────────────────────────────────────────────────────────────

/// Compteur de démappages simulés pour les preuves de refcount (Miri/loom).
/// Sous `--cfg loom`, c'est l'`AtomicUsize` modélisé par loom.
#[cfg(all(any(test, loom), loom))]
type ProbeCounter = loom::sync::atomic::AtomicUsize;
/// Compteur de démappages simulés pour les preuves de refcount (tests/Miri).
#[cfg(all(any(test, loom), not(loom)))]
type ProbeCounter = core::sync::atomic::AtomicUsize;

/// État interne partagé d'une [`MmapRegion`], détenu par un `Arc`. Son `Drop`,
/// au **dernier** détenteur fort uniquement, appelle `munmap` (erreur ignorée,
/// comme [`Mapping`]).
struct MmapRegionInner {
    /// Adresse de base du mapping.
    ptr: NonNull<u8>,
    /// Longueur en octets.
    len: usize,
    /// Protections du mapping (détermine la lisibilité de [`MmapRegion::bytes`]
    /// et l'accès à [`MmapRegion::futex_word`]).
    prot: ProtectionFlags,
    /// Présent uniquement en test/Miri/loom : si `Some`, la région est
    /// **fictive** (créée par `new_for_test`, pointeur non déréférencé) et
    /// `drop_unmap` incrémente ce compteur au lieu d'appeler le vrai `munmap`.
    /// `None` pour les régions réelles (issues d'un `mmap`).
    #[cfg(any(test, loom))]
    unmap_probe: Option<Arc<ProbeCounter>>,
}

// SAFETY: comme `Mapping`/`MappingPointer`, le pointeur désigne un mapping dont
// la **synchronisation des accès** est à la charge de l'appelant. Le partage de
// propriété (compteur fort de l'`Arc`) est lui-même thread-safe.
unsafe impl Send for MmapRegionInner {}
// SAFETY: idem `Send` ci-dessus.
unsafe impl Sync for MmapRegionInner {}

impl MmapRegionInner {
    /// Démappe la région (dernier drop). Sous test/Miri/loom **avec** une région
    /// fictive, **n'appelle pas** le vrai syscall (Miri/loom ne peuvent pas
    /// exécuter l'`asm!`, et la région n'a pas de vrai mapping) : incrémente le
    /// compteur de preuve. Une région réelle (`unmap_probe = None`) démappe
    /// pour de vrai hors Miri/loom.
    fn drop_unmap(&mut self) {
        #[cfg(any(test, loom))]
        if let Some(counter) = &self.unmap_probe {
            counter.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
            return;
        }
        #[cfg(not(any(miri, loom)))]
        {
            // SAFETY: `ptr`/`len` proviennent d'un `mmap` réussi (constructeurs)
            // et la région n'a pas encore été démappée — le **dernier** drop est
            // unique par construction (compteur fort de l'`Arc`). `munmap`
            // ignore l'erreur, comme `Mapping`.
            let _ = raw_munmap(self.ptr.as_ptr(), self.len);
        }
    }
}

impl Drop for MmapRegionInner {
    fn drop(&mut self) {
        self.drop_unmap();
    }
}

/// Mapping mmap **partageable** et compatible io_uring : ses pages restent
/// valides tant qu'une opération io_uring en vol (`madvise`/`futex_*`) y
/// référence de la mémoire. Compté par référence — `munmap` au **dernier**
/// drop (la région **et** toutes les gardes de vivacité d'ops en vol).
///
/// Distinct de [`Mapping`] **à dessein** : `Mapping` reste l'usage synchrone
/// unique/zéro-coût ; `MmapRegion` est l'opt-in partageable (une allocation
/// `Arc`, cf. exception ADR-021 c.4 ci-dessus). Cloner incrémente le compteur
/// fort ; aucune copie de pages, seulement du partage de propriété.
#[derive(Clone)]
pub struct MmapRegion {
    /// Inner partagé. Le `munmap` n'a lieu qu'au drop du **dernier** `Arc`.
    inner: Arc<MmapRegionInner>,
}

impl core::fmt::Debug for MmapRegion {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("MmapRegion")
            .field("ptr", &self.inner.ptr)
            .field("len", &self.inner.len)
            .field("prot", &self.inner.prot)
            .finish()
    }
}

impl MmapRegion {
    /// Mapping anonyme partageable (équivalent [`mmap_anonymous`] rendant une
    /// `MmapRegion`).
    ///
    /// # Errors
    ///
    /// Toute erreur de `mmap(2)` (cf. [`mmap_anonymous`]) : `EINVAL`, `ENOMEM`…
    pub fn new_anonymous(
        len: usize,
        prot: ProtectionFlags,
        flags: MapFlags,
    ) -> Result<Self, Errno> {
        let mapping = mmap_anonymous(len, prot, flags)?;
        Ok(Self::from_mapping_with_prot(mapping, prot))
    }

    /// Mapping de fichier partageable (équivalent [`mmap_file`] rendant une
    /// `MmapRegion`).
    ///
    /// # Errors
    ///
    /// Toute erreur de `mmap(2)` (cf. [`mmap_file`]) : `EINVAL`, `EACCES`…
    pub fn from_file(
        fd: BorrowedFd<'_>,
        len: usize,
        prot: ProtectionFlags,
        flags: MapFlags,
        offset: u64,
    ) -> Result<Self, Errno> {
        let mapping = mmap_file(fd, len, offset, prot, flags)?;
        Ok(Self::from_mapping_with_prot(mapping, prot))
    }

    /// Promeut un [`Mapping`] unique en région partageable : **transfère** la
    /// responsabilité du `munmap` à l'inner partagé. Le `Mapping` est consommé
    /// et **neutralisé** (son `Drop` ne munmap plus) → **pas de double
    /// `munmap`**. Une seule allocation (l'inner).
    ///
    /// **`prot` explicite (obligatoire).** Un `Mapping` nu ne mémorise pas ses
    /// protections ; l'appelant **doit** fournir le `prot` avec lequel le
    /// `Mapping` a été créé, sinon [`MmapRegion::bytes`] / [`MmapRegion::futex_word`]
    /// décideraient de l'accessibilité sur une base fausse (référence qui
    /// **faute** à l'usage). Il n'y a **pas** de défaut `READ|WRITE` : le `prot`
    /// passé fait foi.
    #[must_use]
    pub fn from_mapping(mapping: Mapping, prot: ProtectionFlags) -> Self {
        Self::from_mapping_with_prot(mapping, prot)
    }

    /// Cœur commun : consomme le `Mapping` (sans déclencher son `Drop`) et
    /// construit l'inner partagé avec les protections connues.
    fn from_mapping_with_prot(mapping: Mapping, prot: ProtectionFlags) -> Self {
        // ManuallyDrop empêche `Mapping::drop` d'appeler `munmap` : la
        // responsabilité passe à l'inner (pas de double munmap).
        let md = core::mem::ManuallyDrop::new(mapping);
        let inner = MmapRegionInner {
            ptr: md.addr,
            len: md.len,
            prot,
            #[cfg(any(test, loom))]
            unmap_probe: None,
        };
        Self {
            inner: Arc::new(inner),
        }
    }

    /// Longueur du mapping en octets.
    #[must_use]
    pub fn len(&self) -> usize {
        self.inner.len
    }

    /// `true` si la longueur est zéro.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.inner.len == 0
    }

    /// Pointeur brut vers le début du mapping (consommateurs avancés ; pas de
    /// transfert de propriété — le `munmap` reste géré par la `MmapRegion`).
    #[must_use]
    pub fn as_ptr(&self) -> *const u8 {
        self.inner.ptr.as_ptr()
    }

    /// Tranche d'octets en lecture, **bornée par construction**. Renvoie une
    /// tranche **vide** si la région n'est pas lisible (`prot` sans `READ`) —
    /// jamais de référence vers de la mémoire inaccessible.
    #[must_use]
    pub fn bytes(&self) -> &[u8] {
        if !self.inner.prot.contains(ProtectionFlags::READ) {
            return &[];
        }
        // SAFETY: région lisible (prot ⊇ READ), `ptr` non-null issu d'un mmap,
        // `len` = taille mappée ; la durée de vie de la tranche est liée à
        // `&self`, donc à l'`Arc` qui maintient le mapping vivant.
        unsafe { core::slice::from_raw_parts(self.inner.ptr.as_ptr(), self.inner.len) }
    }

    /// Référence à un **mot futex** ([`AtomicU32`]) à `offset` octets.
    ///
    /// La référence est **mutable par partage** (`AtomicU32` : `store`/`load` via
    /// `&`) ; la rendre sur des pages non inscriptibles serait *unsound* (une
    /// écriture fauterait). La validation amont (Principe 4) exige donc que la
    /// région soit **inscriptible** (`prot ⊇ WRITE`), `offset` **borné**
    /// (`offset + 4 ≤ len`) et **aligné sur 4** (un futex est un `u32` aligné) —
    /// sinon la référence n'est **pas** rendue.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si la région n'est pas inscriptible, ou si `offset` est
    /// hors bornes ou non aligné sur 4.
    pub fn futex_word(&self, offset: usize) -> Result<&AtomicU32, Errno> {
        if !self.inner.prot.contains(ProtectionFlags::WRITE) {
            return Err(Errno::EINVAL);
        }
        // Alignement sur 4 sans opérateur arithmétique nu (bit-and).
        if offset & 0b11 != 0 {
            return Err(Errno::EINVAL);
        }
        let end = offset.checked_add(4).ok_or(Errno::EINVAL)?;
        if end > self.inner.len {
            return Err(Errno::EINVAL);
        }
        // SAFETY: `offset` validé (aligné 4, `offset+4 ≤ len`) ⇒ `ptr+offset`
        // désigne un `u32` **entièrement** dans le mapping inscriptible.
        // `AtomicU32` a le même layout (et les mêmes exigences d'alignement)
        // qu'un `u32` ; l'accès concurrent est admis (le kernel y accède aussi).
        // La durée de vie est liée à `&self` (donc à l'`Arc`).
        let word = unsafe { self.inner.ptr.as_ptr().add(offset).cast::<AtomicU32>() };
        // SAFETY: voir ci-dessus — `word` est aligné, valide et vivant.
        Ok(unsafe { &*word })
    }

    /// Produit une garde de vivacité (clone interne de l'`Arc`). Réservé aux
    /// façades io_uring `submit_madvise`/`submit_futex_*` : la garde est garée
    /// dans le slot S1 et libérée à la complétion → `munmap` au dernier drop.
    pub(crate) fn liveness_handle(&self) -> MmapRegionLiveness {
        MmapRegionLiveness {
            inner: Arc::clone(&self.inner),
        }
    }

    /// Construit une région **fictive** (sans `mmap`) pour les preuves de
    /// refcount (Miri/loom) : le pointeur est *dangling* et **ne doit jamais**
    /// être déréférencé (pas de `bytes()`/`futex_word()`) ; `munmap` est simulé
    /// par l'incrément de `counter` au dernier drop.
    #[cfg(any(test, loom))]
    pub(crate) fn new_for_test(len: usize, counter: Arc<ProbeCounter>) -> Self {
        Self {
            inner: Arc::new(MmapRegionInner {
                ptr: NonNull::<u8>::dangling(),
                len,
                prot: ProtectionFlags::READ | ProtectionFlags::WRITE,
                unmap_probe: Some(counter),
            }),
        }
    }

    /// Nombre de détenteurs forts de l'inner (région + gardes en vol). Réservé
    /// aux tests de refcount déterministes (non utilisé par la preuve loom).
    #[cfg(any(test, loom))]
    #[cfg_attr(loom, allow(dead_code))]
    pub(crate) fn strong_count(&self) -> usize {
        Arc::strong_count(&self.inner)
    }
}

/// Garde de vivacité retenue par le slot S1 d'une opération io_uring en vol qui
/// référence la région. Maintient les pages **mappées** sans donner d'accès :
/// tant qu'une garde existe, `munmap` ne peut pas se produire.
pub struct MmapRegionLiveness {
    /// Clone fort de l'inner : maintient le compteur ≥ 1. Jamais relu — seul son
    /// `Drop` (compteur −1) compte ; `munmap` survient au dernier drop.
    inner: Arc<MmapRegionInner>,
}

impl core::fmt::Debug for MmapRegionLiveness {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("MmapRegionLiveness")
            .field("ptr", &self.inner.ptr)
            .field("len", &self.inner.len)
            .finish()
    }
}

/// Dé-mappe explicitement un mapping et récupère une éventuelle erreur.
///
/// Consomme le [`Mapping`] ; l'appelant récupère l'erreur de `munmap`
/// si elle survient (rare sur Linux moderne). Le `Drop` automatique de
/// `Mapping` appelle aussi `munmap` mais ignore l'erreur.
///
/// # Errors
///
/// - `EINVAL` : adresse ou longueur invalide (ne se produit pas si le
///   `Mapping` a été créé par ce module).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::{mmap_anonymous, munmap};
/// use air_sys_types::mem::{MapFlags, ProtectionFlags};
///
/// let m = mmap_anonymous(4096, ProtectionFlags::READ, MapFlags::PRIVATE).expect("mmap");
/// munmap(m).expect("munmap");
/// ```
pub fn munmap(mapping: Mapping) -> Result<(), Errno> {
    // ManuallyDrop empêche le Drop de Mapping d'appeler munmap une seconde fois.
    let md = core::mem::ManuallyDrop::new(mapping);
    raw_munmap(md.addr.as_ptr(), md.len)
}

/// Libère un mapping par (**adresse, longueur**) brutes (`munmap(2)`) — **descellement
/// additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la **face libc**, qui gère la vie du mapping par `(addr, len)` (comme le C `void
/// *mmap`/`int munmap(void *, size_t)`), et **non** par l'objet RAII [`Mapping`]. La
/// couche 1 [`air-memory`] l'expose à la libc via son `AirMemoryManager`.
///
/// # Safety
/// `address`/`length` **doivent** désigner une région (ou un sous-ensemble de pages
/// alignées) **effectivement mappée** par l'appelant : `munmap` d'une région invalide
/// rend au mieux `EINVAL` (adresse non alignée), mais `munmap` d'une région **en cours
/// d'usage** déprogramme de la mémoire vive (comme le `munmap` C). C'est le contrat C.
pub unsafe fn munmap_raw(address: NonNull<u8>, length: usize) -> Result<(), Errno> {
    // Délègue au wrapper interne : le kernel valide `(addr, len)` (alignement page).
    raw_munmap(address.as_ptr(), length)
}

/// Redimensionne (et éventuellement déplace) un mapping existant.
///
/// Wrappeur de `mremap(2)`. Consomme le [`Mapping`] existant et retourne
/// un nouveau [`Mapping`] à la nouvelle adresse.
///
/// # Parameters
///
/// - `mapping` : mapping source (ownership transféré).
/// - `new_len` : nouvelle longueur souhaitée.
/// - `flags` : [`MremapFlags`]. Inclure `MAYMOVE` pour autoriser le
///   déplacement si le redimensionnement sur place est impossible.
///
/// # Errors
///
/// - `EINVAL` : longueur nulle ou flags invalides.
/// - `ENOMEM` : mémoire insuffisante (avec `MAYMOVE` absent, si sur place
///   impossible).
/// - `EAGAIN` : mapping verrouillé en mémoire et RLIMIT atteint.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::{mmap_anonymous, mremap};
/// use air_sys_types::mem::{MapFlags, MremapFlags, ProtectionFlags};
///
/// let m = mmap_anonymous(4096, ProtectionFlags::READ | ProtectionFlags::WRITE, MapFlags::PRIVATE)
///     .expect("mmap");
/// let m2 = mremap(m, 8192, MremapFlags::MAYMOVE).expect("mremap");
/// ```
pub fn mremap(mapping: Mapping, new_len: usize, flags: MremapFlags) -> Result<Mapping, Errno> {
    // ManuallyDrop empêche le Drop de Mapping d'appeler munmap sur l'ancienne
    // adresse, qui n'est plus valide après mremap.
    let md = core::mem::ManuallyDrop::new(mapping);
    let old_addr = md.addr.as_ptr() as u64;
    let old_len = md.len;
    // SAFETY: mremap(2) consomme l'ancien mapping et retourne un nouveau.
    // L'adresse new_addr (arg4) est 0 car on ne passe pas MREMAP_FIXED.
    let ret = unsafe { raw_syscall_mremap(old_addr, old_len, new_len, flags.bits(), 0_u64) };
    if ret < 0 {
        // Le mapping original n'a pas été modifié par le kernel en cas d'échec ;
        // il faut éviter la fuite — on le restitue dans un nouveau Mapping.
        // Cependant ManuallyDrop a déjà évité le drop. Si l'erreur est retournée,
        // l'original reste mappé mais son handle Rust est perdu : fuite intentionnelle
        // documentée (conforme à la spécification de la famille mem). L'erreur est
        // remontée à l'appelant.
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // ret est la nouvelle adresse du mapping (i64 positif).
    #[allow(clippy::cast_sign_loss)]
    let addr_raw = ret as u64 as *mut u8;
    let address = NonNull::new(addr_raw).expect("mremap returned NULL (impossible)");
    Ok(Mapping {
        addr: address,
        len: new_len,
    })
}

// ─────────────────────────────────────────────────────────────────────────
// Protection
// ─────────────────────────────────────────────────────────────────────────

/// Modifie les permissions d'une plage mémoire mappée.
///
/// Wrappeur de `mprotect(2)`. Typiquement utilisé pour rétrograder les
/// permissions après initialisation d'une zone en lecture seule.
///
/// # Parameters
///
/// - `address` : adresse de début (doit être alignée sur la page size).
/// - `length` : longueur de la plage en octets.
/// - `prot` : nouvelles permissions.
///
/// # Errors
///
/// - `EINVAL` : `address` non aligné, ou plage invalide.
/// - `EACCES` : tentative d'ajouter `EXEC` sur un FS monté `noexec`.
/// - `ENOMEM` : ressources kernel insuffisantes.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::{mmap_anonymous, mprotect};
/// use air_sys_types::mem::{MapFlags, ProtectionFlags};
/// use core::ptr::NonNull;
///
/// let mut m = mmap_anonymous(4096, ProtectionFlags::READ | ProtectionFlags::WRITE, MapFlags::PRIVATE)
///     .expect("mmap");
/// // Initialisez les données, puis passez en lecture seule :
/// mprotect(
///     NonNull::new(m.as_mut_ptr()).expect("non-null"),
///     4096,
///     ProtectionFlags::READ,
/// ).expect("mprotect");
/// ```
pub fn mprotect(address: NonNull<u8>, length: usize, prot: ProtectionFlags) -> Result<(), Errno> {
    // SAFETY: mprotect(2) modifie les permissions d'une plage mémoire.
    // L'appelant garantit que address est aligné et que la plage est mappée.
    let ret = unsafe { raw_syscall_mprotect(address.as_ptr() as u64, length, prot.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Conseils kernel
// ─────────────────────────────────────────────────────────────────────────

/// Informe le kernel sur le pattern d'accès attendu à une plage mémoire.
///
/// Wrappeur de `madvise(2)`. Ces conseils sont des hints : le kernel peut
/// les ignorer. Aucun effet sur la sémantique du programme — uniquement
/// sur les performances.
///
/// # Parameters
///
/// - `address` : adresse de début (alignée sur la page size).
/// - `length` : longueur en octets.
/// - `advice` : conseil à donner au kernel.
///
/// # Errors
///
/// - `EINVAL` : adresse non alignée, plage invalide, ou conseil inconnu.
/// - `EACCES` : `MADV_REMOVE` sur un mapping non partagé.
/// - `ENOMEM` : plage non mappée.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::{madvise, mmap_anonymous};
/// use air_sys_types::mem::{MadviseAdvice, MapFlags, ProtectionFlags};
/// use core::ptr::NonNull;
///
/// let m = mmap_anonymous(65536, ProtectionFlags::READ | ProtectionFlags::WRITE, MapFlags::PRIVATE)
///     .expect("mmap");
/// madvise(
///     NonNull::new(m.as_ptr() as *mut u8).expect("non-null"),
///     65536,
///     MadviseAdvice::Sequential,
/// ).expect("madvise");
/// ```
pub fn madvise(address: NonNull<u8>, length: usize, advice: MadviseAdvice) -> Result<(), Errno> {
    // MadviseAdvice est #[repr(i32)] donc `advice as i32` est une conversion
    // exacte et sans perte.
    #[allow(clippy::as_conversions)]
    let advice_i32 = advice as i32;
    // SAFETY: madvise(2) est un hint pour le kernel ; pas d'accès mémoire
    // utilisateur par le syscall lui-même. L'appelant garantit que la plage
    // [address, address+length) est mappée.
    let ret = unsafe { raw_syscall_madvise(address.as_ptr() as u64, length, advice_i32) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Verrouillage mémoire
// ─────────────────────────────────────────────────────────────────────────

/// Verrouille une plage mémoire en RAM (empêche le swap).
///
/// Wrappeur de `mlock(2)`. Nécessite soit des privilèges root, soit
/// une limite `RLIMIT_MEMLOCK` suffisante.
///
/// # Errors
///
/// - `ENOMEM` : la plage contient des pages non mappées, ou
///   `RLIMIT_MEMLOCK` serait dépassé.
/// - `EPERM` : `RLIMIT_MEMLOCK` est zéro et le processus n'est pas
///   privilégié.
/// - `EINVAL` : adresse ou longueur invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::{mlock, mmap_anonymous};
/// use air_sys_types::mem::{MapFlags, ProtectionFlags};
/// use core::ptr::NonNull;
///
/// let m = mmap_anonymous(4096, ProtectionFlags::READ | ProtectionFlags::WRITE, MapFlags::PRIVATE)
///     .expect("mmap");
/// mlock(NonNull::new(m.as_ptr() as *mut u8).expect("non-null"), 4096)
///     .expect("mlock");
/// ```
pub fn mlock(address: NonNull<u8>, length: usize) -> Result<(), Errno> {
    // SAFETY: mlock(2) demande au kernel de verrouiller une plage en RAM.
    // L'appelant garantit que [address, address+length) est une plage mappée valide.
    let ret = unsafe { raw_syscall_mlock(address.as_ptr() as u64, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Verrouille une plage mémoire avec contrôle du moment du verrouillage.
///
/// Variante de `mlock` avec [`MlockFlags::ONFAULT`] (Linux 4.4+) pour
/// un verrouillage différé au fur et à mesure des fautes mémoire.
///
/// # Errors
///
/// Voir [`mlock`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::mlock2;
/// use air_sys_types::mem::MlockFlags;
/// use core::ptr::NonNull;
///
/// # fn example(address: NonNull<u8>) {
/// mlock2(address, 4096, MlockFlags::ONFAULT).expect("mlock2");
/// # }
/// ```
pub fn mlock2(address: NonNull<u8>, length: usize, flags: MlockFlags) -> Result<(), Errno> {
    // SAFETY: mlock2(2) est identique à mlock avec un argument flags supplémentaire.
    // L'appelant garantit que [address, address+length) est mappée.
    let ret = unsafe { raw_syscall_mlock2(address.as_ptr() as u64, length, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Déverrouille une plage mémoire précédemment verrouillée.
///
/// # Errors
///
/// - `EINVAL` : adresse ou longueur invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::munlock;
/// use core::ptr::NonNull;
///
/// # fn example(address: NonNull<u8>) {
/// munlock(address, 4096).expect("munlock");
/// # }
/// ```
pub fn munlock(address: NonNull<u8>, length: usize) -> Result<(), Errno> {
    // SAFETY: munlock(2) déverrouille une plage mémoire.
    let ret = unsafe { raw_syscall_munlock(address.as_ptr() as u64, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Verrouille toutes les pages du processus en RAM.
///
/// # Errors
///
/// - `EPERM` : non privilégié et `RLIMIT_MEMLOCK` insuffisant.
/// - `ENOMEM` : mémoire physique insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::mlockall;
/// use air_sys_types::mem::MlockallFlags;
///
/// mlockall(MlockallFlags::CURRENT | MlockallFlags::FUTURE).expect("mlockall");
/// ```
pub fn mlockall(flags: MlockallFlags) -> Result<(), Errno> {
    // SAFETY: mlockall(2) prend un seul scalaire i32. Pas d'accès mémoire.
    let ret = unsafe { raw_syscall_mlockall(flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Déverrouille toutes les pages du processus.
///
/// # Errors
///
/// Normalement sans erreur si `mlockall` a été appelé préalablement.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::munlockall;
///
/// munlockall().expect("munlockall");
/// ```
pub fn munlockall() -> Result<(), Errno> {
    // SAFETY: munlockall(2) ne prend aucun argument. Pas d'accès mémoire.
    let ret = unsafe { raw_syscall_munlockall() };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// memfd
// ─────────────────────────────────────────────────────────────────────────

/// Crée un fichier mémoire anonyme (memfd).
///
/// Wrappeur de `memfd_create(2)` (Linux 3.17+, numéro x86_64: 319,
/// aarch64: 279). Primitive centrale pour la mémoire partagée moderne
/// sur Linux, utilisée par le data plane de Conduit (ADR-001).
///
/// Le FD retourné peut être :
/// - étendu avec `ftruncate(2)` ;
/// - mappé avec [`mmap_file`] ;
/// - partagé entre processus via `SCM_RIGHTS` sur un socket Unix ;
/// - scellé pour interdire des modifications futures.
///
/// # Parameters
///
/// - `name` : nom descriptif (visible dans `/proc/PID/fd/`, pas unique).
/// - `flags` : combinaison de [`MemfdFlags`]. `CLOEXEC` recommandé.
///
/// # Errors
///
/// - `EINVAL` : flags invalides ou `name` trop long.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
/// - `ENOMEM` : mémoire kernel insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::memfd_create;
/// use air_sys_types::mem::MemfdFlags;
/// use core::ffi::CStr;
///
/// let fd = memfd_create(c"shared-buffer", MemfdFlags::CLOEXEC | MemfdFlags::ALLOW_SEALING)
///     .expect("memfd_create");
/// ```
pub fn memfd_create(name: &CStr, flags: MemfdFlags) -> Result<OwnedFd, Errno> {
    let name_ptr = name.as_ptr() as u64;
    // SAFETY: memfd_create(2) lit la chaîne NUL-terminée à `name_ptr`.
    // `name` est un &CStr valide, donc la chaîne est correctement terminée.
    // Le syscall retourne un fd valide ou une erreur négative.
    let ret = unsafe { raw_syscall_memfd_create(name_ptr, 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 a alloué un fd valide ; Air en prend la propriété.
    let owned = unsafe { OwnedFd::from_raw_fd(raw_fd) };
    Ok(owned)
}

/// Crée un fichier mémoire secret non accessible au kernel.
///
/// Wrappeur de `memfd_secret(2)` (Linux 5.14+, numéro 447). Réservé
/// aux secrets cryptographiques de haute valeur.
///
/// # Parameters
///
/// - `flags` : réservé pour usage futur, doit être 0 actuellement.
///
/// # Errors
///
/// - `ENOSYS` : kernel < 5.14 ou support non compilé.
/// - `ENOMEM` : mémoire insuffisante.
/// - `EMFILE`/`ENFILE` : quotas FD atteints.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::memfd_secret;
///
/// let fd = memfd_secret(0).expect("memfd_secret");
/// ```
pub fn memfd_secret(flags: u32) -> Result<OwnedFd, Errno> {
    // SAFETY: memfd_secret(2) prend un seul argument scalaire u32.
    // Pas d'accès mémoire utilisateur. Retourne un fd ou une erreur.
    let ret = unsafe { raw_syscall_memfd_secret(flags) };
    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 a alloué un fd valide ; Air en prend la propriété.
    let owned = unsafe { OwnedFd::from_raw_fd(raw_fd) };
    Ok(owned)
}

// ─────────────────────────────────────────────────────────────────────────
// Synchronisation
// ─────────────────────────────────────────────────────────────────────────

/// Force la synchronisation d'un mapping `MAP_SHARED` vers le fichier.
///
/// Wrappeur de `msync(2)`. Utile pour garantir que les modifications
/// d'un mapping partagé sont visibles après une panne.
///
/// # Parameters
///
/// - `address` : adresse de début (alignée sur la page size).
/// - `length` : longueur en octets.
/// - `flags` : [`MsyncFlags::SYNC`] (bloquant) ou `ASYNC` (non-bloquant).
///
/// # Errors
///
/// - `EINVAL` : adresse non alignée, flags invalides, ou `SYNC | ASYNC`
///   simultanés.
/// - `ENOMEM` : plage non entièrement mappée.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::msync;
/// use air_sys_types::mem::MsyncFlags;
/// use core::ptr::NonNull;
///
/// # fn example(address: NonNull<u8>) {
/// msync(address, 4096, MsyncFlags::SYNC).expect("msync");
/// # }
/// ```
pub fn msync(address: NonNull<u8>, length: usize, flags: MsyncFlags) -> Result<(), Errno> {
    // SAFETY: msync(2) synchronise une plage de pages vers le fichier
    // sous-jacent. L'appelant garantit que [address, address+length) est mappée.
    let ret = unsafe { raw_syscall_msync(address.as_ptr() as u64, length, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Accès inter-processus
// ─────────────────────────────────────────────────────────────────────────

/// Lit la mémoire d'un autre processus sans `ptrace`.
///
/// Wrappeur de `process_vm_readv(2)` (Linux 3.2+). Lit depuis les
/// segments `remote_iov` du processus `pid` dans `local_iov`.
///
/// # Parameters
///
/// - `pid` : PID cible (doit avoir les mêmes UID/GID ou `CAP_SYS_PTRACE`).
/// - `local_iov` : buffers locaux de destination.
/// - `remote_iov` : segments dans l'espace d'adressage du processus cible.
/// - `flags` : réservé, doit être 0.
///
/// # Errors
///
/// - `ESRCH` : processus cible introuvable.
/// - `EPERM` : permissions insuffisantes.
/// - `EINVAL` : `flags` non nul, ou `iov` dépasse `UIO_MAXIOV`.
/// - `EFAULT` : adresse locale ou distante invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::process_vm_readv;
/// use air_sys_types::{Pid, mem::RemoteIoSlice};
/// use air_sys_types::net::IoSliceMut;
///
/// # fn example(target: Pid, remote_addr: u64) {
/// let mut buffer = [0u8; 64];
/// let mut local = [IoSliceMut::new(&mut buffer)];
/// let remote = [RemoteIoSlice { addr: remote_addr, len: 64 }];
/// let n = process_vm_readv(target, &mut local, &remote, 0)
///     .expect("process_vm_readv");
/// # }
/// ```
pub fn process_vm_readv(
    pid: Pid,
    local_iov: &mut [IoSliceMut<'_>],
    remote_iov: &[RemoteIoSlice],
    flags: u32,
) -> Result<usize, Errno> {
    let local_ptr = local_iov.as_ptr() as u64;
    let local_cnt = local_iov.len() as u64;
    let remote_ptr = remote_iov.as_ptr() as u64;
    let remote_cnt = remote_iov.len() as u64;
    // SAFETY:
    // - process_vm_readv(2) lit la mémoire distante et écrit dans les
    //   buffers locaux décrits par local_iov.
    // - IoSliceMut est #[repr(C)] compatible avec `struct iovec` Linux.
    // - RemoteIoSlice est #[repr(C)] compatible avec `struct iovec` Linux
    //   (layout identique : { ptr/addr: u64, len: usize } sur LP64).
    // - Les slices sont valides pour la durée du syscall (références Rust).
    // - pid est un Pid valide (newtype sur i32).
    let ret = unsafe {
        raw_syscall_process_vm_readv(
            pid.as_raw(),
            local_ptr,
            local_cnt,
            remote_ptr,
            remote_cnt,
            u64::from(flags),
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Écrit dans la mémoire d'un autre processus sans `ptrace`.
///
/// Wrappeur de `process_vm_writev(2)` (Linux 3.2+). Écrit depuis
/// `local_iov` vers les segments `remote_iov` du processus `pid`.
///
/// # Parameters
///
/// - `pid` : PID cible.
/// - `local_iov` : buffers locaux source.
/// - `remote_iov` : segments cibles dans l'espace d'adressage distant.
/// - `flags` : réservé, doit être 0.
///
/// # Errors
///
/// Voir [`process_vm_readv`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::mem::process_vm_writev;
/// use air_sys_types::{Pid, mem::RemoteIoSlice};
/// use air_sys_types::net::IoSlice;
///
/// # fn example(target: Pid, remote_addr: u64) {
/// let data = b"hello";
/// let local = [IoSlice::new(data)];
/// let remote = [RemoteIoSlice { addr: remote_addr, len: data.len() }];
/// process_vm_writev(target, &local, &remote, 0).expect("process_vm_writev");
/// # }
/// ```
pub fn process_vm_writev(
    pid: Pid,
    local_iov: &[IoSlice<'_>],
    remote_iov: &[RemoteIoSlice],
    flags: u32,
) -> Result<usize, Errno> {
    let local_ptr = local_iov.as_ptr() as u64;
    let local_cnt = local_iov.len() as u64;
    let remote_ptr = remote_iov.as_ptr() as u64;
    let remote_cnt = remote_iov.len() as u64;
    // SAFETY:
    // - process_vm_writev(2) lit les buffers locaux décrits par local_iov
    //   et écrit dans la mémoire distante décrite par remote_iov.
    // - IoSlice est #[repr(C)] compatible avec `struct iovec` Linux.
    // - RemoteIoSlice est #[repr(C)] compatible avec `struct iovec` Linux.
    // - Les slices sont valides pour la durée du syscall.
    // - pid est un Pid valide (newtype sur i32).
    let ret = unsafe {
        raw_syscall_process_vm_writev(
            pid.as_raw(),
            local_ptr,
            local_cnt,
            remote_ptr,
            remote_cnt,
            u64::from(flags),
        )
    };
    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 — mmap
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mmap(
    address: u64,
    length: usize,
    prot: i32,
    flags: i32,
    fd: i64,
    offset: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mmap (x86_64 = 9). 6 arguments : rdi, rsi, rdx, r10, r8, r9.
    // Le kernel mappe une plage de mémoire et retourne l'adresse ou -errno.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 9_i64,
            in("rdi") address,
            in("rsi") length,
            in("rdx") i64::from(prot),
            in("r10") i64::from(flags),
            in("r8")  fd,
            in("r9")  offset,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mmap(
    address: u64,
    length: usize,
    prot: i32,
    flags: i32,
    fd: i64,
    offset: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mmap (aarch64 = 222). x8=nr, x0-x5=args, retour en x0.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  222_i64,
            inout("x0") address => ret,
            in("x1")  length,
            in("x2")  i64::from(prot),
            in("x3")  i64::from(flags),
            in("x4")  fd,
            in("x5")  offset,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — munmap
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_munmap(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_munmap (x86_64 = 11). Libère le mapping ; pas d'accès
    // mémoire utilisateur par le syscall lui-même.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 11_i64,
            in("rdi") address,
            in("rsi") length,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_munmap(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_munmap (aarch64 = 215).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  215_i64,
            inout("x0") address => ret,
            in("x1")  length,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — mremap
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mremap(
    old_addr: u64,
    old_len: usize,
    new_len: usize,
    flags: i32,
    new_addr: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mremap (x86_64 = 25). 5 arguments : rdi, rsi, rdx, r10, r8.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 25_i64,
            in("rdi") old_addr,
            in("rsi") old_len,
            in("rdx") new_len,
            in("r10") i64::from(flags),
            in("r8")  new_addr,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mremap(
    old_addr: u64,
    old_len: usize,
    new_len: usize,
    flags: i32,
    new_addr: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mremap (aarch64 = 216).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  216_i64,
            inout("x0") old_addr => ret,
            in("x1")  old_len,
            in("x2")  new_len,
            in("x3")  i64::from(flags),
            in("x4")  new_addr,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — mprotect
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mprotect(address: u64, length: usize, prot: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mprotect (x86_64 = 10). Scalaires uniquement.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 10_i64,
            in("rdi") address,
            in("rsi") length,
            in("rdx") i64::from(prot),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mprotect(address: u64, length: usize, prot: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mprotect (aarch64 = 226).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  226_i64,
            inout("x0") address => ret,
            in("x1")  length,
            in("x2")  i64::from(prot),
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — madvise
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_madvise(address: u64, length: usize, advice: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_madvise (x86_64 = 28). Scalaires uniquement ; readonly
    // serait incorrect (le kernel peut modifier des métadonnées internes).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 28_i64,
            in("rdi") address,
            in("rsi") length,
            in("rdx") i64::from(advice),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_madvise(address: u64, length: usize, advice: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_madvise (aarch64 = 233).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  233_i64,
            inout("x0") address => ret,
            in("x1")  length,
            in("x2")  i64::from(advice),
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — mlock / mlock2 / munlock / mlockall / munlockall
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mlock(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlock (x86_64 = 149).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 149_i64,
            in("rdi") address,
            in("rsi") length,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mlock(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlock (aarch64 = 228).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  228_i64,
            inout("x0") address => ret,
            in("x1")  length,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mlock2(address: u64, length: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlock2 (x86_64 = 325).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 325_i64,
            in("rdi") address,
            in("rsi") length,
            in("rdx") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mlock2(address: u64, length: usize, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlock2 (aarch64 = 284).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  284_i64,
            inout("x0") address => ret,
            in("x1")  length,
            in("x2")  i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_munlock(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_munlock (x86_64 = 150).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 150_i64,
            in("rdi") address,
            in("rsi") length,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_munlock(address: u64, length: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_munlock (aarch64 = 229).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  229_i64,
            inout("x0") address => ret,
            in("x1")  length,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_mlockall(flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlockall (x86_64 = 151). Un seul scalaire.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 151_i64,
            in("rdi") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_mlockall(flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_mlockall (aarch64 = 230).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  230_i64,
            inout("x0") i64::from(flags) => ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_munlockall() -> i64 {
    let ret: i64;
    // SAFETY: SYS_munlockall (x86_64 = 152). Aucun argument.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 152_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_munlockall() -> i64 {
    let ret: i64;
    // SAFETY: SYS_munlockall (aarch64 = 231). Aucun argument.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  231_i64,
            inout("x0") 0_i64 => ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — memfd_create / memfd_secret
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_memfd_create(name_ptr: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_memfd_create (x86_64 = 319). Lit la chaîne NUL à `name_ptr`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 319_i64,
            in("rdi") name_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_memfd_create(name_ptr: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_memfd_create (aarch64 = 279).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  279_i64,
            inout("x0") name_ptr => ret,
            in("x1")  i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_memfd_secret(flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_memfd_secret (x86_64 = 447). Un seul scalaire.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 447_i64,
            in("rdi") 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_memfd_secret(flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_memfd_secret (aarch64 = 447).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  447_i64,
            inout("x0") i64::from(flags) => ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — msync
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_msync(address: u64, length: usize, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_msync (x86_64 = 26). Scalaires ; le kernel lit les pages
    // mais ne modifie pas la mémoire utilisateur via le pointeur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 26_i64,
            in("rdi") address,
            in("rsi") length,
            in("rdx") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_msync(address: u64, length: usize, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_msync (aarch64 = 227).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  227_i64,
            inout("x0") address => ret,
            in("x1")  length,
            in("x2")  i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — process_vm_readv / process_vm_writev
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_process_vm_readv(
    pid: i32,
    local_iov: u64,
    liovcnt: u64,
    remote_iov: u64,
    riovcnt: u64,
    flags: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_process_vm_readv (x86_64 = 310). 6 arguments.
    // Le kernel lit depuis l'espace d'adressage distant et écrit dans
    // les buffers locaux décrits par local_iov.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 310_i64,
            in("rdi") i64::from(pid),
            in("rsi") local_iov,
            in("rdx") liovcnt,
            in("r10") remote_iov,
            in("r8")  riovcnt,
            in("r9")  flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_process_vm_readv(
    pid: i32,
    local_iov: u64,
    liovcnt: u64,
    remote_iov: u64,
    riovcnt: u64,
    flags: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_process_vm_readv (aarch64 = 270).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  270_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1")  local_iov,
            in("x2")  liovcnt,
            in("x3")  remote_iov,
            in("x4")  riovcnt,
            in("x5")  flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_process_vm_writev(
    pid: i32,
    local_iov: u64,
    liovcnt: u64,
    remote_iov: u64,
    riovcnt: u64,
    flags: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_process_vm_writev (x86_64 = 311). 6 arguments.
    // Le kernel lit depuis les buffers locaux et écrit dans l'espace
    // d'adressage distant.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 311_i64,
            in("rdi") i64::from(pid),
            in("rsi") local_iov,
            in("rdx") liovcnt,
            in("r10") remote_iov,
            in("r8")  riovcnt,
            in("r9")  flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_process_vm_writev(
    pid: i32,
    local_iov: u64,
    liovcnt: u64,
    remote_iov: u64,
    riovcnt: u64,
    flags: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_process_vm_writev (aarch64 = 271).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8")  271_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1")  local_iov,
            in("x2")  liovcnt,
            in("x3")  remote_iov,
            in("x4")  riovcnt,
            in("x5")  flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

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

// Tests fonctionnels sur `Arc`/atomiques `std` (hors loom : créer un `Arc`
// loom hors d'un `loom::model` paniquerait). La preuve de concurrence vit dans
// `mod loom_refcount` (sous `cfg(loom)`).
#[cfg(all(test, target_os = "linux", not(loom)))]
mod tests;

// ───────────────────────────────────────────────────────────────────────────
// Preuve de concurrence (loom) — le compteur fort de `MmapRegion` est correct
// sous réordonnancement : des drops **concurrents** des gardes de vivacité
// produisent `munmap` **exactement une fois**, jamais en avance.
//
// Exécuter : `RUSTFLAGS="--cfg loom" cargo test -p air-sys-syscall --lib loom`.
// ───────────────────────────────────────────────────────────────────────────

#[cfg(loom)]
mod loom_refcount {
    use super::{MmapRegion, ProbeCounter};
    use core::sync::atomic::Ordering;
    use loom::sync::Arc;

    #[test]
    fn munmap_exactly_once_under_concurrent_guard_drops() {
        loom::model(|| {
            let counter = Arc::new(ProbeCounter::new(0));
            let region = MmapRegion::new_for_test(64, Arc::clone(&counter));

            // Deux gardes « en vol » ; l'utilisateur lâche la région.
            let g1 = region.liveness_handle();
            let g2 = region.liveness_handle();
            drop(region);
            assert_eq!(counter.load(Ordering::SeqCst), 0, "munmap en avance");

            // Les deux gardes tombent en parallèle : le compteur fort garantit
            // un seul drop de l'inner → un seul `munmap`, quel que soit l'ordre.
            let t1 = loom::thread::spawn(move || drop(g1));
            let t2 = loom::thread::spawn(move || drop(g2));
            t1.join().expect("join t1");
            t2.join().expect("join t2");

            assert_eq!(
                counter.load(Ordering::SeqCst),
                1,
                "munmap doit survenir exactement une fois"
            );
        });
    }
}