Skip to main content

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}