Skip to main content

qualia_core_db/gpu_context/
caps.rs

1pub use etalon_agent::device_caps::{GpuAdapterCaps, GpuFeatureCaps, GpuLimitCaps};
2/// Feature set to request for native LLM inference, intersected with `available` so nothing unsupported is requested.
3pub fn requested_native_llm_features(available: etalon::Features) -> etalon::Features {
4    let mut desired = etalon::Features::TIMESTAMP_QUERY
5        | etalon::Features::TIMESTAMP_QUERY_INSIDE_PASSES
6        | etalon::Features::PIPELINE_STATISTICS_QUERY
7        | etalon::Features::PIPELINE_CACHE
8        | etalon::Features::SHADER_F16
9        | etalon::Features::SUBGROUP
10        | etalon::Features::SUBGROUP_BARRIER;
11    if experimental_features_allowed() {
12        desired |= etalon::Features::EXPERIMENTAL_COOPERATIVE_MATRIX;
13    }
14    available & desired
15}
16
17/// `true` when experimental GPU features may be requested (build/env policy gate).
18pub fn experimental_features_allowed() -> bool {
19    matches!(
20        std::env::var("QUALIA_WGPU_EXPERIMENTAL_FEATURES")
21            .ok()
22            .as_deref(),
23        Some("1") | Some("true") | Some("yes")
24    )
25}
26
27// ── Inference-pipeline (GPU backend) selection — the "which pipeline for this machine" checker ──
28
29/// An explicit GPU-backend override for the inference device.
30///
31/// Priority:
32/// 1. `QUALIA_WGPU_BACKEND` env (`vulkan` | `dx12` | `metal` | `gl` | `primary` | `all`)
33/// 2. Cached [`crate::hardware_passport`] best GPU circuit (from `qualia-cli llm passport`)
34/// 3. `None` → platform default in `init_shared_gpu_async` (Windows → DX12; else wgpu pick)
35///
36/// This is what lets a machine be pinned by measurement rather than a static hierarchy.
37#[cfg(not(target_arch = "wasm32"))]
38pub fn qualia_backend_override() -> Option<etalon::Backends> {
39    if let Ok(raw) = std::env::var("QUALIA_WGPU_BACKEND") {
40        let v = raw.trim().to_ascii_lowercase();
41        return match v.as_str() {
42            "vulkan" | "vk" => Some(etalon::Backends::VULKAN),
43            "dx12" | "d3d12" | "directx12" => Some(etalon::Backends::DX12),
44            "metal" | "mtl" => Some(etalon::Backends::METAL),
45            "gl" | "opengl" | "gles" => Some(etalon::Backends::GL),
46            "primary" => Some(etalon::Backends::PRIMARY),
47            "all" => Some(etalon::Backends::all()),
48            other => {
49                log::warn!(
50                    "QUALIA_WGPU_BACKEND='{other}' unrecognized — trying passport / default"
51                );
52                None
53            }
54        }
55        .or_else(passport_backend_override);
56    }
57    passport_backend_override()
58}
59
60/// Prefer the measured HardwarePassport GPU backend when no env pin is set.
61#[cfg(not(target_arch = "wasm32"))]
62fn passport_backend_override() -> Option<etalon::Backends> {
63    let backend = crate::hardware_passport::cached_preferred_wgpu_backend()?;
64    let token = crate::hardware_passport::backend_env_token(&backend)?;
65    log::info!("shared_gpu|backend_from_passport|{backend}|token={token}");
66    match token {
67        "vulkan" => Some(etalon::Backends::VULKAN),
68        "dx12" => Some(etalon::Backends::DX12),
69        "metal" => Some(etalon::Backends::METAL),
70        "gl" => Some(etalon::Backends::GL),
71        _ => None,
72    }
73}
74
75/// Capability-aware recommendation for which GPU backend this machine *should* run inference on
76/// (advisory; surfaced by the doctor/setup checker). Prefers the **portable, vendor-neutral**
77/// path so the build is not silently locked to Windows (DX12) or NVIDIA (CUDA). Reactive to the
78/// adapter actually in hand; a full enumerate-all-backends-and-pick is the next layer.
79#[cfg(not(target_arch = "wasm32"))]
80pub fn recommend_inference_backend(caps: &GpuAdapterCaps) -> &'static str {
81    match caps.backend {
82        etalon::Backend::Vulkan => "vulkan — vendor-neutral & portable (recommended)",
83        etalon::Backend::Metal => "metal — Apple-native (recommended on macOS)",
84        etalon::Backend::Dx12 => {
85            "dx12 — Windows-native; set QUALIA_WGPU_BACKEND=vulkan for the portable path"
86        }
87        etalon::Backend::Gl => "gl — compatibility fallback, limited compute (last resort)",
88        etalon::Backend::BrowserWebGpu => "browser-webgpu — WebGPU in the page",
89        _ => "noop/unknown — no GPU compute path",
90    }
91}
92
93#[cfg(target_arch = "wasm32")]
94/// Picks a recommended inference backend label from the adapter's real capabilities.
95pub fn recommend_inference_backend(caps: &GpuAdapterCaps) -> &'static str {
96    match caps.backend {
97        etalon::Backend::BrowserWebGpu => "browser-webgpu — WebGPU in the page (recommended in WASM)",
98        _ => "browser-webgpu — request a WebGPU adapter (recommended in WASM)",
99    }
100}