Merge pull request #3154 from veryl-lang/pr/10-report-effective-engine

feat(simulator): report the engine a run actually used as degraded_modules

Author: dalance

crates/simulator/src/ir.rs

@@ -40,12 +40,14 @@ pub use variable::{
 pub use veryl_analyzer::ir::{Op, Type, VarId, VarPath};
 pub use veryl_analyzer::value::Value;
 
-use crate::HashMap;
 use crate::backend::{self, BackendRegistry, CompiledWhole, DispatchOutcome};
+use crate::residency;
 use crate::simulator::SimProfile;
 use crate::simulator_error::SimulatorError;
-use std::sync::Arc;
-use std::sync::OnceLock;
+use crate::{HashMap, HashSet};
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, OnceLock};
 
 use veryl_analyzer::ir as air;
 use veryl_analyzer::value::MaskCache;
@@ -126,15 +128,19 @@ pub struct Ir {
     /// Base directory for component file I/O (the project root). Relative
     /// reads resolve against it; relative writes go to a per-test output
     /// directory beneath it. `None` leaves paths process-CWD relative.
-    pub component_file_base: Option<std::path::PathBuf>,
+    pub component_file_base: Option<PathBuf>,
     /// See `Module::rtl_driven`.
-    pub rtl_driven: crate::HashSet<VarId>,
+    pub rtl_driven: HashSet<VarId>,
+    /// A failed compile leaves the cell empty forever, so the fallback is
+    /// taken every cycle; the residency table (a mutex) must be touched once.
+    whole_comb_fallback_recorded: AtomicBool,
+    pub(crate) whole_event_fallback_recorded: AtomicBool,
 }
 
 /// A built component library on disk and the type name to look up in it.
 #[derive(Clone, Debug)]
 pub struct ComponentLibrary {
-    pub path: std::path::PathBuf,
+    pub path: PathBuf,
     pub type_name: String,
 }
 
@@ -172,6 +178,8 @@ impl Ir {
             component_libraries: config.component_libraries.clone(),
             component_file_base: config.component_file_base.clone(),
             rtl_driven: module.rtl_driven,
+            whole_comb_fallback_recorded: Default::default(),
+            whole_event_fallback_recorded: Default::default(),
         };
         // Bake the WriteLogBuffer's heap-stable address into every
         // JIT-dispatched Compiled/CompiledBatch so emitted code can perform
@@ -373,7 +381,13 @@ impl Ir {
                         DispatchOutcome::Done => {}
                         DispatchOutcome::NotReady => {
                             // Async compile not finished yet — drop to
-                            // Cranelift for this cycle.
+                            // Cranelift for this cycle (see `residency`).
+                            if !self
+                                .whole_comb_fallback_recorded
+                                .swap(true, Ordering::Relaxed)
+                            {
+                                residency::record_fallback("whole_comb", &self.name.to_string());
+                            }
                             self.run_chunked_settle(mask_cache, profile);
                             return;
                         }
@@ -680,7 +694,7 @@ pub struct Config {
     /// name. Missing entries fall back to the static registry.
     pub component_libraries: std::collections::HashMap<String, ComponentLibrary>,
     /// See `Ir::component_file_base`.
-    pub component_file_base: Option<std::path::PathBuf>,
+    pub component_file_base: Option<PathBuf>,
 }
 
 impl Config {

crates/simulator/src/lib.rs

@@ -5,6 +5,7 @@ pub mod file_table;
 pub mod ir;
 pub mod output_buffer;
 pub mod random_table;
+pub mod residency;
 pub mod simulator;
 pub mod simulator_error;
 pub mod testbench;

crates/simulator/src/residency.rs

@@ -0,0 +1,58 @@
+//! Which engine a run actually used, as opposed to the one it asked for.
+//!
+//! A whole-comb / whole-event handle exists as soon as the emit is accepted,
+//! but its artifact lands asynchronously (`cc` runs off the critical path).
+//! Until then every dispatch returns `NotReady` and the module falls back to
+//! the per-chunk path — correct, but a different engine, and `--format json`
+//! names the *requested* backend, so a run can report `cc` while timing the
+//! fallback.  What is recorded here surfaces as its `degraded_modules`.
+//!
+//! A module that never had an artifact to wait for (emit declined, below the
+//! AOT size threshold) holds no whole-* handle, so nothing is recorded for it.
+
+use crate::HashSet;
+use std::sync::{Mutex, OnceLock};
+
+fn seen() -> &'static Mutex<HashSet<String>> {
+    static SEEN: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+    SEEN.get_or_init(|| Mutex::new(HashSet::default()))
+}
+
+/// `kind` is the dispatch site (`"whole_comb"` / `"whole_event"`).  Repeats
+/// collapse to one entry per (kind, module).
+pub fn record_fallback(kind: &str, module: &str) {
+    let Ok(mut seen) = seen().lock() else { return };
+    seen.insert(format!("{kind}:{module}"));
+}
+
+/// Every `kind:module` that fell back, sorted.  Empty means the run used the
+/// engine it asked for throughout.
+pub fn degraded_modules() -> Vec<String> {
+    let Ok(seen) = seen().lock() else {
+        return Vec::new();
+    };
+    let mut out: Vec<String> = seen.iter().cloned().collect();
+    out.sort();
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fallbacks_are_recorded_once_and_sorted() {
+        record_fallback("whole_comb", "resid_test_b");
+        record_fallback("whole_event", "resid_test_a");
+        record_fallback("whole_comb", "resid_test_b");
+        let listed: Vec<String> = degraded_modules()
+            .into_iter()
+            .filter(|s| s.contains("resid_test_"))
+            .collect();
+        assert_eq!(
+            listed,
+            ["whole_comb:resid_test_b", "whole_event:resid_test_a"],
+            "one entry per (kind, module), sorted"
+        );
+    }
+}

crates/simulator/src/simulator.rs

@@ -1,4 +1,4 @@
-use crate::backend::CompiledWhole;
+use crate::backend::{CompiledWhole, DispatchOutcome};
 use crate::component::loader::ComponentError;
 use crate::component::runtime::{RuntimeComponent, build_components};
 use crate::ir::write_log::{
@@ -8,11 +8,15 @@ use crate::ir::{
     Event, Ir, ModuleVariables, Statement, Value, VarId, VarPath, dispatch_stmt_fast,
     read_native_value, write_native_value,
 };
+use crate::residency;
 use crate::wave_dumper::{DumpVar, WaveDumper};
 use smallvec::SmallVec;
 use std::collections::{BTreeSet, HashMap};
 use std::str::FromStr;
 use std::sync::Arc;
+use std::sync::atomic::Ordering;
+#[cfg(feature = "profile")]
+use std::time::Instant;
 use veryl_analyzer::value::MaskCache;
 
 #[cfg(feature = "profile")]
@@ -455,7 +459,7 @@ impl Simulator {
     pub fn ensure_comb_updated(&mut self) {
         if self.comb_dirty {
             #[cfg(feature = "profile")]
-            let start = std::time::Instant::now();
+            let start = Instant::now();
 
             self.do_settle_comb();
             self.comb_dirty = false;
@@ -514,7 +518,7 @@ impl Simulator {
 
         if self.comb_dirty {
             #[cfg(feature = "profile")]
-            let start = std::time::Instant::now();
+            let start = Instant::now();
 
             self.do_settle_comb();
             self.comb_dirty = false;
@@ -690,7 +694,7 @@ impl Simulator {
     /// one pre-commit state and one commit.
     fn eval_event_stmts(&mut self, event: &Event) {
         #[cfg(feature = "profile")]
-        let event_start = std::time::Instant::now();
+        let event_start = Instant::now();
 
         // Cache both the per-stmt list AND the whole-event AOT-C handle for
         // the current event, keyed on `last_event`.  `event_statements` and
@@ -719,7 +723,6 @@ impl Simulator {
         // current values and pushes WriteLogEntries into the buffer
         // (3rd arg), exactly as the Cranelift event JIT does;
         // `ff_commit_from_log` below applies them.
-        use crate::backend::DispatchOutcome;
         let dispatched = if let Some(wptr) = whole_event_ptr {
             // SAFETY: `wptr` = `Arc::as_ptr` of an `Arc` owned by
             // `self.ir.whole_events`, which is never mutated after `Ir`
@@ -734,10 +737,21 @@ impl Simulator {
             let validate = self.ir.aot_c_validate;
 
             if !validate {
-                matches!(
-                    whole.try_dispatch(ff_ptr, comb_ptr, log_ptr),
-                    DispatchOutcome::Done,
-                )
+                match whole.try_dispatch(ff_ptr, comb_ptr, log_ptr) {
+                    DispatchOutcome::Done => true,
+                    DispatchOutcome::NotReady => {
+                        // `false` degrades to the per-stmt path below
+                        // (see `residency`).
+                        if !self
+                            .ir
+                            .whole_event_fallback_recorded
+                            .swap(true, Ordering::Relaxed)
+                        {
+                            residency::record_fallback("whole_event", &self.ir.name.to_string());
+                        }
+                        false
+                    }
+                }
             } else {
                 // For validate, the wrapper compares the whole-event
                 // dispatch against the per-stmt Cranelift path and panics
@@ -768,7 +782,7 @@ impl Simulator {
     /// Apply the accumulated write log to FF storage and reset the buffer.
     fn commit_event_log(&mut self) {
         #[cfg(feature = "profile")]
-        let ff_start = std::time::Instant::now();
+        let ff_start = Instant::now();
 
         ff_commit_from_log(&mut self.ir.ff_values, &self.ir.write_log_buffer);
 
@@ -1019,7 +1033,7 @@ impl Simulator {
         // Whole-event backend, then capture its pushed entries + ff/comb.
         if matches!(
             whole.try_dispatch(ff_ptr, comb_ptr, log_ptr),
-            crate::backend::DispatchOutcome::NotReady,
+            DispatchOutcome::NotReady,
         ) {
             return false;
         }

crates/veryl/src/cmd_test.rs

@@ -32,7 +32,13 @@ fn random_seed() -> u64 {
 struct TestSuiteReport {
     /// Bump on any breaking change to the report shape.
     format_version: u32,
+    /// The backend that was asked for; see `degraded_modules` for what ran.
     backend: String,
+    /// `kind:module` for every module that fell back, empty when the run used
+    /// `backend` throughout.  A timing comparison is only meaningful when this
+    /// is empty in both arms.
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    degraded_modules: Vec<String>,
     passed: i32,
     failed: i32,
     ignored: usize,
@@ -684,6 +690,7 @@ impl CmdTest {
             let report = TestSuiteReport {
                 format_version: 1,
                 backend: backend_name.to_string(),
+                degraded_modules: veryl_simulator::residency::degraded_modules(),
                 passed: success,
                 failed: failure,
                 ignored: ignored_count,