1#![cfg(not(target_arch = "wasm32"))]
18
19use serde::{Deserialize, Serialize};
20use std::io::Read;
21use std::path::PathBuf;
22
23use crate::device_benchmark::{benchmark_devices, CapabilityMatrix, CircuitKind};
24use crate::host_topology::{probe_host_topology, HostTopology};
25use std::path::Path;
26
27pub const PASSPORT_VERSION: u32 = 2;
30
31pub const PASSPORT_GEMV_N: usize = 2048;
33const MAX_PASSPORT_BYTES: usize = 4 * 1024 * 1024;
34
35#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct HardwarePassport {
38 pub version: u32,
39 pub key: String,
41 pub topology: HostTopology,
42 pub matrix: CapabilityMatrix,
43 #[serde(default)]
46 pub preferred_inference_backend: Option<String>,
47 #[serde(default)]
49 pub probe_gemv_n: usize,
50 #[serde(default, skip_serializing_if = "Option::is_none")]
52 pub decode_proxy_model: Option<String>,
53 #[serde(default)]
55 pub decode_proxy_tokens: u32,
56}
57
58pub fn topology_key(topo: &HostTopology) -> String {
61 let mut ids: Vec<String> = topo
62 .adapters
63 .iter()
64 .map(|a| format!("{:04x}:{:04x}", a.vendor, a.device))
65 .collect();
66 ids.sort();
67 ids.join(",")
68}
69
70pub fn default_cache_path() -> PathBuf {
72 std::env::temp_dir().join("qualia_hardware_passport.cbor")
73}
74
75pub fn write_passport(passport: &HardwarePassport, path: &Path) -> Result<(), String> {
77 if !gpu_cpu_only(passport) {
78 return Err("NPU execution claims cannot be stored in the GPU/CPU passport".into());
79 }
80 let mut buf = PassportBuffer(Vec::new());
81 ciborium::into_writer(passport, &mut buf).map_err(|e| format!("cbor encode: {e}"))?;
82 std::fs::write(path, &buf.0).map_err(|e| format!("write {}: {e}", path.display()))
83}
84
85struct PassportBuffer(Vec<u8>);
86
87impl std::io::Write for PassportBuffer {
88 fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
89 if bytes.len() > MAX_PASSPORT_BYTES.saturating_sub(self.0.len()) {
90 return Err(std::io::Error::other(
91 "hardware passport exceeds its byte budget",
92 ));
93 }
94 self.0.extend_from_slice(bytes);
95 Ok(bytes.len())
96 }
97
98 fn flush(&mut self) -> std::io::Result<()> {
99 Ok(())
100 }
101}
102
103pub fn read_passport(path: &Path) -> Option<HardwarePassport> {
105 let file = std::fs::File::open(path).ok()?;
106 if file.metadata().ok()?.len() > MAX_PASSPORT_BYTES as u64 {
107 return None;
108 }
109 let mut bytes = Vec::new();
110 file.take((MAX_PASSPORT_BYTES + 1) as u64)
111 .read_to_end(&mut bytes)
112 .ok()?;
113 if bytes.len() > MAX_PASSPORT_BYTES {
114 return None;
115 }
116 let passport: HardwarePassport = ciborium::from_reader(&bytes[..]).ok()?;
117 if passport.version != PASSPORT_VERSION || !gpu_cpu_only(&passport) {
118 return None;
119 }
120 Some(passport)
121}
122
123fn gpu_cpu_only(passport: &HardwarePassport) -> bool {
124 !passport.matrix.npu_probed
125 && !passport
126 .matrix
127 .circuits
128 .iter()
129 .any(|circuit| circuit.kind == CircuitKind::Npu)
130}
131
132pub fn load_or_probe(path: &Path, gemv_n: usize) -> (HardwarePassport, bool) {
135 let topology = probe_host_topology();
136 let current_key = topology_key(&topology);
137
138 if let Some(cached) = read_passport(path) {
139 if cache_matches(&cached, ¤t_key, gemv_n) {
140 return (cached, true); }
142 }
144
145 let matrix = benchmark_devices(gemv_n);
146 let preferred = matrix
147 .best()
148 .and_then(|c| backend_env_token(&c.backend))
149 .map(str::to_string);
150 let fresh = HardwarePassport {
151 version: PASSPORT_VERSION,
152 key: current_key,
153 topology,
154 matrix,
155 preferred_inference_backend: preferred,
156 probe_gemv_n: gemv_n,
157 decode_proxy_model: None,
158 decode_proxy_tokens: 0,
159 };
160 let _ = write_passport(&fresh, path);
161 (fresh, false)
162}
163
164fn cache_matches(passport: &HardwarePassport, key: &str, gemv_n: usize) -> bool {
165 passport.key == key
166 && passport.probe_gemv_n == gemv_n
167 && passport.matrix.gemv_n == gemv_n
168 && gpu_cpu_only(passport)
169}
170
171pub fn default_decode_proxy_model() -> Option<std::path::PathBuf> {
173 if let Ok(p) = std::env::var("QUALIA_LLM_PROFILE_MODEL") {
174 let pb = std::path::PathBuf::from(p);
175 if pb.is_file() {
176 return Some(pb);
177 }
178 }
179 const CANDIDATES: &[&str] = &[
180 r"C:\LLM_Models\P64\smollm2-360m-instruct-q8_0.f16.p64",
181 r"C:\LLM_Models\P64\smollm2-360m-instruct-q8_0.p64",
182 r"C:\LLM_Models\GGUF\smollm2-360m-instruct-q8_0.gguf",
183 r"C:\LLM_Models\GGUF\lmstudio-community\smollm2-360m-instruct-q8_0.gguf",
184 ];
185 CANDIDATES
186 .iter()
187 .map(std::path::PathBuf::from)
188 .find(|p| p.is_file())
189}
190
191pub const DECODE_PROXY_PROBE_PROMPT: &str = "The capital of France is";
193
194#[derive(Debug, Clone)]
196pub struct DecodeProxyResult {
197 pub tok_s: f64,
198 pub text: String,
199 pub coherence_ok: bool,
201 pub execution_path: String,
204 pub resident_hits: u64,
205 pub resident_fallbacks: u64,
206 pub cuda_mega_hits: u64,
207 pub cuda_mega_fallbacks: u64,
208}
209
210pub fn decode_proxy_coherence_ok(text: &str) -> bool {
213 text.to_ascii_lowercase().contains("paris")
214}
215
216pub fn measure_decode_proxy(model: &Path, n_tokens: u32) -> Option<DecodeProxyResult> {
225 #[cfg(feature = "wgsl-forge")]
226 crate::wgsl_forge::dispatch::ensure_cuda_runtime_path();
227 let n = n_tokens.max(8).min(128);
228 let path = model.to_path_buf();
229 crate::llm_bench::set_sampler_config(None);
231 let path_str = path.to_str()?.to_string();
232 let join = std::thread::Builder::new()
233 .name("decode-proxy".into())
234 .spawn(move || {
235 let prompt = DECODE_PROXY_PROBE_PROMPT;
236 let _ = crate::llm_bench::decode_with_metrics_blocking(&path_str, prompt, 4);
238 crate::llm_bench::reset_resident_path_counts();
239 crate::llm_bench::reset_cuda_mega_path_counts();
240 let measured = crate::llm_bench::decode_with_metrics_blocking(&path_str, prompt, n);
241 let resident = crate::llm_bench::resident_path_counts();
242 let cuda = crate::llm_bench::cuda_mega_path_counts();
243 (measured, resident, cuda)
244 })
245 .ok()?
246 .join();
247 match join {
248 Ok((Ok((text, tok_s)), resident, cuda)) if tok_s > 0.0 => {
249 let coherence_ok = decode_proxy_coherence_ok(&text);
250 let execution_path = match (resident.0 > 0, cuda.0 > 0) {
251 (true, false) => "wgpu-resident",
252 (false, true) => "cuda-c",
253 (true, true) => "mixed",
254 (false, false) => "legacy-or-unattributed",
255 }
256 .to_string();
257 Some(DecodeProxyResult {
258 tok_s,
259 text,
260 coherence_ok,
261 execution_path,
262 resident_hits: resident.0,
263 resident_fallbacks: resident.1,
264 cuda_mega_hits: cuda.0,
265 cuda_mega_fallbacks: cuda.1,
266 })
267 }
268 Ok((Ok(_), _, _)) => None,
269 Ok((Err(e), _, _)) => {
270 log::warn!("decode_proxy|fail|{e}");
271 None
272 }
273 Err(_) => {
274 log::warn!("decode_proxy|thread_panic");
275 None
276 }
277 }
278}
279
280pub fn measure_decode_proxy_tok_s(model: &Path, n_tokens: u32) -> Option<f64> {
282 measure_decode_proxy(model, n_tokens).map(|r| r.tok_s)
283}
284
285pub fn attach_decode_proxy_via_subprocess(
291 matrix: &mut CapabilityMatrix,
292 model: &Path,
293 n_tokens: u32,
294 self_exe: &Path,
295) {
296 use std::process::Command;
297 let n = n_tokens.max(8).min(64);
298 let mut seen_tokens = std::collections::HashSet::<String>::new();
301 for c in matrix.circuits.iter_mut() {
302 if c.kind != CircuitKind::DiscreteGpu {
303 continue;
304 }
305 let Some(token) = backend_env_token(&c.backend) else {
306 continue;
307 };
308 if !seen_tokens.insert(token.to_string()) {
309 continue;
310 }
311 let output = Command::new(self_exe)
312 .args([
313 "llm",
314 "decode-proxy",
315 &model.display().to_string(),
316 "--tokens",
317 &n.to_string(),
318 ])
319 .env("QUALIA_WGPU_BACKEND", token)
320 .env("QUALIA_P64_INTEGRITY", "metadata")
321 .env("RUST_LOG", "error")
322 .output();
323 let tok_s = match output {
324 Ok(o) if o.status.success() => {
325 let stdout = String::from_utf8_lossy(&o.stdout);
326 parse_decode_proxy_line(&stdout)
327 }
328 Ok(o) => {
329 log::warn!(
330 "decode_proxy|child_fail|backend={token}|{}",
331 String::from_utf8_lossy(&o.stderr)
332 );
333 None
334 }
335 Err(e) => {
336 log::warn!("decode_proxy|spawn_fail|backend={token}|{e}");
337 None
338 }
339 };
340 c.decode_proxy_tok_s = tok_s;
341 if let Some(t) = tok_s {
342 log::info!("decode_proxy|ok|backend={token}|{t:.2} tok/s");
343 }
344 }
345 let mut by_token: std::collections::HashMap<String, f64> = std::collections::HashMap::new();
347 for c in &matrix.circuits {
348 if c.kind != CircuitKind::DiscreteGpu {
349 continue;
350 }
351 if let (Some(tok), Some(t)) = (backend_env_token(&c.backend), c.decode_proxy_tok_s) {
352 by_token.insert(tok.to_string(), t);
353 }
354 }
355 for c in matrix.circuits.iter_mut() {
356 if c.kind != CircuitKind::DiscreteGpu || c.decode_proxy_tok_s.is_some() {
357 continue;
358 }
359 if let Some(tok) = backend_env_token(&c.backend) {
360 if let Some(&t) = by_token.get(tok) {
361 c.decode_proxy_tok_s = Some(t);
362 }
363 }
364 }
365 matrix.apply_decode_proxy_ranking();
366}
367
368pub fn parse_decode_proxy_line(stdout: &str) -> Option<f64> {
370 parse_decode_proxy_record(stdout).map(|r| r.tok_s)
371}
372
373#[derive(Debug, Clone)]
375pub struct DecodeProxyLine {
376 pub tok_s: f64,
377 pub coherence_ok: Option<bool>,
378 pub execution_path: Option<String>,
379}
380
381pub fn parse_decode_proxy_record(stdout: &str) -> Option<DecodeProxyLine> {
383 for line in stdout.lines() {
384 let line = line.trim();
385 if let Some(rest) = line.strip_prefix("DECODE_PROXY ") {
386 let mut tok_s: Option<f64> = None;
387 let mut coherence_ok: Option<bool> = None;
388 let mut execution_path: Option<String> = None;
389 for part in rest.split_whitespace() {
390 if let Some(v) = part.strip_prefix("tok_s=") {
391 tok_s = v.parse().ok();
392 } else if let Some(v) = part.strip_prefix("coherence=") {
393 coherence_ok = Some(v == "1" || v.eq_ignore_ascii_case("true"));
394 } else if let Some(v) = part.strip_prefix("path=") {
395 execution_path = Some(v.to_string());
396 }
397 }
398 if let Some(tok_s) = tok_s {
399 return Some(DecodeProxyLine {
400 tok_s,
401 coherence_ok,
402 execution_path,
403 });
404 }
405 }
406 }
407 None
408}
409
410pub fn load_or_probe_default() -> (HardwarePassport, bool) {
412 load_or_probe(&default_cache_path(), PASSPORT_GEMV_N)
413}
414
415pub fn cached_preferred_wgpu_backend() -> Option<String> {
419 let path = default_cache_path();
420 let passport = read_passport(&path)?;
421 if let Some(ref t) = passport.preferred_inference_backend {
423 return Some(t.clone());
424 }
425 let best = passport.matrix.best()?;
426 if matches!(best.kind, crate::device_benchmark::CircuitKind::Cpu) {
428 return None;
429 }
430 Some(best.backend.clone())
431}
432
433pub fn backend_env_token(backend: &str) -> Option<&'static str> {
435 let s = backend.to_ascii_lowercase();
436 if s.contains("dx12") || s.contains("d3d12") {
437 Some("dx12")
438 } else if s.contains("vulkan") {
439 Some("vulkan")
440 } else if s.contains("metal") {
441 Some("metal")
442 } else if s.contains("gl") {
443 Some("gl")
444 } else {
445 None
446 }
447}
448
449#[cfg(test)]
450mod tests {
451 use super::*;
452 use crate::device_benchmark::{CapabilityMatrix, CircuitBench, CircuitKind};
453 use crate::host_topology::{AdapterClass, AdapterDesc, HostMemoryTopology, HostTopology};
454
455 const GB: u64 = 1024 * 1024 * 1024;
456
457 fn synthetic_passport() -> HardwarePassport {
458 let topology = HostTopology {
459 adapters: vec![
460 AdapterDesc {
461 name: "Discrete GPU".into(),
462 backend: "Dx12".into(),
463 class: AdapterClass::Discrete,
464 vendor: 0x10de,
465 device: 0x2571,
466 dedicated_vram_bytes: 12 * GB,
467 },
468 AdapterDesc {
469 name: "iGPU".into(),
470 backend: "Dx12".into(),
471 class: AdapterClass::Integrated,
472 vendor: 0x8086,
473 device: 0x1912,
474 dedicated_vram_bytes: 0,
475 },
476 ],
477 topology: HostMemoryTopology::Discrete,
478 host_ram_bytes: 64 * GB,
479 host_ram_available_bytes: 32 * GB,
480 cpu_cores: 8,
481 os_floor_bytes: 3 * GB / 2,
482 usable_model_budget_bytes: 12 * GB,
483 };
484 let matrix = CapabilityMatrix {
485 circuits: vec![
486 CircuitBench {
487 label: "Discrete GPU".into(),
488 kind: CircuitKind::DiscreteGpu,
489 backend: "Dx12".into(),
490 ms_per_gemv: 0.43,
491 gflops: 19.5,
492 upload_gbps: 3.3,
493 rel_score: 1.0,
494 decode_proxy_tok_s: Some(18.0),
495 },
496 CircuitBench {
497 label: "CPU native".into(),
498 kind: CircuitKind::Cpu,
499 backend: "native".into(),
500 ms_per_gemv: 23.0,
501 gflops: 0.4,
502 upload_gbps: f64::INFINITY, rel_score: 0.02,
504 decode_proxy_tok_s: None,
505 },
506 ],
507 gemv_n: 2048,
508 npu_probed: false,
509 };
510 HardwarePassport {
511 version: PASSPORT_VERSION,
512 key: topology_key(&topology),
513 topology,
514 matrix,
515 preferred_inference_backend: Some("dx12".into()),
516 probe_gemv_n: 2048,
517 decode_proxy_model: None,
518 decode_proxy_tokens: 0,
519 }
520 }
521
522 #[test]
523 fn cbor_round_trip_preserves_infinity_and_key() {
524 let p = synthetic_passport();
525 let dir = tempfile::tempdir().unwrap();
526 let path = dir.path().join("passport.cbor");
527
528 write_passport(&p, &path).expect("write");
529 let back = read_passport(&path).expect("read");
530
531 assert_eq!(back.version, PASSPORT_VERSION);
532 assert_eq!(back.key, p.key);
533 assert_eq!(back.key, "10de:2571,8086:1912");
534 assert_eq!(back.topology.adapters.len(), 2);
535 let cpu = back
537 .matrix
538 .circuits
539 .iter()
540 .find(|c| c.kind == CircuitKind::Cpu)
541 .unwrap();
542 assert!(
543 cpu.upload_gbps.is_infinite(),
544 "f64::INFINITY must round-trip through CBOR"
545 );
546 assert!((back.matrix.circuits[0].ms_per_gemv - 0.43).abs() < 1e-9);
547 }
548
549 #[test]
550 fn version_mismatch_is_ignored() {
551 let mut p = synthetic_passport();
552 p.version = 999;
553 let dir = tempfile::tempdir().unwrap();
554 let path = dir.path().join("passport.cbor");
555 write_passport(&p, &path).unwrap();
556 assert!(
557 read_passport(&path).is_none(),
558 "stale version must be rejected → re-probe"
559 );
560 }
561
562 #[test]
563 fn gpu_passport_cannot_restore_npu_execution_claims() {
564 let dir = tempfile::tempdir().unwrap();
565 let path = dir.path().join("passport.cbor");
566 for has_npu_row in [false, true] {
567 let mut passport = synthetic_passport();
568 if has_npu_row {
569 passport.matrix.circuits[0].kind = CircuitKind::Npu;
570 } else {
571 passport.matrix.npu_probed = true;
572 }
573 let mut bytes = Vec::new();
574 ciborium::into_writer(&passport, &mut bytes).unwrap();
575 std::fs::write(&path, bytes).unwrap();
576 assert!(read_passport(&path).is_none());
577 assert!(write_passport(&passport, &path).is_err());
578 }
579 }
580
581 #[test]
582 fn benchmark_shape_changes_invalidate_the_gpu_cache() {
583 let mut passport = synthetic_passport();
584 assert!(cache_matches(&passport, &passport.key, 2048));
585 assert!(!cache_matches(&passport, &passport.key, 512));
586 passport.matrix.gemv_n = 512;
587 assert!(!cache_matches(&passport, &passport.key, 2048));
588 }
589
590 #[test]
591 fn oversized_passports_are_rejected_before_decoding() {
592 let dir = tempfile::tempdir().unwrap();
593 let path = dir.path().join("passport.cbor");
594 std::fs::File::create(&path)
595 .unwrap()
596 .set_len((MAX_PASSPORT_BYTES + 1) as u64)
597 .unwrap();
598 assert!(read_passport(&path).is_none());
599 let mut passport = synthetic_passport();
600 passport.key = "a".repeat(MAX_PASSPORT_BYTES);
601 assert!(write_passport(&passport, &path).is_err());
602 }
603
604 #[test]
605 fn parse_decode_proxy_line_extracts_tok_s() {
606 let s = "noise\nDECODE_PROXY tok_s=12.50 backend=dx12 coherence=1\nmore\n";
607 assert!((parse_decode_proxy_line(s).unwrap() - 12.5).abs() < 1e-9);
608 let r = parse_decode_proxy_record(s).unwrap();
609 assert_eq!(r.coherence_ok, Some(true));
610 assert_eq!(r.execution_path, None);
611
612 let attributed =
613 "DECODE_PROXY tok_s=44.25 backend=cuda path=cuda-c coherence=1 cuda_hits=16\n";
614 let attributed = parse_decode_proxy_record(attributed).unwrap();
615 assert_eq!(attributed.execution_path.as_deref(), Some("cuda-c"));
616 assert!(parse_decode_proxy_line("nope").is_none());
617 assert!(decode_proxy_coherence_ok("… Paris is lovely"));
618 assert!(!decode_proxy_coherence_ok("asdkfjhasdf"));
619 }
620
621 #[test]
622 fn decode_proxy_ranking_prefers_higher_tok_s() {
623 let mut matrix = CapabilityMatrix {
624 circuits: vec![
625 CircuitBench {
626 label: "fast gemv slow decode".into(),
627 kind: CircuitKind::DiscreteGpu,
628 backend: "Vulkan".into(),
629 ms_per_gemv: 0.1,
630 gflops: 50.0,
631 upload_gbps: 4.0,
632 rel_score: 1.0,
633 decode_proxy_tok_s: Some(5.0),
634 },
635 CircuitBench {
636 label: "slower gemv fast decode".into(),
637 kind: CircuitKind::DiscreteGpu,
638 backend: "Dx12".into(),
639 ms_per_gemv: 0.2,
640 gflops: 25.0,
641 upload_gbps: 4.0,
642 rel_score: 0.5,
643 decode_proxy_tok_s: Some(18.0),
644 },
645 ],
646 gemv_n: 512,
647 npu_probed: false,
648 };
649 matrix.apply_decode_proxy_ranking();
650 assert_eq!(matrix.best().unwrap().backend, "Dx12");
651 assert!((matrix.best().unwrap().rel_score - 1.0).abs() < 1e-9);
652 }
653
654 #[test]
657 fn load_or_probe_caches_then_hits() {
658 let dir = tempfile::tempdir().unwrap();
659 let path = dir.path().join("passport.cbor");
660
661 let (first, cached1) = load_or_probe(&path, 512);
662 assert!(!cached1, "first call must probe");
663 assert!(path.exists(), "probe must write the cache");
664 assert!(!first.matrix.circuits.is_empty());
665
666 let (second, cached2) = load_or_probe(&path, 512);
667 assert!(cached2, "second call must hit the cache (fast-boot)");
668 assert_eq!(second.key, first.key);
669 }
670}