Skip to main content

trueno/hardware/
mod.rs

1//! Hardware Capability Detection (PMAT-447)
2//!
3//! Detects CPU SIMD capabilities, GPU presence, and calculates
4//! theoretical peak performance for roofline analysis.
5//!
6//! Integrates with `pmat brick-score` for hardware-aware profiling.
7
8use serde::{Deserialize, Serialize};
9use std::fs;
10use std::path::Path;
11
12/// Get hostname (native only, returns "wasm" on WASM targets)
13#[cfg(not(target_arch = "wasm32"))]
14fn get_hostname() -> String {
15    hostname::get().map(|h| h.to_string_lossy().to_string()).unwrap_or_else(|e| {
16        eprintln!("warning: failed to get hostname: {e}");
17        "unknown".to_string()
18    })
19}
20
21/// Get hostname (WASM fallback)
22#[cfg(target_arch = "wasm32")]
23fn get_hostname() -> String {
24    "wasm".to_string()
25}
26
27/// SIMD instruction set width
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
29pub enum SimdWidth {
30    /// No SIMD (scalar)
31    Scalar,
32    /// ARM NEON (128-bit, 4×f32)
33    Neon128,
34    /// SSE2 (128-bit, 4×f32)
35    Sse2,
36    /// AVX2 (256-bit, 8×f32)
37    Avx2,
38    /// AVX-512 (512-bit, 16×f32)
39    Avx512,
40    /// WebAssembly SIMD (128-bit, 4×f32)
41    WasmSimd128,
42}
43
44impl SimdWidth {
45    /// Number of f32 lanes
46    pub fn lanes(&self) -> usize {
47        match self {
48            SimdWidth::Scalar => 1,
49            SimdWidth::Neon128 | SimdWidth::Sse2 | SimdWidth::WasmSimd128 => 4,
50            SimdWidth::Avx2 => 8,
51            SimdWidth::Avx512 => 16,
52        }
53    }
54
55    /// Bit width
56    pub fn bits(&self) -> usize {
57        self.lanes() * 32
58    }
59
60    /// Typical speedup factor for compute-bound operations
61    pub fn compute_speedup(&self) -> f64 {
62        match self {
63            SimdWidth::Scalar => 1.0,
64            SimdWidth::Neon128 | SimdWidth::Sse2 | SimdWidth::WasmSimd128 => 4.0,
65            SimdWidth::Avx2 => 10.0,   // 8-12x measured in trueno-zram
66            SimdWidth::Avx512 => 12.0, // 8-13x measured
67        }
68    }
69}
70
71/// GPU compute backend
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
73pub enum GpuBackend {
74    /// No GPU available
75    None,
76    /// NVIDIA CUDA
77    Cuda,
78    /// WebGPU (cross-platform)
79    Wgpu,
80    /// Apple Metal
81    Metal,
82    /// Vulkan compute
83    Vulkan,
84}
85
86/// CPU capabilities
87#[derive(Debug, Clone, Serialize, Deserialize)]
88pub struct CpuCapability {
89    /// CPU vendor (Intel, AMD, Apple, etc.)
90    pub vendor: String,
91    /// CPU model name
92    pub model: String,
93    /// Number of physical cores
94    pub cores: usize,
95    /// Number of logical threads
96    pub threads: usize,
97    /// Best available SIMD width
98    pub simd: SimdWidth,
99    /// Base frequency in GHz
100    pub base_freq_ghz: f64,
101    /// Theoretical peak GFLOP/s (FMA)
102    pub peak_gflops: f64,
103    /// Memory bandwidth in GB/s (estimated)
104    pub memory_bw_gbps: f64,
105}
106
107/// GPU capabilities
108#[derive(Debug, Clone, Serialize, Deserialize)]
109pub struct GpuCapability {
110    /// GPU vendor
111    pub vendor: String,
112    /// GPU model name
113    pub model: String,
114    /// Compute backend
115    pub backend: GpuBackend,
116    /// CUDA compute capability (e.g., "8.9" for RTX 4090)
117    pub compute_capability: Option<String>,
118    /// Peak FP32 TFLOP/s
119    pub peak_tflops_fp32: f64,
120    /// Peak Tensor Core TFLOP/s (NVIDIA only)
121    pub peak_tflops_tensor: Option<f64>,
122    /// Memory bandwidth in GB/s
123    pub memory_bw_gbps: f64,
124    /// VRAM in GB
125    pub vram_gb: f64,
126}
127
128/// Complete hardware capability profile
129#[derive(Debug, Clone, Serialize, Deserialize)]
130pub struct HardwareCapability {
131    /// Detection timestamp
132    pub timestamp: String,
133    /// Hostname
134    pub hostname: String,
135    /// CPU capabilities
136    pub cpu: CpuCapability,
137    /// GPU capabilities (if present)
138    pub gpu: Option<GpuCapability>,
139    /// Roofline model parameters
140    pub roofline: RooflineParams,
141    /// PMAT-452: Byte budget configuration for compression/I/O workloads
142    #[serde(default)]
143    pub byte_budget: Option<crate::brick::ByteBudget>,
144}
145
146/// Roofline model parameters
147#[derive(Debug, Clone, Serialize, Deserialize)]
148pub struct RooflineParams {
149    /// CPU arithmetic intensity threshold (GFLOP/s ÷ GB/s)
150    pub cpu_arithmetic_intensity: f64,
151    /// GPU arithmetic intensity threshold
152    pub gpu_arithmetic_intensity: Option<f64>,
153}
154
155/// Format a UTC instant as RFC 3339, byte-identical to the former
156/// `chrono::Utc::now().to_rfc3339()` (`YYYY-MM-DDTHH:MM:SS[.fff[fff[fff]]]+00:00`,
157/// fractional digits only as needed in groups of 3; PMAT-7195 dropped chrono).
158fn format_rfc3339_utc(secs: i64, nanos: u32) -> String {
159    let days = secs.div_euclid(86_400);
160    let tod = secs.rem_euclid(86_400);
161    // Civil-from-days (Howard Hinnant), proleptic Gregorian.
162    let z = days + 719_468;
163    let era = z.div_euclid(146_097);
164    let doe = z.rem_euclid(146_097);
165    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
166    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
167    let mp = (5 * doy + 2) / 153;
168    let d = doy - (153 * mp + 2) / 5 + 1;
169    let m = if mp < 10 { mp + 3 } else { mp - 9 };
170    let y = yoe + era * 400 + i64::from(m <= 2);
171    let frac = if nanos == 0 {
172        String::new()
173    } else if nanos % 1_000_000 == 0 {
174        format!(".{:03}", nanos / 1_000_000)
175    } else if nanos % 1_000 == 0 {
176        format!(".{:06}", nanos / 1_000)
177    } else {
178        format!(".{nanos:09}")
179    };
180    format!(
181        "{y:04}-{m:02}-{d:02}T{:02}:{:02}:{:02}{frac}+00:00",
182        tod / 3_600,
183        tod % 3_600 / 60,
184        tod % 60
185    )
186}
187
188/// Current UTC time as RFC 3339.
189fn now_rfc3339() -> String {
190    let d = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap_or_default();
191    format_rfc3339_utc(d.as_secs() as i64, d.subsec_nanos())
192}
193
194impl HardwareCapability {
195    /// Detect hardware capabilities at runtime
196    pub fn detect() -> Self {
197        let cpu = detect_cpu();
198        let gpu = detect_gpu();
199
200        let cpu_ai = cpu.peak_gflops / cpu.memory_bw_gbps;
201        let gpu_ai = gpu.as_ref().map(|g| g.peak_tflops_fp32 * 1000.0 / g.memory_bw_gbps);
202        // PMAT-452: Extract memory bandwidth before moving cpu
203        let byte_budget_throughput = cpu.memory_bw_gbps.min(25.0);
204
205        HardwareCapability {
206            timestamp: now_rfc3339(),
207            hostname: get_hostname(),
208            cpu,
209            gpu,
210            roofline: RooflineParams {
211                cpu_arithmetic_intensity: cpu_ai,
212                gpu_arithmetic_intensity: gpu_ai,
213            },
214            // PMAT-452: Default byte budget based on memory bandwidth
215            byte_budget: Some(crate::brick::ByteBudget::from_throughput(byte_budget_throughput)),
216        }
217    }
218
219    /// Load from TOML file or detect if missing
220    pub fn load_or_detect(path: &Path) -> Self {
221        if path.exists() {
222            if let Ok(content) = fs::read_to_string(path) {
223                if let Ok(cap) = toml::from_str(&content) {
224                    return cap;
225                }
226            }
227        }
228        let cap = Self::detect();
229        // Try to cache it
230        let _ = cap.save(path);
231        cap
232    }
233
234    /// Save to TOML file
235    pub fn save(&self, path: &Path) -> std::io::Result<()> {
236        if let Some(parent) = path.parent() {
237            fs::create_dir_all(parent)?;
238        }
239        let content = toml::to_string_pretty(self)
240            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
241        fs::write(path, content)
242    }
243
244    /// Get the best available backend for a workload
245    pub fn best_backend(&self) -> GpuBackend {
246        self.gpu.as_ref().map(|g| g.backend).unwrap_or(GpuBackend::None)
247    }
248
249    /// Calculate expected throughput for a brick given its arithmetic intensity
250    pub fn expected_throughput_gflops(&self, arithmetic_intensity: f64, use_gpu: bool) -> f64 {
251        if use_gpu {
252            if let Some(gpu) = &self.gpu {
253                let memory_bound = gpu.memory_bw_gbps * arithmetic_intensity;
254                let compute_bound = gpu.peak_tflops_fp32 * 1000.0;
255                memory_bound.min(compute_bound)
256            } else {
257                self.cpu_expected_throughput(arithmetic_intensity)
258            }
259        } else {
260            self.cpu_expected_throughput(arithmetic_intensity)
261        }
262    }
263
264    fn cpu_expected_throughput(&self, arithmetic_intensity: f64) -> f64 {
265        let memory_bound = self.cpu.memory_bw_gbps * arithmetic_intensity;
266        let compute_bound = self.cpu.peak_gflops;
267        memory_bound.min(compute_bound)
268    }
269
270    /// Determine if workload is memory-bound or compute-bound
271    pub fn bottleneck(&self, arithmetic_intensity: f64, use_gpu: bool) -> Bottleneck {
272        let threshold = if use_gpu {
273            self.roofline.gpu_arithmetic_intensity.unwrap_or(f64::MAX)
274        } else {
275            self.roofline.cpu_arithmetic_intensity
276        };
277
278        if arithmetic_intensity < threshold {
279            Bottleneck::Memory
280        } else {
281            Bottleneck::Compute
282        }
283    }
284}
285
286/// Workload bottleneck classification
287#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
288pub enum Bottleneck {
289    /// Limited by memory bandwidth
290    Memory,
291    /// Limited by compute throughput
292    Compute,
293}
294
295/// Map a raw x86 `vendor_id` to a human-readable vendor name.
296fn normalize_cpu_vendor(raw: &str) -> String {
297    match raw.trim() {
298        "GenuineIntel" => "Intel".to_string(),
299        "AuthenticAMD" => "AMD".to_string(),
300        "" => "Unknown".to_string(),
301        other => other.to_string(),
302    }
303}
304
305/// Parse `(vendor, model)` out of `/proc/cpuinfo` contents.
306///
307/// GH-2395: `detect_cpu` hardcoded `vendor: "Unknown", model: "Unknown"`, so the
308/// roofline block of `apr profile` reported `Hardware: Unknown Unknown (24 cores, …)`
309/// while the peak GFLOPS and bandwidth printed beside it — the basis for the
310/// MEMORY BOUND verdict — claimed to describe that machine.
311///
312/// Split out from the filesystem read so it is testable without `/proc`. Handles
313/// the x86 layout (`vendor_id` / `model name`) and the aarch64 layout
314/// (`CPU implementer` / `Model`, with no `model name` on many kernels).
315pub fn parse_cpuinfo(contents: &str) -> (Option<String>, Option<String>) {
316    let mut vendor = None;
317    let mut model = None;
318    for line in contents.lines() {
319        let Some((key, value)) = line.split_once(':') else {
320            continue;
321        };
322        let key = key.trim();
323        let value = value.trim();
324        if value.is_empty() {
325            continue;
326        }
327        match key {
328            "vendor_id" if vendor.is_none() => vendor = Some(normalize_cpu_vendor(value)),
329            "model name" | "Model" if model.is_none() => model = Some(value.to_string()),
330            // aarch64 has no vendor_id; implementer 0x41 is ARM Ltd.
331            "CPU implementer" if vendor.is_none() => {
332                vendor = Some(match value {
333                    "0x41" => "ARM".to_string(),
334                    "0x51" => "Qualcomm".to_string(),
335                    "0x4e" => "NVIDIA".to_string(),
336                    other => other.to_string(),
337                });
338            }
339            _ => {}
340        }
341    }
342    (vendor, model)
343}
344
345/// Read CPU vendor/model from the OS, falling back to `"Unknown"`.
346fn detect_cpu_identity() -> (String, String) {
347    #[cfg(target_os = "linux")]
348    {
349        if let Ok(contents) = fs::read_to_string("/proc/cpuinfo") {
350            let (vendor, model) = parse_cpuinfo(&contents);
351            return (
352                vendor.unwrap_or_else(|| "Unknown".to_string()),
353                model.unwrap_or_else(|| "Unknown".to_string()),
354            );
355        }
356    }
357    ("Unknown".to_string(), "Unknown".to_string())
358}
359
360/// Detect CPU capabilities
361fn detect_cpu() -> CpuCapability {
362    let simd = detect_simd();
363    let cores = num_cpus::get_physical();
364    let threads = num_cpus::get();
365    let (vendor, model) = detect_cpu_identity();
366
367    // Estimate frequency (fallback to 3.0 GHz if unknown)
368    let base_freq_ghz = 3.0;
369
370    // Calculate peak GFLOP/s: cores × lanes × 2 (FMA) × freq
371    let peak_gflops = (cores as f64) * (simd.lanes() as f64) * 2.0 * base_freq_ghz;
372
373    // Estimate memory bandwidth (DDR5-5600 dual channel ≈ 89.6 GB/s)
374    let memory_bw_gbps = 80.0; // Conservative estimate
375
376    CpuCapability {
377        vendor,
378        model,
379        cores,
380        threads,
381        simd,
382        base_freq_ghz,
383        peak_gflops,
384        memory_bw_gbps,
385    }
386}
387
388/// Detect best available SIMD width
389fn detect_simd() -> SimdWidth {
390    #[cfg(target_arch = "x86_64")]
391    {
392        if is_x86_feature_detected!("avx512f") {
393            return SimdWidth::Avx512;
394        }
395        if is_x86_feature_detected!("avx2") {
396            return SimdWidth::Avx2;
397        }
398        if is_x86_feature_detected!("sse2") {
399            return SimdWidth::Sse2;
400        }
401    }
402
403    #[cfg(target_arch = "aarch64")]
404    {
405        // NEON is always available on aarch64
406        SimdWidth::Neon128
407    }
408
409    #[cfg(target_arch = "wasm32")]
410    {
411        SimdWidth::WasmSimd128
412    }
413
414    #[cfg(not(any(target_arch = "aarch64", target_arch = "wasm32")))]
415    {
416        SimdWidth::Scalar
417    }
418}
419
420/// Detect GPU capabilities
421fn detect_gpu() -> Option<GpuCapability> {
422    // Check for CUDA first (highest performance)
423    #[cfg(feature = "cuda")]
424    {
425        if let Some(gpu) = detect_cuda_gpu() {
426            return Some(gpu);
427        }
428    }
429
430    // Fallback: no GPU detected
431    None
432}
433
434#[cfg(feature = "cuda")]
435fn detect_cuda_gpu() -> Option<GpuCapability> {
436    // This would use cuDeviceGetAttribute in a real implementation
437    // For now, return None and let the caller provide GPU info
438    None
439}
440
441/// Default hardware.toml path
442pub fn default_hardware_path() -> std::path::PathBuf {
443    #[cfg(feature = "hardware-detect")]
444    {
445        dirs::home_dir()
446            .unwrap_or_else(|| std::path::PathBuf::from("."))
447            .join(".pmat")
448            .join("hardware.toml")
449    }
450    #[cfg(not(feature = "hardware-detect"))]
451    {
452        std::path::PathBuf::from(".pmat").join("hardware.toml")
453    }
454}
455
456#[cfg(test)]
457mod tests;