Crate rustdv_gpi 

rustdv-gpi

Safe wrapper over the simulator programming interface (design-doc §3.3). Invariants upheld here so everything above is safe Rust:

1. Handles are opaque and non-null; fallible acquisition is Result.
2. Object-handle lifetime = simulation lifetime (freely Copyable IDs). Callback handles invalidate on removal/fire — modeled by RAII (CallbackHandle): dropping an unfired handle removes the callback.
3. Strings are copied at the boundary, every call.
4. No unwinding across FFI: every trampoline wraps the closure in catch_unwind; panics are routed to the panic sink.
5. Callback user-data ownership: an Rc whose C-side reference is reclaimed exactly once (on fire for one-shots, on removal otherwise).

Thread affinity (§3.4): all types here hold raw pointers and are therefore !Send/!Sync — the compiler rejects moving them off the simulator thread.

Re-exports

pub use value::Logic;

pub use value::LogicArray;

Modules

value

4-state value types: port of cocotb’s Logic/LogicArray (cocotb: types/, design-doc mapping row 23). Conversion failures are Results, not exceptions.

Structs

CallbackHandle

RAII callback registration. Dropping an unfired/live handle removes the simulator callback — this is what makes drop-based task cancellation (design-doc §4.6) clean up trigger registrations for free.

HierarchyHandle

A module/scope handle. Port of cocotb’s HierarchyObject (cocotb: handle.py), with Result-returning lookup (mapping row 19).

LogicHandle

A value-bearing signal handle (net/reg/var). Port of cocotb’s LogicObject surface: explicit get()/set() (mapping row 20). Buffered-write semantics live a layer up in rustdv-sim; the methods here apply values immediately.

ObjHandle

Raw non-null simulator object handle. Valid for the whole simulation (invariant 2), hence Copy. !Send because it wraps a raw pointer.

Enums

AnyHandle

Any simulator object, classified by type (design-doc §3.3 downcasting).

HandleError

ValueError

Functions

finish

End the simulation (vpi_control(vpiFinish)).

register_end_of_simulation

One-shot callback at end of simulation.

register_next_sim_time

One-shot callback at the next simulation time step.

register_read_only

One-shot callback at the next ReadOnly synch point.

register_read_write

One-shot callback at the next ReadWrite synch point.

register_start_of_simulation

One-shot callback at start of simulation (the bootstrap hook).

register_timer

One-shot callback after steps precision units (cbAfterDelay).

register_value_change

Recurring callback on any value change of sig (cbValueChange). The closure reads the signal itself; edge filtering happens in rustdv-sim.

set_panic_sink

Install the handler invoked when a callback closure panics (the runner routes this to “fail the current test”, mirroring cocotb catching BaseException per task).

sim_time_steps

Current simulation time in simulator precision steps.

time_precision

Simulator time precision as a power of ten (e.g. -9 = 1 ns).

top_module

The first top-level module (the DUT in single-top designs).

top_modules

All top-level modules in the design.