Skip to main content

tpt_gpu_primitives/memory/
buffer.rs

1//! GPU Buffer Types
2use crate::error::{TptpError, TptpResult};
3use bytemuck::Pod;
4use std::fmt;
5
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
7#[repr(u8)]
8pub enum DType {
9    Bool = 0,
10    I8 = 1,
11    I16 = 2,
12    I32 = 3,
13    I64 = 4,
14    F16 = 5,
15    BF16 = 6,
16    F32 = 7,
17    F64 = 8,
18}
19
20impl DType {
21    pub fn size_bytes(&self) -> usize {
22        match self {
23            DType::Bool => 1,
24            DType::I8 => 1,
25            DType::I16 => 2,
26            DType::I32 => 4,
27            DType::I64 => 8,
28            DType::F16 => 2,
29            DType::BF16 => 2,
30            DType::F32 => 4,
31            DType::F64 => 8,
32        }
33    }
34    pub fn is_float(&self) -> bool {
35        matches!(self, DType::F16 | DType::BF16 | DType::F32 | DType::F64)
36    }
37    pub fn is_int(&self) -> bool {
38        matches!(
39            self,
40            DType::Bool | DType::I8 | DType::I16 | DType::I32 | DType::I64
41        )
42    }
43}
44
45impl fmt::Display for DType {
46    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47        let name = match self {
48            DType::Bool => "bool",
49            DType::I8 => "i8",
50            DType::I16 => "i16",
51            DType::I32 => "i32",
52            DType::I64 => "i64",
53            DType::F16 => "f16",
54            DType::BF16 => "bf16",
55            DType::F32 => "f32",
56            DType::F64 => "f64",
57        };
58        write!(f, "{}", name)
59    }
60}
61
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
63pub struct BufferFlags(u32);
64
65impl BufferFlags {
66    pub const fn empty() -> Self {
67        BufferFlags(0)
68    }
69    pub const HOST_VISIBLE: Self = BufferFlags(1 << 0);
70    pub const HOST_COHERENT: Self = BufferFlags(1 << 1);
71    pub const STORAGE: Self = BufferFlags(1 << 3);
72    pub const fn with(self, other: Self) -> Self {
73        BufferFlags(self.0 | other.0)
74    }
75    pub const fn contains(self, other: Self) -> bool {
76        (self.0 & other.0) != 0
77    }
78}
79
80impl std::ops::BitOr for BufferFlags {
81    type Output = Self;
82    fn bitor(self, rhs: Self) -> Self::Output {
83        self.with(rhs)
84    }
85}
86
87#[derive(Debug, Clone, PartialEq, Eq, Hash)]
88pub struct Shape {
89    dims: Vec<usize>,
90}
91
92impl Shape {
93    pub fn new(dims: &[usize]) -> Self {
94        Shape {
95            dims: dims.to_vec(),
96        }
97    }
98    pub fn dim2(a: usize, b: usize) -> Self {
99        Shape { dims: vec![a, b] }
100    }
101    pub fn dim4(a: usize, b: usize, c: usize, d: usize) -> Self {
102        Shape {
103            dims: vec![a, b, c, d],
104        }
105    }
106    pub fn ndim(&self) -> usize {
107        self.dims.len()
108    }
109    pub fn dim(&self, i: usize) -> Option<usize> {
110        self.dims.get(i).copied()
111    }
112    pub fn num_elements(&self) -> usize {
113        self.dims.iter().product()
114    }
115    pub fn is_valid(&self) -> bool {
116        self.dims.iter().all(|&d| d > 0)
117    }
118}
119
120impl fmt::Display for Shape {
121    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122        write!(f, "[")?;
123        for (i, dim) in self.dims.iter().enumerate() {
124            if i > 0 {
125                write!(f, ", ")?;
126            }
127            write!(f, "{}", dim)?;
128        }
129        write!(f, "]")
130    }
131}
132
133/// GPU buffer handle.
134///
135/// Always maintains a host-side `storage` backing store so that
136/// `copy_from_host` / `copy_to_host` work in all build configurations —
137/// including sim mode and CI without hardware. On real hardware the backing
138/// store serves as the staging buffer for transfers; the GPU-side handle
139/// would be carried separately once Layer 2 driver integration is complete.
140#[derive(Clone)]
141pub struct GpuBuffer<T: Pod> {
142    shape: Shape,
143    dtype: DType,
144    byte_size: usize,
145    #[allow(dead_code)]
146    flags: BufferFlags,
147    storage: Vec<u8>,
148    _phantom: std::marker::PhantomData<T>,
149}
150
151unsafe impl<T: Pod> Send for GpuBuffer<T> {}
152unsafe impl<T: Pod> Sync for GpuBuffer<T> {}
153
154impl<T: Pod> GpuBuffer<T> {
155    pub fn new(shape: Shape, dtype: DType, flags: BufferFlags) -> TptpResult<Self> {
156        if !shape.is_valid() {
157            return Err(TptpError::ShapeError {
158                message: format!("invalid shape: {}", shape),
159                expected: None,
160                got: None,
161            });
162        }
163        let num_elements = shape.num_elements();
164        let byte_size = num_elements
165            .checked_mul(dtype.size_bytes())
166            .ok_or_else(|| TptpError::ShapeError {
167                message: "shape too large".to_string(),
168                expected: None,
169                got: None,
170            })?;
171        Ok(GpuBuffer {
172            shape,
173            dtype,
174            byte_size,
175            flags,
176            storage: vec![0u8; byte_size],
177            _phantom: std::marker::PhantomData,
178        })
179    }
180    pub fn shape(&self) -> &Shape {
181        &self.shape
182    }
183    pub fn dtype(&self) -> DType {
184        self.dtype
185    }
186    pub fn num_elements(&self) -> usize {
187        self.shape.num_elements()
188    }
189    pub fn byte_size(&self) -> usize {
190        self.byte_size
191    }
192    pub fn ndim(&self) -> usize {
193        self.shape.ndim()
194    }
195    pub fn dim(&self, i: usize) -> Option<usize> {
196        self.shape.dim(i)
197    }
198
199    pub fn copy_from_host(&mut self, data: &[T]) -> TptpResult<()> {
200        if data.len() != self.num_elements() {
201            return Err(TptpError::ShapeError {
202                message: format!(
203                    "data length {} != buffer size {}",
204                    data.len(),
205                    self.num_elements()
206                ),
207                expected: Some(self.num_elements().to_string()),
208                got: Some(data.len().to_string()),
209            });
210        }
211        let bytes = bytemuck::cast_slice(data);
212        self.storage[..bytes.len()].copy_from_slice(bytes);
213        Ok(())
214    }
215
216    pub fn copy_to_host(&self, data: &mut [T]) -> TptpResult<()> {
217        if data.len() != self.num_elements() {
218            return Err(TptpError::ShapeError {
219                message: format!(
220                    "output length {} != buffer size {}",
221                    data.len(),
222                    self.num_elements()
223                ),
224                expected: Some(self.num_elements().to_string()),
225                got: Some(data.len().to_string()),
226            });
227        }
228        let bytes = bytemuck::cast_slice_mut(data);
229        bytes.copy_from_slice(&self.storage[..bytes.len()]);
230        Ok(())
231    }
232}
233
234impl<T: Pod> fmt::Debug for GpuBuffer<T> {
235    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
236        f.debug_struct("GpuBuffer")
237            .field("shape", &self.shape)
238            .field("dtype", &self.dtype)
239            .field("byte_size", &self.byte_size)
240            .finish()
241    }
242}