Skip to main content

tpt_gpu_runtime/kernel/
launch.rs

1//! Kernel Launch Implementation - Config, argument packing, and execution tracking.
2use crate::error::{ErrorCode, TptrError, TptrResult};
3use std::sync::atomic::{AtomicU64, Ordering};
4use std::sync::Arc;
5
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub struct Dim3 {
8    pub x: u32,
9    pub y: u32,
10    pub z: u32,
11}
12
13impl Dim3 {
14    pub const fn new(x: u32, y: u32, z: u32) -> Self {
15        Self { x, y, z }
16    }
17    pub fn product(&self) -> u64 {
18        self.x as u64 * self.y as u64 * self.z as u64
19    }
20    pub fn validate(&self, max: &Dim3) -> TptrResult<()> {
21        if self.x == 0 || self.y == 0 || self.z == 0 {
22            return Err(TptrError::new(
23                ErrorCode::ConfigurationError,
24                "dimensions must be >= 1",
25            ));
26        }
27        if self.x > max.x || self.y > max.y || self.z > max.z {
28            return Err(TptrError::new(
29                ErrorCode::ConfigurationError,
30                format!(
31                    "dims ({},{},{}) exceed max ({},{},{})",
32                    self.x, self.y, self.z, max.x, max.y, max.z
33                ),
34            ));
35        }
36        Ok(())
37    }
38}
39
40impl From<(u32, u32, u32)> for Dim3 {
41    fn from(v: (u32, u32, u32)) -> Self {
42        Self::new(v.0, v.1, v.2)
43    }
44}
45
46pub const MAX_BLOCK_DIM: Dim3 = Dim3::new(1024, 1024, 64);
47pub const MAX_GRID_DIM: Dim3 = Dim3::new(1 << 30, 1 << 16, 1 << 16);
48
49#[derive(Debug, Clone, Copy, PartialEq, Eq)]
50pub enum KernelLaunchMode {
51    Synchronous,
52    Asynchronous,
53    Callback,
54}
55
56#[derive(Debug, Clone)]
57pub struct KernelConfig {
58    pub grid_size: Dim3,
59    pub block_size: Dim3,
60    pub shared_mem_bytes: u32,
61    pub launch_mode: KernelLaunchMode,
62}
63
64impl KernelConfig {
65    pub fn new(grid_size: impl Into<Dim3>, block_size: impl Into<Dim3>) -> Self {
66        Self {
67            grid_size: grid_size.into(),
68            block_size: block_size.into(),
69            shared_mem_bytes: 0,
70            launch_mode: KernelLaunchMode::Asynchronous,
71        }
72    }
73    pub fn with_shared_mem(mut self, bytes: u32) -> Self {
74        self.shared_mem_bytes = bytes;
75        self
76    }
77    pub fn with_launch_mode(mut self, mode: KernelLaunchMode) -> Self {
78        self.launch_mode = mode;
79        self
80    }
81    pub fn validate(&self) -> TptrResult<()> {
82        self.grid_size
83            .validate(&MAX_GRID_DIM)
84            .map_err(|e| e.with("field", "grid_size"))?;
85        self.block_size
86            .validate(&MAX_BLOCK_DIM)
87            .map_err(|e| e.with("field", "block_size"))?;
88        let total = self.block_size.product();
89        if total > 1024 {
90            return Err(TptrError::new(
91                ErrorCode::ConfigurationError,
92                format!("threads/block ({}) exceeds 1024", total),
93            ));
94        }
95        Ok(())
96    }
97    pub fn num_blocks(&self) -> u64 {
98        self.grid_size.product()
99    }
100    pub fn num_threads(&self) -> u64 {
101        self.grid_size.product() * self.block_size.product()
102    }
103}
104
105#[derive(Debug, Clone, Default)]
106pub struct ArgumentBuffer {
107    data: Vec<u8>,
108}
109
110impl ArgumentBuffer {
111    pub fn new() -> Self {
112        Self { data: Vec::new() }
113    }
114    pub fn push<T: bytemuck::Pod>(&mut self, value: &T) {
115        self.data.extend_from_slice(bytemuck::bytes_of(value));
116    }
117    pub fn push_bytes(&mut self, bytes: &[u8]) {
118        self.data.extend_from_slice(bytes);
119    }
120    pub fn data(&self) -> &[u8] {
121        &self.data
122    }
123    pub fn size(&self) -> usize {
124        self.data.len()
125    }
126}
127
128#[derive(Debug, Clone, Copy, PartialEq, Eq)]
129pub enum KernelState {
130    Pending,
131    Running,
132    Completed,
133    Failed,
134}
135
136#[derive(Debug, Clone)]
137pub struct KernelHandle {
138    id: u64,
139    state: Arc<AtomicU64>,
140}
141
142impl KernelHandle {
143    pub(crate) fn new(id: u64) -> Self {
144        Self {
145            id,
146            state: Arc::new(AtomicU64::new(0)),
147        }
148    }
149    pub fn id(&self) -> u64 {
150        self.id
151    }
152    pub fn state(&self) -> KernelState {
153        match self.state.load(Ordering::SeqCst) {
154            0 => KernelState::Pending,
155            1 => KernelState::Running,
156            2 => KernelState::Completed,
157            _ => KernelState::Failed,
158        }
159    }
160    pub fn is_complete(&self) -> bool {
161        self.state() == KernelState::Completed
162    }
163    pub fn wait(&self) {
164        while self.state.load(Ordering::Acquire) != 2 {
165            std::hint::spin_loop();
166        }
167    }
168    #[allow(dead_code)]
169    pub(crate) fn set_running(&self) {
170        self.state.store(1, Ordering::Release);
171    }
172    pub(crate) fn set_completed(&self) {
173        self.state.store(2, Ordering::Release);
174    }
175    pub(crate) fn set_failed(&self) {
176        self.state.store(3, Ordering::Release);
177    }
178}
179
180/// Compiled form of a TPTIR module produced by `Device::load_module`.
181///
182/// Holds the original source plus the compiler backend output so that
183/// `launch_kernel` can dispatch against real, runnable code instead of an
184/// empty `entry_point` string.
185#[derive(Debug, Clone)]
186pub struct CompiledModule {
187    pub source: String,
188    pub compiled: String,
189    pub target: String,
190}
191
192#[derive(Debug, Clone)]
193pub struct Kernel {
194    name: String,
195    entry_point: String,
196    shared_mem_bytes: u32,
197    module: Option<CompiledModule>,
198}
199
200impl Kernel {
201    pub fn new(name: impl Into<String>) -> Self {
202        Self {
203            name: name.into(),
204            entry_point: String::new(),
205            shared_mem_bytes: 0,
206            module: None,
207        }
208    }
209    pub fn name(&self) -> &str {
210        &self.name
211    }
212    pub fn entry_point(&self) -> &str {
213        &self.entry_point
214    }
215    pub fn shared_mem_bytes(&self) -> u32 {
216        self.shared_mem_bytes
217    }
218    /// Returns the compiled TPTIR module if this kernel was produced by
219    /// `Device::load_module`, otherwise `None` (a bare named kernel).
220    pub fn module(&self) -> Option<&CompiledModule> {
221        self.module.as_ref()
222    }
223    /// Attach a compiled module; used by `Device::load_module`.
224    pub(crate) fn with_module(mut self, module: CompiledModule) -> Self {
225        self.module = Some(module);
226        self
227    }
228}
229
230#[cfg(test)]
231mod tests {
232    use super::*;
233    #[test]
234    fn test_dim3_validation() {
235        assert!(Dim3::new(1, 1, 1).validate(&MAX_BLOCK_DIM).is_ok());
236        assert!(Dim3::new(0, 1, 1).validate(&MAX_BLOCK_DIM).is_err());
237    }
238    #[test]
239    fn test_kernel_config() {
240        let c = KernelConfig::new((16, 1, 1), (256, 1, 1));
241        assert!(c.validate().is_ok());
242        assert_eq!(c.num_blocks(), 16);
243        assert_eq!(c.num_threads(), 4096);
244    }
245    #[test]
246    fn test_config_too_many_threads() {
247        let c = KernelConfig::new((1, 1, 1), (2048, 1, 1));
248        assert!(c.validate().is_err());
249    }
250    #[test]
251    fn test_arg_buffer() {
252        let mut b = ArgumentBuffer::new();
253        let v: u32 = 42;
254        b.push(&v);
255        assert_eq!(b.size(), 4);
256    }
257    #[test]
258    fn test_handle_lifecycle() {
259        let h = KernelHandle::new(1);
260        assert_eq!(h.state(), KernelState::Pending);
261        h.set_running();
262        assert_eq!(h.state(), KernelState::Running);
263        h.set_completed();
264        assert!(h.is_complete());
265    }
266    #[test]
267    fn test_dim3_product() {
268        assert_eq!(Dim3::new(16, 1, 1).product(), 16);
269        assert_eq!(Dim3::new(4, 4, 4).product(), 64);
270    }
271}