Crate rustdv_sim 

rustdv-sim

The cocotb-analog core (design-doc §4): a bespoke single-threaded executor driven by simulator callbacks (D4.1 — not tokio), the task model, the trigger inventory, typed signal handles with buffered writes, Clock, and sim-aware Event/Lock/Queue.

Control-flow contract (§4.1): a GPI/VPI callback fires → subscribed tasks are woken → the run queue is drained to exhaustion (Executor::run_until_idle) → control returns to the simulator.

Re-exports

pub use clock::Clock;

pub use combinators::first2;

pub use combinators::join2;

pub use combinators::join_all;

pub use combinators::with_timeout;

pub use combinators::Either;

pub use combinators::TimeoutError;

pub use executor::spawn;

pub use executor::spawn_named;

pub use executor::Executor;

pub use executor::TaskError;

pub use executor::TaskHandle;

pub use executor::TaskId;

pub use executor::TaskState;

pub use path::RustdvPath;

pub use handle::AnyHandle;

pub use handle::HierarchyHandle;

pub use handle::LogicHandle;

pub use phase::read_only;

pub use phase::read_write;

pub use phase::next_time_step;

pub use queue::Queue;

pub use rng::Rng;

pub use sync::Event;

pub use sync::Lock;

pub use sync::LockGuard;

pub use time::sim_time_ns;

pub use time::sim_time_steps;

pub use time::SimDuration;

pub use triggers::NullTrigger;

pub use triggers::Timer;

Modules

clock

Clock generator (port of cocotb Clock, mapping row 24).

combinators

Ports of First/Combine (design-doc mapping row 16): future combinators with drop-based cancellation of the losers — the cleanup cocotb does manually with kill-on-completion tasks falls out of RAII.

executor

The bespoke single-threaded executor (design-doc §4.2/§4.3).

handle

Typed DUT handles with scheduled-write semantics and edge methods — the user-facing layer over rustdv-gpi (design-doc mapping rows 14, 19–22). set() is buffered and applied at the next ReadWrite phase; set_now() is the immediate variant.

log

Sim-time-stamped logging in the book’s format: 2.00ns INFO ... (design-doc OQ-8: the tracing mapping is deferred; this minimal zero-dependency logger reproduces the output format the book teaches).

path

RustdvPath — a component’s position in the tree, as segments.

phase

Phase triggers (ReadOnly / ReadWrite / NextTimeStep) and the scheduled write buffer (design-doc §4.1(4), §4.4, mapping rows 15 & 22).

queue

Sim-aware FIFO queue (port of cocotb.queue.Queue, mapping row 18 — the foundation for TLM FIFOs, as in pyuvm).

rng

Tiny deterministic RNG (SplitMix64). Zero-dependency substitute for the rand crate; seeded by the runner from RUSTDV_RANDOM_SEED (port of cocotb’s RANDOM_SEED handling, design-doc D2.4).

sync

Sim-aware synchronization primitives: Event and FIFO-fair Lock (design-doc mapping row 17 — std/tokio primitives don’t know sim time).

testing

Running futures in a unit test, with no simulator.

time

Simulation time (design-doc §3.1: time as u64 steps + precision).

triggers

GPI-backed awaitables: Timer, edge triggers, NullTrigger (design-doc §4.4). Each future registers its simulator callback lazily on first poll and removes it via RAII when dropped — cancellation of a waiting task cleans up its trigger registration for free (§4.6).

Macros

first

first!(a, b, ...) — first completed future wins; losers are dropped.

join

join!(a, b, ...) — wait for all.

Structs

LogicArray

A fixed-width vector of 4-state bits, MSB first (binstr order).

Enums

HandleError

Logic

One 4-state bit.

ValueError

Functions

init

Initialize the sim context: install a fresh executor and phase hub on this thread. Called once by the runner at start-of-simulation.