qualia_core_db/platform/compute_bridge/backend.rs
1//! The open backend registry (HARDWARE_BACKEND_AUTOSELECT_PLAN.md §2.2, §4).
2//!
3//! The bridge's expansion point: backends are **not** a closed enum. Each
4//! acceleration method (CPU, the wgpu backends, later CUDA / ROCm / oneAPI / NPU
5//! runtimes) is one `impl ProbeableBackend` registered into a [`BackendRegistry`].
6//! The benchmark loop, the ranking, the passport schema and `ComputePolicy::select`
7//! all iterate the registry — so **adding a backend is one `register()` call and
8//! never edits the decision tree** (the load-bearing requirement). A backend that
9//! is not `available()` on this machine simply contributes no rows.
10//!
11//! `BackendId` is a `Copy` `&'static str` so it is zero-heap to pass around and
12//! string-keyed in the passport (forward-compatible: a passport written by a core
13//! build is still readable by an expansion build — the new backend is just absent
14//! and gets probed on next boot).
15
16use super::kernel_class::KernelClass;
17use crate::device_benchmark::CircuitBench;
18
19/// Stable, string-keyed backend identifier. `Copy`, zero-heap. Built-ins:
20/// `"cpu"`, `"wgpu"` (which itself reports per-adapter circuits via wgpu's
21/// `Vulkan`/`Dx12`/`Metal`/`Gl`); expansion ids: `"cuda"`, `"rocm"`, `"oneapi"`,
22/// `"npu-directml"`, …
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
24pub struct BackendId(pub &'static str);
25
26impl BackendId {
27 pub const CPU: BackendId = BackendId("cpu");
28 pub const WGPU: BackendId = BackendId("wgpu");
29
30 /// Stable string form.
31 pub fn as_str(self) -> &'static str {
32 self.0
33 }
34}
35
36impl core::fmt::Display for BackendId {
37 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
38 f.write_str(self.0)
39 }
40}
41
42/// Why a dispatch could not run on the requested backend. The dispatcher must
43/// degrade to CPU on any of these, never panic (plan §7: CPU never hard-fails).
44#[derive(Debug, Clone, PartialEq, Eq)]
45pub enum DispatchError {
46 /// The backend exists but cannot run this kernel class.
47 UnsupportedClass(KernelClass),
48 /// The backend's runtime/SDK is not present on this host.
49 Unavailable(BackendId),
50 /// A backend-internal failure (driver, allocation, …) — caller falls back to CPU.
51 BackendFailure(String),
52}
53
54impl core::fmt::Display for DispatchError {
55 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
56 match self {
57 DispatchError::UnsupportedClass(c) => {
58 write!(f, "backend cannot run kernel class {}", c.label())
59 }
60 DispatchError::Unavailable(b) => write!(f, "backend {b} is not available on this host"),
61 DispatchError::BackendFailure(m) => write!(f, "backend failure: {m}"),
62 }
63 }
64}
65impl std::error::Error for DispatchError {}
66
67/// Per-class problem sizes for the measurement panel. Kept small; cached in the
68/// passport so the heavy pass runs once per machine (plan §3 cost guard). `quick()`
69/// shrinks the sizes for low-tier devices / fast boot.
70#[derive(Debug, Clone, Copy)]
71pub struct KernelPanel {
72 /// GEMV/GEMM side length (DenseLinear).
73 pub dense_n: usize,
74 /// Vector length for ElementwiseMap / Reduction / Scan.
75 pub vector_len: usize,
76 /// Grid length for the 1-D Stencil pass.
77 pub grid_n: usize,
78 /// Particle count for the AllPairs (N-body) pass.
79 pub nbody_n: usize,
80 /// Transform length for the FFT (must be a power of two).
81 pub fft_n: usize,
82 /// Monte-Carlo steps for the Divergent pass.
83 pub mc_steps: usize,
84}
85
86impl Default for KernelPanel {
87 fn default() -> Self {
88 Self {
89 dense_n: 1024,
90 vector_len: 1 << 20,
91 grid_n: 1 << 20,
92 nbody_n: 2048,
93 fft_n: 1 << 16,
94 mc_steps: 1 << 20,
95 }
96 }
97}
98
99impl KernelPanel {
100 /// Smaller panel for fast boot / Tier-0 devices (plan §3 `--quick`).
101 pub fn quick() -> Self {
102 Self {
103 dense_n: 256,
104 vector_len: 1 << 16,
105 grid_n: 1 << 16,
106 nbody_n: 512,
107 fft_n: 1 << 12,
108 mc_steps: 1 << 16,
109 }
110 }
111}
112
113/// One acceleration method. Implementors register into a [`BackendRegistry`]; the
114/// rest of the bridge only ever sees them through this trait, which is why adding a
115/// backend never edits `select()`.
116pub trait ProbeableBackend: Send + Sync {
117 /// Stable identifier (`"cpu"`, `"wgpu"`, `"cuda"`, …).
118 fn id(&self) -> BackendId;
119
120 /// Is this backend's runtime/SDK present and usable on THIS machine? A `false`
121 /// backend contributes no rows and is never selected.
122 fn available(&self) -> bool;
123
124 /// Measure this backend on one kernel class, returning a row per physical
125 /// circuit it can drive (e.g. wgpu returns one row per adapter). Empty when the
126 /// backend cannot run the class or is unavailable — recorded honestly as "no
127 /// rows," never a fabricated number.
128 fn probe_class(&self, class: KernelClass, panel: &KernelPanel) -> Vec<CircuitBench>;
129}
130
131/// The registry of acceleration methods. Heap-using and boot-time only (the heavy
132/// probe runs once and is cached in the passport — never on a hot path).
133#[derive(Default)]
134pub struct BackendRegistry {
135 backends: Vec<Box<dyn ProbeableBackend>>,
136}
137
138impl BackendRegistry {
139 /// Creates a default `BackendRegistry`.
140 pub fn new() -> Self {
141 Self {
142 backends: Vec::new(),
143 }
144 }
145
146 /// Register a backend. Adding one here is the *only* change needed to bring a
147 /// new acceleration method into the benchmark, ranking and policy.
148 pub fn register(&mut self, backend: Box<dyn ProbeableBackend>) -> &mut Self {
149 self.backends.push(backend);
150 self
151 }
152
153 /// All registered backends (including currently-unavailable ones).
154 pub fn iter(&self) -> impl Iterator<Item = &dyn ProbeableBackend> {
155 self.backends.iter().map(|b| b.as_ref())
156 }
157
158 /// Backends actually usable on this host.
159 pub fn available(&self) -> impl Iterator<Item = &dyn ProbeableBackend> {
160 self.backends
161 .iter()
162 .map(|b| b.as_ref())
163 .filter(|b| b.available())
164 }
165
166 /// Number of elements.
167 pub fn len(&self) -> usize {
168 self.backends.len()
169 }
170
171 /// `true` when empty.
172 pub fn is_empty(&self) -> bool {
173 self.backends.is_empty()
174 }
175}
176
177#[cfg(test)]
178mod tests {
179 use super::*;
180 use crate::device_benchmark::CircuitKind;
181
182 /// A synthetic backend proving the registry is open: it registers and is iterated
183 /// without any change to the registry, panel, matrix, or policy code.
184 struct StubBackend {
185 id: BackendId,
186 up: bool,
187 }
188 impl ProbeableBackend for StubBackend {
189 fn id(&self) -> BackendId {
190 self.id
191 }
192 fn available(&self) -> bool {
193 self.up
194 }
195 fn probe_class(&self, _class: KernelClass, _panel: &KernelPanel) -> Vec<CircuitBench> {
196 if !self.up {
197 return Vec::new();
198 }
199 vec![CircuitBench {
200 label: self.id.as_str().to_string(),
201 kind: CircuitKind::Other,
202 backend: self.id.as_str().to_string(),
203 ms_per_gemv: 1.0,
204 gflops: 1.0,
205 upload_gbps: 1.0,
206 rel_score: 1.0,
207 decode_proxy_tok_s: None,
208 }]
209 }
210 }
211
212 #[test]
213 fn registry_is_open_and_iterates_members() {
214 let mut reg = BackendRegistry::new();
215 reg.register(Box::new(StubBackend {
216 id: BackendId("alpha"),
217 up: true,
218 }))
219 .register(Box::new(StubBackend {
220 id: BackendId("beta"),
221 up: false,
222 }));
223 assert_eq!(reg.len(), 2);
224 // Only the available backend is offered for work.
225 let avail: Vec<_> = reg.available().map(|b| b.id()).collect();
226 assert_eq!(avail, vec![BackendId("alpha")]);
227 // Unavailable backend contributes no rows (honest "not probed").
228 let rows: Vec<_> = reg
229 .iter()
230 .flat_map(|b| b.probe_class(KernelClass::DenseLinear, &KernelPanel::quick()))
231 .collect();
232 assert_eq!(rows.len(), 1, "only the available backend yields a row");
233 }
234
235 #[test]
236 fn backend_id_is_copy_and_string_keyed() {
237 let a = BackendId::CPU;
238 let b = a; // Copy
239 assert_eq!(a, b);
240 assert_eq!(BackendId::WGPU.as_str(), "wgpu");
241 }
242}