air_sys_syscall/io_uring/

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

//! **Registration** (Temps 3a) : enregistrement de ressources fixes auprès du
//! kernel via `io_uring_register(2)` (n° 427) — tables de descripteurs fixes
//! ([`FixedFdTable`]), buffers enregistrés ([`RegisteredBuffers`]), ring fd
//! enregistré, eventfd, personality, réglage du pool io-wq, NAPI, horloge. Ce
//! Temps **débloque** les variantes « direct »/« fixed » référencées depuis les
//! Temps 2a–2c.
//!
//! Référence normative : `docs/specs/layer-0/io-uring-3a-registration.md`.
//!
//! **Modèle d'ownership (ADR-028, ADR-032).** Les ressources enregistrées
//! restent valides **tant qu'elles sont enregistrées** : [`FixedFdTable`]
//! **possède** les [`OwnedFd`] des slots remplis ; [`RegisteredBuffers`]
//! possède les buffers épinglés (`Vec<u8>` ou [`MmapRegion`]). Les références
//! d'usage ([`FixedSlot`], [`RegisteredBufferSlice`]) y sont liées par
//! *lifetime* → inutilisables après désenregistrement (sûreté par construction).
//! Le désenregistrement **restitue l'intégralité** des ressources reprises
//! (zéro discard) ; toute consommation explicite (FD remplacé par `set`, buffer
//! remplacé par `update`) est documentée par contrat.
//!
//! **`io_uring_register` est synchrone** (pas une op de SQE) : ces façades
//! appellent directement la couture `syscall::register` sur le FD du ring
//! (emprunté `&mut` le temps de l'appel), et **n'enregistrent jamais
//! automatiquement** (ADR-022 D4) — l'application le demande.
//!
//! **Legacy évacués** : seules les variantes `*2` taguées sont exposées (pas de
//! `REGISTER_BUFFERS`/`FILES`/`FILES_UPDATE` v1).

use super::owned::OwnedOp;
use super::{Completion, IoUring, SubmissionToken, raw, syscall};
use crate::mem::MmapRegion;
use air_sys_types::Errno;
use air_sys_types::fd::{AsRawFd, BorrowedFd, OwnedFd};
use air_sys_types::fs::{DirFd, OpenHow};
use air_sys_types::net::{AcceptFlags, SocketDomain, SocketType};
use air_sys_types::system::CpuSet;
use alloc::boxed::Box;
use alloc::vec::Vec;
use core::marker::PhantomData;
use core::num::NonZeroU32;
use core::ops::Range;

// ───────────────────────────────────────────────────────────────────────────
// Couture register : appel synchrone + décodage errno
// ───────────────────────────────────────────────────────────────────────────

/// Appelle `io_uring_register(2)` sur le FD du ring et décode le retour.
///
/// Rend la valeur non-négative renvoyée par le kernel (`0` en général, l'**id**
/// pour `REGISTER_PERSONALITY`, un compte pour certains opcodes).
///
/// # Safety
///
/// `(opcode, arg, nr_args)` doivent être **cohérents** : `arg` pointe une
/// structure valide et accessible du type attendu par `opcode`, dimensionnée
/// selon la convention du register opcode (`nr_args`). L'appelant emprunte le
/// ring `&mut` le temps de l'appel (pas de soumission concurrente).
unsafe fn register_raw(ring: &IoUring, opcode: u32, arg: u64, nr_args: u32) -> Result<i32, Errno> {
    // SAFETY: déléguée à l'appelant (cf. doc) ; `fd_raw` est un ring fd valide.
    let ret = unsafe { syscall::register(ring.fd_raw(), opcode, arg, nr_args) };
    if ret < 0 {
        return Err(raw::errno_from_negative_syscall_ret(ret));
    }
    // Les register opcodes rendent un petit entier non-négatif (toujours ≤ i32).
    Ok(i32::try_from(ret).unwrap_or(0))
}

/// Convertit un indice `u32` (slot/buffer) en `usize` (toujours valide sur la
/// cible LP64). La borne effective est vérifiée par le `get`/`get_mut` qui suit
/// (l'`expect` est structurellement inatteignable, comme `ring::usz`).
fn usz(index: u32) -> usize {
    usize::try_from(index).expect("u32 ⊆ usize sur cible LP64")
}

/// `nr_args` d'un register opcode dont l'argument est une **structure unique** :
/// la **taille en octets** de cette structure (convention kernel de
/// `FILES2`/`BUFFERS2` et `*_UPDATE2`). Les tailles (32 o) sont figées par les
/// `assert` de layout de `raw.rs` ⇒ l'`unwrap_or` est structurellement inerte.
fn struct_nr_args<T>() -> u32 {
    u32::try_from(core::mem::size_of::<T>()).unwrap_or(0)
}

// ───────────────────────────────────────────────────────────────────────────
// Types de la surface 3a
// ───────────────────────────────────────────────────────────────────────────

/// Cible d'un slot pour une variante « direct » : indice **précis**, ou
/// **auto-allocation** par le kernel.
///
/// [`FixedSlotTarget::Alloc`] est un `enum` typé, **jamais** la sentinelle
/// kernel `IORING_FILE_INDEX_ALLOC` (`~0U`) exposée (ADR-021 conv. 1).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FixedSlotTarget {
    /// Slot précis (l'indice exact dans la table de FD fixes).
    Index(u32),
    /// Le kernel choisit un slot libre (dans la plage d'`set_alloc_range`) et le
    /// rend dans `cqe->res` ([`Completion::allocated_slot`]) ; `-ENFILE` si plein.
    Alloc,
}

impl FixedSlotTarget {
    /// Encode le `file_index` du SQE : `Alloc` ⇒ sentinelle kernel `~0U` ;
    /// `Index(n)` ⇒ `n + 1` (le kernel décrémente ; `0` = « pas de slot »).
    fn to_file_index(self) -> Result<u32, Errno> {
        match self {
            Self::Alloc => Ok(raw::IORING_FILE_INDEX_ALLOC),
            // `n + 1` : `u32::MAX` (qui collisionnerait avec `~0U`/Alloc) ⇒ EINVAL.
            Self::Index(n) => n.checked_add(1).ok_or(Errno::EINVAL),
        }
    }
}

/// Identité (credentials) enregistrée dans le ring ([`IoUring::register_personality`]).
///
/// L'**id** opaque est placé dans `sqe.personality` (via
/// [`IoUring::with_personality`]) pour exécuter une op avec ces credentials.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Personality(u16);

impl Personality {
    /// Id kernel de la personality (placé dans `sqe.personality`).
    #[must_use]
    pub fn id(self) -> u16 {
        self.0
    }

    /// Id brut, usage interne (façade `with_personality`).
    pub(crate) fn raw(self) -> u16 {
        self.0
    }
}

/// Plafonds de workers io-wq rendus par [`IoUring::set_work_queue_max_workers`]
/// (les valeurs **précédentes**, réécrites par le kernel).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct WorkQueueWorkerLimits {
    /// Plafond de la catégorie **bornée** (`IO_WQ_BOUND` : I/O disque).
    pub bounded: u32,
    /// Plafond de la catégorie **non-bornée** (`IO_WQ_UNBOUND` : réseau).
    pub unbounded: u32,
}

/// Configuration du busy-poll NAPI ([`IoUring::register_napi`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct NapiConfig {
    /// Délai de busy-poll en **microsecondes** (`busy_poll_to`). `0` désactive.
    pub busy_poll_us: u32,
    /// Préfère le busy-poll (`prefer_busy_poll`).
    pub prefer_busy_poll: bool,
}

/// Source d'horloge des timeouts du ring ([`IoUring::register_clock`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClockSource {
    /// `CLOCK_MONOTONIC` : monotone, hors veille.
    Monotonic,
    /// `CLOCK_BOOTTIME` : monotone incluant le temps de veille.
    Boottime,
    /// `CLOCK_REALTIME` : temps réel (peut sauter).
    Realtime,
}

impl ClockSource {
    /// Valeur kernel (`CLOCK_*`).
    fn clockid(self) -> u32 {
        match self {
            Self::Monotonic => raw::CLOCK_MONOTONIC,
            Self::Boottime => raw::CLOCK_BOOTTIME,
            Self::Realtime => raw::CLOCK_REALTIME,
        }
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Table de descripteurs fixes — FixedFdTable
// ───────────────────────────────────────────────────────────────────────────

/// Table de descripteurs de fichiers **fixes** (`REGISTER_FILES2`, 13).
///
/// Possède les [`OwnedFd`] des slots remplis ; sparse par défaut (slots vides à
/// remplir plus tard). Les opérations sur FD fixe ([`FixedSlot`]) évitent au
/// kernel la résolution du FD à chaque op (`IOSQE_FIXED_FILE`).
#[derive(Debug)]
pub struct FixedFdTable {
    /// Un slot par capacité : `Some(fd)` rempli, `None` vide (sparse). Possède
    /// les FD tant qu'ils sont enregistrés (restitués au désenregistrement).
    slots: Vec<Option<OwnedFd>>,
}

impl FixedFdTable {
    /// `REGISTER_FILES2` (13) : table **sparse** de `capacity` slots vides.
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` : [`Errno::EINVAL`] (capacité trop grande,
    /// déjà enregistré), [`Errno::EMFILE`]/[`Errno::ENOMEM`].
    pub fn register(ring: &mut IoUring, capacity: NonZeroU32) -> Result<Self, Errno> {
        let nr = capacity.get();
        let rr = raw::IoUringRsrcRegister {
            nr,
            flags: raw::IORING_RSRC_REGISTER_SPARSE,
            resv2: 0,
            data: 0,
            tags: 0,
        };
        // SAFETY: FILES2 attend une `io_uring_rsrc_register` (nr_args == 1) ;
        // sparse ⇒ `data` nul (aucun FD initial lu). `rr` vit pendant l'appel.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_FILES2,
                core::ptr::from_ref(&rr) as u64,
                struct_nr_args::<raw::IoUringRsrcRegister>(),
            )?;
        }
        Ok(Self {
            slots: (0..nr).map(|_| None).collect(),
        })
    }

    /// `REGISTER_FILES2` (13) avec un jeu **initial** de FD (slots remplis dans
    /// l'ordre, à partir de l'indice 0). Les FD sont possédés par la table.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `fds` est vide ou déborde un `u32` ; erreurs de
    /// `io_uring_register`.
    pub fn register_with(ring: &mut IoUring, fds: Vec<OwnedFd>) -> Result<Self, Errno> {
        let nr = u32::try_from(fds.len()).map_err(|_| Errno::EINVAL)?;
        if nr == 0 {
            return Err(Errno::EINVAL);
        }
        // Tableau de FD bruts lu par le kernel pendant l'enregistrement synchrone.
        let raw_fds: Vec<i32> = fds.iter().map(AsRawFd::as_raw_fd).collect();
        let rr = raw::IoUringRsrcRegister {
            nr,
            flags: 0,
            resv2: 0,
            data: raw_fds.as_ptr() as u64,
            tags: 0,
        };
        // SAFETY: FILES2 (nr_args == 1) ; `data` pointe `nr` `i32` (`raw_fds`)
        // vivants pour la durée de l'appel synchrone ; `rr` vit aussi.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_FILES2,
                core::ptr::from_ref(&rr) as u64,
                struct_nr_args::<raw::IoUringRsrcRegister>(),
            )?;
        }
        Ok(Self {
            slots: fds.into_iter().map(Some).collect(),
        })
    }

    /// `REGISTER_FILES_UPDATE2` (14) : place/remplace le FD du slot `slot`.
    ///
    /// **Consomme** tout FD précédemment présent dans ce slot (fermé) — transfert
    /// d'ownership voulu, gravé dans la signature (ADR-032 : consommation
    /// explicite ≠ discard).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `slot` est hors borne ; erreurs de `io_uring_register`.
    pub fn set(&mut self, ring: &mut IoUring, slot: u32, fd: OwnedFd) -> Result<(), Errno> {
        let slot_ref = self.slots.get_mut(usz(slot)).ok_or(Errno::EINVAL)?;
        let raw_fd = fd.as_raw_fd();
        let up = raw::IoUringRsrcUpdate2 {
            offset: slot,
            resv: 0,
            data: core::ptr::from_ref(&raw_fd) as u64,
            tags: 0,
            nr: 1,
            resv2: 0,
        };
        // SAFETY: FILES_UPDATE2 (nr_args == 1) ; `data` pointe un `i32` (`raw_fd`)
        // vivant ; `up` vit pendant l'appel. Le slot n'est mis à jour côté Air
        // qu'**après** le succès kernel (sinon `fd` est rendu via le `?`).
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_FILES_UPDATE2,
                core::ptr::from_ref(&up) as u64,
                struct_nr_args::<raw::IoUringRsrcUpdate2>(),
            )?;
        }
        // L'ancien FD (le cas échéant) est fermé par ce remplacement.
        *slot_ref = Some(fd);
        Ok(())
    }

    /// `REGISTER_FILES_UPDATE2` (14) avec `fd = -1` : **vide** le slot. Rend le
    /// FD qu'il contenait (zéro discard), ou `None` s'il était déjà vide.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `slot` est hors borne ; erreurs de `io_uring_register`.
    pub fn clear(&mut self, ring: &mut IoUring, slot: u32) -> Result<Option<OwnedFd>, Errno> {
        let slot_ref = self.slots.get_mut(usz(slot)).ok_or(Errno::EINVAL)?;
        let clear_fd: i32 = -1;
        let up = raw::IoUringRsrcUpdate2 {
            offset: slot,
            resv: 0,
            data: core::ptr::from_ref(&clear_fd) as u64,
            tags: 0,
            nr: 1,
            resv2: 0,
        };
        // SAFETY: FILES_UPDATE2 (nr_args == 1) ; `data` pointe un `i32` (`-1`)
        // vivant ; `up` vit pendant l'appel.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_FILES_UPDATE2,
                core::ptr::from_ref(&up) as u64,
                struct_nr_args::<raw::IoUringRsrcUpdate2>(),
            )?;
        }
        Ok(slot_ref.take())
    }

    /// `REGISTER_FILE_ALLOC_RANGE` (25) : borne la plage `[start, end)` des slots
    /// éligibles à l'auto-allocation ([`FixedSlotTarget::Alloc`]).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `range` est inversé ou déborde la capacité ; erreurs
    /// de `io_uring_register`.
    pub fn set_alloc_range(&mut self, ring: &mut IoUring, range: Range<u32>) -> Result<(), Errno> {
        // `end - start` : `None` (donc EINVAL) si `start > end`.
        let len = range.end.checked_sub(range.start).ok_or(Errno::EINVAL)?;
        let capacity = u32::try_from(self.slots.len()).unwrap_or(u32::MAX);
        if range.end > capacity {
            return Err(Errno::EINVAL);
        }
        let index_range = raw::IoUringFileIndexRange {
            off: range.start,
            len,
            resv: 0,
        };
        // SAFETY: FILE_ALLOC_RANGE attend une `io_uring_file_index_range`
        // (nr_args == 1) ; `index_range` vit pendant l'appel.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_FILE_ALLOC_RANGE,
                core::ptr::from_ref(&index_range) as u64,
                0,
            )?;
        }
        Ok(())
    }

    /// `UNREGISTER_FILES` (3) : désenregistre toute la table et **rend** les FD
    /// restants (restitution intégrale, ADR-032).
    ///
    /// **Sûreté par construction** : un [`FixedSlot`] emprunté à la table ne peut
    /// pas survivre à ce désenregistrement (qui consomme `self`) — le code
    /// suivant **ne compile pas** :
    ///
    /// ```compile_fail
    /// # use air_sys_syscall::io_uring::{FixedFdTable, IoUring};
    /// # use core::num::NonZeroU32;
    /// # fn demo(ring: &mut IoUring) {
    /// let table = FixedFdTable::register(ring, NonZeroU32::new(4).unwrap()).unwrap();
    /// let slot = table.slot(0).unwrap();         // emprunte `table`
    /// let _fds = table.unregister(ring).unwrap(); // déplace `table`…
    /// let _ = slot.index();                       // …emprunt encore vivant ⇒ ERREUR
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si rien n'est
    /// enregistré, [`Errno::EBUSY`]). En cas d'erreur, les FD possédés sont
    /// fermés (la table est consommée).
    pub fn unregister(self, ring: &mut IoUring) -> Result<Vec<OwnedFd>, Errno> {
        // SAFETY: UNREGISTER_FILES ne lit aucune mémoire (arg/nr_args nuls).
        unsafe {
            register_raw(ring, raw::IORING_UNREGISTER_FILES, 0, 0)?;
        }
        Ok(self.slots.into_iter().flatten().collect())
    }

    /// Référence empruntée au slot `slot` **pour usage en opération**
    /// (`IOSQE_FIXED_FILE`), si l'indice est **dans la capacité** de la table.
    /// `None` si hors borne.
    ///
    /// La référence est bornée par l'indice, pas par le suivi d'ownership : un
    /// slot peut avoir été rempli par une variante « direct » (côté kernel, sans
    /// `OwnedFd` côté Air). Référencer un slot **vide** est sûr — l'op échoue
    /// alors proprement à la complétion (`EBADF`), jamais d'UB.
    #[must_use]
    pub fn slot(&self, slot: u32) -> Option<FixedSlot<'_>> {
        if usz(slot) < self.slots.len() {
            Some(FixedSlot {
                index: slot,
                _marker: PhantomData,
            })
        } else {
            None
        }
    }
}

/// Référence empruntée à un slot d'une [`FixedFdTable`], liée à la table par
/// *lifetime* — inutilisable après son désenregistrement (sûreté par
/// construction).
#[derive(Debug, Clone, Copy)]
pub struct FixedSlot<'t> {
    /// Indice du slot dans la table.
    index: u32,
    /// Lie la référence à la table (empêche l'usage après `unregister`).
    _marker: PhantomData<&'t FixedFdTable>,
}

impl FixedSlot<'_> {
    /// Indice du slot dans la table de FD fixes.
    #[must_use]
    pub fn index(&self) -> u32 {
        self.index
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Buffers enregistrés — RegisteredBuffers
// ───────────────────────────────────────────────────────────────────────────

/// Origine des buffers d'une [`RegisteredBuffers`] (mémoire possédée).
#[derive(Debug)]
enum BufferBacking {
    /// Buffers `Vec<u8>` possédés (épinglés par le kernel à l'enregistrement).
    Owned(Vec<Vec<u8>>),
    /// Régions mmap possédées (data plane : `memfd` partagé AirCom).
    Mapped(Vec<MmapRegion>),
    /// Buffers **clonés** d'un autre ring ([`RegisteredBuffers::clone_from`]) :
    /// la mémoire est possédée par le ring **source** (qui doit rester vivant).
    Cloned,
}

/// Buffers enregistrés (`REGISTER_BUFFERS2`, 15) : l'épinglage et la traduction
/// d'adresses sont faits **une fois** ⇒ `read_fixed`/`write_fixed` évitent ce
/// coût par op (cas chaud du data plane AirCom).
///
/// Possède les buffers épinglés ; les références d'usage
/// ([`RegisteredBufferSlice`]) y sont liées par *lifetime*.
#[derive(Debug)]
pub struct RegisteredBuffers {
    backing: BufferBacking,
}

impl RegisteredBuffers {
    /// Construit les `iovec` désignant `bufs` puis enregistre via `BUFFERS2`.
    /// Cœur commun [`Self::register`] / [`Self::register_mmap`].
    fn register_iovecs(
        ring: &mut IoUring,
        iovecs: &[raw::Iovec],
        backing: BufferBacking,
    ) -> Result<Self, Errno> {
        let nr = u32::try_from(iovecs.len()).map_err(|_| Errno::EINVAL)?;
        if nr == 0 {
            return Err(Errno::EINVAL);
        }
        let rr = raw::IoUringRsrcRegister {
            nr,
            flags: 0,
            resv2: 0,
            data: iovecs.as_ptr() as u64,
            tags: 0,
        };
        // SAFETY: BUFFERS2 attend une `io_uring_rsrc_register` (nr_args == 1) ;
        // `data` pointe `nr` `iovec` vivants pour la durée de l'appel ; le kernel
        // épingle les pages référencées (synchrone). La mémoire des buffers est
        // possédée par `backing` (vivante tant que la table existe).
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_BUFFERS2,
                core::ptr::from_ref(&rr) as u64,
                struct_nr_args::<raw::IoUringRsrcRegister>(),
            )?;
        }
        Ok(Self { backing })
    }

    /// `REGISTER_BUFFERS2` (15) : épingle des buffers `Vec<u8>` possédés.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `buffers` est vide ou déborde un `u32` ; erreurs de
    /// `io_uring_register` ([`Errno::ENOMEM`], [`Errno::EFAULT`]).
    pub fn register(ring: &mut IoUring, buffers: Vec<Vec<u8>>) -> Result<Self, Errno> {
        let iovecs: Vec<raw::Iovec> = buffers
            .iter()
            .map(|b| raw::Iovec {
                iov_base: b.as_ptr() as *mut u8,
                iov_len: b.len(),
            })
            .collect();
        Self::register_iovecs(ring, &iovecs, BufferBacking::Owned(buffers))
    }

    /// `REGISTER_BUFFERS2` (15) adossé à des [`MmapRegion`] **possédées** (data
    /// plane : `memfd` partagé). Réutilise le handle de vivacité de `family-mem`.
    ///
    /// # Errors
    ///
    /// Voir [`RegisteredBuffers::register`].
    pub fn register_mmap(ring: &mut IoUring, regions: Vec<MmapRegion>) -> Result<Self, Errno> {
        let iovecs: Vec<raw::Iovec> = regions
            .iter()
            .map(|r| raw::Iovec {
                iov_base: r.as_ptr() as *mut u8,
                iov_len: r.len(),
            })
            .collect();
        Self::register_iovecs(ring, &iovecs, BufferBacking::Mapped(regions))
    }

    /// `REGISTER_BUFFERS_UPDATE` (16) : remplace le buffer d'indice `index`.
    ///
    /// **Consomme** le buffer précédent (remplacement explicite). Réservé au
    /// backing `Vec<u8>` (les variantes mmap/clonées rendent [`Errno::EINVAL`]).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `index` est hors borne, ou si le backing n'est pas
    /// `Vec<u8>` ; erreurs de `io_uring_register`.
    pub fn update(&mut self, ring: &mut IoUring, index: u32, buffer: Vec<u8>) -> Result<(), Errno> {
        let BufferBacking::Owned(buffers) = &mut self.backing else {
            return Err(Errno::EINVAL);
        };
        let slot = buffers.get_mut(usz(index)).ok_or(Errno::EINVAL)?;
        let iov = raw::Iovec {
            iov_base: buffer.as_ptr() as *mut u8,
            iov_len: buffer.len(),
        };
        let up = raw::IoUringRsrcUpdate2 {
            offset: index,
            resv: 0,
            data: core::ptr::from_ref(&iov) as u64,
            tags: 0,
            nr: 1,
            resv2: 0,
        };
        // SAFETY: BUFFERS_UPDATE (nr_args == 1) ; `data` pointe un `iovec` vivant
        // désignant `buffer` (vivant) ; `up` vit pendant l'appel. Le slot n'est
        // remplacé côté Air qu'**après** le succès kernel.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_BUFFERS_UPDATE,
                core::ptr::from_ref(&up) as u64,
                struct_nr_args::<raw::IoUringRsrcUpdate2>(),
            )?;
        }
        *slot = buffer;
        Ok(())
    }

    /// `REGISTER_CLONE_BUFFERS` (30) : clone les buffers enregistrés du ring
    /// `src` (partage thread-per-core sans réépinglage).
    ///
    /// La mémoire reste possédée par `src` : la table rendue ne possède rien et
    /// n'est valide que **tant que `src` garde ses buffers enregistrés et
    /// vivants** (consommation par contrat). Les [`RegisteredBufferSlice`] à
    /// utiliser proviennent de la table de `src` (mêmes adresses, même process).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`], [`Errno::EBUSY`] si la
    /// table de destination est déjà peuplée).
    pub fn clone_from(ring: &mut IoUring, src: &IoUring) -> Result<Self, Errno> {
        let clone = raw::IoUringCloneBuffers {
            src_fd: src.fd_raw().cast_unsigned(),
            flags: 0,
            pad: [0; 6],
        };
        // SAFETY: CLONE_BUFFERS attend une `io_uring_clone_buffers` ; `clone` vit
        // pendant l'appel ; `src_fd` est le FD du ring source vivant.
        unsafe {
            register_raw(
                ring,
                raw::IORING_REGISTER_CLONE_BUFFERS,
                core::ptr::from_ref(&clone) as u64,
                1,
            )?;
        }
        Ok(Self {
            backing: BufferBacking::Cloned,
        })
    }

    /// `UNREGISTER_BUFFERS` (1) : désenregistre et **rend** les buffers `Vec<u8>`
    /// possédés (restitution intégrale, ADR-032).
    ///
    /// Pour un backing mmap, les régions sont **consommées** (munmap au dernier
    /// drop — la signature `Vec<Vec<u8>>` ne peut les porter ; clonez la
    /// [`MmapRegion`] avant si besoin). Pour un clone, rien à rendre.
    ///
    /// **Sûreté par construction** : un [`RegisteredBufferSlice`] ne peut pas
    /// survivre à ce désenregistrement — le code suivant **ne compile pas** :
    ///
    /// ```compile_fail
    /// # use air_sys_syscall::io_uring::{IoUring, RegisteredBuffers};
    /// # fn demo(ring: &mut IoUring) {
    /// let buffers = RegisteredBuffers::register(ring, vec![vec![0u8; 16]]).unwrap();
    /// let slice = buffers.slice(0, 0..8).unwrap();  // emprunte `buffers`
    /// let _ = buffers.unregister(ring).unwrap();     // déplace `buffers`…
    /// let _ = slice.len();                           // …emprunt encore vivant ⇒ ERREUR
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register`. En cas d'erreur, les buffers possédés sont
    /// libérés (la table est consommée).
    pub fn unregister(self, ring: &mut IoUring) -> Result<Vec<Vec<u8>>, Errno> {
        // SAFETY: UNREGISTER_BUFFERS ne lit aucune mémoire (arg/nr_args nuls).
        unsafe {
            register_raw(ring, raw::IORING_UNREGISTER_BUFFERS, 0, 0)?;
        }
        match self.backing {
            BufferBacking::Owned(buffers) => Ok(buffers),
            // Régions munmappées / clone sans mémoire propre : rien à restituer.
            BufferBacking::Mapped(_) | BufferBacking::Cloned => Ok(Vec::new()),
        }
    }

    /// Tranche `[range)` du buffer enregistré d'indice `index`, pour
    /// `read_fixed`/`write_fixed`. `None` si l'indice/range est hors borne, ou si
    /// le backing est cloné (géométrie inconnue côté destination).
    #[must_use]
    pub fn slice(&self, index: u32, range: Range<usize>) -> Option<RegisteredBufferSlice<'_>> {
        let idx = usz(index);
        let (base, buf_len) = match &self.backing {
            BufferBacking::Owned(buffers) => {
                let buf = buffers.get(idx)?;
                (buf.as_ptr() as u64, buf.len())
            }
            BufferBacking::Mapped(regions) => {
                let region = regions.get(idx)?;
                (region.as_ptr() as u64, region.len())
            }
            BufferBacking::Cloned => return None,
        };
        if range.end > buf_len {
            return None;
        }
        // `end - start` : `None` si `start > end`.
        let span = range.end.checked_sub(range.start)?;
        let start = u64::try_from(range.start).ok()?;
        let addr = base.checked_add(start)?;
        Some(RegisteredBufferSlice {
            index,
            addr,
            len: span,
            _marker: PhantomData,
        })
    }
}

/// Référence à une tranche d'un buffer enregistré, liée par *lifetime* à la
/// [`RegisteredBuffers`] — `read_fixed` sur une tranche périmée ne compile pas.
#[derive(Debug, Clone, Copy)]
pub struct RegisteredBufferSlice<'b> {
    /// Indice du buffer enregistré (`buf_index` du SQE).
    index: u32,
    /// Adresse de la tranche (dans la mémoire épinglée).
    addr: u64,
    /// Longueur de la tranche en octets.
    len: usize,
    /// Lie la tranche à la table (empêche l'usage après `unregister`).
    _marker: PhantomData<&'b RegisteredBuffers>,
}

impl RegisteredBufferSlice<'_> {
    /// Indice du buffer enregistré.
    #[must_use]
    pub fn index(&self) -> u32 {
        self.index
    }

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

    /// `true` si la tranche est vide.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Registrations portées par l'IoUring (ring fd, eventfd, personality, io-wq,
// napi, horloge) + variantes « direct »/« fixed » et fixed_fd_install.
// ───────────────────────────────────────────────────────────────────────────

impl IoUring {
    // ── Ring fd enregistré (§4) ───────────────────────────────────────────

    /// `REGISTER_RING_FDS` (20) : enregistre le FD du ring → les
    /// `io_uring_enter` suivants utilisent `IORING_ENTER_REGISTERED_RING` (pas
    /// de résolution de FD). Idempotent côté façade : un second appel
    /// ré-enregistre (le kernel rend l'index).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si déjà enregistré côté
    /// kernel, [`Errno::ENXIO`]).
    pub fn register_ring_fd(&mut self) -> Result<(), Errno> {
        let mut update = raw::IoUringRsrcUpdate {
            offset: u32::MAX,
            resv: 0,
            data: u64::from(self.fd_raw().cast_unsigned()),
        };
        // SAFETY: RING_FDS attend un tableau de `io_uring_rsrc_update`
        // (nr_args == 1) ; `update` vit pendant l'appel et le kernel y **réécrit**
        // l'index assigné.
        let ret = unsafe {
            syscall::register(
                self.fd_raw(),
                raw::IORING_REGISTER_RING_FDS,
                core::ptr::from_mut(&mut update) as u64,
                1,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        self.enter_ring_index = Some(update.offset);
        Ok(())
    }

    /// `UNREGISTER_RING_FDS` (21) : désenregistre le FD du ring (retour aux
    /// `enter` par FD ordinaire).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si le ring fd n'était pas enregistré ; erreurs de
    /// `io_uring_register`.
    pub fn unregister_ring_fd(&mut self) -> Result<(), Errno> {
        let index = self.enter_ring_index.ok_or(Errno::EINVAL)?;
        let mut update = raw::IoUringRsrcUpdate {
            offset: index,
            resv: 0,
            data: 0,
        };
        // SAFETY: UNREGISTER_RING_FDS attend un tableau de `io_uring_rsrc_update`
        // (nr_args == 1) ; `update` vit pendant l'appel. On désigne le FD
        // ordinaire (jamais l'index) pour ce register.
        let ret = unsafe {
            syscall::register(
                self.fd_raw(),
                raw::IORING_UNREGISTER_RING_FDS,
                core::ptr::from_mut(&mut update) as u64,
                1,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        self.enter_ring_index = None;
        Ok(())
    }

    // ── eventfd (§5) ──────────────────────────────────────────────────────

    /// Cœur commun `register_eventfd`/`_async` : enregistre `efd` sous `opcode`.
    fn register_eventfd_op(&mut self, efd: BorrowedFd<'_>, opcode: u32) -> Result<(), Errno> {
        let fd = efd.as_raw_fd();
        // SAFETY: REGISTER_EVENTFD[_ASYNC] attend un `*const i32` (nr_args == 1) ;
        // `fd` (variable locale) vit pendant l'appel.
        unsafe {
            register_raw(self, opcode, core::ptr::from_ref(&fd) as u64, 1)?;
        }
        Ok(())
    }

    /// `REGISTER_EVENTFD` (4) : lie un `eventfd` (famille `ipc`) aux complétions
    /// (le kernel y écrit à chaque CQE posté → réveil d'un reactor via epoll).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si un eventfd est déjà enregistré ; [`Errno::EBADF`] si
    /// `efd` est invalide.
    pub fn register_eventfd(&mut self, efd: BorrowedFd<'_>) -> Result<(), Errno> {
        self.register_eventfd_op(efd, raw::IORING_REGISTER_EVENTFD)
    }

    /// `REGISTER_EVENTFD_ASYNC` (7) : comme [`IoUring::register_eventfd`] mais ne
    /// notifie que pour les complétions traitées en **asynchrone** (filtre le
    /// bruit des complétions inline).
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::register_eventfd`].
    pub fn register_eventfd_async(&mut self, efd: BorrowedFd<'_>) -> Result<(), Errno> {
        self.register_eventfd_op(efd, raw::IORING_REGISTER_EVENTFD_ASYNC)
    }

    /// `UNREGISTER_EVENTFD` (5) : détache l'eventfd.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si aucun eventfd n'était enregistré.
    pub fn unregister_eventfd(&mut self) -> Result<(), Errno> {
        // SAFETY: UNREGISTER_EVENTFD ne lit aucune mémoire (arg/nr_args nuls).
        unsafe {
            register_raw(self, raw::IORING_UNREGISTER_EVENTFD, 0, 0)?;
        }
        Ok(())
    }

    // ── Personality (§6) ──────────────────────────────────────────────────

    /// `REGISTER_PERSONALITY` (9) : enregistre les credentials du process et rend
    /// un id ([`Personality`]) — une op peut ensuite s'exécuter avec ces
    /// credentials (`sqe.personality`, via [`IoUring::with_personality`]).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si la table de
    /// personalities est pleine).
    pub fn register_personality(&mut self) -> Result<Personality, Errno> {
        // SAFETY: REGISTER_PERSONALITY ne lit aucune mémoire (arg/nr_args nuls) ;
        // le kernel rend l'id (> 0) en valeur de retour.
        let id = unsafe { register_raw(self, raw::IORING_REGISTER_PERSONALITY, 0, 0)? };
        let id = u16::try_from(id).map_err(|_| Errno::EINVAL)?;
        Ok(Personality(id))
    }

    /// `UNREGISTER_PERSONALITY` (10) : retire la personality `p` (id passé en
    /// `nr_args`).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si l'id n'est pas enregistré.
    pub fn unregister_personality(&mut self, p: Personality) -> Result<(), Errno> {
        // SAFETY: UNREGISTER_PERSONALITY ne lit aucune mémoire ; l'id voyage dans
        // `nr_args` (convention kernel).
        unsafe {
            register_raw(
                self,
                raw::IORING_UNREGISTER_PERSONALITY,
                0,
                u32::from(p.raw()),
            )?;
        }
        Ok(())
    }

    // ── Réglage du pool io-wq (§7) ────────────────────────────────────────

    /// `REGISTER_IOWQ_AFF` (17) : fixe l'affinité CPU des workers io-wq.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] (masque invalide) ; erreurs de `io_uring_register`.
    pub fn set_work_queue_affinity(&mut self, cpus: &CpuSet) -> Result<(), Errno> {
        let bytes = cpus.as_bytes();
        let nr = u32::try_from(bytes.len()).map_err(|_| Errno::EINVAL)?;
        // SAFETY: IOWQ_AFF attend un `cpumask` de `nr` octets ; `bytes` (vue du
        // `CpuSet` emprunté) vit pendant l'appel.
        unsafe {
            register_raw(
                self,
                raw::IORING_REGISTER_IOWQ_AFF,
                bytes.as_ptr() as u64,
                nr,
            )?;
        }
        Ok(())
    }

    /// `UNREGISTER_IOWQ_AFF` (18) : rétablit l'affinité par défaut des workers.
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register`.
    pub fn clear_work_queue_affinity(&mut self) -> Result<(), Errno> {
        // SAFETY: UNREGISTER_IOWQ_AFF ne lit aucune mémoire (arg/nr_args nuls).
        unsafe {
            register_raw(self, raw::IORING_UNREGISTER_IOWQ_AFF, 0, 0)?;
        }
        Ok(())
    }

    /// `REGISTER_IOWQ_MAX_WORKERS` (19) : plafonne les workers bornés/non-bornés
    /// (`0` = inchangé). Rend les valeurs **précédentes** (réécrites par le
    /// kernel) — maîtrise de l'empreinte CPU sur matériel modeste (Charte).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register`.
    pub fn set_work_queue_max_workers(
        &mut self,
        bounded: u32,
        unbounded: u32,
    ) -> Result<WorkQueueWorkerLimits, Errno> {
        let mut limits = [bounded, unbounded];
        // SAFETY: IOWQ_MAX_WORKERS attend un `[u32; 2]` (nr_args == 2) ; le kernel
        // y réécrit les anciennes valeurs. `limits` vit pendant l'appel.
        unsafe {
            register_raw(
                self,
                raw::IORING_REGISTER_IOWQ_MAX_WORKERS,
                limits.as_mut_ptr() as u64,
                2,
            )?;
        }
        Ok(WorkQueueWorkerLimits {
            bounded: limits[raw::IO_WQ_BOUND],
            unbounded: limits[raw::IO_WQ_UNBOUND],
        })
    }

    // ── NAPI busy-poll (§8) ───────────────────────────────────────────────

    /// `REGISTER_NAPI` (27) : active le busy-poll NAPI (latence réseau ↓, CPU ↑).
    /// Rend la configuration **précédente** (réécrite par le kernel).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si NAPI indisponible).
    pub fn register_napi(&mut self, config: NapiConfig) -> Result<NapiConfig, Errno> {
        let mut napi = raw::IoUringNapi {
            busy_poll_to: config.busy_poll_us,
            prefer_busy_poll: u8::from(config.prefer_busy_poll),
            pad: [0; 3],
            resv: 0,
        };
        // SAFETY: REGISTER_NAPI attend une `io_uring_napi` ; le kernel y réécrit
        // la config précédente. `napi` vit pendant l'appel (nr_args == 0, liburing).
        unsafe {
            register_raw(
                self,
                raw::IORING_REGISTER_NAPI,
                core::ptr::from_mut(&mut napi) as u64,
                0,
            )?;
        }
        Ok(NapiConfig {
            busy_poll_us: napi.busy_poll_to,
            prefer_busy_poll: napi.prefer_busy_poll != 0,
        })
    }

    /// `UNREGISTER_NAPI` (28) : désactive le busy-poll NAPI.
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register`.
    pub fn unregister_napi(&mut self) -> Result<(), Errno> {
        // Le kernel réécrit l'ancienne config dans le tampon passé ; ignorée ici.
        let mut napi = raw::IoUringNapi::default();
        // SAFETY: UNREGISTER_NAPI attend une `io_uring_napi` ; `napi` vit pendant
        // l'appel (nr_args == 0, liburing).
        unsafe {
            register_raw(
                self,
                raw::IORING_UNREGISTER_NAPI,
                core::ptr::from_mut(&mut napi) as u64,
                0,
            )?;
        }
        Ok(())
    }

    // ── Source d'horloge (§9) ─────────────────────────────────────────────

    /// `REGISTER_CLOCK` (29) : fixe l'horloge des timeouts du ring (cohérent avec
    /// `TimeoutFlags` du Temps 2c et `family-time`).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si l'horloge n'est pas
    /// supportée).
    pub fn register_clock(&mut self, clock: ClockSource) -> Result<(), Errno> {
        let reg = raw::IoUringClockRegister {
            clockid: clock.clockid(),
            resv: [0; 3],
        };
        // SAFETY: REGISTER_CLOCK attend une `io_uring_clock_register` ; `reg` vit
        // pendant l'appel (nr_args == 0, liburing).
        unsafe {
            register_raw(
                self,
                raw::IORING_REGISTER_CLOCK,
                core::ptr::from_ref(&reg) as u64,
                0,
            )?;
        }
        Ok(())
    }

    // ── Variantes « direct descriptor » (§2.1) ────────────────────────────

    /// `IORING_OP_OPENAT2` (28) **direct** : range le FD ouvert dans un slot fixe
    /// (`slot`) au lieu de le rendre en FD ordinaire. Pour [`FixedSlotTarget::Alloc`],
    /// le slot choisi est rendu dans `cqe->res` ([`Completion::allocated_slot`]).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `slot` est `Index(u32::MAX)` ; [`Errno::EBUSY`] si la
    /// SQ/le slab sont pleins.
    pub fn submit_openat2_direct(
        &mut self,
        dirfd: DirFd<'_>,
        path: alloc::ffi::CString,
        how: OpenHow,
        slot: FixedSlotTarget,
    ) -> Result<SubmissionToken, Errno> {
        let file_index = slot.to_file_index()?;
        let dirfd = match dirfd {
            DirFd::Cwd => raw::AT_FDCWD,
            DirFd::Fd(fd) => fd.as_raw_fd(),
        };
        // Pas de `O_CLOEXEC` ici : le kernel le **rejette** (`EINVAL`) sur un
        // descripteur direct (kernel-managed, non hérité à l'exec par nature ;
        // le `O_CLOEXEC` est posé à la matérialisation `fixed_fd_install`).
        let how = Box::new(raw::OpenHowRaw {
            flags: how.flags.bits(),
            mode: u64::from(how.mode),
            resolve: how.resolve.bits(),
        });
        let how_ptr = core::ptr::from_ref(&*how) as u64;
        let path_ptr = path.as_ptr() as u64;
        self.submit_op(Some(OwnedOp::Open { path, how }), |sqe| {
            sqe.opcode = raw::IORING_OP_OPENAT2;
            sqe.fd = dirfd;
            sqe.addr_or_splice_off_in = path_ptr;
            sqe.len = 24; // sizeof(open_how), figé par l'assert de layout
            sqe.off_or_addr2 = how_ptr;
            sqe.splice_fd_in_or_file_index = file_index;
        })
    }

    /// `IORING_OP_ACCEPT` (13) **direct** : range le socket accepté dans un slot
    /// fixe. Pas de restitution d'adresse pair.
    ///
    /// Le kernel **rejette** `SOCK_CLOEXEC` sur un descripteur direct
    /// (kernel-managed) : ne pas l'ajouter (`flags` transmis tel quel). Le
    /// `O_CLOEXEC` est posé à la matérialisation (`fixed_fd_install`).
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_openat2_direct`].
    pub fn submit_accept_direct(
        &mut self,
        listener: BorrowedFd<'_>,
        flags: AcceptFlags,
        slot: FixedSlotTarget,
    ) -> Result<SubmissionToken, Errno> {
        let file_index = slot.to_file_index()?;
        let fd = listener.as_raw_fd();
        let accept_flags = flags.bits().cast_unsigned();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_ACCEPT;
            sqe.fd = fd;
            sqe.op_flags = accept_flags;
            sqe.splice_fd_in_or_file_index = file_index;
        })
    }

    /// `IORING_OP_SOCKET` (45) **direct** : crée un socket rangé dans un slot fixe.
    ///
    /// Le kernel **rejette** `SOCK_CLOEXEC` sur un descripteur direct : ne pas
    /// l'ajouter. Le `O_CLOEXEC` est posé à la matérialisation (`fixed_fd_install`).
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_openat2_direct`].
    pub fn submit_socket_direct(
        &mut self,
        domain: SocketDomain,
        ty: SocketType,
        protocol: i32,
        slot: FixedSlotTarget,
    ) -> Result<SubmissionToken, Errno> {
        let file_index = slot.to_file_index()?;
        let domain = domain as i32;
        let ty = ty as i32;
        let protocol = protocol.cast_unsigned();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_SOCKET;
            sqe.fd = domain;
            sqe.off_or_addr2 = u64::from(ty.cast_unsigned());
            sqe.len = protocol;
            sqe.splice_fd_in_or_file_index = file_index;
        })
    }

    // ── Opérations sur FD fixe (IOSQE_FIXED_FILE) ─────────────────────────

    /// `IORING_OP_READ` (22) via un [`FixedSlot`] (`IOSQE_FIXED_FILE`) : lit dans
    /// `buffer` (déplacé dans le slot). Complétion via
    /// [`Completion::into_buffer_result`].
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `buffer.len()` déborde un `u32` ; [`Errno::EBUSY`]
    /// (SQ/slab pleins).
    pub fn submit_read_fixed_file(
        &mut self,
        slot: FixedSlot<'_>,
        mut buffer: Vec<u8>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let len = u32::try_from(buffer.len()).map_err(|_| Errno::EINVAL)?;
        let addr = buffer.as_mut_ptr() as u64;
        let off = offset.unwrap_or(u64::MAX);
        let index = slot.index().cast_signed();
        self.pending_options = self.pending_options.fixed_file();
        self.submit_op(Some(OwnedOp::Bytes(buffer)), |sqe| {
            sqe.opcode = raw::IORING_OP_READ;
            sqe.fd = index;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
        })
    }

    /// `IORING_OP_WRITE` (23) via un [`FixedSlot`] : écrit `buffer` (déplacé dans
    /// le slot). Complétion via [`Completion::into_buffer_result`].
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_read_fixed_file`].
    pub fn submit_write_fixed_file(
        &mut self,
        slot: FixedSlot<'_>,
        buffer: Vec<u8>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let len = u32::try_from(buffer.len()).map_err(|_| Errno::EINVAL)?;
        let addr = buffer.as_ptr() as u64;
        let off = offset.unwrap_or(u64::MAX);
        let index = slot.index().cast_signed();
        self.pending_options = self.pending_options.fixed_file();
        self.submit_op(Some(OwnedOp::Bytes(buffer)), |sqe| {
            sqe.opcode = raw::IORING_OP_WRITE;
            sqe.fd = index;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
        })
    }

    /// `IORING_OP_FIXED_FD_INSTALL` (54) : matérialise un [`FixedSlot`] (FD
    /// direct) en FD **ordinaire** (`O_CLOEXEC` posé). Complétion via
    /// [`Completion::opened_fd`].
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab pleins) ; à la complétion, `EBADF` si le slot
    /// est vide.
    pub fn submit_fixed_fd_install(
        &mut self,
        slot: FixedSlot<'_>,
    ) -> Result<SubmissionToken, Errno> {
        let index = slot.index().cast_signed();
        self.pending_options = self.pending_options.fixed_file();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_FIXED_FD_INSTALL;
            sqe.fd = index;
            // install_fd_flags = 0 ⇒ O_CLOEXEC posé (défaut Air, cohérent couche 0).
            sqe.op_flags = 0;
        })
    }

    // ── read_fixed / write_fixed (buffer enregistré) ──────────────────────

    /// `IORING_OP_READ_FIXED` (4) : lit `fd` dans la tranche d'un buffer
    /// enregistré (`slice`). Les octets atterrissent dans la mémoire épinglée
    /// (relue via la [`RegisteredBuffers`]). Complétion via
    /// [`Completion::into_result`] (nombre d'octets).
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si la tranche déborde un `u32`/`u16` ; [`Errno::EBUSY`].
    pub fn submit_read_fixed(
        &mut self,
        fd: BorrowedFd<'_>,
        slice: RegisteredBufferSlice<'_>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = u32::try_from(slice.len()).map_err(|_| Errno::EINVAL)?;
        let buf_index = u16::try_from(slice.index()).map_err(|_| Errno::EINVAL)?;
        let off = offset.unwrap_or(u64::MAX);
        let addr = slice.addr;
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_READ_FIXED;
            sqe.fd = fd;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
            sqe.buf_index_or_group = buf_index;
        })
    }

    /// `IORING_OP_WRITE_FIXED` (5) : écrit dans `fd` depuis la tranche d'un buffer
    /// enregistré. Complétion via [`Completion::into_result`] (nombre d'octets).
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_read_fixed`].
    pub fn submit_write_fixed(
        &mut self,
        fd: BorrowedFd<'_>,
        slice: RegisteredBufferSlice<'_>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = u32::try_from(slice.len()).map_err(|_| Errno::EINVAL)?;
        let buf_index = u16::try_from(slice.index()).map_err(|_| Errno::EINVAL)?;
        let off = offset.unwrap_or(u64::MAX);
        let addr = slice.addr;
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_WRITE_FIXED;
            sqe.fd = fd;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
            sqe.buf_index_or_group = buf_index;
        })
    }
}

impl Completion {
    /// Slot choisi par le kernel pour une variante « direct » à cible
    /// [`FixedSlotTarget::Alloc`] (rendu dans `cqe->res`).
    ///
    /// # Errors
    ///
    /// L'[`Errno`] décodé de la complétion (ex. [`Errno::ENFILE`] si la plage
    /// d'auto-allocation est pleine), ou [`Errno::EINVAL`] si `res` est négatif
    /// hors errno.
    pub fn allocated_slot(self) -> Result<u32, Errno> {
        let res = self.into_result()?;
        u32::try_from(res).map_err(|_| Errno::EINVAL)
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Tests
// ───────────────────────────────────────────────────────────────────────────
//
// Les tests **purs** (encodage `FixedSlotTarget`, propagation d'erreur via le
// simulateur de syscalls) tournent **sous Miri**. Les tests d'**intégration**
// (kernel réel : registration, variantes direct, read/write fixed) portent
// `#[cfg_attr(miri, ignore)]` — Miri ne modélise pas `io_uring_register`/`enter`.
// La **sûreté de lifetime** (une référence ne survit pas au désenregistrement)
// est prouvée par les doctests `compile_fail` sur `FixedFdTable::unregister` et
// `RegisteredBuffers::unregister`.

#[cfg(test)]
mod tests {
    use super::syscall::sim::{self, Syscall};
    use super::*;
    use crate::test_support::{sfd, std_file};
    use air_sys_types::fd::AsFd;
    use air_sys_types::fs::{OpenFlags, OpenHow};
    use air_sys_types::ipc::EventFdFlags;
    use air_sys_types::mem::{MapFlags, ProtectionFlags};
    use air_sys_types::net::{SocketDomain, SocketType};
    use core::sync::atomic::{AtomicU32, Ordering};
    use std::ffi::CString;
    use std::io::Read;
    use std::os::unix::ffi::OsStrExt;
    use std::path::{Path, PathBuf};

    static COUNTER: AtomicU32 = AtomicU32::new(0);

    fn ring8() -> IoUring {
        IoUring::new(NonZeroU32::new(8).expect("8 ≠ 0")).expect("io_uring_setup 6.12")
    }

    fn nz(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("n ≠ 0")
    }

    fn temp_path(tag: &str) -> PathBuf {
        let n = COUNTER.fetch_add(1, Ordering::Relaxed);
        std::env::temp_dir().join(format!("air-iou3a-{}-{n}-{tag}", std::process::id()))
    }

    fn cpath(p: &Path) -> CString {
        CString::new(p.as_os_str().as_bytes()).expect("chemin sans NUL")
    }

    fn rw_file(path: &Path) -> std::fs::File {
        std::fs::OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(true)
            .open(path)
            .expect("ouverture fichier de test")
    }

    fn rw_region(len: usize) -> MmapRegion {
        MmapRegion::new_anonymous(
            len,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE,
        )
        .expect("new_anonymous RW")
    }

    fn complete_one(ring: &mut IoUring, expected: SubmissionToken) -> Completion {
        assert_eq!(ring.submit_and_wait(1).expect("submit_and_wait"), 1);
        let completion = ring.wait_completion().expect("wait_completion");
        assert_eq!(completion.token(), expected, "user_data round-trip");
        completion
    }

    // ── Pur : encodage FixedSlotTarget (tourne sous Miri) ─────────────────

    #[test]
    fn fixed_slot_target_encoding() {
        assert_eq!(
            FixedSlotTarget::Alloc.to_file_index(),
            Ok(raw::IORING_FILE_INDEX_ALLOC)
        );
        assert_eq!(FixedSlotTarget::Index(0).to_file_index(), Ok(1));
        assert_eq!(FixedSlotTarget::Index(41).to_file_index(), Ok(42));
        // `u32::MAX` collisionnerait avec la sentinelle Alloc ⇒ refusé en amont.
        assert_eq!(
            FixedSlotTarget::Index(u32::MAX).to_file_index(),
            Err(Errno::EINVAL)
        );
        // Couvre Debug/Eq/Copy des types de surface (lints `must_use`).
        assert_eq!(FixedSlotTarget::Alloc, FixedSlotTarget::Alloc);
        assert_ne!(FixedSlotTarget::Index(1), FixedSlotTarget::Alloc);
    }

    #[test]
    fn surface_types_are_debug_and_eq() {
        // Couvre les dérivations Debug/Default/Eq des types de configuration.
        let limits = WorkQueueWorkerLimits::default();
        assert!(format!("{limits:?}").contains("bounded"));
        let napi = NapiConfig {
            busy_poll_us: 7,
            prefer_busy_poll: true,
        };
        assert_eq!(
            napi,
            NapiConfig {
                busy_poll_us: 7,
                prefer_busy_poll: true
            }
        );
        assert_ne!(ClockSource::Monotonic, ClockSource::Realtime);
        let p = Personality(3);
        assert_eq!(p.id(), 3);
        assert!(format!("{p:?}").contains("Personality"));
        assert_eq!(ClockSource::Monotonic.clockid(), raw::CLOCK_MONOTONIC);
        assert_eq!(ClockSource::Boottime.clockid(), raw::CLOCK_BOOTTIME);
        assert_eq!(ClockSource::Realtime.clockid(), raw::CLOCK_REALTIME);
    }

    // ── Pur : propagation d'erreur via simulateur (tourne sous Miri) ──────

    #[test]
    fn register_errors_propagate_through_facades() {
        sim::clear();
        let mut ring = ring8();
        // FixedFdTable::register → EINVAL injecté.
        sim::inject(Syscall::Register, -22); // -EINVAL
        assert_eq!(
            FixedFdTable::register(&mut ring, nz(4)).err(),
            Some(Errno::EINVAL)
        );
        // RegisteredBuffers::register → EINVAL injecté.
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            RegisteredBuffers::register(&mut ring, vec![vec![0u8; 8]]).err(),
            Some(Errno::EINVAL)
        );
        // register_personality → EBADF injecté (-9).
        sim::inject(Syscall::Register, -9);
        assert_eq!(ring.register_personality().err(), Some(Errno::EBADF));
        // register_clock → EINVAL injecté.
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            ring.register_clock(ClockSource::Monotonic).err(),
            Some(Errno::EINVAL)
        );
        // register_napi → EINVAL injecté.
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            ring.register_napi(NapiConfig::default()).err(),
            Some(Errno::EINVAL)
        );
        // set_work_queue_max_workers → EINVAL injecté.
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            ring.set_work_queue_max_workers(1, 1).err(),
            Some(Errno::EINVAL)
        );
        // register_eventfd → EBADF injecté.
        let efd = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("eventfd2");
        sim::inject(Syscall::Register, -9);
        assert_eq!(ring.register_eventfd(efd.as_fd()).err(), Some(Errno::EBADF));
        // register_ring_fd → EINVAL injecté (chemin d'erreur du syscall direct).
        sim::inject(Syscall::Register, -22);
        assert_eq!(ring.register_ring_fd().err(), Some(Errno::EINVAL));
        // set_work_queue_affinity → EINVAL injecté.
        let mut cpus = CpuSet::new();
        cpus.set(0);
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            ring.set_work_queue_affinity(&cpus).err(),
            Some(Errno::EINVAL)
        );
        // clear_work_queue_affinity / unregister_eventfd / unregister_napi
        // (chemins d'erreur des opcodes sans argument).
        sim::inject(Syscall::Register, -22);
        assert_eq!(ring.clear_work_queue_affinity().err(), Some(Errno::EINVAL));
        sim::inject(Syscall::Register, -22);
        assert_eq!(ring.unregister_eventfd().err(), Some(Errno::EINVAL));
        sim::inject(Syscall::Register, -22);
        assert_eq!(ring.unregister_napi().err(), Some(Errno::EINVAL));
        sim::clear();
    }

    #[test]
    fn register_with_and_buffers_reject_empty() {
        sim::clear();
        let mut ring = ring8();
        // register_with([]) → EINVAL **en amont** (aucun syscall).
        assert_eq!(
            FixedFdTable::register_with(&mut ring, Vec::new()).err(),
            Some(Errno::EINVAL)
        );
        // RegisteredBuffers::register([]) → EINVAL en amont.
        assert_eq!(
            RegisteredBuffers::register(&mut ring, Vec::new()).err(),
            Some(Errno::EINVAL)
        );
        assert_eq!(
            RegisteredBuffers::register_mmap(&mut ring, Vec::new()).err(),
            Some(Errno::EINVAL)
        );
    }

    // ── Intégration : FixedFdTable (sparse, set/clear/unregister) ─────────

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn fixed_fd_table_sparse_bounds_and_unregister() {
        let mut ring = ring8();
        let table = FixedFdTable::register(&mut ring, nz(4)).expect("register sparse");
        // slot in-range → Some ; hors borne → None.
        assert!(table.slot(0).is_some());
        assert!(table.slot(3).is_some());
        assert!(table.slot(4).is_none());
        assert_eq!(table.slot(2).expect("slot 2").index(), 2);
        // Désenregistrement : aucun FD possédé (sparse) ⇒ Vec vide.
        let returned = table.unregister(&mut ring).expect("unregister");
        assert!(returned.is_empty());
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn fixed_fd_table_register_with_set_clear() {
        let mut ring = ring8();
        // Deux eventfd comme FD possédés.
        let a = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("eventfd a");
        let b = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("eventfd b");
        let mut table = FixedFdTable::register_with(&mut ring, vec![a.into_fd(), b.into_fd()])
            .expect("register_with");
        // set hors borne → EINVAL (aucun syscall).
        let spare = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("eventfd spare");
        assert_eq!(
            table.set(&mut ring, 99, spare.into_fd()).err(),
            Some(Errno::EINVAL)
        );
        // clear hors borne → EINVAL.
        assert_eq!(table.clear(&mut ring, 99).err(), Some(Errno::EINVAL));
        // clear slot 0 → rend le FD possédé (encore valide).
        let cleared = table.clear(&mut ring, 0).expect("clear ok");
        // FD restitué (possédé, encore valide) ; son drop le ferme — non-fuite.
        let _cleared_fd = cleared.expect("slot 0 était rempli");
        // set slot 0 avec un nouveau FD.
        let c = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("eventfd c");
        table.set(&mut ring, 0, c.into_fd()).expect("set ok");
        // unregister rend les FD restants (slots 0 et 1).
        let remaining = table.unregister(&mut ring).expect("unregister");
        assert_eq!(remaining.len(), 2, "slots 0 (re-set) et 1 restitués");
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn fixed_fd_table_alloc_range_validation() {
        let mut ring = ring8();
        let mut table = FixedFdTable::register(&mut ring, nz(4)).expect("register");
        table
            .set_alloc_range(&mut ring, 0..4)
            .expect("alloc range plein");
        table
            .set_alloc_range(&mut ring, 1..3)
            .expect("alloc range partiel");
        // Plage inversée → EINVAL (checked_sub None). `Range` explicite pour
        // éviter le lint `reversed_empty_ranges` (intention testée).
        let inverted = core::ops::Range {
            start: 3u32,
            end: 2u32,
        };
        assert_eq!(
            table.set_alloc_range(&mut ring, inverted).err(),
            Some(Errno::EINVAL)
        );
        // Plage débordant la capacité → EINVAL.
        assert_eq!(
            table.set_alloc_range(&mut ring, 0..9).err(),
            Some(Errno::EINVAL)
        );
    }

    // ── Intégration : variantes direct + fixed-file + fixed_fd_install ────

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn direct_openat2_then_fixed_rw_then_install() {
        let path = temp_path("direct-rw");
        let _f = rw_file(&path); // crée le fichier
        let mut ring = ring8();
        let table = FixedFdTable::register(&mut ring, nz(4)).expect("register");
        // openat2_direct(Alloc) : le FD ouvert va dans un slot choisi par le kernel.
        let how = OpenHow {
            flags: OpenFlags::RDWR,
            ..OpenHow::default()
        };
        let tok = ring
            .submit_openat2_direct(DirFd::Cwd, cpath(&path), how, FixedSlotTarget::Alloc)
            .expect("openat2_direct");
        let slot_idx = complete_one(&mut ring, tok)
            .allocated_slot()
            .expect("slot alloué");
        assert!(slot_idx < 4);
        // write via FixedSlot.
        let fs = table.slot(slot_idx).expect("slot rempli");
        let tok = ring
            .submit_write_fixed_file(fs, b"fixed!".to_vec(), Some(0))
            .expect("write_fixed_file");
        let (_buf, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("write ok");
        assert_eq!(n, 6);
        // read via FixedSlot.
        let tok = ring
            .submit_read_fixed_file(fs, vec![0u8; 6], Some(0))
            .expect("read_fixed_file");
        let (buf, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("read ok");
        assert_eq!(n, 6);
        assert_eq!(&buf, b"fixed!");
        // fixed_fd_install : le FD direct redevient un FD ordinaire.
        let tok = ring.submit_fixed_fd_install(fs).expect("fixed_fd_install");
        let ofd = complete_one(&mut ring, tok)
            .opened_fd()
            .expect("fd ordinaire");
        // Le FD ordinaire lit le contenu écrit.
        let mut file = std_file(ofd);
        let mut content = String::new();
        use std::io::Seek;
        file.seek(std::io::SeekFrom::Start(0)).expect("seek");
        file.read_to_string(&mut content).expect("read");
        assert_eq!(content, "fixed!");
        table.unregister(&mut ring).expect("unregister");
        std::fs::remove_file(&path).ok();
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn direct_socket_index_then_install() {
        let mut ring = ring8();
        let table = FixedFdTable::register(&mut ring, nz(4)).expect("register");
        // socket_direct vers un slot **précis** (Index).
        let tok = ring
            .submit_socket_direct(
                SocketDomain::Ipv4,
                SocketType::Stream,
                0,
                FixedSlotTarget::Index(2),
            )
            .expect("socket_direct");
        // Pour Index, cqe->res == 0 (succès).
        complete_one(&mut ring, tok).completed().expect("socket ok");
        let fs = table.slot(2).expect("slot 2");
        let tok = ring.submit_fixed_fd_install(fs).expect("install");
        let ofd = complete_one(&mut ring, tok).opened_fd().expect("fd socket");
        // FD ordinaire valide : un getsockopt socket réussit (c'est bien un socket).
        crate::net::get_so_reuseaddr(ofd.as_fd()).expect("getsockopt sur socket");
        table.unregister(&mut ring).expect("unregister");
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn direct_accept_into_slot() {
        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind");
        let addr = listener.local_addr().expect("addr");
        let _client = std::net::TcpStream::connect(addr).expect("connect"); // remplit le backlog
        std::thread::sleep(std::time::Duration::from_millis(20));
        let mut ring = ring8();
        let table = FixedFdTable::register(&mut ring, nz(4)).expect("register");
        let tok = ring
            .submit_accept_direct(sfd(&listener), AcceptFlags::empty(), FixedSlotTarget::Alloc)
            .expect("accept_direct");
        let slot = complete_one(&mut ring, tok)
            .allocated_slot()
            .expect("slot accepté");
        assert!(slot < 4);
        let fs = table.slot(slot).expect("slot");
        let tok = ring.submit_fixed_fd_install(fs).expect("install");
        let _ofd = complete_one(&mut ring, tok)
            .opened_fd()
            .expect("fd accepté");
        table.unregister(&mut ring).expect("unregister");
    }

    // ── Intégration : RegisteredBuffers (mmap round-trip + owned + clone) ──

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn registered_buffers_mmap_read_write_fixed_round_trip() {
        let path = temp_path("regbuf");
        let file = rw_file(&path);
        let region0 = rw_region(4096);
        let region1 = rw_region(4096);
        // Écrit un motif connu dans region0 avant l'enregistrement.
        // SAFETY (test): `region0` est PROT_WRITE, 4096 o ; on écrit 8 o au début.
        unsafe {
            std::ptr::copy_nonoverlapping(b"regdata!".as_ptr(), region0.as_ptr().cast_mut(), 8);
        }
        let r1_view = region1.clone(); // partage la mémoire pour relire après read_fixed
        let mut ring = ring8();
        let buffers = RegisteredBuffers::register_mmap(&mut ring, vec![region0, region1])
            .expect("register_mmap");
        // write_fixed : region0[0..8] → fichier.
        let slice0 = buffers.slice(0, 0..8).expect("slice 0");
        assert_eq!(slice0.len(), 8);
        assert!(!slice0.is_empty());
        assert_eq!(slice0.index(), 0);
        let tok = ring
            .submit_write_fixed(sfd(&file), slice0, Some(0))
            .expect("write_fixed");
        let n = complete_one(&mut ring, tok)
            .into_result()
            .expect("write ok");
        assert_eq!(n, 8);
        // read_fixed : fichier → region1[0..8].
        let slice1 = buffers.slice(1, 0..8).expect("slice 1");
        let tok = ring
            .submit_read_fixed(sfd(&file), slice1, Some(0))
            .expect("read_fixed");
        let n = complete_one(&mut ring, tok).into_result().expect("read ok");
        assert_eq!(n, 8);
        assert_eq!(&r1_view.bytes()[0..8], b"regdata!");
        // unregister mmap → Vec vide (régions consommées).
        let returned = buffers.unregister(&mut ring).expect("unregister");
        assert!(returned.is_empty());
        std::fs::remove_file(&path).ok();
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn registered_buffers_owned_update_slice_unregister() {
        let mut ring = ring8();
        let mut buffers =
            RegisteredBuffers::register(&mut ring, vec![vec![0u8; 64], vec![0u8; 64]])
                .expect("register");
        // slice bornée OK ; hors borne → None.
        assert!(buffers.slice(0, 0..10).is_some());
        assert!(buffers.slice(0, 0..65).is_none()); // range > buffer
        assert!(buffers.slice(2, 0..1).is_none()); // index hors borne
        // slice inversée → None (checked_sub). `Range` construit explicitement
        // pour éviter le lint `reversed_empty_ranges` (intention testée).
        let inverted = core::ops::Range {
            start: 10usize,
            end: 5usize,
        };
        assert!(buffers.slice(0, inverted).is_none());
        // update remplace le buffer 0.
        buffers
            .update(&mut ring, 0, vec![1u8; 32])
            .expect("update ok");
        // update hors borne → EINVAL.
        assert_eq!(
            buffers.update(&mut ring, 9, vec![0u8; 4]).err(),
            Some(Errno::EINVAL)
        );
        // unregister rend les buffers possédés.
        let returned = buffers.unregister(&mut ring).expect("unregister");
        assert_eq!(returned.len(), 2);
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn registered_buffers_update_rejects_mmap_backing() {
        let mut ring = ring8();
        let mut buffers = RegisteredBuffers::register_mmap(&mut ring, vec![rw_region(4096)])
            .expect("register_mmap");
        // update est Vec-orienté : backing mmap ⇒ EINVAL.
        assert_eq!(
            buffers.update(&mut ring, 0, vec![0u8; 4]).err(),
            Some(Errno::EINVAL)
        );
        buffers.unregister(&mut ring).expect("unregister");
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn clone_buffers_between_rings() {
        let path = temp_path("clone");
        let file = rw_file(&path);
        let mut src = ring8();
        let mut dst = ring8();
        let src_bufs = RegisteredBuffers::register(&mut src, vec![b"clonable".to_vec()])
            .expect("register src");
        let dst_clone = RegisteredBuffers::clone_from(&mut dst, &src).expect("clone_from");
        // slice sur un backing cloné → None (géométrie inconnue).
        assert!(dst_clone.slice(0, 0..4).is_none());
        // Le ring destination écrit depuis le buffer cloné (même VA process).
        let slice = src_bufs.slice(0, 0..8).expect("slice src");
        let tok = dst
            .submit_write_fixed(sfd(&file), slice, Some(0))
            .expect("write_fixed dst");
        let n = complete_one(&mut dst, tok).into_result().expect("write ok");
        assert_eq!(n, 8);
        let mut content = String::new();
        use std::io::Seek;
        let mut f = file;
        f.seek(std::io::SeekFrom::Start(0)).expect("seek");
        f.read_to_string(&mut content).expect("read");
        assert_eq!(content, "clonable");
        dst_clone.unregister(&mut dst).expect("unregister dst");
        src_bufs.unregister(&mut src).expect("unregister src");
        std::fs::remove_file(&path).ok();
    }

    // ── Intégration : eventfd, personality, io-wq, napi, clock, ring fd ───

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_eventfd_notifies_completions() {
        let mut ring = ring8();
        let efd = crate::ipc::eventfd2(0, EventFdFlags::NONBLOCK).expect("eventfd2");
        ring.register_eventfd(efd.as_fd())
            .expect("register_eventfd");
        // Une complétion (nop) → le kernel écrit dans l'eventfd.
        let tok = ring.submit_nop().expect("nop");
        complete_one(&mut ring, tok).completed().expect("nop ok");
        let count = efd.read().expect("eventfd read");
        assert!(count >= 1, "eventfd notifié");
        ring.unregister_eventfd().expect("unregister_eventfd");
        // Variante async : ré-enregistre puis désenregistre.
        ring.register_eventfd_async(efd.as_fd())
            .expect("register_eventfd_async");
        ring.unregister_eventfd().expect("unregister async");
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_personality_and_use_in_op() {
        let path = temp_path("perso");
        let _f = rw_file(&path);
        let mut ring = ring8();
        let p = ring.register_personality().expect("register_personality");
        // Op avec la personality enregistrée.
        let how = OpenHow {
            flags: OpenFlags::RDONLY,
            ..OpenHow::default()
        };
        let tok = ring
            .with_personality(p)
            .submit_openat2(DirFd::Cwd, cpath(&path), how)
            .expect("openat2 with personality");
        let _fd = complete_one(&mut ring, tok).opened_fd().expect("ouvert");
        ring.unregister_personality(p)
            .expect("unregister_personality");
        std::fs::remove_file(&path).ok();
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn work_queue_max_workers_reports_values() {
        let mut ring = ring8();
        // Fixe les plafonds.
        ring.set_work_queue_max_workers(2, 3)
            .expect("set max workers");
        // Relit (0,0 = inchangé) : rend les valeurs courantes (2,3).
        let limits = ring
            .set_work_queue_max_workers(0, 0)
            .expect("read max workers");
        assert_eq!(limits.bounded, 2);
        assert_eq!(limits.unbounded, 3);
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn work_queue_affinity_set_and_clear() {
        let mut ring = ring8();
        let mut cpus = CpuSet::new();
        cpus.set(0);
        ring.set_work_queue_affinity(&cpus).expect("set affinity");
        ring.clear_work_queue_affinity().expect("clear affinity");
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_napi_round_trip_when_available() {
        let mut ring = ring8();
        let cfg = NapiConfig {
            busy_poll_us: 50,
            prefer_busy_poll: true,
        };
        // NAPI peut être absent (FEATURE-KERNEL) : on tolère EINVAL.
        match ring.register_napi(cfg) {
            Ok(_previous) => {
                ring.unregister_napi().expect("unregister_napi");
            }
            Err(e) => assert_eq!(e, Errno::EINVAL, "NAPI indisponible ⇒ EINVAL"),
        }
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_clock_all_sources() {
        let mut ring = ring8();
        ring.register_clock(ClockSource::Monotonic)
            .expect("monotonic");
        ring.register_clock(ClockSource::Boottime)
            .expect("boottime");
        // ÉCART KERNEL : io_uring 6.12 n'accepte que MONOTONIC/BOOTTIME pour
        // l'horloge des timeouts ; REALTIME est **rejeté** (`EINVAL`). Le type
        // `ClockSource::Realtime` reste exposé (surface validée), mais son
        // enregistrement échoue — signalé dans l'`.out` (jamais corrigé en silence).
        assert_eq!(
            ring.register_clock(ClockSource::Realtime).err(),
            Some(Errno::EINVAL)
        );
    }

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_ring_fd_round_trip() {
        let mut ring = ring8();
        // Désenregistrer sans enregistrer → EINVAL.
        assert_eq!(ring.unregister_ring_fd().err(), Some(Errno::EINVAL));
        ring.register_ring_fd().expect("register_ring_fd");
        // Une soumission passe désormais par le ring fd enregistré (enter_target).
        let tok = ring.submit_nop().expect("nop");
        complete_one(&mut ring, tok)
            .completed()
            .expect("nop via registered ring");
        ring.unregister_ring_fd().expect("unregister_ring_fd");
        // Après désenregistrement, l'enter ordinaire fonctionne toujours.
        let tok = ring.submit_nop().expect("nop 2");
        complete_one(&mut ring, tok)
            .completed()
            .expect("nop via fd ordinaire");
    }

    // ── Chemins d'erreur des façades (registre injecté) ───────────────────
    //
    // Couvre les bras `?` Err de chaque façade qui appelle `io_uring_register`
    // **après** sa validation amont (ces bras ne sont pas atteignables par la
    // seule validation, qui retourne avant le syscall). Le simulateur injecte
    // un errno sur le **prochain** register.

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn register_facade_error_paths_propagate() {
        sim::clear();
        let mut ring = ring8();
        let mut src = ring8();
        // FixedFdTable construite réellement, puis erreurs injectées.
        let mut table = FixedFdTable::register(&mut ring, nz(4)).expect("register table");
        let fd_a = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("efd a");
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            table.set(&mut ring, 0, fd_a.into_fd()).err(),
            Some(Errno::EINVAL)
        );
        sim::inject(Syscall::Register, -22);
        assert_eq!(table.clear(&mut ring, 0).err(), Some(Errno::EINVAL));
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            table.set_alloc_range(&mut ring, 0..2).err(),
            Some(Errno::EINVAL)
        );
        sim::inject(Syscall::Register, -22);
        assert_eq!(table.unregister(&mut ring).err(), Some(Errno::EINVAL));
        // register_with (chemin syscall).
        let fd_b = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("efd b");
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            FixedFdTable::register_with(&mut ring, vec![fd_b.into_fd()]).err(),
            Some(Errno::EINVAL)
        );
        // RegisteredBuffers : update + unregister + clone_from.
        let mut buffers =
            RegisteredBuffers::register(&mut ring, vec![vec![0u8; 8]]).expect("register buffers");
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            buffers.update(&mut ring, 0, vec![1u8; 4]).err(),
            Some(Errno::EINVAL)
        );
        sim::inject(Syscall::Register, -22);
        assert_eq!(buffers.unregister(&mut ring).err(), Some(Errno::EINVAL));
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            RegisteredBuffers::clone_from(&mut src, &ring).err(),
            Some(Errno::EINVAL)
        );
        // unregister_personality (id passé en nr_args).
        sim::inject(Syscall::Register, -22);
        assert_eq!(
            ring.unregister_personality(Personality(1)).err(),
            Some(Errno::EINVAL)
        );
        // register_eventfd_async (variante partageant register_eventfd_op).
        let efd = crate::ipc::eventfd2(0, EventFdFlags::empty()).expect("efd c");
        sim::inject(Syscall::Register, -9);
        assert_eq!(
            ring.register_eventfd_async(efd.as_fd()).err(),
            Some(Errno::EBADF)
        );
        // unregister_ring_fd : enregistrement réel (pose l'index), puis erreur
        // injectée sur le désenregistrement (bras `if ret < 0`).
        ring.register_ring_fd().expect("register_ring_fd réel");
        sim::inject(Syscall::Register, -22);
        assert_eq!(ring.unregister_ring_fd().err(), Some(Errno::EINVAL));
        // Remet l'état propre (désenregistre réellement) pour un téardown net.
        ring.unregister_ring_fd().expect("unregister réel");
        sim::clear();
    }

    // ── openat2_direct relatif à un dirfd (couvre DirFd::Fd) ───────────────

    #[test]
    #[cfg_attr(miri, ignore = "io_uring_register non supporté par Miri")]
    fn openat2_direct_relative_to_dirfd() {
        let dir = temp_path("dir");
        std::fs::create_dir_all(&dir).expect("mkdir");
        let file_path = dir.join("rel.txt");
        let _f = rw_file(&file_path);
        let dir_fd = std::fs::File::open(&dir).expect("open dir");
        let mut ring = ring8();
        let table = FixedFdTable::register(&mut ring, nz(2)).expect("register");
        let how = OpenHow {
            flags: OpenFlags::RDONLY,
            ..OpenHow::default()
        };
        let tok = ring
            .submit_openat2_direct(
                DirFd::Fd(sfd(&dir_fd)),
                CString::new("rel.txt").expect("nom"),
                how,
                FixedSlotTarget::Index(1),
            )
            .expect("openat2_direct relatif");
        complete_one(&mut ring, tok)
            .completed()
            .expect("ouvert relatif au dirfd");
        table.unregister(&mut ring).expect("unregister");
        std::fs::remove_file(&file_path).ok();
        std::fs::remove_dir(&dir).ok();
    }
}