air_sys_types/

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

//! Types de données **pures** du module `io_uring` (Temps 1, cible kernel 6.12).
//!
//! Ce module ne contient que les types à sémantique publique autonome, sans
//! état interne consommé par le wrapper : les bitflags de setup
//! ([`SetupFlags`]) et de complétion ([`CompletionFlags`]), et l'énumération
//! des opcodes ([`IoUringOpcode`]). Les types couplés au wrapper
//! (`IoUring`, `IoUringBuilder`, `SubmissionToken`, `SubmitOptions`,
//! `IoUringParams`, `IoUringCapabilities`, `Completion`, `CompletionIter`,
//! `CancelTarget`, `Restriction`) vivent dans `air-sys-syscall::io_uring`.
//!
//! > **Note de cadrage (Pass A) :** la spec §13 (`io-uring-1-core.md`) liste
//! > l'ensemble de ces types « ajoutés à air-sys-types ». Plusieurs d'entre eux
//! > exposent des internes consommés par le wrapper (décodage du `user_data`,
//! > traduction `SubmitOptions`→SQE, champs ABI d'`io_uring_params`) : les
//! > placer ici exigerait des accesseurs publics hors contrat. Ils sont donc
//! > gardés côté wrapper au Temps 1 ; **placement final à valider**.
//!
//! Référence normative : `docs/specs/layer-0/io-uring-1-core.md`,
//! `docs/specs/layer-0/io-uring-0-inventaire.md` §5.

bitflags::bitflags! {
    /// Flags de `io_uring_setup(2)` (axe A, 17 flags en 6.12).
    ///
    /// Appliqués via `IoUringBuilder`. Deux flags de l'axe A ne figurent pas
    /// ici car exposés par des **méthodes** du builder : `CQSIZE`
    /// (`with_completion_queue_entries`) et `ATTACH_WQ` (`attach_work_queue`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct SetupFlags: u32 {
        /// `IORING_SETUP_IOPOLL` : polling I/O (stockage `O_DIRECT`).
        const IOPOLL = 1 << 0;
        /// `IORING_SETUP_SQPOLL` : thread kernel de poll de la SQ (Temps 3e).
        const SQPOLL = 1 << 1;
        /// `IORING_SETUP_SQ_AFF` : affinité CPU du thread SQPOLL.
        const SQ_AFF = 1 << 2;
        /// `IORING_SETUP_CLAMP` : borne `entries` aux limites kernel.
        const CLAMP = 1 << 4;
        /// `IORING_SETUP_R_DISABLED` : ring créé désactivé (primitive sandbox, Temps 3f).
        const R_DISABLED = 1 << 6;
        /// `IORING_SETUP_SUBMIT_ALL` : ne pas s'arrêter à la première erreur de soumission.
        const SUBMIT_ALL = 1 << 7;
        /// `IORING_SETUP_COOP_TASKRUN` : task-work coopératif (moins d'IPI).
        const COOP_TASKRUN = 1 << 8;
        /// `IORING_SETUP_TASKRUN_FLAG` : signale le task-work en attente via un flag d'anneau.
        const TASKRUN_FLAG = 1 << 9;
        /// `IORING_SETUP_SQE128` : SQE de 128 octets (requis pour `URING_CMD` large).
        const SQE128 = 1 << 10;
        /// `IORING_SETUP_CQE32` : CQE de 32 octets (complétions étendues).
        const CQE32 = 1 << 11;
        /// `IORING_SETUP_SINGLE_ISSUER` : un seul thread soumetteur (recommandé Air).
        const SINGLE_ISSUER = 1 << 12;
        /// `IORING_SETUP_DEFER_TASKRUN` : task-work différé à `GETEVENTS` (latence basse).
        const DEFER_TASKRUN = 1 << 13;
        /// `IORING_SETUP_NO_MMAP` : mémoire des anneaux fournie par l'appelant (avancé, gated).
        const NO_MMAP = 1 << 14;
        /// `IORING_SETUP_REGISTERED_FD_ONLY` : ring fd uniquement enregistré.
        const REGISTERED_FD_ONLY = 1 << 15;
        /// `IORING_SETUP_NO_SQARRAY` : supprime l'indirection du tableau d'index SQ.
        const NO_SQARRAY = 1 << 16;
    }

    /// Flags de complétion `IORING_CQE_F_*` (axe E, 5 flags en 6.12).
    ///
    /// Exposés de façon typée par les méthodes de `Completion`
    /// (`has_more`, `is_notif`, `buffer_id`, `socket_has_pending_data`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct CompletionFlags: u32 {
        /// `IORING_CQE_F_BUFFER` : un buffer fourni a été consommé (id dans les bits hauts).
        const BUFFER = 1 << 0;
        /// `IORING_CQE_F_MORE` : d'autres complétions suivront (multishot, Temps 3d).
        const MORE = 1 << 1;
        /// `IORING_CQE_F_SOCK_NONEMPTY` : données restantes lisibles après un `recv`.
        const SOCK_NONEMPTY = 1 << 2;
        /// `IORING_CQE_F_NOTIF` : complétion de notification zero-copy (Temps 2b).
        const NOTIF = 1 << 3;
        /// `IORING_CQE_F_BUF_MORE` : consommation incrémentale d'un buffer (Temps 3b).
        const BUF_MORE = 1 << 4;
    }
}

/// Énumération des 55 opcodes `IORING_OP_*` retenus (axe B, 6.12).
///
/// Sert au probe (`IoUring::supports_op`) et aux restrictions (S3). Les 3
/// opcodes obsolètes (`OPENAT`, `PROVIDE_BUFFERS`, `REMOVE_BUFFERS`) sont
/// évacués (cf. `UNSUPPORTED.md`) et **absents** de cette énumération.
/// `#[non_exhaustive]` : de futurs kernels peuvent en ajouter.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum IoUringOpcode {
    /// `IORING_OP_NOP` (0) — no-op (validation du cœur, Temps 2c).
    Nop,
    /// `IORING_OP_READV` (1) — lecture vectorisée.
    Readv,
    /// `IORING_OP_WRITEV` (2) — écriture vectorisée.
    Writev,
    /// `IORING_OP_FSYNC` (3) — synchronisation fichier.
    Fsync,
    /// `IORING_OP_READ_FIXED` (4) — lecture vers buffer enregistré.
    ReadFixed,
    /// `IORING_OP_WRITE_FIXED` (5) — écriture depuis buffer enregistré.
    WriteFixed,
    /// `IORING_OP_POLL_ADD` (6) — ajout d'un poll.
    PollAdd,
    /// `IORING_OP_POLL_REMOVE` (7) — retrait d'un poll.
    PollRemove,
    /// `IORING_OP_SYNC_FILE_RANGE` (8) — synchronisation d'une plage de fichier.
    SyncFileRange,
    /// `IORING_OP_SENDMSG` (9) — envoi de message socket.
    Sendmsg,
    /// `IORING_OP_RECVMSG` (10) — réception de message socket.
    Recvmsg,
    /// `IORING_OP_TIMEOUT` (11) — minuterie.
    Timeout,
    /// `IORING_OP_TIMEOUT_REMOVE` (12) — retrait/màj de minuterie.
    TimeoutRemove,
    /// `IORING_OP_ACCEPT` (13) — acceptation de connexion.
    Accept,
    /// `IORING_OP_ASYNC_CANCEL` (14) — annulation asynchrone.
    AsyncCancel,
    /// `IORING_OP_LINK_TIMEOUT` (15) — timeout lié à l'opération précédente.
    LinkTimeout,
    /// `IORING_OP_CONNECT` (16) — connexion socket.
    Connect,
    /// `IORING_OP_FALLOCATE` (17) — pré-allocation d'espace fichier.
    Fallocate,
    /// `IORING_OP_CLOSE` (19) — fermeture de FD.
    Close,
    /// `IORING_OP_FILES_UPDATE` (20) — mise à jour de la table de FD fixes (op).
    FilesUpdate,
    /// `IORING_OP_STATX` (21) — métadonnées de fichier étendues.
    Statx,
    /// `IORING_OP_READ` (22) — lecture.
    Read,
    /// `IORING_OP_WRITE` (23) — écriture.
    Write,
    /// `IORING_OP_FADVISE` (24) — conseils d'accès fichier.
    Fadvise,
    /// `IORING_OP_MADVISE` (25) — conseils d'accès mémoire.
    Madvise,
    /// `IORING_OP_SEND` (26) — envoi socket.
    Send,
    /// `IORING_OP_RECV` (27) — réception socket.
    Recv,
    /// `IORING_OP_OPENAT2` (28) — ouverture de fichier (superset d'`openat`).
    Openat2,
    /// `IORING_OP_EPOLL_CTL` (29) — contrôle d'un epoll.
    EpollCtl,
    /// `IORING_OP_SPLICE` (30) — copie zero-copy entre FDs.
    Splice,
    /// `IORING_OP_TEE` (33) — duplication zero-copy entre pipes.
    Tee,
    /// `IORING_OP_SHUTDOWN` (34) — arrêt d'un socket.
    Shutdown,
    /// `IORING_OP_RENAMEAT` (35) — renommage (sémantique `renameat2`).
    Renameat,
    /// `IORING_OP_UNLINKAT` (36) — suppression d'entrée de répertoire.
    Unlinkat,
    /// `IORING_OP_MKDIRAT` (37) — création de répertoire.
    Mkdirat,
    /// `IORING_OP_SYMLINKAT` (38) — création de lien symbolique.
    Symlinkat,
    /// `IORING_OP_LINKAT` (39) — création de lien dur.
    Linkat,
    /// `IORING_OP_MSG_RING` (40) — message vers un autre ring.
    MsgRing,
    /// `IORING_OP_FSETXATTR` (41) — pose d'attribut étendu (par FD).
    Fsetxattr,
    /// `IORING_OP_SETXATTR` (42) — pose d'attribut étendu (par chemin).
    Setxattr,
    /// `IORING_OP_FGETXATTR` (43) — lecture d'attribut étendu (par FD).
    Fgetxattr,
    /// `IORING_OP_GETXATTR` (44) — lecture d'attribut étendu (par chemin).
    Getxattr,
    /// `IORING_OP_SOCKET` (45) — création de socket.
    Socket,
    /// `IORING_OP_URING_CMD` (46) — commande passthrough (Temps 2d).
    UringCmd,
    /// `IORING_OP_SEND_ZC` (47) — envoi zero-copy (CQE `NOTIF`).
    SendZc,
    /// `IORING_OP_SENDMSG_ZC` (48) — envoi de message zero-copy.
    SendmsgZc,
    /// `IORING_OP_READ_MULTISHOT` (49) — lecture multishot (Temps 3d).
    ReadMultishot,
    /// `IORING_OP_WAITID` (50) — attente d'état de processus.
    Waitid,
    /// `IORING_OP_FUTEX_WAIT` (51) — attente sur futex.
    FutexWait,
    /// `IORING_OP_FUTEX_WAKE` (52) — réveil de futex.
    FutexWake,
    /// `IORING_OP_FUTEX_WAITV` (53) — attente sur un vecteur de futex.
    FutexWaitv,
    /// `IORING_OP_FIXED_FD_INSTALL` (54) — installe un FD fixe comme FD normal.
    FixedFdInstall,
    /// `IORING_OP_FTRUNCATE` (55) — troncature de fichier.
    Ftruncate,
    /// `IORING_OP_BIND` (56) — liaison d'adresse socket.
    Bind,
    /// `IORING_OP_LISTEN` (57) — mise en écoute d'un socket.
    Listen,
}

// ─────────────────────────────────────────────────────────────────────────
// Types ajoutés au Temps 2c (async-spécifiques). Cf.
// docs/specs/layer-0/io-uring-2c-async.md §9. Valeurs : uapi Linux 6.12.
// ─────────────────────────────────────────────────────────────────────────

// `PollEvents` a été **promu** vers la famille `poll` (`crate::poll`, ADR-044) et
// est **ré-exporté** ci-dessous : son chemin historique
// `air_sys_types::io_uring::PollEvents` reste valide (type inchangé sur le fil).
pub use crate::poll::PollEvents;

bitflags::bitflags! {
    /// Drapeaux de l'op `IORING_OP_TIMEOUT` (`IORING_TIMEOUT_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct TimeoutFlags: u32 {
        /// `ABS` : l'échéance est **absolue** (pas une durée relative).
        const ABS           = 1 << 0;
        /// `BOOTTIME` : horloge `CLOCK_BOOTTIME`.
        const BOOTTIME      = 1 << 2;
        /// `REALTIME` : horloge `CLOCK_REALTIME`.
        const REALTIME      = 1 << 3;
        /// `ETIME_SUCCESS` : l'expiration est un **succès** (pas `-ETIME`).
        const ETIME_SUCCESS = 1 << 5;
        /// `MULTISHOT` : déclenchements répétés (variante multishot, Temps 3d).
        const MULTISHOT     = 1 << 6;
    }

    /// Drapeaux de l'annulation asynchrone (`IORING_OP_ASYNC_CANCEL`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct CancelFlags: u32 {
        /// `IORING_ASYNC_CANCEL_ALL` : annule **toutes** les correspondances
        /// (pas seulement la première).
        const ALL = 1 << 0;
    }

    /// Drapeaux de l'op `IORING_OP_MSG_RING` (`IORING_MSG_RING_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct MessageRingFlags: u32 {
        /// `CQE_SKIP` : ne pas poster de CQE côté **cible**.
        const CQE_SKIP   = 1 << 0;
        /// `FLAGS_PASS` : propager les `cqe_flags` vers le CQE cible.
        const FLAGS_PASS = 1 << 1;
    }

    /// Drapeaux d'un futex io_uring (`FUTEX_WAIT`/`WAKE`/`WAITV`), sous-ensemble
    /// `FUTEX2_*` pertinent pour un mot futex `u32`.
    ///
    /// La **taille** du mot est toujours `FUTEX2_SIZE_U32` : le mot futex d'une
    /// `MmapRegion` est un [`core::sync::atomic::AtomicU32`]. La façade
    /// `air-sys-syscall` l'impose ; il n'a donc **pas** à être passé ici, et seul
    /// `PRIVATE` est exposé (le seul autre bit de réglage utile pour un mot
    /// `u32` sans NUMA).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct FutexFlags: u32 {
        /// `FUTEX2_PRIVATE` : le futex est **privé** au processus (pas de
        /// partage inter-processus). Optimisation : le kernel évite le verrou
        /// inter-espace-d'adressage. Valeur `FUTEX_PRIVATE_FLAG` (`0x80`).
        const PRIVATE = 0x80;
    }

    /// Drapeaux de l'op `IORING_OP_URING_CMD` (46, Temps 2d) — `IORING_URING_CMD_*`.
    ///
    /// Seul `FIXED` existe en kernel 6.12 (`IORING_URING_CMD_MASK == FIXED`).
    /// `MULTISHOT` est postérieur à 6.12 → hors périmètre.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct UringCmdFlags: u32 {
        /// `IORING_URING_CMD_FIXED` (bit 0) : la commande utilise un **buffer
        /// enregistré** (index dans `buf_index`) comme zone de données associée.
        const FIXED = 1 << 0;
    }
}

/// Spécification d'une op `TIMEOUT` : durée et/ou seuil de complétions.
///
/// - `duration` : échéance temporelle (relative, ou absolue avec
///   [`TimeoutFlags::ABS`]). `None` ⇒ timeout purement basé sur le compte.
/// - `count` : nombre de CQE après lequel le timeout se déclenche (`off` du
///   SQE). `0` ⇒ timeout purement temporel.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct TimeoutSpec {
    /// Échéance temporelle (`__kernel_timespec`).
    pub duration: Option<core::time::Duration>,
    /// Seuil de complétions (`off`).
    pub count: u32,
}

impl TimeoutSpec {
    /// Timeout purement temporel (après `duration`).
    #[must_use]
    pub fn after(duration: core::time::Duration) -> Self {
        Self {
            duration: Some(duration),
            count: 0,
        }
    }

    /// Timeout purement par comptage (après `count` complétions).
    #[must_use]
    pub fn after_completions(count: u32) -> Self {
        Self {
            duration: None,
            count,
        }
    }
}

/// Opération de `epoll_ctl(2)` (`EPOLL_CTL_*`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(i32)]
pub enum EpollOp {
    /// `EPOLL_CTL_ADD` : ajoute le FD au set.
    Add = 1,
    /// `EPOLL_CTL_DEL` : retire le FD du set.
    Delete = 2,
    /// `EPOLL_CTL_MOD` : modifie les événements surveillés.
    Modify = 3,
}

impl EpollOp {
    /// Valeur kernel (`EPOLL_CTL_*`).
    #[must_use]
    pub const fn as_raw(self) -> i32 {
        self as i32
    }
}

/// Miroir `#[repr(C, packed)]` de `struct epoll_event` (12 octets sur
/// x86_64/aarch64). Lu de façon asynchrone par `IORING_OP_EPOLL_CTL` ⇒ gardé en
/// vie dans le slot S1 jusqu'à la complétion.
#[repr(C, packed)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EpollEvent {
    /// Événements surveillés (`POLL*`/`EPOLL*`).
    pub events: u32,
    /// Donnée opaque renvoyée à la notification (`epoll_data_t`).
    pub data: u64,
}

impl EpollEvent {
    /// Construit un `epoll_event` à partir d'événements typés et d'une donnée.
    #[must_use]
    pub fn new(events: PollEvents, data: u64) -> Self {
        Self {
            events: events.bits(),
            data,
        }
    }
}

// Layout ABI figé par le kernel (epoll_event packed = 12 octets).
const _: () = {
    assert!(core::mem::size_of::<EpollEvent>() == 12);
};

#[cfg(test)]
mod time_2c_tests;