Module io_uring 

Module air-sys-syscall::io_uring — façade typée d’io_uring (cible 6.12).

Niveau d’abstraction 2 (ADR-022, Décision 1) : soumission/complétion typée. Le niveau 1 (anneaux bruts) vivra dans raw. Les buffers suivent le modèle de transfert d’ownership (ADR-022, Décision 3), garés dans un slab pré-alloué (S1) ; le téardown est sûr par Drop quiescent + IoUring::shutdown (S2).

Périmètre — Temps 1 (cœur). Cycle de vie du ring (setup flags, mmaps SQ/ CQ/SQE, négociation des features), slab d’opérations en vol (S1), protocole d’anneau acquire/release (§3.2 de la spec), soumission/complétion, Completion, téardown sûr (S2), introspection (probe + capabilities). Les opérations métier submit_* (Temps 2a–2d) et les sous-modules (shared, multishot, sandbox, registration/provided/linked/cmd) relèvent de PRs ultérieures.

Référence normative : docs/specs/layer-0/io-uring-1-core.md (contrat) et docs/specs/layer-0/io-uring-0-inventaire.md §7 (squelette).

Les trois syscalls sous-jacents — io_uring_setup (425), io_uring_enter (426), io_uring_register (427), numéros identiques x86_64/ARM64 — sont appelés directement via core::arch::asm! (aucune dépendance externe).

Re-exports

pub use shared::LockedIoUring;

pub use shared::RingHandle;

pub use shared::RingPool;

pub use shared::SqpollIoUring;

pub use sandbox::RegisterOp;

pub use sandbox::RestrictionSet;

pub use sandbox::SqeFlagSet;

pub use raw::RAW_USER_DATA_TAG;

pub use raw::RawCompletionQueueEntry;

pub use raw::RawOpcode;

pub use raw::RawSubmissionQueueEntry;

Modules

multishot

Opérations multishot (Temps 3d) : une unique soumission produit un flux de complétions. Sous-module air-sys-syscall::io_uring::multishot. Repose sur le drapeau de complétion CQE_F_MORE (axe E), sur les buffers fournis du Temps 3b (recv/read) et les descripteurs directs du Temps 3a (accept direct). Aucun register opcode ; un opcode dédié (READ_MULTISHOT, 49) et des drapeaux d’op.

raw

Niveau brut du module io_uring : numéros de syscalls, wrappers asm! des trois appels (io_uring_setup/enter/register) et miroirs #[repr(C)] des structures kernel du protocole d’anneau (cible 6.12).

sandbox

Confinement d’un ring (Temps 3f) — sous-module air-sys-syscall::io_uring::sandbox. Matérialise la décision de soundness S3 : un ring qui ne peut émettre que les opérations explicitement mises en liste blanche, imposé par le kernel.

shared

Usage multi-thread d’io_uring (Temps 3e). Sous-module air-sys-syscall::io_uring::shared. Repose sur l’invariant ADR-022 Décision 6 (IoUring est Send mais !Sync), sur SETUP_SQPOLL (Temps 1), ATTACH_WQ (Temps 3a) et msg_ring (Temps 2c). Aucun register opcode propre.

Structs

ChainTokens

Jetons des maillons d’une chaîne, dans l’ordre de soumission (corrèle chaque complétion à son maillon).

Completion

Une complétion (CQE décodé). Au Temps 1, les interprétations sont génériques ; les variantes typées riches (fd accepté/ouvert, etc.) arrivent aux Temps 2a–2d (ADR-022 Décision 9). Convention de résultat : un res négatif est un -errno, converti en Err(Errno) par les méthodes into_* ; un res ≥ 0 est la valeur utile.

CompletionFlags

Flags de complétion IORING_CQE_F_* (axe E, 5 flags en 6.12).

CompletionIter

Itérateur sur les complétions disponibles d’un IoUring (emprunte le ring).

FixedFdTable

Table de descripteurs de fichiers fixes (REGISTER_FILES2, 13).

FixedSlot

Référence empruntée à un slot d’une FixedFdTable, liée à la table par lifetime — inutilisable après son désenregistrement (sûreté par construction).

FutexWaiter

Un attendu de IoUring::submit_futex_waitv : la région partageable + le décalage du mot futex, et la valeur attendue.

IoUring

Anneau io_uring : FD + mmaps (SQ/CQ/SQE) + slab d’opérations en vol (S1) + capabilities négociées.

IoUringBuilder

Construit un IoUring : applique setup flags et restrictions (S3) avant l’activation, puis io_uring_setup(2).

IoUringCapabilities

Features io_uring du kernel courant (axe G, 16 features en 6.12). Lues dans io_uring_params.features après setup, exposées par prédicats stables.

IoUringParams

Miroir typé de struct io_uring_params (entrées/sorties de io_uring_setup(2)).

LinkedChainBuilder

Constructeur d’une chaîne d’opérations liées sur un IoUring en mode staging (cf. module). Emprunte le ring &mut pour toute sa durée (aucune soumission directe ne peut s’intercaler).

MultishotToken

Jeton d’une opération multishot (un slot, plusieurs complétions). Voir multishot (Temps 3d).

NapiConfig

Configuration du busy-poll NAPI (IoUring::register_napi).

Personality

Identité (credentials) enregistrée dans le ring (IoUring::register_personality).

ProvidedBuffer

Accès RAII aux données reçues dans un buffer fourni. Rend le buffer au groupe (réapprovisionnement) à la libération — sauf en mode incrémental quand CQE_F_BUF_MORE est positionné (le kernel garde le buffer).

ProvidedBufferRing

Groupe de buffers fournis ring-mapped (IORING_REGISTER_PBUF_RING, 22).

ProvidedBufferRingOptions

Options de création d’un ProvidedBufferRing.

ProvidedBufferRingStatus

État d’un groupe rendu par ProvidedBufferRing::status (PBUF_STATUS).

RegisteredBufferSlice

Référence à une tranche d’un buffer enregistré, liée par lifetime à la RegisteredBuffers — read_fixed sur une tranche périmée ne compile pas.

RegisteredBuffers

Buffers enregistrés (REGISTER_BUFFERS2, 15) : l’épinglage et la traduction d’adresses sont faits une fois ⇒ read_fixed/write_fixed évitent ce coût par op (cas chaud du data plane AirCom).

SetupFlags

Flags de io_uring_setup(2) (axe A, 17 flags en 6.12).

SubmissionToken

Jeton opaque reliant une soumission à sa complétion (décision S1).

SubmitOptions

Options de soumission par-opération (flags IOSQE_* exposés sûrement).

UringCmdFlags

Drapeaux de l’op IORING_OP_URING_CMD (46, Temps 2d) — IORING_URING_CMD_*.

WorkQueueWorkerLimits

Plafonds de workers io-wq rendus par IoUring::set_work_queue_max_workers (les valeurs précédentes, réécrites par le kernel).

Enums

CancelTarget

Cible d’une annulation synchrone (IoUring::sync_cancel).

ClockSource

Source d’horloge des timeouts du ring (IoUring::register_clock).

FixedSlotTarget

Cible d’un slot pour une variante « direct » : indice précis, ou auto-allocation par le kernel.

IoUringOpcode

Énumération des 55 opcodes IORING_OP_* retenus (axe B, 6.12).

Restriction

Restriction appliquée à un ring avant son activation (décision S3 ; struct io_uring_restriction).

Traits

UringCommand

Une commande passthrough d’un sous-système, sérialisable dans la zone cmd[] d’URING_CMD.