air_sys_syscall/io_uring/

cmd.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ération **`URING_CMD`** (opcode 46, **Temps 2d**) : passthrough par lequel
//! io_uring transmet une **commande opaque** au gestionnaire `uring_cmd` du
//! sous-système propriétaire du fichier visé (socket, NVMe, ublk…). C'est
//! l'opération la plus « brute » des Temps 2x : sa sémantique dépend du
//! sous-système cible, pas d'io_uring.
//!
//! Référence normative : `docs/specs/layer-0/io-uring-2d-cmd.md`.
//!
//! Deux niveaux d'exposition :
//! - **Commandes socket typées sûres** (`submit_socket_inq`/`outq`,
//!   `submit_getsockopt`/`setsockopt`) — les quatre `io_uring_socket_op` de 6.12 ;
//! - **Générique** : [`UringCommand`] (`unsafe trait`) + [`IoUring::submit_uring_cmd`]
//!   pour les sous-systèmes typés par leur consommateur (les structures NVMe/ublk
//!   vivent **là où elles sont utilisées**, pas en couche 0), et la forme **brute
//!   `unsafe`** [`IoUring::submit_uring_cmd_raw`] en dernier recours.
//!
//! **Disposition kernel du SQE pour `URING_CMD`** (uapi 6.12) : `cmd_op` en
//! `off` (offset 8) ; pour `getsockopt`/`setsockopt`, `level`/`optname` en `addr`
//! (offset 16, deux `u32`), `optlen` en `splice_fd_in` (offset 44), `optval` en
//! `addr3` (offset 48) ; la **zone `cmd[]`** générique commence à l'offset 48
//! (`addr3`/`__pad2` = 16 octets, étendue à 80 octets avec `SETUP_SQE128`).

use super::owned::OwnedOp;
use super::raw;
use super::{Completion, IoUring, SubmissionToken};
use air_sys_types::Errno;
use air_sys_types::fd::{AsRawFd, BorrowedFd};
use air_sys_types::io_uring::UringCmdFlags;
use air_sys_types::net::SocketOptionLevel;
use alloc::vec::Vec;

/// Une **commande passthrough** d'un sous-système, sérialisable dans la zone
/// `cmd[]` d'`URING_CMD`.
///
/// # Safety
///
/// L'implémenteur garantit que [`encode`](UringCommand::encode) produit une
/// commande **valide** pour le gestionnaire `uring_cmd` du `fd` ciblé, que
/// [`cmd_op`](UringCommand::cmd_op) est l'opération correcte du sous-système, et
/// que tout buffer externe référencé par la commande reste valide jusqu'à la
/// complétion. io_uring ne peut pas vérifier ces invariants (la zone `cmd[]` lui
/// est **opaque**) — d'où le `unsafe trait`.
pub unsafe trait UringCommand {
    /// Type de la valeur interprétée à la complétion.
    type Output;

    /// Opération propre au sous-système (`cmd_op`, posée en `off`).
    fn cmd_op(&self) -> u32;

    /// Taille requise de la zone de commande, en octets (`≤ 16`, ou `≤ 80` si le
    /// ring a `SETUP_SQE128`).
    fn cmd_len(&self) -> usize;

    /// Sérialise la commande dans `out` (de longueur exacte `cmd_len()`).
    fn encode(&self, out: &mut [u8]);

    /// Interprétation typée de la complétion (appelée par le consommateur, qui
    /// conserve une instance de la commande).
    ///
    /// # Errors
    ///
    /// L'[`Errno`] décodé de la complétion, ou toute erreur d'interprétation
    /// propre au sous-système.
    fn interpret(&self, completion: &Completion) -> Result<Self::Output, Errno>;
}

impl IoUring {
    /// Capacité de la zone `cmd[]` en octets : `16` (SQE standard) ou `80` si le
    /// ring a été créé avec `SetupFlags::SQE128`.
    fn cmd_zone_capacity(&self) -> usize {
        self.sq.sqe_size().saturating_sub(raw::CMD_ZONE_OFFSET)
    }

    /// Cœur commun `inq`/`outq` : `URING_CMD` sans buffer, `cmd_op` en `off`.
    /// Complétion via [`Completion::into_result`] (nombre d'octets en file).
    fn submit_socket_queue(
        &mut self,
        sock: BorrowedFd<'_>,
        cmd_op: u32,
    ) -> Result<SubmissionToken, Errno> {
        let fd = sock.as_raw_fd();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_URING_CMD;
            sqe.fd = fd;
            sqe.off_or_addr2 = u64::from(cmd_op);
        })
    }

    /// Soumet `SIOCINQ` (octets disponibles en **lecture**) via `URING_CMD` sur
    /// un socket — l'équivalent `ioctl(SIOCINQ)` **dans le ring**.
    /// `cmd_op = SOCKET_URING_OP_SIOCINQ` (0). Complétion via
    /// [`Completion::into_result`] (nombre d'octets).
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins ; à la complétion,
    /// `ENOTSOCK`/`EINVAL` selon le FD.
    pub fn submit_socket_inq(&mut self, sock: BorrowedFd<'_>) -> Result<SubmissionToken, Errno> {
        self.submit_socket_queue(sock, raw::SOCKET_URING_OP_SIOCINQ)
    }

    /// Soumet `SIOCOUTQ` (octets **en attente d'émission**) via `URING_CMD`.
    /// `cmd_op = SOCKET_URING_OP_SIOCOUTQ` (1). Complétion via
    /// [`Completion::into_result`].
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_socket_inq`].
    pub fn submit_socket_outq(&mut self, sock: BorrowedFd<'_>) -> Result<SubmissionToken, Errno> {
        self.submit_socket_queue(sock, raw::SOCKET_URING_OP_SIOCOUTQ)
    }

    /// Encode `level`/`optname` dans le champ `addr` (offset 16) : `level` en bits
    /// bas, `optname` en bits hauts (deux `u32`, ABI `getsockopt`/`setsockopt`).
    fn level_optname(level: SocketOptionLevel, optname: i32) -> u64 {
        u64::from(level.as_raw().cast_unsigned()) | (u64::from(optname.cast_unsigned()) << 32)
    }

    /// Soumet un **`getsockopt`** via `URING_CMD` (`cmd_op = GETSOCKOPT`, 2). Le
    /// buffer `value` est le **buffer de sortie** (ownership transféré, S1) : le
    /// kernel y écrit l'option. Complétion via
    /// [`Completion::into_buffer_result`] → `(value, longueur effective)`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32` ; à la complétion, `ENOPROTOOPT`/`EINVAL`/`ENOTSOCK`/`EFAULT`.
    pub fn submit_getsockopt(
        &mut self,
        sock: BorrowedFd<'_>,
        level: SocketOptionLevel,
        optname: i32,
        mut value: Vec<u8>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = sock.as_raw_fd();
        let optlen = u32::try_from(value.len()).map_err(|_| Errno::EINVAL)?;
        let optval = value.as_mut_ptr() as u64;
        let level_optname = Self::level_optname(level, optname);
        self.submit_op(Some(OwnedOp::Bytes(value)), |sqe| {
            sqe.opcode = raw::IORING_OP_URING_CMD;
            sqe.fd = fd;
            sqe.off_or_addr2 = u64::from(raw::SOCKET_URING_OP_GETSOCKOPT);
            sqe.addr_or_splice_off_in = level_optname;
            sqe.splice_fd_in_or_file_index = optlen;
            sqe.addr3 = optval;
        })
    }

    /// Soumet un **`setsockopt`** via `URING_CMD` (`cmd_op = SETSOCKOPT`, 3). Le
    /// buffer `value` (octets, Principe 3) est **déplacé dans le slot** (le kernel
    /// le lit jusqu'à la complétion). Complétion via [`Completion::completed`].
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] (SQ/slab plein) ; [`Errno::EINVAL`] si `value.len()`
    /// déborde un `u32` ; à la complétion, `ENOPROTOOPT`/`EINVAL`/`ENOTSOCK`/`EFAULT`.
    pub fn submit_setsockopt(
        &mut self,
        sock: BorrowedFd<'_>,
        level: SocketOptionLevel,
        optname: i32,
        value: Vec<u8>,
    ) -> Result<SubmissionToken, Errno> {
        let fd = sock.as_raw_fd();
        let optlen = u32::try_from(value.len()).map_err(|_| Errno::EINVAL)?;
        let optval = value.as_ptr() as u64;
        let level_optname = Self::level_optname(level, optname);
        self.submit_op(Some(OwnedOp::Bytes(value)), |sqe| {
            sqe.opcode = raw::IORING_OP_URING_CMD;
            sqe.fd = fd;
            sqe.off_or_addr2 = u64::from(raw::SOCKET_URING_OP_SETSOCKOPT);
            sqe.addr_or_splice_off_in = level_optname;
            sqe.splice_fd_in_or_file_index = optlen;
            sqe.addr3 = optval;
        })
    }

    /// Écrit les champs nommés (`opcode`/`fd`/`cmd_op`/`op_flags`) puis sérialise
    /// `cmd_bytes` dans la **zone `cmd[]`** (offset 48), via le pointeur brut du
    /// slot (dont la provenance couvre tout le SQE, y compris l'extension
    /// `SQE128`). Cœur commun du générique et du brut.
    fn submit_cmd_zone(
        &mut self,
        fd: i32,
        cmd_op: u32,
        op_flags: u32,
        cmd_bytes: &[u8],
    ) -> Result<SubmissionToken, Errno> {
        self.submit_filled(None, |sqe_ptr| {
            {
                // SAFETY: `sqe_ptr` pointe un slot SQE valide et exclusivement
                // détenu ; le `&mut` ne vit que cette portée (avant l'écriture
                // brute de `cmd[]` ci-dessous — pas d'aliasing simultané).
                let sqe = unsafe { &mut *sqe_ptr };
                sqe.opcode = raw::IORING_OP_URING_CMD;
                sqe.fd = fd;
                sqe.off_or_addr2 = u64::from(cmd_op);
                sqe.op_flags = op_flags;
            }
            // SAFETY: `cmd_bytes.len() ≤ cmd_zone_capacity()` (validé par les
            // appelants) ⇒ `[48, 48 + len)` est **dans** le slot (`sqe_size`
            // octets). La provenance de `sqe_ptr` couvre tout le slot (cf.
            // `SubmissionRing::prepare`). `cmd_bytes` (source) et la zone (dest)
            // ne se chevauchent pas (buffer local vs mmap).
            unsafe {
                let zone = sqe_ptr.cast::<u8>().add(raw::CMD_ZONE_OFFSET);
                core::ptr::copy_nonoverlapping(cmd_bytes.as_ptr(), zone, cmd_bytes.len());
            }
        })
    }

    /// Soumet une commande passthrough **typée** ([`UringCommand`]) sur `fd`. La
    /// commande est **sérialisée** dans la zone `cmd[]` (la complétion sera
    /// interprétée par le consommateur via [`UringCommand::interpret`]).
    ///
    /// Vérifie `cmd.cmd_len() ≤ 16` (ou `≤ 80` si le ring a `SQE128`) **en amont**
    /// (Principe 4) — **pas de troncature silencieuse**.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `cmd.cmd_len()` dépasse la capacité de la zone `cmd[]`
    /// du ring ; [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub fn submit_uring_cmd<C: UringCommand>(
        &mut self,
        fd: BorrowedFd<'_>,
        cmd: C,
    ) -> Result<SubmissionToken, Errno> {
        let len = cmd.cmd_len();
        if len > self.cmd_zone_capacity() {
            return Err(Errno::EINVAL);
        }
        // Zone maximale 6.12 (80 octets avec SQE128) ; sérialisation sur la pile.
        let mut buffer = [0u8; 80];
        // `len ≤ cmd_zone_capacity() ≤ 80` ⇒ tranche valide.
        let scratch = buffer.get_mut(..len).ok_or(Errno::EINVAL)?;
        cmd.encode(scratch);
        let fd = fd.as_raw_fd();
        let cmd_op = cmd.cmd_op();
        self.submit_cmd_zone(fd, cmd_op, 0, &buffer[..len])
    }

    /// Soumet une commande passthrough **brute** — échappatoire de dernier recours
    /// pour un sous-système non encore typé.
    ///
    /// # Safety
    ///
    /// L'appelant garantit que :
    /// 1. `cmd_data` est une commande **valide** pour le gestionnaire `uring_cmd`
    ///    du `fd` ciblé (contenu opaque pour io_uring) ;
    /// 2. tout buffer **référencé** par `cmd_data` reste valide **jusqu'à la
    ///    complétion** (la façade ne le maintient pas en vie) ;
    /// 3. `cmd_data.len() ≤ 16` (ou `≤ 80` si le ring a `SetupFlags::SQE128`) —
    ///    sinon `Err(EINVAL)` est rendu sans rien soumettre.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `cmd_data.len()` dépasse la capacité de la zone
    /// `cmd[]` ; [`Errno::EBUSY`] si la SQ ou le slab sont pleins.
    pub unsafe fn submit_uring_cmd_raw(
        &mut self,
        fd: BorrowedFd<'_>,
        cmd_op: u32,
        cmd_data: &[u8],
        flags: UringCmdFlags,
    ) -> Result<SubmissionToken, Errno> {
        if cmd_data.len() > self.cmd_zone_capacity() {
            return Err(Errno::EINVAL);
        }
        let fd = fd.as_raw_fd();
        let op_flags = if flags.contains(UringCmdFlags::FIXED) {
            raw::IORING_URING_CMD_FIXED
        } else {
            0
        };
        self.submit_cmd_zone(fd, cmd_op, op_flags, cmd_data)
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Tests
// ───────────────────────────────────────────────────────────────────────────
//
// Intégration (kernel 6.12 réel : socket loopback) en `#[cfg_attr(miri, ignore)]`
// (Miri ne modélise pas `io_uring_enter`). La sérialisation `encode` (bornée
// dans `cmd[]`) est testée **sous Miri** (logique pure, sans ring).

#[cfg(test)]
mod tests;