vyre_runtime/megakernel/io/
mod.rs

1//! IO subsystem  -  GPU↔runtime DMA request queue for the persistent megakernel.
2//!
3//! Module ownership:
4//!  - `mod.rs`: doc + constants + IoRequest/IoCompletion + word/op/status modules
5//!  - `queue.rs`: [`ResidentIoQueue`] + view
6//!  - `poll.rs`: host poll/claim/peek surface + the GPU completion-poll IR builder
7//!  - `complete.rs`: completion-write surface
8//!  - `encode.rs`: bytes <-> validated queue helpers
9//!  - `queue_words.rs`: bounds-checked slot-word addressing + queue validation
10//!  - `tests.rs`: full test suite
11//!
12//! ## Protocol
13//!
14//! Each IO slot is 8 × u32 words:
15//! ```text
16//! [op_type, src_handle, dst_handle, offset_lo, offset_hi, byte_count, status, tag]
17//! ```
18//!
19//! The GPU CAS-claims slots like the work ring, but uses the io_queue
20//! buffer. The host polls `status` for REQUEST and services the DMA.
21
22mod complete;
23mod encode;
24mod poll;
25mod queue;
26mod queue_words;
27
28#[cfg(test)]
29mod tests;
30
31pub use complete::{
32    complete_io_request, complete_io_requests_batch, try_complete_io_request,
33    try_complete_io_requests_batch,
34};
35pub(crate) use encode::empty_io_queue_byte_len;
36pub use encode::{
37    encode_empty_io_queue, try_encode_empty_io_queue, try_encode_empty_io_queue_into,
38    validate_io_queue_bytes,
39};
40pub use poll::{
41    claim_io_requests_into, io_completion_poll_body, try_claim_io_requests_into,
42    try_poll_io_requests, try_poll_io_requests_into,
43};
44pub use queue::ResidentIoQueue;
45
46/// Number of u32 words per IO queue slot.
47pub const IO_SLOT_WORDS: u32 = 8;
48
49/// Default number of IO queue slots.
50pub const IO_SLOT_COUNT: u32 = 64;
51
52/// Resource table name used for resolving IO source handles.
53pub const IO_SOURCE_CAPABILITY_TABLE: &str = "io_source_capability_table";
54
55/// Resource table name used for resolving IO destination handles.
56pub const IO_DESTINATION_CAPABILITY_TABLE: &str = "io_destination_capability_table";
57
58/// Async stream tag used by megakernel IO DMA requests.
59pub const IO_QUEUE_DMA_TAG: &str = "io_queue_dma";
60
61/// Word offsets within an IO slot.
62pub mod io_word {
63    /// DMA operation type (see `IoOp`).
64    pub const OP_TYPE: u32 = 0;
65    /// Source buffer handle id.
66    pub const SRC_HANDLE: u32 = 1;
67    /// Destination buffer handle id.
68    pub const DST_HANDLE: u32 = 2;
69    /// Byte offset into source (low 32 bits).
70    pub const OFFSET_LO: u32 = 3;
71    /// Byte offset into source (high 32 bits, for >4GB transfers).
72    pub const OFFSET_HI: u32 = 4;
73    /// Number of bytes to transfer.
74    pub const BYTE_COUNT: u32 = 5;
75    /// Slot status  -  same semantics as work ring (EMPTY/PUBLISHED/CLAIMED/DONE).
76    pub const STATUS: u32 = 6;
77    /// Caller-supplied tag for correlating completions.
78    pub const TAG: u32 = 7;
79}
80
81/// IO operation types.
82pub mod io_op {
83    /// Read from storage into GPU buffer.
84    pub const READ: u32 = 0x01;
85    /// Write from GPU buffer to storage.
86    pub const WRITE: u32 = 0x02;
87    /// Memory fence  -  ensure all prior IO ops are visible.
88    pub const FENCE: u32 = 0x03;
89}
90
91/// IO completion status codes written by the host pump.
92pub mod io_status {
93    /// Operation completed successfully.
94    pub const OK: u32 = 0x10;
95    /// Operation failed  -  error code in the tag word.
96    pub const ERROR: u32 = 0x11;
97}
98
99/// Host-side IO request decoded from the io_queue buffer.
100#[derive(Debug, Clone, Copy, PartialEq, Eq)]
101pub struct IoRequest {
102    /// Slot index in the io_queue.
103    pub slot_idx: u32,
104    /// Operation type.
105    pub op_type: u32,
106    /// Source buffer handle.
107    pub src_handle: u32,
108    /// Destination buffer handle.
109    pub dst_handle: u32,
110    /// 64-bit byte offset into source.
111    pub offset: u64,
112    /// Byte count to transfer.
113    pub byte_count: u32,
114    /// Caller tag.
115    pub tag: u32,
116}
117
118/// Host-side completion record published into `io_queue` for a mapped
119/// ingest slot the GPU can consume.
120#[derive(Debug, Clone, Copy, PartialEq, Eq)]
121pub struct IoCompletion {
122    /// Queue slot index.
123    pub slot_idx: u32,
124    /// Mapped ingest slot id / destination handle.
125    pub mapped_slot: u32,
126    /// Number of bytes now valid in the mapped slot.
127    pub byte_count: u32,
128    /// Caller-defined completion tag.
129    pub tag: u32,
130}
vyre_runtime/megakernel/io/mod.rs

vyre_runtime/megakernel/io/
mod.rs
