Skip to main content

oneliner_runtime/
interface.rs

1use super::{Access, Aligned, AlignedType};
2
3#[cfg(feature = "ndarray")]
4use ndarray::{ArrayView4, ArrayViewMut4};
5
6pub type Shape4D = (usize, usize, usize, usize);
7
8pub type Shape = Shape4D;
9
10pub type TensorArray<T, const D1: usize, const D2: usize, const D3: usize, const D4: usize> =
11    [[[[T; D4]; D3]; D2]; D1];
12
13/// Four-dimensional tensor backed by an owned, aligned, fixed-size nested array.
14pub struct Tensor4D<T, const D1: usize, const D2: usize, const D3: usize, const D4: usize> {
15    storage: Aligned<AlignedType, TensorArray<T, D1, D2, D3, D4>>,
16}
17
18pub type Tensor<T, const D1: usize, const D2: usize, const D3: usize, const D4: usize> =
19    Tensor4D<T, D1, D2, D3, D4>;
20
21impl<T, const D1: usize, const D2: usize, const D3: usize, const D4: usize>
22    Tensor4D<T, D1, D2, D3, D4>
23{
24    pub const SHAPE: Shape = (D1, D2, D3, D4);
25
26    pub const LEN: usize = D1 * D2 * D3 * D4;
27
28    pub const fn new(value: T) -> Self
29    where
30        T: Copy,
31    {
32        Self {
33            storage: Aligned([[[[value; D4]; D3]; D2]; D1]),
34        }
35    }
36
37    pub const fn from_array(storage: TensorArray<T, D1, D2, D3, D4>) -> Self {
38        Self {
39            storage: Aligned(storage),
40        }
41    }
42
43    pub fn as_slice(&self) -> &[T] {
44        self.storage[..]
45            .as_flattened()
46            .as_flattened()
47            .as_flattened()
48    }
49
50    pub fn as_slice_mut(&mut self) -> &mut [T] {
51        self.storage[..]
52            .as_flattened_mut()
53            .as_flattened_mut()
54            .as_flattened_mut()
55    }
56
57    pub fn as_ptr(&self) -> *const T {
58        self.as_slice().as_ptr()
59    }
60
61    pub fn as_mut_ptr(&mut self) -> *mut T {
62        self.as_slice_mut().as_mut_ptr()
63    }
64
65    pub fn byte_len(&self) -> usize {
66        core::mem::size_of_val(self.as_slice())
67    }
68
69    pub const fn len(&self) -> usize {
70        Self::LEN
71    }
72
73    pub const fn is_empty(&self) -> bool {
74        Self::LEN == 0
75    }
76
77    pub const fn dim(&self) -> Shape {
78        Self::SHAPE
79    }
80
81    #[cfg(feature = "ndarray")]
82    pub fn view(&self) -> ArrayView4<'_, T> {
83        ArrayView4::from_shape(Self::SHAPE, self.as_slice())
84            .expect("Tensor4D shape must match its storage")
85    }
86
87    #[cfg(feature = "ndarray")]
88    pub fn view_mut(&mut self) -> ArrayViewMut4<'_, T> {
89        ArrayViewMut4::from_shape(Self::SHAPE, self.as_slice_mut())
90            .expect("Tensor4D shape must match its storage")
91    }
92
93    #[cfg(feature = "ndarray")]
94    pub fn fill(&mut self, value: T)
95    where
96        T: Clone,
97    {
98        self.view_mut().fill(value);
99    }
100
101    #[cfg(not(feature = "ndarray"))]
102    pub fn fill(&mut self, value: T)
103    where
104        T: Clone,
105    {
106        self.as_slice_mut().fill(value);
107    }
108}
109
110/// Typed tensor inference implemented directly by generated model instances.
111pub trait ModelInference {
112    type InputTensor;
113    type OutputTensor;
114
115    /// Runs inference and returns an owned output tensor.
116    fn run(&mut self, input: &Self::InputTensor) -> Self::OutputTensor;
117
118    /// Creates a zero-filled input tensor with the model's element type and dimensions.
119    fn create_input_tensor() -> Self::InputTensor;
120}
121
122/// Metadata exposed by a model generated with `#[model]`.
123///
124/// Input: no runtime input; metadata is provided as associated constants.
125/// Output: model path and generated artifact metadata.
126pub trait ModelSource {
127    const MODEL_PATH: &'static str;
128    const ARTIFACTS: ModelArtifacts;
129}
130
131#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub enum Error {
133    TooManyBindings {
134        provided: usize,
135        capacity: usize,
136    },
137    TooManyConstants {
138        provided: usize,
139        capacity: usize,
140    },
141    MissingDispatchFunction {
142        ordinal: usize,
143    },
144    WorkgroupCountTooLarge {
145        dimension: char,
146        value: u32,
147    },
148    BufferRangeOutOfBounds {
149        offset: usize,
150        length: usize,
151        capacity: usize,
152    },
153    DispatchFailed {
154        status: i32,
155    },
156    InvalidAccess {
157        access: Access,
158        required: Access,
159    },
160    NullPointer,
161}
162
163impl core::fmt::Display for Error {
164    /// Formats a runtime error for diagnostics.
165    ///
166    /// Input: formatter supplied by Rust formatting machinery.
167    /// Output: `Ok(())` when the message was written.
168    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
169        match self {
170            Self::TooManyBindings { provided, capacity } => write!(
171                f,
172                "dispatch has {provided} bindings, but runtime stack storage holds {capacity}"
173            ),
174            Self::TooManyConstants { provided, capacity } => write!(
175                f,
176                "dispatch has {provided} constants, but the IREE ABI supports {capacity}"
177            ),
178            Self::MissingDispatchFunction { ordinal } => {
179                write!(f, "IREE library does not expose dispatch ordinal {ordinal}")
180            }
181            Self::WorkgroupCountTooLarge { dimension, value } => write!(
182                f,
183                "workgroup count {dimension}={value} exceeds the IREE ABI limit"
184            ),
185            Self::BufferRangeOutOfBounds {
186                offset,
187                length,
188                capacity,
189            } => write!(
190                f,
191                "tensor range offset={offset} length={length} exceeds capacity {capacity}"
192            ),
193            Self::DispatchFailed { status } => {
194                write!(f, "backend dispatch returned status {status}")
195            }
196
197            Self::InvalidAccess { access, required } => write!(
198                f,
199                "tensor access {access:?} is invalid; expected {required:?}"
200            ),
201            Self::NullPointer => write!(f, "tensor pointer is null"),
202        }
203    }
204}
205
206#[derive(Debug, Clone, Copy, PartialEq, Eq)]
207pub struct ModelArtifacts {
208    pub backend: &'static str,
209    pub expansion: &'static str,
210    pub model_path: &'static str,
211    pub compile_input_path: &'static str,
212    pub object_path: &'static str,
213    pub link_path: &'static str,
214    pub ir_path: &'static str,
215    pub flow_rs_path: &'static str,
216    pub metadata_json_path: &'static str,
217    /// Size in bytes of the model's single input tensor.
218    pub input_size: usize,
219    /// Size in bytes of the model's single output tensor.
220    pub output_size: usize,
221    /// Model parameter/weight bytes placed in flash (read-only model data).
222    pub params_size: usize,
223    /// Machine code bytes of the compiled model placed in flash.
224    pub code_size: usize,
225    /// Read-only data bytes embedded in the compiled model object (lookup
226    /// tables, library metadata, unwind tables) placed in flash.
227    pub rodata_size: usize,
228    /// Total model flash footprint: parameters plus compiled code and data.
229    pub total_flash_size: usize,
230    /// Transient workspace bytes held in RAM during inference.
231    pub ram_size: usize,
232}