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;