Skip to main content

qualia_core_db/net/
host_topology.rs

1//! STELLAR §A AH-track H0 — **host topology + capability sensor** (decision D23/D24).
2//!
3//! The engine must *sense then route* instead of grabbing one adapter. Today `gpu_context::
4//! shared_gpu()` requests a single `PowerPreference::HighPerformance` device — on a discrete +
5//! integrated box that silently takes only the discrete GPU and ignores the integrated GPU and all
6//! of system RAM. This module enumerates **every** adapter, classifies the memory topology
7//! (discrete vs unified), reads host RAM, and computes the bounded OS floor (D24). The residency
8//! planner (H2) and heterogeneous/cluster dispatch (H3/H5) consume this; it makes no routing
9//! decision itself and changes no existing behaviour.
10//!
11//! Native only — `enumerate_adapters` is not available on the wasm/WebGPU path.
12#![cfg(not(target_arch = "wasm32"))]
13
14use serde::{Deserialize, Serialize};
15
16/// Coarse adapter class (maps `etalon::DeviceType`).
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
18pub enum AdapterClass {
19    Discrete,
20    Integrated,
21    Cpu,
22    Virtual,
23    Other,
24}
25
26impl AdapterClass {
27    #[cfg(feature = "gpu-runtime")]
28    fn from_wgpu(t: etalon::DeviceType) -> Self {
29        match t {
30            etalon::DeviceType::DiscreteGpu => Self::Discrete,
31            etalon::DeviceType::IntegratedGpu => Self::Integrated,
32            etalon::DeviceType::Cpu => Self::Cpu,
33            etalon::DeviceType::VirtualGpu => Self::Virtual,
34            etalon::DeviceType::Other => Self::Other,
35        }
36    }
37}
38
39/// Whole-host memory topology: is there a dedicated VRAM pool, or one shared pool?
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
41pub enum HostMemoryTopology {
42    /// At least one discrete GPU with its own VRAM (PCIe boundary matters).
43    Discrete,
44    /// Only integrated/CPU adapters — VRAM and system RAM are one pool (Apple Silicon, iGPU-only, phone).
45    Unified,
46}
47
48/// One enumerated adapter.
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct AdapterDesc {
51    pub name: String,
52    pub backend: String,
53    pub class: AdapterClass,
54    pub vendor: u32,
55    pub device: u32,
56    /// Best-effort dedicated VRAM (Windows/DXGI only; 0 = unknown on this platform).
57    pub dedicated_vram_bytes: u64,
58}
59
60/// The sensed host: adapters, topology, host memory, and the bounded OS floor (D24).
61#[derive(Debug, Clone, Serialize, Deserialize)]
62pub struct HostTopology {
63    pub adapters: Vec<AdapterDesc>,
64    pub topology: HostMemoryTopology,
65    pub host_ram_bytes: u64,
66    pub host_ram_available_bytes: u64,
67    pub cpu_cores: usize,
68    /// Hard floor reserved for the OS/display (D24): discrete → VRAM display floor; unified → host floor.
69    pub os_floor_bytes: u64,
70    /// Best-effort memory the LLM may inhabit after the floor (discrete: VRAM−floor; unified: RAM−floor).
71    pub usable_model_budget_bytes: u64,
72}
73
74const DISCRETE_VRAM_FLOOR: u64 = 1_500 * 1024 * 1024; // ~1.5 GB for the display server
75const UNIFIED_HOST_FLOOR_MAX: u64 = 6 * 1024 * 1024 * 1024; // cap the unified host reservation
76
77/// Rank backends so the same physical GPU (enumerated once per backend) collapses to the preferred one.
78#[cfg(feature = "gpu-runtime")]
79fn backend_rank(b: etalon::Backend) -> u8 {
80    match b {
81        // Prefer the backend each OS actually runs the engine on.
82        etalon::Backend::Metal => 0,
83        etalon::Backend::Dx12 => 1,
84        etalon::Backend::Vulkan => 2,
85        etalon::Backend::Gl => 3,
86        _ => 4,
87    }
88}
89
90/// wgpu adapter enumeration. CPU topology (RAM / cores / OS floor) still runs without this.
91#[cfg(feature = "gpu-runtime")]
92fn probe_adapters() -> Vec<AdapterDesc> {
93    // Enumerate every adapter across every backend, then dedup by physical (vendor, device).
94    let instance = etalon::Instance::default();
95    let raw = pollster::block_on(instance.enumerate_adapters(etalon::Backends::all()));
96    let mut best: std::collections::HashMap<(u32, u32), (u8, AdapterDesc)> =
97        std::collections::HashMap::new();
98    for adapter in raw {
99        let info = adapter.get_info();
100        let rank = backend_rank(info.backend);
101        let desc = AdapterDesc {
102            name: info.name.clone(),
103            backend: format!("{:?}", info.backend),
104            class: AdapterClass::from_wgpu(info.device_type),
105            vendor: info.vendor,
106            device: info.device,
107            dedicated_vram_bytes: 0,
108        };
109        best.entry((info.vendor, info.device))
110            .and_modify(|(r, d)| {
111                if rank < *r {
112                    *r = rank;
113                    *d = desc.clone();
114                }
115            })
116            .or_insert((rank, desc));
117    }
118    let mut adapters: Vec<AdapterDesc> = best.into_values().map(|(_, d)| d).collect();
119    // Drop phantom duplicates: some backends (notably GL) report device id 0 for a card already
120    // enumerated with a real id on another backend. (Limitation: two *identical-model* cards share
121    // (vendor, device) and collapse to one — precise multi-GPU counting of identical cards needs a
122    // per-OS PCI-bus / LUID probe that wgpu doesn't expose; deferred to H3/H5.)
123    let vendors_with_real_dev: std::collections::HashSet<u32> = adapters
124        .iter()
125        .filter(|a| a.device != 0)
126        .map(|a| a.vendor)
127        .collect();
128    adapters.retain(|a| a.device != 0 || !vendors_with_real_dev.contains(&a.vendor));
129    // Discrete first, then integrated, then the rest — deterministic order for the planner.
130    adapters.sort_by_key(|a| (a.class as u8, a.vendor, a.device));
131    adapters
132}
133
134#[cfg(not(feature = "gpu-runtime"))]
135fn probe_adapters() -> Vec<AdapterDesc> {
136    Vec::new()
137}
138
139/// Probe the host: enumerate all adapters (deduped across backends), classify, size the floor.
140pub fn probe_host_topology() -> HostTopology {
141    use sysinfo::System;
142    let sys = System::new_all();
143    let host_ram_bytes = sys.total_memory(); // bytes (sysinfo ≥ 0.30)
144    let host_ram_available_bytes = sys.available_memory();
145    let cpu_cores = num_cpus::get();
146
147    #[cfg(target_os = "windows")]
148    let mut adapters = probe_adapters();
149    #[cfg(not(target_os = "windows"))]
150    let adapters = probe_adapters();
151
152    let has_discrete = adapters.iter().any(|a| a.class == AdapterClass::Discrete);
153    let topology = if has_discrete {
154        HostMemoryTopology::Discrete
155    } else {
156        HostMemoryTopology::Unified
157    };
158
159    // Best-effort dedicated VRAM for the discrete card (Windows/DXGI).
160    #[cfg(target_os = "windows")]
161    if has_discrete {
162        if let Ok(mem) = crate::directml_bridge::probe_best_adapter_memory() {
163            let vram = mem.dedicated_vram_bytes.max(mem.local_budget_bytes);
164            if let Some(disc) = adapters
165                .iter_mut()
166                .find(|a| a.class == AdapterClass::Discrete)
167            {
168                disc.dedicated_vram_bytes = vram;
169            }
170        }
171    }
172
173    let (os_floor_bytes, usable_model_budget_bytes) = match topology {
174        HostMemoryTopology::Discrete => {
175            let vram = adapters
176                .iter()
177                .filter(|a| a.class == AdapterClass::Discrete)
178                .map(|a| a.dedicated_vram_bytes)
179                .max()
180                .unwrap_or(0);
181            let floor = DISCRETE_VRAM_FLOOR.min(vram / 4); // never reserve more than ¼ of a tiny card
182            (floor, vram.saturating_sub(floor))
183        }
184        HostMemoryTopology::Unified => {
185            // Reserve up to 6 GB or a quarter of RAM, whichever is smaller, for the host OS.
186            let floor = UNIFIED_HOST_FLOOR_MAX.min(host_ram_bytes / 4);
187            (floor, host_ram_bytes.saturating_sub(floor))
188        }
189    };
190
191    HostTopology {
192        adapters,
193        topology,
194        host_ram_bytes,
195        host_ram_available_bytes,
196        cpu_cores,
197        os_floor_bytes,
198        usable_model_budget_bytes,
199    }
200}
201
202impl HostTopology {
203    /// True when there is both a discrete GPU and a (system-RAM-backed) integrated GPU —
204    /// the heterogeneous-overflow opportunity (H3): the iGPU can host overflow layers in system RAM.
205    pub fn has_heterogeneous_overflow(&self) -> bool {
206        self.topology == HostMemoryTopology::Discrete
207            && self
208                .adapters
209                .iter()
210                .any(|a| a.class == AdapterClass::Integrated)
211    }
212
213    /// One-line-per-field human summary for logs / the progress record.
214    pub fn summary(&self) -> String {
215        let mut s = format!(
216            "HostTopology: {:?} | host RAM {:.1} GB ({:.1} GB free) | {} cores | OS floor {:.1} GB | model budget {:.1} GB | heterogeneous={}\n",
217            self.topology,
218            self.host_ram_bytes as f64 / 1e9,
219            self.host_ram_available_bytes as f64 / 1e9,
220            self.cpu_cores,
221            self.os_floor_bytes as f64 / 1e9,
222            self.usable_model_budget_bytes as f64 / 1e9,
223            self.has_heterogeneous_overflow(),
224        );
225        for a in &self.adapters {
226            s.push_str(&format!(
227                "  - {:?} [{}] {} (vendor 0x{:04x} dev 0x{:04x}){}\n",
228                a.class,
229                a.backend,
230                a.name,
231                a.vendor,
232                a.device,
233                if a.dedicated_vram_bytes > 0 {
234                    format!(" VRAM {:.1} GB", a.dedicated_vram_bytes as f64 / 1e9)
235                } else {
236                    String::new()
237                },
238            ));
239        }
240        s
241    }
242}
243
244#[cfg(test)]
245mod tests {
246    use super::*;
247
248    #[test]
249    fn h0_probes_host_topology() {
250        let topo = probe_host_topology();
251        eprintln!("{}", topo.summary());
252
253        // Host memory + CPU are always available.
254        assert!(topo.host_ram_bytes > 0, "host RAM must be sensed");
255        assert!(topo.cpu_cores > 0, "cpu cores must be sensed");
256
257        if topo.adapters.is_empty() {
258            eprintln!("[h0] no wgpu adapters (headless CI) — RAM/CPU still sensed");
259            return;
260        }
261
262        // Topology classification is consistent with the enumerated adapters.
263        let any_discrete = topo
264            .adapters
265            .iter()
266            .any(|a| a.class == AdapterClass::Discrete);
267        assert_eq!(
268            any_discrete,
269            topo.topology == HostMemoryTopology::Discrete,
270            "topology must match presence of a discrete adapter"
271        );
272        // The model budget never exceeds the relevant pool.
273        assert!(
274            topo.usable_model_budget_bytes
275                <= topo
276                    .host_ram_bytes
277                    .max(
278                        topo.adapters
279                            .iter()
280                            .map(|a| a.dedicated_vram_bytes)
281                            .max()
282                            .unwrap_or(0)
283                    )
284                    .max(1)
285        );
286    }
287}