air_sys_syscall/io_uring/

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

//! Opérations **filesystem** d'io_uring (Temps 2a), par-dessus le cœur du
//! Temps 1. Chaque façade encode un opcode `IORING_OP_*` (uapi 6.12) dans un
//! SQE, **gare l'état possédé** (buffers, chemins) dans le slot S1 à la
//! soumission, et restitue à la complétion via les accesseurs typés de
//! [`Completion`](super::Completion).
//!
//! Référence normative : `docs/specs/layer-0/io-uring-2a-filesystem.md`.
//!
//! **Hors périmètre (Temps 3a) :** `read_fixed`/`write_fixed` (reposent sur
//! `RegisteredBufferSlice`), variantes « direct descriptor », `close` fixed.
//! **`madvise` (OP 25)** est désormais **implémenté** (PR coordonnée
//! `family-mem`) : il prend une [`MmapRegion`] dont une garde de vivacité est
//! garée dans le slot S1 — cf. `family-mem-mmap-region.md`.

use super::owned::OwnedOp;
use super::raw::{self, IoUringSqe, Iovec, OpenHowRaw};
use super::{IoUring, SubmissionToken, SubmitOptions};
use crate::mem::MmapRegion;
use air_sys_types::Errno;
use air_sys_types::fd::{AsRawFd, BorrowedFd, IntoRawFd, OwnedFd};
use air_sys_types::fs::{
    DirFd, FadviseAdvice, FallocateMode, FsyncFlags, LinkFlags, Mode, OpenHow, RenameFlags, Statx,
    StatxFlags, StatxMask, SyncFileRangeFlags, UnlinkFlags, XattrFlags,
};
use air_sys_types::ipc::SpliceFlags;
use air_sys_types::mem::MadviseAdvice;
use alloc::boxed::Box;
use alloc::ffi::CString;
use alloc::vec::Vec;
use core::ops::Range;

/// Descripteur kernel d'un [`DirFd`] : `AT_FDCWD` pour `Cwd`, le FD brut sinon.
/// Le `None` typé (`DirFd::Cwd`) remplace la sentinelle `-100` (ADR-021 conv. 1).
fn dirfd_to_raw(dirfd: DirFd<'_>) -> i32 {
    match dirfd {
        DirFd::Cwd => raw::AT_FDCWD,
        DirFd::Fd(fd) => fd.as_raw_fd(),
    }
}

/// Encode un `offset: Option<u64>` : `Some(n)` ⇒ `n` ; `None` ⇒ position
/// courante (transmis comme `-1` au kernel, `IORING_FEAT_RW_CUR_POS`). On
/// n'expose **jamais** le `-1` magique (ADR-021 conv. 1).
fn offset_to_raw(offset: Option<u64>) -> u64 {
    // `-1i64 as u64` = `u64::MAX` : le motif binaire attendu par le kernel.
    offset.unwrap_or(u64::MAX)
}

/// Longueur `usize` → `u32` (champ `len` du SQE), `EINVAL` si débordement
/// (validation amont, Principe 4).
fn len_u32(n: usize) -> Result<u32, Errno> {
    u32::try_from(n).map_err(|_| Errno::EINVAL)
}

impl IoUring {
    /// Réserve un slot S1 (y déplaçant `payload`), prépare un SQE zéro-initialisé
    /// rempli par `fill`, pose `user_data` et les flags `IOSQE_*` en attente, et
    /// retourne le jeton. La soumission effective se fait par
    /// [`IoUring::submit`] / [`IoUring::submit_and_wait`].
    ///
    /// Les pointeurs vers le payload utilisés dans `fill` doivent être capturés
    /// **avant** l'appel (les tas restent stables lors du déplacement du payload
    /// dans le slot — c'est l'invariant de sûreté S1).
    pub(crate) fn submit_op(
        &mut self,
        payload: Option<OwnedOp>,
        fill: impl FnOnce(&mut IoUringSqe),
    ) -> Result<SubmissionToken, Errno> {
        self.submit_filled(payload, |sqe_ptr| {
            // SAFETY: `sqe_ptr` pointe un slot SQE valide fraîchement
            // zéro-initialisé, exclusivement détenu jusqu'à la publication ; le
            // `&mut` ne vit que le temps de `fill`.
            let sqe = unsafe { &mut *sqe_ptr };
            fill(sqe);
        })
    }

    /// Variante bas niveau de [`IoUring::submit_op`] : `fill` reçoit le **pointeur
    /// brut** du slot SQE (et non un `&mut IoUringSqe`), ce qui autorise l'écriture
    /// de la **zone `cmd[]`** d'`URING_CMD` au-delà des 64 octets nommés (jusqu'à
    /// `sqe_size`, cf. `SETUP_SQE128`) — la provenance du pointeur couvre tout le
    /// slot. Toute la mécanique S1 (réservation slab, `user_data`, flags `IOSQE_*`)
    /// est partagée. Réservé au sous-module `cmd` (Temps 2d).
    pub(crate) fn submit_filled(
        &mut self,
        payload: Option<OwnedOp>,
        fill: impl FnOnce(*mut IoUringSqe),
    ) -> Result<SubmissionToken, Errno> {
        if self.sq.space_left() == 0 {
            return Err(Errno::EBUSY);
        }
        let has_payload = payload.is_some();
        let token = self.slab.reserve(payload).map_err(|_| Errno::EBUSY)?;
        let opts = self.pending_options;
        self.pending_options = SubmitOptions::default();
        // Personality en attente (Temps 3a §6) : `0` = aucune (credentials du
        // process). Consommée pour cette seule soumission.
        let personality = self.pending_personality;
        self.pending_personality = 0;
        // SAFETY: place SQ vérifiée > 0 juste au-dessus ; le slot (entier,
        // `sqe_size` octets) est zéro-initialisé par `prepare` et rempli
        // intégralement ci-dessous avant toute publication de la `tail`.
        let sqe_ptr = unsafe { self.sq.prepare() }.expect("place SQ vérifiée");
        fill(sqe_ptr);
        // SAFETY: `sqe_ptr` pointe le slot SQE, exclusivement détenu jusqu'à la
        // publication ; après `fill`, on pose `user_data`/`flags` via les champs
        // nommés (le `&mut` est créé *après* d'éventuelles écritures brutes de
        // `cmd[]` — pas d'aliasing simultané).
        let sqe = unsafe { &mut *sqe_ptr };
        sqe.user_data = token.to_user_data();
        sqe.personality = personality;
        let mut flags = opts.iosqe_flags();
        if has_payload {
            // Une op à payload ne doit jamais sauter son CQE : le slot doit être
            // libéré à la complétion pour restituer/dropper le buffer (sinon le
            // kernel écrirait dans de la mémoire qu'on aurait pu libérer). On
            // retire donc `CQE_SKIP_SUCCESS` pour ces ops (sûreté > micro-optim).
            flags &= !raw::IOSQE_CQE_SKIP_SUCCESS;
        }
        sqe.flags = flags;
        if !has_payload && opts.skips_cqe_on_success() {
            // Op sans payload + skip demandé : aucun CQE en cas de succès ⇒
            // libère le slot S1 dès la soumission (cohérent avec `submit_nop`).
            self.slab.release(token);
        }
        Ok(token)
    }

    // ── Lecture / écriture ────────────────────────────────────────────────

    /// Soumet un `IORING_OP_READ` (22). Le `buffer` est déplacé dans le slot ;
    /// sa longueur logique borne le nombre d'octets lus. À la complétion,
    /// [`Completion::into_buffer_result`](super::Completion::into_buffer_result)
    /// le restitue avec le compte d'octets.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins (avant tout syscall) ;
    /// [`Errno::EINVAL`] si `buffer.len()` déborde un `u32`.
    pub fn submit_read(
        &mut self,
        fd: BorrowedFd<'_>,
        mut buffer: Vec<u8>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = len_u32(buffer.len())?;
        let addr = buffer.as_mut_ptr() as u64;
        let off = offset_to_raw(offset);
        self.submit_op(Some(OwnedOp::Bytes(buffer)), |sqe| {
            sqe.opcode = raw::IORING_OP_READ;
            sqe.fd = fd;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
        })
    }

    /// Soumet un `IORING_OP_WRITE` (23) : écrit `buffer.len()` octets du buffer
    /// (déplacé dans le slot). Complétion via `into_buffer_result`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `buffer.len()`
    /// déborde un `u32`.
    pub fn submit_write(
        &mut self,
        fd: BorrowedFd<'_>,
        mut buffer: Vec<u8>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = len_u32(buffer.len())?;
        let addr = buffer.as_mut_ptr() as u64;
        let off = offset_to_raw(offset);
        self.submit_op(Some(OwnedOp::Bytes(buffer)), |sqe| {
            sqe.opcode = raw::IORING_OP_WRITE;
            sqe.fd = fd;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.off_or_addr2 = off;
        })
    }

    /// Soumet un `IORING_OP_READV` (1). Le tableau d'`iovec` est construit en
    /// interne et garé dans le slot avec les `buffers` possédés. Complétion via
    /// [`Completion::into_vectored_result`](super::Completion::into_vectored_result).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si le nombre de
    /// buffers dépasse `IOV_MAX` (1024).
    pub fn submit_readv(
        &mut self,
        fd: BorrowedFd<'_>,
        buffers: Vec<Vec<u8>>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        self.submit_vectored(raw::IORING_OP_READV, fd, buffers, offset)
    }

    /// Soumet un `IORING_OP_WRITEV` (2). Voir [`IoUring::submit_readv`].
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si le nombre de
    /// buffers dépasse `IOV_MAX`.
    pub fn submit_writev(
        &mut self,
        fd: BorrowedFd<'_>,
        buffers: Vec<Vec<u8>>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        self.submit_vectored(raw::IORING_OP_WRITEV, fd, buffers, offset)
    }

    /// Cœur commun de `readv`/`writev` : valide `IOV_MAX`, construit le tableau
    /// d'`iovec` à partir des buffers possédés, et gare les deux dans le slot.
    fn submit_vectored(
        &mut self,
        opcode: u8,
        fd: BorrowedFd<'_>,
        mut buffers: Vec<Vec<u8>>,
        offset: Option<u64>,
    ) -> Result<SubmissionToken, Errno> {
        if buffers.len() > raw::IOV_MAX {
            return Err(Errno::EINVAL);
        }
        let fd = fd.as_raw_fd();
        let off = offset_to_raw(offset);
        // Construit les `iovec` à partir des tas (stables) des buffers possédés.
        let mut iovecs: Vec<Iovec> = Vec::with_capacity(buffers.len());
        for buf in &mut buffers {
            iovecs.push(Iovec {
                iov_base: buf.as_mut_ptr(),
                iov_len: buf.len(),
            });
        }
        let iovecs = iovecs.into_boxed_slice();
        // `iovecs.len() == buffers.len() ≤ IOV_MAX (1024)` (validé ci-dessus),
        // tient toujours dans un `u32` : `unwrap_or` n'est jamais déclenché (pas
        // de branche d'erreur morte ici).
        let count = u32::try_from(iovecs.len()).unwrap_or(u32::MAX);
        let addr = iovecs.as_ptr() as u64;
        self.submit_op(Some(OwnedOp::Vectored { buffers, iovecs }), |sqe| {
            sqe.opcode = opcode;
            sqe.fd = fd;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = count;
            sqe.off_or_addr2 = off;
        })
    }

    // ── Synchronisation / allocation / troncature ─────────────────────────

    /// Soumet un `IORING_OP_FSYNC` (3). `FsyncFlags::DATASYNC` ⇒ sémantique
    /// `fdatasync`. Complétion via [`Completion::completed`](super::Completion::completed).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_fsync(
        &mut self,
        fd: BorrowedFd<'_>,
        flags: FsyncFlags,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let fsync_flags = if flags.contains(FsyncFlags::DATASYNC) {
            raw::IORING_FSYNC_DATASYNC
        } else {
            0
        };
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_FSYNC;
            sqe.fd = fd;
            sqe.op_flags = fsync_flags;
        })
    }

    /// Soumet un `IORING_OP_SYNC_FILE_RANGE` (8). Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `nbytes` déborde
    /// un `u32` (champ `len` du SQE).
    pub fn submit_sync_file_range(
        &mut self,
        fd: BorrowedFd<'_>,
        offset: u64,
        nbytes: u64,
        flags: SyncFileRangeFlags,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = u32::try_from(nbytes).map_err(|_| Errno::EINVAL)?;
        let op_flags = flags.bits();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_SYNC_FILE_RANGE;
            sqe.fd = fd;
            sqe.off_or_addr2 = offset;
            sqe.len = len;
            sqe.op_flags = op_flags;
        })
    }

    /// Soumet un `IORING_OP_FALLOCATE` (17). Valide en amont `length > 0` et
    /// l'absence de débordement `offset + length` (Principe 4). Complétion via
    /// `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `length ≤ 0`,
    /// `offset < 0`, ou `offset + length` déborde un `i64`.
    pub fn submit_fallocate(
        &mut self,
        fd: BorrowedFd<'_>,
        mode: FallocateMode,
        offset: i64,
        length: i64,
    ) -> Result<SubmissionToken, Errno> {
        if length <= 0 || offset < 0 || offset.checked_add(length).is_none() {
            return Err(Errno::EINVAL);
        }
        let fd = fd.as_raw_fd();
        // `off = offset`, `addr = length`, `len = mode` (mapping io_uring).
        let off = offset.cast_unsigned();
        let addr = length.cast_unsigned();
        let mode_bits = mode.bits().cast_unsigned();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_FALLOCATE;
            sqe.fd = fd;
            sqe.off_or_addr2 = off;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = mode_bits;
        })
    }

    /// Soumet un `IORING_OP_FTRUNCATE` (55) : redimensionne à `length` octets.
    /// Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_ftruncate(
        &mut self,
        fd: BorrowedFd<'_>,
        length: u64,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_FTRUNCATE;
            sqe.fd = fd;
            sqe.off_or_addr2 = length;
        })
    }

    // ── Ouverture / fermeture ─────────────────────────────────────────────

    /// Soumet un `IORING_OP_OPENAT2` (28). Le chemin et la `struct open_how`
    /// (lus de façon asynchrone) sont gardés en vie dans le slot. `O_CLOEXEC`
    /// est ajouté d'office (cohérent avec le wrapper synchrone). Complétion via
    /// [`Completion::opened_fd`](super::Completion::opened_fd).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_openat2(
        &mut self,
        dirfd: DirFd<'_>,
        path: CString,
        how: OpenHow,
    ) -> Result<SubmissionToken, Errno> {
        let dirfd = dirfd_to_raw(dirfd);
        let how = Box::new(OpenHowRaw {
            flags: how.flags.bits() | raw::O_CLOEXEC,
            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;
        // `len` = sizeof(open_how) = 24, figé par l'assert de layout de `raw.rs`.
        let how_len: u32 = 24;
        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 = how_len;
            sqe.off_or_addr2 = how_ptr;
        })
    }

    /// Soumet un `IORING_OP_CLOSE` (19). **Consomme** l'`OwnedFd` (déplacé dans
    /// le slot) : il ne peut plus être réutilisé ⇒ pas de double close. Le FD
    /// n'est effectivement fermé qu'à l'exécution kernel. Complétion via
    /// `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_close(&mut self, fd: OwnedFd) -> Result<SubmissionToken, Errno> {
        // `into_raw_fd` **cède** l'ownership au kernel sans fermer : c'est l'op
        // CLOSE qui fermera le FD. On ne gare donc aucun payload (sinon le `Drop`
        // de l'`OwnedFd` à la complétion fermerait une seconde fois — double
        // close). Le numéro reste valide jusqu'à l'exécution kernel (personne
        // d'autre ne le possède), donc aucune réutilisation prématurée.
        let raw_fd = fd.into_raw_fd();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_CLOSE;
            sqe.fd = raw_fd;
        })
    }

    // ── Métadonnées ───────────────────────────────────────────────────────

    /// Soumet un `IORING_OP_STATX` (21). Le kernel écrit la structure dans `out`
    /// (gardé en vie avec le chemin). Complétion via
    /// [`Completion::into_statx`](super::Completion::into_statx).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_statx(
        &mut self,
        dirfd: DirFd<'_>,
        path: CString,
        flags: StatxFlags,
        mask: StatxMask,
        mut out: Box<Statx>,
    ) -> Result<SubmissionToken, Errno> {
        let dirfd = dirfd_to_raw(dirfd);
        let path_ptr = path.as_ptr() as u64;
        let out_ptr = core::ptr::from_mut(&mut *out) as u64;
        let mask_bits = mask.bits();
        let flags_bits = flags.bits();
        self.submit_op(Some(OwnedOp::Statx { out, path }), |sqe| {
            sqe.opcode = raw::IORING_OP_STATX;
            sqe.fd = dirfd;
            sqe.addr_or_splice_off_in = path_ptr;
            sqe.len = mask_bits;
            sqe.off_or_addr2 = out_ptr;
            sqe.op_flags = flags_bits;
        })
    }

    // ── Conseils d'accès ──────────────────────────────────────────────────

    /// Soumet un `IORING_OP_FADVISE` (24) : conseil d'accès `posix_fadvise`.
    /// Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `length` déborde
    /// un `u32` (champ `len` du SQE en 6.12).
    pub fn submit_fadvise(
        &mut self,
        fd: BorrowedFd<'_>,
        offset: u64,
        length: u64,
        advice: FadviseAdvice,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let len = u32::try_from(length).map_err(|_| Errno::EINVAL)?;
        let advice = advice.as_raw().cast_unsigned();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_FADVISE;
            sqe.fd = fd;
            sqe.off_or_addr2 = offset;
            sqe.len = len;
            sqe.op_flags = advice;
        })
    }

    /// Soumet un `IORING_OP_MADVISE` (25) : conseil kernel sur le pattern
    /// d'accès à un sous-`range` d'une [`MmapRegion`] **partageable**. La région
    /// **doit rester mappée jusqu'à la complétion** : le slot S1 retient une
    /// garde de vivacité ([`MmapRegion::liveness_handle`]) — `munmap` ne peut
    /// donc pas survenir tant que l'op est en vol (sûreté par construction,
    /// cf. `family-mem-mmap-region.md`). Complétion via
    /// [`Completion::completed`](super::Completion::completed).
    ///
    /// `range` est validé **en amont** (Principe 4) contre les bornes de la
    /// région : pas de plage brute, pas d'API `unsafe`.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `range` est mal formé (`start > end`) ou déborde la
    /// région (`range.end > region.len()`), ou si la longueur déborde un `u32` ;
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_madvise(
        &mut self,
        region: &MmapRegion,
        range: Range<usize>,
        advice: MadviseAdvice,
    ) -> Result<SubmissionToken, Errno> {
        // Validation amont : sous-plage bien formée et dans les bornes.
        if range.start > range.end || range.end > region.len() {
            return Err(Errno::EINVAL);
        }
        let span = range.end.checked_sub(range.start).ok_or(Errno::EINVAL)?;
        let len = len_u32(span)?;
        let start = u64::try_from(range.start).map_err(|_| Errno::EINVAL)?;
        let addr = (region.as_ptr() as u64)
            .checked_add(start)
            .ok_or(Errno::EINVAL)?;
        // MadviseAdvice est `#[repr(i32)]` : `advice as i32` est exact et sans
        // perte (même idiome que le `madvise` synchrone de la famille `mem`).
        #[allow(clippy::as_conversions)]
        let advice_flags = (advice as i32).cast_unsigned();
        let guard = region.liveness_handle();
        self.submit_op(Some(OwnedOp::MemLiveness(guard)), |sqe| {
            sqe.opcode = raw::IORING_OP_MADVISE;
            sqe.fd = -1;
            sqe.addr_or_splice_off_in = addr;
            sqe.len = len;
            sqe.op_flags = advice_flags;
        })
    }

    // ── Zero-copy FD↔FD ───────────────────────────────────────────────────

    /// Soumet un `IORING_OP_SPLICE` (30). Au moins un des deux FDs est un pipe.
    /// Les offsets `None` valent « position courante / FD non seekable ».
    /// Complétion via [`Completion::into_result`](super::Completion::into_result)
    /// (octets transférés).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_splice(
        &mut self,
        fd_in: BorrowedFd<'_>,
        offset_in: Option<u64>,
        fd_out: BorrowedFd<'_>,
        offset_out: Option<u64>,
        length: u32,
        flags: SpliceFlags,
    ) -> Result<SubmissionToken, Errno> {
        let fd_in = fd_in.as_raw_fd();
        let fd_out = fd_out.as_raw_fd();
        let off_in = offset_to_raw(offset_in);
        let off_out = offset_to_raw(offset_out);
        let op_flags = flags.bits();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_SPLICE;
            sqe.fd = fd_out;
            sqe.off_or_addr2 = off_out;
            sqe.addr_or_splice_off_in = off_in;
            sqe.len = length;
            sqe.op_flags = op_flags;
            sqe.splice_fd_in_or_file_index = fd_in.cast_unsigned();
        })
    }

    /// Soumet un `IORING_OP_TEE` (33) : duplique entre deux pipes sans consommer
    /// la source. Complétion via `into_result` (octets transférés).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_tee(
        &mut self,
        fd_in: BorrowedFd<'_>,
        fd_out: BorrowedFd<'_>,
        length: u32,
        flags: SpliceFlags,
    ) -> Result<SubmissionToken, Errno> {
        let fd_in = fd_in.as_raw_fd();
        let fd_out = fd_out.as_raw_fd();
        let op_flags = flags.bits();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_TEE;
            sqe.fd = fd_out;
            sqe.len = length;
            sqe.op_flags = op_flags;
            sqe.splice_fd_in_or_file_index = fd_in.cast_unsigned();
        })
    }

    // ── Répertoires et liens ──────────────────────────────────────────────

    /// Soumet un `IORING_OP_MKDIRAT` (37). Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_mkdirat(
        &mut self,
        dirfd: DirFd<'_>,
        path: CString,
        mode: Mode,
    ) -> Result<SubmissionToken, Errno> {
        let dirfd = dirfd_to_raw(dirfd);
        let path_ptr = path.as_ptr() as u64;
        self.submit_op(Some(OwnedOp::Path(path)), |sqe| {
            sqe.opcode = raw::IORING_OP_MKDIRAT;
            sqe.fd = dirfd;
            sqe.addr_or_splice_off_in = path_ptr;
            sqe.len = mode;
        })
    }

    /// Soumet un `IORING_OP_UNLINKAT` (36). `UnlinkFlags::REMOVEDIR` supprime un
    /// répertoire. Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_unlinkat(
        &mut self,
        dirfd: DirFd<'_>,
        path: CString,
        flags: UnlinkFlags,
    ) -> Result<SubmissionToken, Errno> {
        let dirfd = dirfd_to_raw(dirfd);
        let path_ptr = path.as_ptr() as u64;
        let op_flags = flags.bits().cast_unsigned();
        self.submit_op(Some(OwnedOp::Path(path)), |sqe| {
            sqe.opcode = raw::IORING_OP_UNLINKAT;
            sqe.fd = dirfd;
            sqe.addr_or_splice_off_in = path_ptr;
            sqe.op_flags = op_flags;
        })
    }

    /// Soumet un `IORING_OP_RENAMEAT` (35, sémantique `renameat2`). Les deux
    /// chemins sont gardés en vie dans le slot. Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_renameat(
        &mut self,
        old_dirfd: DirFd<'_>,
        old_path: CString,
        new_dirfd: DirFd<'_>,
        new_path: CString,
        flags: RenameFlags,
    ) -> Result<SubmissionToken, Errno> {
        let old_dirfd = dirfd_to_raw(old_dirfd);
        let new_dirfd = dirfd_to_raw(new_dirfd);
        let old_ptr = old_path.as_ptr() as u64;
        let new_ptr = new_path.as_ptr() as u64;
        let op_flags = flags.bits();
        self.submit_op(Some(OwnedOp::TwoPaths(old_path, new_path)), |sqe| {
            sqe.opcode = raw::IORING_OP_RENAMEAT;
            sqe.fd = old_dirfd;
            sqe.addr_or_splice_off_in = old_ptr;
            sqe.len = new_dirfd.cast_unsigned();
            sqe.off_or_addr2 = new_ptr;
            sqe.op_flags = op_flags;
        })
    }

    /// Soumet un `IORING_OP_LINKAT` (39). Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_linkat(
        &mut self,
        old_dirfd: DirFd<'_>,
        old_path: CString,
        new_dirfd: DirFd<'_>,
        new_path: CString,
        flags: LinkFlags,
    ) -> Result<SubmissionToken, Errno> {
        let old_dirfd = dirfd_to_raw(old_dirfd);
        let new_dirfd = dirfd_to_raw(new_dirfd);
        let old_ptr = old_path.as_ptr() as u64;
        let new_ptr = new_path.as_ptr() as u64;
        let op_flags = flags.bits().cast_unsigned();
        self.submit_op(Some(OwnedOp::TwoPaths(old_path, new_path)), |sqe| {
            sqe.opcode = raw::IORING_OP_LINKAT;
            sqe.fd = old_dirfd;
            sqe.addr_or_splice_off_in = old_ptr;
            sqe.len = new_dirfd.cast_unsigned();
            sqe.off_or_addr2 = new_ptr;
            sqe.op_flags = op_flags;
        })
    }

    /// Soumet un `IORING_OP_SYMLINKAT` (38) : crée `link_path` pointant vers
    /// `target`. Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_symlinkat(
        &mut self,
        target: CString,
        new_dirfd: DirFd<'_>,
        link_path: CString,
    ) -> Result<SubmissionToken, Errno> {
        let new_dirfd = dirfd_to_raw(new_dirfd);
        let target_ptr = target.as_ptr() as u64;
        let link_ptr = link_path.as_ptr() as u64;
        self.submit_op(Some(OwnedOp::TwoPaths(target, link_path)), |sqe| {
            sqe.opcode = raw::IORING_OP_SYMLINKAT;
            sqe.fd = new_dirfd;
            sqe.addr_or_splice_off_in = target_ptr;
            sqe.off_or_addr2 = link_ptr;
        })
    }

    // ── Attributs étendus (xattr) ─────────────────────────────────────────

    /// Soumet un `IORING_OP_SETXATTR` (42). `name`, `value` et `path` sont gardés
    /// en vie dans le slot. Complétion via `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32`.
    pub fn submit_setxattr(
        &mut self,
        path: CString,
        name: CString,
        value: Vec<u8>,
        flags: XattrFlags,
    ) -> Result<SubmissionToken, Errno> {
        let name_ptr = name.as_ptr() as u64;
        let path_ptr = path.as_ptr() as u64;
        let value_ptr = value.as_ptr() as u64;
        let len = len_u32(value.len())?;
        let op_flags = flags.bits().cast_unsigned();
        self.submit_op(
            Some(OwnedOp::Xattr {
                value,
                name,
                path: Some(path),
            }),
            |sqe| {
                sqe.opcode = raw::IORING_OP_SETXATTR;
                sqe.addr_or_splice_off_in = name_ptr;
                sqe.off_or_addr2 = value_ptr;
                sqe.len = len;
                sqe.addr3 = path_ptr;
                sqe.op_flags = op_flags;
            },
        )
    }

    /// Soumet un `IORING_OP_GETXATTR` (44). `value` sert de buffer de sortie.
    /// Complétion via
    /// [`Completion::into_xattr_result`](super::Completion::into_xattr_result).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32`.
    pub fn submit_getxattr(
        &mut self,
        path: CString,
        name: CString,
        mut value: Vec<u8>,
    ) -> Result<SubmissionToken, Errno> {
        let name_ptr = name.as_ptr() as u64;
        let path_ptr = path.as_ptr() as u64;
        let value_ptr = value.as_mut_ptr() as u64;
        let len = len_u32(value.len())?;
        self.submit_op(
            Some(OwnedOp::Xattr {
                value,
                name,
                path: Some(path),
            }),
            |sqe| {
                sqe.opcode = raw::IORING_OP_GETXATTR;
                sqe.addr_or_splice_off_in = name_ptr;
                sqe.off_or_addr2 = value_ptr;
                sqe.len = len;
                sqe.addr3 = path_ptr;
            },
        )
    }

    /// Soumet un `IORING_OP_FSETXATTR` (41) : variante par FD. Complétion via
    /// `completed`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32`.
    pub fn submit_fsetxattr(
        &mut self,
        fd: BorrowedFd<'_>,
        name: CString,
        value: Vec<u8>,
        flags: XattrFlags,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let name_ptr = name.as_ptr() as u64;
        let value_ptr = value.as_ptr() as u64;
        let len = len_u32(value.len())?;
        let op_flags = flags.bits().cast_unsigned();
        self.submit_op(
            Some(OwnedOp::Xattr {
                value,
                name,
                path: None,
            }),
            |sqe| {
                sqe.opcode = raw::IORING_OP_FSETXATTR;
                sqe.fd = fd;
                sqe.addr_or_splice_off_in = name_ptr;
                sqe.off_or_addr2 = value_ptr;
                sqe.len = len;
                sqe.op_flags = op_flags;
            },
        )
    }

    /// Soumet un `IORING_OP_FGETXATTR` (43) : variante par FD. Complétion via
    /// `into_xattr_result`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32`.
    pub fn submit_fgetxattr(
        &mut self,
        fd: BorrowedFd<'_>,
        name: CString,
        mut value: Vec<u8>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let name_ptr = name.as_ptr() as u64;
        let value_ptr = value.as_mut_ptr() as u64;
        let len = len_u32(value.len())?;
        self.submit_op(
            Some(OwnedOp::Xattr {
                value,
                name,
                path: None,
            }),
            |sqe| {
                sqe.opcode = raw::IORING_OP_FGETXATTR;
                sqe.fd = fd;
                sqe.addr_or_splice_off_in = name_ptr;
                sqe.off_or_addr2 = value_ptr;
                sqe.len = len;
            },
        )
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Tests
// ───────────────────────────────────────────────────────────────────────────
//
// Les tests d'**intégration** (kernel 6.12 réel : tmpfs/ext4, pipes) portent
// `#[cfg_attr(miri, ignore)]` car Miri ne modélise pas `io_uring_enter` ni
// l'`asm!`. Les tests **purs** (accesseurs de `Completion`, invariants
// d'ownership) tournent SOUS Miri : `cargo +nightly miri test -p
// air-sys-syscall io_uring::fs_ops::ownership` prouve qu'un buffer en vol ne
// peut être ni libéré ni réutilisé (transfert/restitution sound).

#[cfg(test)]
mod tests {
    use super::*;
    use crate::io_uring::{Completion, IoUring, SubmissionToken};
    use crate::test_support::sfd;
    use air_sys_types::fd::AsFd;
    use air_sys_types::fs::OpenHow;
    use core::num::NonZeroU32;
    use std::ffi::CString;
    use std::io::{Read, Write};
    use std::os::unix::ffi::OsStrExt;
    use std::path::{Path, PathBuf};
    use std::sync::atomic::{AtomicU32, Ordering};

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

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

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

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

    /// Crée (tronque) un fichier de travail et le rend en lecture/écriture.
    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")
    }

    /// Soumet, attend une complétion, et vérifie le jeton retourné.
    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
    }

    // ── Intégration : lecture / écriture + offsets ────────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn write_then_read_round_trips_with_some_and_none_offset() {
        let path = temp_path("rw");
        let file = rw_file(&path);
        let mut ring = ring8();

        // write "hello" @ Some(0).
        let tok = ring
            .submit_write(sfd(&file), b"hello".to_vec(), Some(0))
            .expect("submit_write");
        let (buf, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("write ok");
        assert_eq!(n, 5);
        assert_eq!(buf, b"hello");

        // read 5 @ Some(0) → "hello" restitué.
        let tok = ring
            .submit_read(sfd(&file), vec![0u8; 5], Some(0))
            .expect("submit_read");
        let (buf, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("read ok");
        assert_eq!(n, 5);
        assert_eq!(&buf, b"hello");

        // write @ None (position courante = 0) puis read @ None lit l'EOF (0).
        let tok = ring
            .submit_write(sfd(&file), b"WORLD".to_vec(), None)
            .expect("submit_write None");
        let (_b, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("write None ok");
        assert_eq!(n, 5);
        let tok = ring
            .submit_read(sfd(&file), vec![0u8; 5], None)
            .expect("submit_read None");
        let (_b, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("read None ok");
        assert_eq!(n, 0, "position avancée par l'écriture None ⇒ EOF");

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn readv_writev_round_trip_multi_buffers() {
        let path = temp_path("rwv");
        let file = rw_file(&path);
        let mut ring = ring8();

        let tok = ring
            .submit_writev(sfd(&file), vec![b"foo".to_vec(), b"bar".to_vec()], Some(0))
            .expect("submit_writev");
        let (_bufs, n) = complete_one(&mut ring, tok)
            .into_vectored_result()
            .expect("writev ok");
        assert_eq!(n, 6);

        let tok = ring
            .submit_readv(sfd(&file), vec![vec![0u8; 3], vec![0u8; 3]], Some(0))
            .expect("submit_readv");
        let (bufs, n) = complete_one(&mut ring, tok)
            .into_vectored_result()
            .expect("readv ok");
        assert_eq!(n, 6);
        assert_eq!(bufs, vec![b"foo".to_vec(), b"bar".to_vec()]);

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn openat2_then_read_then_close_chain() {
        let path = temp_path("open");
        std::fs::write(&path, b"hello world").expect("fixture");
        let mut ring = ring8();

        let tok = ring
            .submit_openat2(DirFd::Cwd, cpath(&path), OpenHow::default())
            .expect("submit_openat2");
        let opened = complete_one(&mut ring, tok)
            .opened_fd()
            .expect("openat2 ok");

        let tok = ring
            .submit_read(opened.as_fd(), vec![0u8; 11], Some(0))
            .expect("submit_read");
        let (buf, n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("read ok");
        assert_eq!(&buf[..n], b"hello world");

        let tok = ring.submit_close(opened).expect("submit_close");
        complete_one(&mut ring, tok).completed().expect("close ok");

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn statx_reports_size() {
        let path = temp_path("statx");
        std::fs::write(&path, b"0123456789").expect("fixture (10 octets)");
        let mut ring = ring8();

        let tok = ring
            .submit_statx(
                DirFd::Cwd,
                cpath(&path),
                StatxFlags::empty(),
                StatxMask::SIZE,
                Box::new(Statx::default()),
            )
            .expect("submit_statx");
        let statx = complete_one(&mut ring, tok).into_statx().expect("statx ok");
        assert!(statx.has(StatxMask::SIZE));
        assert_eq!(statx.size, 10);

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn directory_and_link_ops() {
        let mut ring = ring8();

        // mkdirat + unlinkat(REMOVEDIR).
        let dir = temp_path("dir");
        let tok = ring
            .submit_mkdirat(DirFd::Cwd, cpath(&dir), 0o755)
            .expect("submit_mkdirat");
        complete_one(&mut ring, tok).completed().expect("mkdir ok");
        assert!(dir.is_dir());
        let tok = ring
            .submit_unlinkat(DirFd::Cwd, cpath(&dir), UnlinkFlags::REMOVEDIR)
            .expect("submit_unlinkat");
        complete_one(&mut ring, tok).completed().expect("rmdir ok");
        assert!(!dir.exists());

        // renameat.
        let src = temp_path("ren-a");
        let dst = temp_path("ren-b");
        std::fs::write(&src, b"x").expect("fixture");
        let tok = ring
            .submit_renameat(
                DirFd::Cwd,
                cpath(&src),
                DirFd::Cwd,
                cpath(&dst),
                RenameFlags::empty(),
            )
            .expect("submit_renameat");
        complete_one(&mut ring, tok).completed().expect("rename ok");
        assert!(!src.exists() && dst.exists());

        // linkat (hardlink) puis unlinkat (fichier).
        let link = temp_path("link");
        let tok = ring
            .submit_linkat(
                DirFd::Cwd,
                cpath(&dst),
                DirFd::Cwd,
                cpath(&link),
                LinkFlags::empty(),
            )
            .expect("submit_linkat");
        complete_one(&mut ring, tok).completed().expect("link ok");
        assert!(link.exists());

        // symlinkat.
        let sym = temp_path("sym");
        let tok = ring
            .submit_symlinkat(cpath(&dst), DirFd::Cwd, cpath(&sym))
            .expect("submit_symlinkat");
        complete_one(&mut ring, tok)
            .completed()
            .expect("symlink ok");
        assert!(
            std::fs::symlink_metadata(&sym)
                .expect("lstat")
                .file_type()
                .is_symlink()
        );

        for p in [&dst, &link, &sym] {
            let _ = std::fs::remove_file(p);
        }
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn xattr_set_get_round_trip() {
        let path = temp_path("xattr");
        std::fs::write(&path, b"data").expect("fixture");
        let mut ring = ring8();
        let name = CString::new("user.air_test").expect("nom sans NUL");

        // setxattr (chemin).
        let tok = ring
            .submit_setxattr(
                cpath(&path),
                name.clone(),
                b"value42".to_vec(),
                XattrFlags::empty(),
            )
            .expect("submit_setxattr");
        complete_one(&mut ring, tok)
            .completed()
            .expect("setxattr ok (ext4 supporte user.*)");

        // getxattr (chemin) → restitue la valeur.
        let tok = ring
            .submit_getxattr(cpath(&path), name.clone(), vec![0u8; 64])
            .expect("submit_getxattr");
        let (value, n) = complete_one(&mut ring, tok)
            .into_xattr_result()
            .expect("getxattr ok");
        assert_eq!(&value[..n], b"value42");

        // fsetxattr / fgetxattr (par FD) sur le même fichier.
        let file = std::fs::OpenOptions::new()
            .read(true)
            .write(true)
            .open(&path)
            .expect("réouverture");
        let fname = CString::new("user.air_fd").expect("nom sans NUL");
        let tok = ring
            .submit_fsetxattr(
                sfd(&file),
                fname.clone(),
                b"fdval".to_vec(),
                XattrFlags::empty(),
            )
            .expect("submit_fsetxattr");
        complete_one(&mut ring, tok)
            .completed()
            .expect("fsetxattr ok");
        let tok = ring
            .submit_fgetxattr(sfd(&file), fname, vec![0u8; 64])
            .expect("submit_fgetxattr");
        let (value, n) = complete_one(&mut ring, tok)
            .into_xattr_result()
            .expect("fgetxattr ok");
        assert_eq!(&value[..n], b"fdval");

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn sync_alloc_trunc_advise_ops() {
        let path = temp_path("sync");
        let file = rw_file(&path);
        let mut ring = ring8();

        // Écrit un contenu pour donner du grain aux ops.
        let tok = ring
            .submit_write(sfd(&file), vec![7u8; 256], Some(0))
            .expect("submit_write");
        let _ = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("ok");

        // fsync (DATASYNC) puis fsync (complet).
        let tok = ring
            .submit_fsync(sfd(&file), FsyncFlags::DATASYNC)
            .expect("submit_fsync");
        complete_one(&mut ring, tok)
            .completed()
            .expect("fdatasync ok");
        let tok = ring
            .submit_fsync(sfd(&file), FsyncFlags::empty())
            .expect("submit_fsync");
        complete_one(&mut ring, tok).completed().expect("fsync ok");

        // sync_file_range.
        let tok = ring
            .submit_sync_file_range(sfd(&file), 0, 256, SyncFileRangeFlags::WRITE)
            .expect("submit_sync_file_range");
        complete_one(&mut ring, tok)
            .completed()
            .expect("sync_file_range ok");

        // fallocate (alloue 4 Kio).
        let tok = ring
            .submit_fallocate(sfd(&file), FallocateMode::empty(), 0, 4096)
            .expect("submit_fallocate");
        complete_one(&mut ring, tok)
            .completed()
            .expect("fallocate ok");
        assert!(std::fs::metadata(&path).expect("stat").len() >= 4096);

        // ftruncate (réduit à 100).
        let tok = ring
            .submit_ftruncate(sfd(&file), 100)
            .expect("submit_ftruncate");
        complete_one(&mut ring, tok)
            .completed()
            .expect("ftruncate ok");
        assert_eq!(std::fs::metadata(&path).expect("stat").len(), 100);

        // fadvise.
        let tok = ring
            .submit_fadvise(sfd(&file), 0, 0, FadviseAdvice::WillNeed)
            .expect("submit_fadvise");
        complete_one(&mut ring, tok)
            .completed()
            .expect("fadvise ok");

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn splice_file_to_pipe_and_tee_pipe_to_pipe() {
        let path = temp_path("splice");
        std::fs::write(&path, b"splice me").expect("fixture (9 octets)");
        let file = std::fs::File::open(&path).expect("open ro");
        let mut ring = ring8();

        // splice fichier → pipe.
        let (mut reader, writer) = std::io::pipe().expect("pipe");
        let tok = ring
            .submit_splice(
                sfd(&file),
                Some(0),
                sfd(&writer),
                None,
                9,
                SpliceFlags::empty(),
            )
            .expect("submit_splice");
        let n = complete_one(&mut ring, tok)
            .into_result()
            .expect("splice ok");
        assert_eq!(n, 9);
        let mut got = [0u8; 9];
        reader.read_exact(&mut got).expect("lecture pipe");
        assert_eq!(&got, b"splice me");

        // tee pipe → pipe.
        let (reader1, mut writer1) = std::io::pipe().expect("pipe1");
        let (mut reader2, writer2) = std::io::pipe().expect("pipe2");
        writer1.write_all(b"tee").expect("alim pipe1");
        let tok = ring
            .submit_tee(sfd(&reader1), sfd(&writer2), 3, SpliceFlags::empty())
            .expect("submit_tee");
        let n = complete_one(&mut ring, tok).into_result().expect("tee ok");
        assert_eq!(n, 3);
        let mut got = [0u8; 3];
        reader2.read_exact(&mut got).expect("lecture pipe2");
        assert_eq!(&got, b"tee");

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn relative_ops_resolve_against_a_directory_fd() {
        // Couvre le bras `DirFd::Fd` de `dirfd_to_raw` (les autres tests usent
        // `DirFd::Cwd`) : un chemin relatif est résolu contre un FD de
        // répertoire ouvert.
        let dir = temp_path("dirfd");
        std::fs::create_dir(&dir).expect("mkdir fixture");
        std::fs::write(dir.join("inside.txt"), b"abcd").expect("fichier interne");
        let dir_fd = std::fs::File::open(&dir).expect("open dir fd");
        let mut ring = ring8();

        let rel = CString::new("inside.txt").expect("nom sans NUL");
        let tok = ring
            .submit_statx(
                DirFd::Fd(sfd(&dir_fd)),
                rel,
                StatxFlags::empty(),
                StatxMask::SIZE,
                Box::new(Statx::default()),
            )
            .expect("submit_statx relatif");
        let statx = complete_one(&mut ring, tok).into_statx().expect("statx ok");
        assert_eq!(statx.size, 4, "taille du fichier résolu via le dir fd");

        let _ = std::fs::remove_file(dir.join("inside.txt"));
        let _ = std::fs::remove_dir(&dir);
    }

    // ── Validation amont (Principe 4) — sans kernel ───────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn fallocate_rejects_invalid_geometry_before_submission() {
        let path = temp_path("falloc-inval");
        let file = rw_file(&path);
        let mut ring = ring8();
        // length ≤ 0.
        assert_eq!(
            ring.submit_fallocate(sfd(&file), FallocateMode::empty(), 0, 0),
            Err(Errno::EINVAL)
        );
        // offset < 0.
        assert_eq!(
            ring.submit_fallocate(sfd(&file), FallocateMode::empty(), -1, 10),
            Err(Errno::EINVAL)
        );
        // offset + length déborde un i64.
        assert_eq!(
            ring.submit_fallocate(sfd(&file), FallocateMode::empty(), i64::MAX, 1),
            Err(Errno::EINVAL)
        );
        assert_eq!(ring.in_flight(), 0, "aucun slot consommé sur rejet amont");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn length_overflow_validations_reject_before_submission() {
        let path = temp_path("len-inval");
        let file = rw_file(&path);
        let mut ring = ring8();
        let over_u32 = u64::from(u32::MAX) + 1;
        assert_eq!(
            ring.submit_sync_file_range(sfd(&file), 0, over_u32, SyncFileRangeFlags::WRITE),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            ring.submit_fadvise(sfd(&file), 0, over_u32, FadviseAdvice::Normal),
            Err(Errno::EINVAL)
        );
        // readv au-delà d'IOV_MAX.
        let too_many = vec![Vec::<u8>::new(); raw::IOV_MAX + 1];
        assert_eq!(
            ring.submit_readv(sfd(&file), too_many, Some(0)),
            Err(Errno::EINVAL)
        );
        assert_eq!(ring.in_flight(), 0);
        let _ = std::fs::remove_file(&path);
    }

    // ── Back-pressure (EBUSY) : les deux branches de `submit_op` ───────────

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn slab_full_returns_ebusy() {
        use crate::io_uring::IoUringBuilder;
        let path = temp_path("ebusy-slab");
        let file = rw_file(&path);
        // Slab limité à 1 via le builder.
        let mut ring = IoUringBuilder::new(NonZeroU32::new(8).expect("8"))
            .max_inflight(NonZeroU32::new(1).expect("1"))
            .build()
            .expect("ring slab=1");
        let _t = ring
            .submit_read(sfd(&file), vec![0u8; 4], Some(0))
            .expect("1ʳᵉ op");
        assert_eq!(
            ring.submit_read(sfd(&file), vec![0u8; 4], Some(0)),
            Err(Errno::EBUSY),
            "slab plein ⇒ EBUSY (reserve)"
        );
        // Quiesce.
        ring.submit_and_wait(1).expect("submit");
        let _ = ring.wait_completion().expect("complétion");
        let _ = std::fs::remove_file(&path);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn full_submission_queue_returns_ebusy() {
        use crate::io_uring::IoUringBuilder;
        let path = temp_path("ebusy-sq");
        let file = rw_file(&path);
        // SQ = 4, slab = 8 : la SQ se remplit d'abord.
        let mut ring = IoUringBuilder::new(NonZeroU32::new(4).expect("4"))
            .max_inflight(NonZeroU32::new(8).expect("8"))
            .build()
            .expect("ring SQ=4");
        for _ in 0..4 {
            ring.submit_fsync(sfd(&file), FsyncFlags::empty())
                .expect("remplissage SQ");
        }
        assert_eq!(
            ring.submit_fsync(sfd(&file), FsyncFlags::empty()),
            Err(Errno::EBUSY),
            "SQ pleine ⇒ EBUSY (space_left == 0)"
        );
        // Draine les 4.
        ring.submit_and_wait(4).expect("submit");
        let mut n = 0;
        while n < 4 {
            for _ in ring.completions() {
                n += 1;
            }
        }
        let _ = std::fs::remove_file(&path);
    }

    // ── Options de soumission (skip_cqe_on_success) ───────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn skip_cqe_applies_to_no_payload_ops_only() {
        use crate::io_uring::SubmitOptions;
        let path = temp_path("skip");
        let file = rw_file(&path);
        let mut ring = ring8();

        // Op SANS payload (fsync) + skip : slot libéré à la soumission.
        ring.with(SubmitOptions::default().skip_cqe_on_success());
        ring.submit_fsync(sfd(&file), FsyncFlags::empty())
            .expect("fsync skip");
        assert_eq!(ring.in_flight(), 0, "no-payload + skip ⇒ slot libéré");
        assert_eq!(ring.submit().expect("submit"), 1);

        // Op AVEC payload (read) + skip : le bit est retiré (sûreté), slot retenu.
        ring.with(SubmitOptions::default().skip_cqe_on_success());
        let tok = ring
            .submit_read(sfd(&file), vec![0u8; 4], Some(0))
            .expect("read skip");
        assert_eq!(ring.in_flight(), 1, "payload + skip ⇒ slot conservé");
        let (_b, _n) = complete_one(&mut ring, tok)
            .into_buffer_result()
            .expect("read complète bien (CQE non sauté)");
        assert_eq!(ring.in_flight(), 0);
        let _ = std::fs::remove_file(&path);
    }

    // ── Robustesse aux chemins non-UTF-8 (property-based) ──────────────────

    proptest::proptest! {
        /// Un chemin fait d'octets arbitraires non nuls (souvent non-UTF-8) ne
        /// fait jamais paniquer la soumission ni le décodage : la complétion
        /// renvoie une valeur typée ou une erreur typée (ici `ENOENT`/`Ok`).
        #[test]
        #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
        fn non_utf8_paths_never_panic(bytes in proptest::collection::vec(1u8..=255, 1..40)) {
            let cpath = CString::new(bytes).expect("aucun NUL (octets 1..=255)");
            let mut ring = ring8();
            let tok = ring
                .submit_statx(
                    DirFd::Cwd,
                    cpath,
                    StatxFlags::empty(),
                    StatxMask::SIZE,
                    Box::new(Statx::default()),
                )
                .expect("submission jamais en panique");
            assert_eq!(ring.submit_and_wait(1).expect("submit"), 1);
            let completion = ring.wait_completion().expect("complétion");
            proptest::prop_assert_eq!(completion.token(), tok);
            // `into_statx` rend Ok(Box<Statx>) ou Err(errno) — jamais de panique.
            let _ = completion.into_statx();
        }

        /// read/write : octets transférés ≤ len, et restitution **fidèle** du
        /// buffer (le contenu écrit est relu à l'identique).
        #[test]
        #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
        fn write_read_transfers_bounded_and_faithful(
            data in proptest::collection::vec(proptest::prelude::any::<u8>(), 0..512)
        ) {
            let path = temp_path("prop-rw");
            let file = rw_file(&path);
            let mut ring = ring8();
            let len = data.len();

            let tok = ring
                .submit_write(sfd(&file), data.clone(), Some(0))
                .expect("submit_write");
            assert_eq!(ring.submit_and_wait(1).expect("submit"), 1);
            let (_b, written) = ring
                .wait_completion()
                .expect("complétion")
                .into_buffer_result()
                .expect("write ok");
            let _ = tok;
            proptest::prop_assert!(written <= len);
            proptest::prop_assert_eq!(written, len);

            let tok = ring
                .submit_read(sfd(&file), vec![0u8; len], Some(0))
                .expect("submit_read");
            assert_eq!(ring.submit_and_wait(1).expect("submit"), 1);
            let (buf, read) = ring
                .wait_completion()
                .expect("complétion")
                .into_buffer_result()
                .expect("read ok");
            let _ = tok;
            proptest::prop_assert!(read <= len);
            proptest::prop_assert_eq!(&buf[..read], &data[..read]);
            let _ = std::fs::remove_file(&path);
        }
    }

    // ── Accesseurs de complétion : bras défensifs + erreurs (purs) ─────────
    //
    // Construits directement (sans kernel) ⇒ tournent sous Miri. Couvrent les
    // bras `_` (mauvais payload) et les bras d'erreur (`res < 0`) des
    // accesseurs typés, que le chemin nominal (intégration) ne traverse pas.

    fn cqe(res: i32, payload: Option<OwnedOp>) -> Completion {
        Completion {
            token: SubmissionToken::new(0, 0),
            res,
            raw_flags: 0,
            payload,
            multishot: false,
        }
    }

    #[test]
    fn accessors_on_wrong_payload_yield_empty_defaults() {
        // into_buffer_result sur payload non-Bytes ⇒ buffer vide.
        let (b, n) = cqe(0, Some(OwnedOp::Path(CString::new("x").unwrap())))
            .into_buffer_result()
            .expect("ok");
        assert!(b.is_empty() && n == 0);
        // into_vectored_result sur Bytes ⇒ vecteur vide.
        let (v, n) = cqe(0, Some(OwnedOp::Bytes(vec![1, 2])))
            .into_vectored_result()
            .expect("ok");
        assert!(v.is_empty() && n == 0);
        // into_statx sur None ⇒ Statx zéro-initialisé.
        let st = cqe(0, None).into_statx().expect("ok");
        assert_eq!(st.mask, 0);
        // into_xattr_result sur None ⇒ valeur vide.
        let (val, n) = cqe(0, None).into_xattr_result().expect("ok");
        assert!(val.is_empty() && n == 0);
    }

    #[test]
    fn accessors_propagate_kernel_errors() {
        // res < 0 ⇒ Err(errno) sur chaque accesseur.
        assert_eq!(
            cqe(-2, Some(OwnedOp::Bytes(vec![1]))).into_buffer_result(),
            Err(Errno::ENOENT)
        );
        assert_eq!(cqe(-2, None).into_vectored_result(), Err(Errno::ENOENT));
        assert_eq!(cqe(-13, None).into_statx().err(), Some(Errno::EACCES));
        assert_eq!(cqe(-9, None).into_xattr_result(), Err(Errno::EBADF));
        // opened_fd : res < 0 ⇒ Err (pas de FD créé).
        assert_eq!(cqe(-2, None).opened_fd().err(), Some(Errno::ENOENT));
    }

    // ── Invariants d'ownership (Miri) : transfert + restitution sound ──────

    #[test]
    fn ownership_bytes_round_trips_without_uaf() {
        let data = vec![3u8; 32];
        let (buf, n) = cqe(32, Some(OwnedOp::Bytes(data.clone())))
            .into_buffer_result()
            .expect("ok");
        assert_eq!(n, 32);
        assert_eq!(buf, data);
    }

    #[test]
    fn ownership_vectored_round_trips_without_uaf() {
        let original = vec![vec![1u8, 2, 3], vec![4, 5]];
        let mut buffers = original.clone();
        let iovecs: Box<[Iovec]> = buffers
            .iter_mut()
            .map(|b| Iovec {
                iov_base: b.as_mut_ptr(),
                iov_len: b.len(),
            })
            .collect();
        let payload = OwnedOp::Vectored { buffers, iovecs };
        let (restituted, n) = cqe(5, Some(payload)).into_vectored_result().expect("ok");
        assert_eq!(n, 5);
        assert_eq!(restituted, original);
    }

    #[test]
    fn ownership_statx_and_xattr_round_trip_without_uaf() {
        let mut out = Box::new(Statx::default());
        out.size = 4242;
        let payload = OwnedOp::Statx {
            out,
            path: CString::new("/some/path").unwrap(),
        };
        let st = cqe(0, Some(payload)).into_statx().expect("ok");
        assert_eq!(st.size, 4242);

        let payload = OwnedOp::Xattr {
            value: b"abc".to_vec(),
            name: CString::new("user.k").unwrap(),
            path: Some(CString::new("/p").unwrap()),
        };
        let (value, n) = cqe(3, Some(payload)).into_xattr_result().expect("ok");
        assert_eq!(&value[..n], b"abc");
    }

    #[test]
    fn ownership_payloads_drop_without_extraction() {
        // Un payload jamais extrait (op annulée, complétion ignorée) se drop
        // proprement : aucun double-free / fuite (vérifié sous Miri).
        let mut buffers = vec![vec![9u8; 8]];
        let iovecs: Box<[Iovec]> = buffers
            .iter_mut()
            .map(|b| Iovec {
                iov_base: b.as_mut_ptr(),
                iov_len: b.len(),
            })
            .collect();
        let payloads = [
            OwnedOp::Bytes(vec![1, 2, 3]),
            OwnedOp::Vectored { buffers, iovecs },
            OwnedOp::Path(CString::new("p").unwrap()),
            OwnedOp::TwoPaths(CString::new("a").unwrap(), CString::new("b").unwrap()),
            OwnedOp::Xattr {
                value: vec![0u8; 4],
                name: CString::new("n").unwrap(),
                path: None,
            },
        ];
        for p in payloads {
            drop(cqe(0, Some(p)));
        }
    }

    // ── Madvise sur MmapRegion ────────────────────────────────────────────

    /// `submit_madvise(WILLNEED)` sur une `MmapRegion` complète ; la validation
    /// amont du `range` rend `EINVAL` (hors bornes / mal formé) avant soumission.
    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn madvise_on_mmap_region_completes_and_validates() {
        use air_sys_types::mem::{MapFlags, ProtectionFlags};
        let region = MmapRegion::new_anonymous(
            4096,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE,
        )
        .expect("new_anonymous");
        let mut ring = ring8();

        let tok = ring
            .submit_madvise(&region, 0..4096, MadviseAdvice::WillNeed)
            .expect("submit_madvise");
        complete_one(&mut ring, tok)
            .completed()
            .expect("madvise WILLNEED ok");

        // Sous-plage valide (DONTNEED sur une moitié).
        let tok = ring
            .submit_madvise(&region, 0..2048, MadviseAdvice::DontNeed)
            .expect("submit_madvise demi");
        complete_one(&mut ring, tok)
            .completed()
            .expect("madvise DONTNEED ok");

        // Validation amont : range.end > len ⇒ EINVAL avant soumission.
        assert_eq!(
            ring.submit_madvise(&region, 0..8192, MadviseAdvice::DontNeed)
                .unwrap_err(),
            Errno::EINVAL
        );
        // range mal formé (start > end) ⇒ EINVAL. Construit explicitement pour
        // ne pas déclencher `clippy::reversed_empty_ranges` sur un littéral.
        let malformed = Range {
            start: 100,
            end: 50,
        };
        assert_eq!(
            ring.submit_madvise(&region, malformed, MadviseAdvice::Normal)
                .unwrap_err(),
            Errno::EINVAL
        );
    }

    /// Dropper la `MmapRegion` côté utilisateur **pendant** qu'une op `madvise`
    /// est en vol ne corrompt rien : la garde du slot tient la région mappée
    /// jusqu'à la complétion (ni UAF, ni fuite).
    #[test]
    #[cfg_attr(miri, ignore = "syscall io_uring non supporté par Miri")]
    fn madvise_keeps_region_alive_while_in_flight() {
        use air_sys_types::mem::{MapFlags, ProtectionFlags};
        let region = MmapRegion::new_anonymous(
            4096,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE,
        )
        .expect("new_anonymous");
        let mut ring = ring8();
        let tok = ring
            .submit_madvise(&region, 0..4096, MadviseAdvice::WillNeed)
            .expect("submit_madvise");
        // L'utilisateur lâche sa référence : la garde garée en S1 reste.
        drop(region);
        // L'op complète proprement ; la région est démappée au drop du slot.
        complete_one(&mut ring, tok)
            .completed()
            .expect("madvise en vol ok malgré drop côté utilisateur");
    }
}