Struct Simulator 

pub struct Simulator<B: SimBackend = DefaultBackend> { /* private fields */ }

The core logic evaluation engine.

Encapsulates the backend, the original SIR program, and an optional VCD writer. Provides low-level, event-driven control.

The default type parameter B = DefaultBackend means that bare Simulator uses the custom native backend on a matching host and Cranelift for cross-codegen builds or unsupported hosts.

Implementations

impl<B: SimBackend> Simulator<B>

pub fn with_backend_and_program( backend: B, program: RuntimeProgram, warnings: Vec<CompilationWarning>, ) -> Self

pub fn drain_runtime_events(&mut self) -> Vec<RuntimeEvent>

pub fn drain_runtime_events_with_context( &mut self, ctx: RuntimeFormatContext<'_>, ) -> Vec<RuntimeEvent>

pub fn runtime_event_drain(&mut self) -> Option<RuntimeEventDrain>

pub fn program(&self) -> &RuntimeProgram

Returns a reference to the compiled SIR program.

pub fn backend_ref(&self) -> &B

Returns a reference to the backend (for signal/event resolution).

pub fn warnings(&self) -> &[CompilationWarning]

Returns warnings emitted during compilation.

pub fn dump(&mut self, timestamp: u64)

Captures the current state of all signals and writes them to the VCD file.

pub fn set<T: Copy>(&mut self, signal: SignalRef, val: T)

Sets a signal value and marks combinational logic as dirty.

pub fn set_wide(&mut self, signal: SignalRef, val: BigUint)

Sets a wide signal value and marks combinational logic as dirty.

pub fn set_four_state(&mut self, signal: SignalRef, val: BigUint, mask: BigUint)

Sets a four-state signal value and marks combinational logic as dirty.

pub fn modify<F>(&mut self, f: F) -> Result<(), RuntimeErrorCode>

where F: FnOnce(&mut IOContext<'_, B>),

Modifies internal state via a callback and marks combinational logic as dirty.

pub fn tick(&mut self, event: B::Event) -> Result<(), RuntimeErrorCode>

Manually triggers a clock or event to process sequential logic.

pub fn signal(&self, path: &str) -> SignalRef

Resolves a signal path into a performance-optimized SignalRef. This handle allows for direct memory access without HashMap lookups.

pub fn event(&self, port: &str) -> B::Event

Resolve a port name to an event handle.

pub fn try_signal(&self, path: &str) -> Result<SignalRef, AddrLookupError>

Try to resolve a signal path. Returns Err if the path is not found or ambiguous.

pub fn try_event(&self, port: &str) -> Result<B::Event, AddrLookupError>

Try to resolve a port name to an event handle.

pub fn get_as<T: Default + Copy>(&mut self, signal: SignalRef) -> T

Retrieves the current value as a fixed-size type without BigUint allocation. Lazily evaluates combinational logic if the state is dirty.

pub fn get(&mut self, signal: SignalRef) -> BigUint

Retrieves the current value of a variable using a pre-resolved SignalRef handle. Lazily evaluates combinational logic if the state is dirty.

pub fn get_four_state(&mut self, signal: SignalRef) -> (BigUint, BigUint)

Retrieves the current 4-state value (value, mask) of a variable using a SignalRef handle. Lazily evaluates combinational logic if the state is dirty.

pub fn eval_comb(&mut self) -> Result<(), RuntimeErrorCode>

Directly execute combinational logic evaluation.

pub fn memory_as_ptr(&self) -> (*const u8, usize)

Returns a raw pointer to the backend memory and its total size in bytes.

pub fn memory_as_mut_ptr(&mut self) -> (*mut u8, usize)

Returns a mutable raw pointer to the backend memory and its total size in bytes.

pub fn stable_region_size(&self) -> usize

Returns the stable region size in bytes.

pub fn layout(&self) -> &MemoryLayout

Returns a reference to the memory layout.

pub fn take_vcd_writer(&mut self) -> Option<VcdWriter>

Take ownership of the VCD writer, if one was configured at build time.

Builders create the writer themselves so that layout selection can account for VCD recording; callers building handles around a backend use this to keep tracing alive without rebuilding descriptors.

pub fn build_vcd_descs(&self, four_state_mode: bool) -> Vec<VcdSignalDesc>

Build VCD signal descriptors for all instances.

The returned descriptors are self-contained (no IR references) and can be cached alongside SharedJitCode so that VCD works on cache-hit paths without the original RuntimeProgram.

pub fn named_signals(&self) -> Vec<NamedSignal>

Returns all ports of the top-level module with their resolved signal references.

pub fn instance_signals( &self, instance_path: &[(&str, usize)], ) -> Vec<NamedSignal>

Returns all signals for the instance at the given hierarchical path.

The path is specified as a slice of (instance_name, index) pairs. Returns an empty Vec if the path does not exist.

pub fn named_events(&self) -> Vec<NamedEvent<B>>

Returns all events (clock/reset signals) with their IDs and event references.

pub fn tick_by_id(&mut self, event_id: usize) -> Result<(), RuntimeErrorCode>

Triggers a clock/event by its numeric ID.

Errors

Returns RuntimeErrorCode::NotAnEvent if event_id is not a known event ID, or a runtime error if evaluating the event fails.

pub fn tick_by_id_n( &mut self, event_id: usize, count: u32, ) -> Result<(), RuntimeErrorCode>

Triggers a clock/event N times by its numeric ID. Avoids repeated cross-boundary calls when used from FFI. The event ID is validated even when count is zero.

Errors

Returns RuntimeErrorCode::NotAnEvent if event_id is not a known event ID, or a runtime error if evaluating an event fails.

pub fn child_signal( &self, instance_path: &[(&str, usize)], var: &str, ) -> SignalRef

Resolves a signal inside a child instance.

pub fn try_child_signal( &self, instance_path: &[(&str, usize)], var: &str, ) -> Result<SignalRef, AddrLookupError>

Try to resolve a signal inside a child instance.

pub fn named_hierarchy(&self) -> InstanceHierarchy

Returns the full instance hierarchy starting from the top module.

impl Simulator

pub fn builder<'a>( code: &'a str, top: &'a str, ) -> SimulatorBuilder<'a, Simulator>

pub fn from_sources<'a>( sources: Vec<(&'a str, &'a Path)>, top: &'a str, ) -> SimulatorBuilder<'a, Simulator>

pub fn from_frontend( artifact: FrontendArtifact, ) -> SimulatorBuilder<'static, Simulator>

Low-level adapter hook for an elaborated external frontend artifact.

Frontend crates should wrap this with a constructor named for their own artifact type instead of exposing celox_frontend_sdk::FrontendArtifact to applications.

pub fn from_frontend_with_testbench<'a>( artifact: FrontendArtifact, sources: Vec<(&'a str, &'a Path)>, top: &'a str, ) -> SimulatorBuilder<'a, Simulator>

Low-level adapter hook for a Veryl testbench around an external module.

impl Simulator<JitBackend>

pub fn shared_code(&self) -> Arc<SharedJitCode>

Returns the shared compiled JIT code, allowing it to be reused for creating additional simulator instances without recompilation.

pub fn into_backend(self) -> JitBackend

Consume the simulator and return the inner JIT backend.

impl Simulator<WasmBackend>

pub fn into_backend(self) -> WasmBackend

Consume the simulator and return the inner Wasmtime backend.

impl Simulator<TieredBackend>

pub fn is_compiled(&self) -> bool

Whether this tiered simulation has adopted its compiled tier.

False while background compilation is still running or after it failed (the interpreter then remains the permanent tier).

pub fn tiered_execution_stats(&self) -> TieredExecutionStats

Return deterministic tier lifecycle and evaluation measurements.

The snapshot contains counts rather than ad-hoc wall-clock samples; use a statistical benchmark harness to measure elapsed time.

pub fn start_tiered_execution_timing(&mut self)

Start opt-in wall-clock measurement from workload execution to promotion. Ordinary tiered simulation does not read the host clock.

pub fn finish_tiered_execution_timing( &mut self, ) -> Option<TieredExecutionTiming>

Stop tiered execution timing and return the promotion interval.

pub fn promotion_error(&self) -> Option<&SimulatorError>

Why promotion has not happened yet, for diagnostics.

pub fn cancel_background_compilation(&mut self) -> bool

Request cancellation of background compilation.

The simulation stays on the interpreter permanently and Simulator::promotion_error reports the cancellation. Returns whether a background compilation was still pending.

pub fn into_backend(self) -> TieredBackend

Consume the simulator and return the inner tiered backend.

impl Simulator<NativeBackend>

pub fn shared_code(&self) -> Arc<SharedNativeCode>

Returns the shared compiled native code, allowing it to be reused for creating additional simulator instances without recompilation.

pub fn start_native_execution_timing(&mut self)

Start measuring time spent inside generated native simulator functions.

The measurement is disabled by default, so ordinary simulation does not read the host clock. Native tick loops are measured once per host-side batch rather than once per simulated tick.

pub fn finish_native_execution_timing( &mut self, ) -> Option<NativeExecutionTiming>

Stop native execution timing and return the accumulated measurement.

pub fn from_shared(shared: Arc<SharedNativeCode>, program: OptimizedSir) -> Self

Create a simulator from pre-compiled shared native code.

pub fn into_backend(self) -> NativeBackend

Consume the simulator and return the inner native backend.

Trait Implementations

impl<B: SimBackend> Debug for Simulator<B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B: SimBackend> SimulationExecutor for Simulator<B>

type Backend = B

fn backend(&self) -> &B

fn backend_mut(&mut self) -> &mut B

fn eval_comb(&mut self) -> Result<(), RuntimeErrorCode>

fn eval_apply_ff_at(&mut self, event: B::Event) -> Result<(), RuntimeErrorCode>

fn eval_only_ff_at(&mut self, event: B::Event) -> Result<(), RuntimeErrorCode>

fn apply_ff_at(&mut self, event: B::Event) -> Result<(), RuntimeErrorCode>

fn stage_external_event( &mut self, event: B::Event, _timestamp: u64, ) -> Result<(), RuntimeErrorCode>

Snapshot external-component inputs immediately before an event domain evaluates its sequential logic.

fn fire_external_event( &mut self, event: B::Event, timestamp: u64, ) -> Result<(), RuntimeErrorCode>

Fire external-component hooks after the event domain commits and before the following combinational settle.

fn finish_timed_step(&mut self, timestamp: u64)

Called after the state for a simulation timestamp has stabilized.