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;