Skip to main content

tpt_gpu_runtime/command/
queue.rs

1//! Command Queue and Scheduler - Priority-based GPU command execution.
2use crate::error::{ErrorCode, TptrError, TptrResult};
3use crate::kernel::KernelConfig;
4use crate::memory::MemoryAllocation;
5use std::collections::{HashMap, VecDeque};
6use std::sync::atomic::{AtomicU64, Ordering};
7use std::time::Instant;
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
10pub enum QueuePriority {
11    High = 2,
12    Normal = 1,
13    Low = 0,
14}
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum CommandStatus {
18    Queued,
19    Running,
20    Completed,
21    Failed,
22}
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25pub struct EventHandle(pub u64);
26
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
28pub struct QueueHandle(pub u64);
29
30#[derive(Debug, Clone)]
31pub enum Command {
32    Allocate {
33        size: u64,
34        region: crate::memory::MemoryRegion,
35        mem_type: crate::memory::MemType,
36        access: crate::memory::MemAccess,
37    },
38    Free(MemoryAllocation),
39    Memcpy {
40        dst: MemoryAllocation,
41        src: MemoryAllocation,
42        size: u64,
43        dst_offset: u64,
44        src_offset: u64,
45    },
46    Memset {
47        dst: MemoryAllocation,
48        value: u8,
49        size: u64,
50        offset: u64,
51    },
52    LaunchKernel {
53        kernel: String,
54        config: KernelConfig,
55        args: Vec<Vec<u8>>,
56    },
57    Barrier,
58    WaitEvent(EventHandle),
59    SignalEvent(EventHandle),
60}
61
62impl Command {
63    pub fn label(&self) -> &'static str {
64        match self {
65            Self::Allocate { .. } => "Allocate",
66            Self::Free(..) => "Free",
67            Self::Memcpy { .. } => "Memcpy",
68            Self::Memset { .. } => "Memset",
69            Self::LaunchKernel { .. } => "LaunchKernel",
70            Self::Barrier => "Barrier",
71            Self::WaitEvent(..) => "WaitEvent",
72            Self::SignalEvent(..) => "SignalEvent",
73        }
74    }
75}
76
77#[derive(Debug)]
78struct CommandEntry {
79    id: u64,
80    command: Command,
81    #[allow(dead_code)]
82    priority: QueuePriority,
83    #[allow(dead_code)]
84    submit_time: Instant,
85    #[allow(dead_code)]
86    status: CommandStatus,
87}
88
89#[derive(Debug)]
90pub struct CommandQueue {
91    handle: QueueHandle,
92    high_queue: VecDeque<CommandEntry>,
93    normal_queue: VecDeque<CommandEntry>,
94    low_queue: VecDeque<CommandEntry>,
95    next_cmd_id: AtomicU64,
96    events: HashMap<EventHandle, bool>,
97    aging_counter: u64,
98    max_aging: u64,
99    capacity: usize,
100}
101
102impl CommandQueue {
103    pub fn new(handle: QueueHandle, capacity: usize) -> Self {
104        Self {
105            handle,
106            high_queue: VecDeque::with_capacity(capacity),
107            normal_queue: VecDeque::with_capacity(capacity),
108            low_queue: VecDeque::with_capacity(capacity),
109            next_cmd_id: AtomicU64::new(1),
110            events: HashMap::new(),
111            aging_counter: 0,
112            max_aging: 10,
113            capacity,
114        }
115    }
116    pub fn handle(&self) -> QueueHandle {
117        self.handle
118    }
119    pub fn submit(&mut self, cmd: Command, pri: QueuePriority) -> TptrResult<u64> {
120        let total = self.high_queue.len() + self.normal_queue.len() + self.low_queue.len();
121        if total >= self.capacity {
122            return Err(TptrError::new(
123                ErrorCode::QueueFull,
124                format!("capacity {} exhausted", self.capacity),
125            ));
126        }
127        let id = self.next_cmd_id.fetch_add(1, Ordering::SeqCst);
128        let entry = CommandEntry {
129            id,
130            command: cmd,
131            priority: pri,
132            submit_time: Instant::now(),
133            status: CommandStatus::Queued,
134        };
135        match pri {
136            QueuePriority::High => self.high_queue.push_back(entry),
137            QueuePriority::Normal => self.normal_queue.push_back(entry),
138            QueuePriority::Low => self.low_queue.push_back(entry),
139        }
140        Ok(id)
141    }
142    pub fn dequeue(&mut self) -> Option<(u64, Command)> {
143        if let Some(e) = self.high_queue.pop_front() {
144            return Some((e.id, e.command));
145        }
146        if let Some(e) = self.normal_queue.pop_front() {
147            return Some((e.id, e.command));
148        }
149        self.aging_counter += 1;
150        if self.aging_counter >= self.max_aging && !self.low_queue.is_empty() {
151            self.aging_counter = 0;
152            if let Some(e) = self.low_queue.pop_front() {
153                return Some((e.id, e.command));
154            }
155        }
156        if let Some(e) = self.low_queue.pop_front() {
157            return Some((e.id, e.command));
158        }
159        None
160    }
161    pub fn peek(&self) -> Option<&Command> {
162        self.high_queue
163            .front()
164            .or_else(|| self.normal_queue.front())
165            .or_else(|| self.low_queue.front())
166            .map(|e| &e.command)
167    }
168    pub fn len(&self) -> usize {
169        self.high_queue.len() + self.normal_queue.len() + self.low_queue.len()
170    }
171    pub fn is_empty(&self) -> bool {
172        self.len() == 0
173    }
174    pub fn clear(&mut self) {
175        self.high_queue.clear();
176        self.normal_queue.clear();
177        self.low_queue.clear();
178    }
179    pub fn create_event(&mut self) -> EventHandle {
180        let id = self.next_cmd_id.fetch_add(1, Ordering::SeqCst);
181        let h = EventHandle(id);
182        self.events.insert(h, false);
183        h
184    }
185    pub fn signal_event(&mut self, event: EventHandle) {
186        self.events.insert(event, true);
187    }
188    pub fn is_event_signaled(&self, event: EventHandle) -> bool {
189        self.events.get(&event).copied().unwrap_or(false)
190    }
191}
192
193#[derive(Debug)]
194pub struct CommandScheduler {
195    queues: HashMap<QueueHandle, CommandQueue>,
196    next_queue_id: AtomicU64,
197}
198
199impl Default for CommandScheduler {
200    fn default() -> Self {
201        Self::new()
202    }
203}
204
205impl CommandScheduler {
206    pub fn new() -> Self {
207        Self {
208            queues: HashMap::new(),
209            next_queue_id: AtomicU64::new(1),
210        }
211    }
212    pub fn create_queue(&mut self, capacity: usize) -> QueueHandle {
213        let id = self.next_queue_id.fetch_add(1, Ordering::SeqCst);
214        let handle = QueueHandle(id);
215        self.queues
216            .insert(handle, CommandQueue::new(handle, capacity));
217        handle
218    }
219    pub fn submit(
220        &mut self,
221        queue: QueueHandle,
222        command: Command,
223        priority: QueuePriority,
224    ) -> TptrResult<u64> {
225        let q = self.queues.get_mut(&queue).ok_or_else(|| {
226            TptrError::new(
227                ErrorCode::InvalidKernel,
228                format!("Queue {:?} not found", queue),
229            )
230        })?;
231        q.submit(command, priority)
232    }
233    pub fn dequeue_next(&mut self) -> Option<(QueueHandle, u64, Command)> {
234        let handles: Vec<QueueHandle> = self.queues.keys().copied().collect();
235        for handle in &handles {
236            if let Some(q) = self.queues.get_mut(handle) {
237                if let Some((id, cmd)) = q.dequeue() {
238                    return Some((*handle, id, cmd));
239                }
240            }
241        }
242        None
243    }
244    pub fn queue_mut(&mut self, handle: QueueHandle) -> Option<&mut CommandQueue> {
245        self.queues.get_mut(&handle)
246    }
247    pub fn queue(&self, handle: QueueHandle) -> Option<&CommandQueue> {
248        self.queues.get(&handle)
249    }
250    pub fn remove_queue(&mut self, handle: QueueHandle) -> Option<CommandQueue> {
251        self.queues.remove(&handle)
252    }
253    pub fn total_pending(&self) -> usize {
254        self.queues.values().map(|q| q.len()).sum()
255    }
256    pub fn num_queues(&self) -> usize {
257        self.queues.len()
258    }
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264    #[test]
265    fn test_submit_dequeue() {
266        let mut q = CommandQueue::new(QueueHandle(1), 64);
267        let id = q.submit(Command::Barrier, QueuePriority::Normal).unwrap();
268        assert_eq!(id, 1);
269        let (did, cmd) = q.dequeue().unwrap();
270        assert_eq!(did, 1);
271        assert!(matches!(cmd, Command::Barrier));
272        assert!(q.is_empty());
273    }
274    #[test]
275    fn test_priority() {
276        let mut q = CommandQueue::new(QueueHandle(1), 64);
277        q.submit(Command::Barrier, QueuePriority::Low).unwrap();
278        q.submit(Command::Barrier, QueuePriority::High).unwrap();
279        let (_, cmd) = q.dequeue().unwrap();
280        assert!(matches!(cmd, Command::Barrier));
281    }
282    #[test]
283    fn test_capacity() {
284        let mut q = CommandQueue::new(QueueHandle(1), 2);
285        q.submit(Command::Barrier, QueuePriority::Normal).unwrap();
286        q.submit(Command::Barrier, QueuePriority::Normal).unwrap();
287        assert!(q.submit(Command::Barrier, QueuePriority::Normal).is_err());
288    }
289    #[test]
290    fn test_scheduler() {
291        let mut s = CommandScheduler::new();
292        let h1 = s.create_queue(64);
293        let h2 = s.create_queue(64);
294        assert_eq!(s.num_queues(), 2);
295        s.submit(h1, Command::Barrier, QueuePriority::Normal)
296            .unwrap();
297        s.submit(h2, Command::Barrier, QueuePriority::High).unwrap();
298        assert_eq!(s.total_pending(), 2);
299        let (qh, _, _) = s.dequeue_next().unwrap();
300        assert!(qh == h1 || qh == h2);
301    }
302    #[test]
303    fn test_events() {
304        let mut q = CommandQueue::new(QueueHandle(1), 64);
305        let ev = q.create_event();
306        assert!(!q.is_event_signaled(ev));
307        q.signal_event(ev);
308        assert!(q.is_event_signaled(ev));
309    }
310}