# for format limits and native reader setup.
In particular, the FST reader can panic on malformed input; it is not a hardened
parser for untrusted files.
### SHM setup
Enable `shm-lib` and set `XCELIUM_HOME` to the selected Xcelium installation when
building on Linux x86_64 GNU. Building requires a C++17 compiler, binutils and
zlib development files. The selected library must remain at its build-time path.
Use a compatible reader from Xcelium (2021+).
Readers with an ELF `SONAME` also require explicit runtime lookup, for example
through `LD_LIBRARY_PATH`. Use a directory with a symlink to the selected
`libsst2.so` to avoid selecting an older bundled C++ runtime.
SHM input is a complete database directory. Byte input is unsupported. The
adapter reads the latest matching recording across its TRN components.
It preserves bits, real values, ASCII strings and event observations.
Confirmed aliases share a handle. If the reader does not provide
alias identity, each declaration has a separate handle. Qualified bit-only points
can seek values after certifying their availability. Other histories traverse
their prefixes to establish state, then deliver completed ticks in bounded batches.
Ondas retains one pending tick per selected history and at most 1024 batch records
(64 in the first batch). Each batch stops at 64 KiB of retained payload capacity; one value can cross that
threshold. Same-tick state writes are folded and events are counted. `Break`
releases these buffers after that bounded read-ahead. Value sizes and SDK
histories have separate memory costs. Validated entering states can bound later
window traversal.
Recording gaps and invalid strings return
errors. Keep the directory and its components unchanged and available.
```no_run
# #[cfg(feature = "shm-lib")]
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut wave = ondas::open_with("waveform.shm", "shm-lib")?;
let signal = wave.hierarchy().signal("top.ready")?;
let sample = wave.sample(signal, ondas::Time::from_ticks(10))?;
# Ok(())
# }
```
### WDB setup
Enable `wdb-lib` and set `XILINX_VIVADO` to the selected installation when building
on Linux x86_64 GNU. Building requires a C++17 compiler and binutils. At runtime,
set `RDI_DATADIR` to that installation's `data` directory and make its
`lib/lnx64.o` libraries and their dependencies available to the dynamic loader.
The application must use a compatible system C++ runtime. The build selects the
installed `rdi` or `xv` reader libraries without a separate setting. A confirmed
newer embedded DBG format returns [`Error::UnsupportedFeature`].
First access to selected stored bytes builds their SDK history indexes, including
times after the query end. Every waveform drop releases those indexes. A native owner
may outlive the logical session and keep its imported declarations, so a later
logical open of the same unchanged file reuses them without importing again; its
histories are built again on first access. A point or early stop can therefore pay the
full selected-history loading cost in a reuse hit. One closed owner may wait, keeping
the native reader descriptor and the copied declarations. When the reader kernel
provides the storage cleanup entry point, the drop also releases the temporary SDK
backing storage before the owner waits; without it, the owner is closed instead of
retained, so a later open imports again. A different path, a metadata-only request or
a failed identity destroys it, and a normal exit destroys it best-effort while the SDK
and owner locks are uncontended.
Later bit points and range reads with an established entering state can seek.
This includes compositions whose intermediate values are whole copies of one
source, joined or sliced at source-width boundaries. Other compositions can
still traverse a prefix to establish their change times.
Proving `changed_at` for a constant slice can still require many predecessor reads.
A packed `logic` or `reg` array whose storage the adapter qualifies decodes from its two stored
planes instead of the vendor formatter. A slice of one such array compares only the stored bits it
depends on when the whole extent is recorded from tick zero; other layouts keep the previous paths.
The adapter uses a private reader ABI. Build-time symbol checks do not qualify
other reader layouts. Keep the source file unchanged and available. The reader
libraries must remain at their build-time paths. A different loaded installation
is rejected before opening a native session. The reader provides bits, binary64
real values, native enum tables and static one-dimensional VHDL CHARACTER arrays
as strings. Strings preserve ASCII NUL; non-ASCII contents return
[`Error::NonAsciiString`]. Dynamic SystemVerilog String and named Event values
have no qualified read path and return [`Error::UnsupportedSignal`] when selected.
This does not establish whether those values are present in an existing recording.
Changing unsigned 129-bit enum values are also unqualified: a tested A-to-B-to-C
sequence is read as A throughout. These histories can return stale values instead
of an error. The cause remains unresolved between recording and reading. Successful
constant values and enum tables do not qualify changing unsigned 129-bit values.
Reads preserve the common completed-tick semantics. Vendor calls are serialized; user callbacks run
after the lock is released.
Opening a WDB file imports every native declaration and usually costs more than another format
containing only logged declarations. Every ordinary open hashes the whole file as part of the reuse
identity, a cold open included. A sequential reopen of an unchanged file then reuses one validated
owner instead of importing again: it repeats the container and reader guards and creates a fresh
hierarchy identity, so handles from the earlier open are rejected. Only one closed owner waits; a
different path, a metadata-only request or a failed identity destroys it. A native or decode error,
or an unwind through the backend while it reads native state, makes that reader's owner unparkable
until it is dropped, without affecting another idle owner. A panic in a late callback over results
that the backend already completed does not by itself prevent the owner from being reused. A live
reader keeps its own native indexes until it is dropped or parked. A concurrent writer is not
promised an atomic snapshot.
```no_run
# #[cfg(feature = "wdb-lib")]
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut wave = ondas::open_with("waveform.wdb", "wdb-lib")?;
let signal = wave.hierarchy().signal("top.ready")?;
let sample = wave.sample(signal, ondas::Time::from_ticks(10))?;
# Ok(())
# }
```
## How the API fits together
Open a source, resolve its signals, then query their values. The public types
are available directly under `ondas`, for example `ondas::Waveform`; the source
modules are private.
| Type | What it represents |
|---|---|
| [`Waveform`] | An open source with its [`Metadata`], hierarchy and query interface. |
| [`Hierarchy`] | Immutable declarations. [`Scope`] groups declarations. [`Variable`] describes one declaration. |
| [`Signal`] | A handle to a signal's history, optionally sliced to fixed bit positions. Aliased declarations can share a signal. |
| [`Selection`] | An ordered signal list reused across queries. It mutably borrows its waveform and preserves order and duplicates. |
| [`Sample`], [`Trace`] | Owned query results: an observation at one tick, or state and changes over a range. |
| [`SampleRef`], [`ScanRef`], [`ValueRef`] | Borrowed views. Callback views cannot escape their callback. Use [`ValueRef::to_owned`] when a value must be retained. |
Use [`open`] or [`open_bytes`] for automatic backend selection. Use [`open_with`]
or [`open_bytes_with`] to select a backend explicitly, without fallback.
[`read_metadata`] returns owned file metadata without a waveform or hierarchy.
[`Format`] describes source contents, not the reader implementation.
## Read a signal
This example opens a small VCD from memory, resolves `ready` by name and samples
it. The first recorded value is at tick 5, so the earlier sample has no known
state. It runs without an external waveform file.
```rust
use ondas::{Encoding, Sample, Time};
# fn main() -> Result<(), Box<dyn std::error::Error>> {
let data = b"$var wire 1 ! ready $end $enddefinitions $end #5 1!";
let mut wave = ondas::open_bytes_with("tiny.vcd", data.as_slice().into(), "vcd-native")?;
let ready = wave.hierarchy().signal("ready")?;
assert_eq!(ready.encoding(), Encoding::Bits { width: 1 });
assert!(matches!(wave.sample(ready, Time::from_ticks(4))?, Sample::Missing { .. }));
assert!(matches!(wave.sample(ready, Time::from_ticks(5))?, Sample::Value { .. }));
# Ok(())
# }
```
For a file, start with `ondas::open("dump.fst")?` instead. The [`Waveform`] example
also shows escaped hierarchy names, a bit slice and a trace over a bounded range.
File-based examples use `no_run` because they require the named signals.
[`HierarchyPath`] represents exact names and escaping. [`Hierarchy::signal`]
first looks up an exact variable path, then considers one trailing `[msb:lsb]`
slice if exact lookup fails. To separate name lookup from slicing, use [`Hierarchy::signal_path`]
followed by [`Signal::slice`]. Slice indices are normalized value positions,
not HDL indices.
## Choose a query
| Task | Operation |
|---|---|
| Read one signal at one tick | [`Waveform::sample`] |
| Read several signals at one tick | [`Waveform::samples`] or [`Selection::samples`] |
| Read signals at specified ticks | [`Waveform::samples_at`] or [`Selection::samples_at`] |
| Keep the state and changes over a range | [`Waveform::trace`], [`Waveform::traces`] or [`Selection::traces`] |
| Read a saved window at specified ticks | [`Trace::sample`] or [`Trace::samples_at`] |
| Process changes without collecting a trace | [`Selection::scan`] or [`Selection::scan_each`] |
| Visit possible change times | [`Selection::scan_candidate_times`] |
| Check conditions at activity ticks and read only the requested samples | [`Selection::query`] |
Use a point read when you know one observation tick. Use an explicit-time batch
for several ticks, including quiet ticks. It preserves time and selection order,
including duplicates. A saved trace can answer repeated reads without source access;
outside its coverage, sampling returns [`Error::TraceCoverage`].
Use a selection for repeated queries over the same signal list.
For streamed output, [`Selection::scan_each`] identifies each record by its
position in the selection. Its example exports a bus, an alias and two slices,
then stops early.
For conditional sampling, [`Selection::query`] separates driver signals, which
determine candidate times, from the other signals the caller may read. Each
[`QueryContext`] can read its completed tick and the preceding tick. It cannot
read arbitrary history. Its example checks a transition and control value before copying a
payload. Selected data may fail decoding before the condition matches, including
a query with no matches. Write conditions in ordinary Rust code. The query does not collect a
candidate list or require another waveform borrow inside a callback.
## Time, values and errors
- [`Time`] counts absolute source ticks, not indices into a backend time table.
Ranges include both bounds. A reversed bounded range is empty and returns no error.
- A point sample reports the final persistent state at its tick. Delta cycles
are not modeled. [`Sample::Missing`] means no persistent state is known at or
before the requested time.
- An event sample counts reader-observed occurrences at exactly that tick,
including zero. Scans and traces carry one positive total count per selection
entry and tick. These counts cannot recover omitted events or show occurrence
order within a tick.
- A scan separates state strictly before the range from changes inside it.
Candidate-time scans include all change times in strictly increasing order.
They can include extra times. Initial states and repeated events at one tick
do not add candidate times. See
[`Selection::scan`] and [`Selection::scan_candidate_times`] for the full contracts.
- [`PathError`], [`PathFormatError`], [`LookupError`] and [`SliceError`] describe
path and metadata resolution errors. Opening and query failures use [`Error`].
Reader failures return errors. Empty results do not represent failures.
- Scans and callback queries may have delivered observations before a later
failure. Owned samples, explicit-time batches and traces return no partial collection.
A callback break stops further delivery and returns its payload. It does not
limit work already done by the reader or SDK.
## Reader details
### VCD
<details>
<summary>Validation, value representation and event limits</summary>
`vcd-native` validates the source with a full sequential pass when opening, then
replays selected signals for queries. It does not store full value histories.
Source files must remain unchanged while open.
A chunked file opening can retain a bounded index of validated record positions.
A late point or prefix decodes indexed records and proves change times from
earlier records. A sparse selection can read those records in tick order, with
the byte offset as the consumed boundary and one bounded source window. Dense
selections, unsupported encodings and records above the indexed working state
keep the walk, which still supports them. Candidate-time scans can visit
indexed base activity as the documented superset. It keeps the chronological
replay when a proof or a resource bound is insufficient. The index stores no
values, source bytes or query state, and other inputs retain no index.
- The reader preserves aliases, exact ranges, nine-state bits, real signed zero,
strings and ordinary repeated events. Strings decode escapes and retain ASCII,
including NUL and padding. Non-ASCII values return [`Error::NonAsciiString`].
A real declaration with string records is
classified as string storage before signal handles are returned.
- Persistent dump-block records apply at their recorded tick. Event records in
`$dumpvars`, `$dumpall`, `$dumpoff` and `$dumpon` are snapshots, not occurrences.
Mixed checkpoint/event ticks do not establish physical multiplicity. Resume
records establish observed state, not the physical time of hidden changes.
- Unknown significant commands, incompatible aliases and malformed records fail
opening. EVCD strength records and nonzero timezero are unsupported.
</details>
### FST
<details>
<summary>Reader behavior, declaration metadata and query costs</summary>
`fst-lib` is a direct, unmodified adapter to `fst-reader` 0.17.0. It reads bits,
reals, strings and event callbacks, preserving aliases and explicit source ranges.
- Strings preserve ASCII bytes, including NUL and padding. Non-ASCII bytes return
[`Error::NonAsciiString`], whether or not they form valid UTF-8.
- Enum keys are exposed only when they match the whole stored bit width and logic
states. Keys use [`BitsRef`], as queried bit values do. Labels retain the
published decoder spelling; escaped label text can
remain escaped. The adapter does not guess a missing mapping.
- Explicit FST SystemVerilog types can supply [`Variable::logic_domain`]. Explicit
VHDL type attributes can also supply [`Variable::signedness`]. Legacy storage
kinds and type-name text do not establish either field. The current VCD and
FSDB adapters leave both fields unavailable.
- Some malformed inputs can make the underlying reader panic. Ondas does not
intercept those panics. Ordinary reader errors and detected hierarchy
inconsistencies return [`Error`].
- At the first recorded tick, event callbacks can include an initialization
snapshot that the reader cannot distinguish from occurrences. Ondas preserves
those callbacks. They do not establish exact physical event counts at that tick.
Selections reuse validated handles and base-signal grouping. They do not retain
complete value histories. Stateful queries traverse selected histories from their
beginning through their end to establish state. Scans retain entering and pending
final values per selected entry. They stop reader callbacks on `Break`. Owned
traces also retain their output. The decoder owns input and decompression buffers, so this is not a
fixed bound on total memory use. Candidate-time scans skip sections before their
window and avoid retaining values, but still decode and validate selected chains
without a separate activity index. Section frames and base activity may
produce extra candidates. These costs do not change observation semantics.
</details>
### GHW
`ghw-native` is a private Rust reader for uncompressed GHW versions 0 and 1.
It supports files and shared bytes. Opening validates the complete body to
establish the time span. [`read_metadata`] uses the same full opening path.
Source files must remain unchanged while open.
- Integer and physical scalars use signed 32- or 64-bit bits. Real values preserve
binary64 payloads and byte order. Explicit source markers establish two- or
nine-state logic domains. Enum labels keep their original ordinal encodings.
- One-dimensional integer-indexed bit and std_ulogic vectors are whole signals.
Other arrays and records become scopes with readable leaves. Null vectors keep
a declaration without a signal or range. Null arrays keep an empty scope.
- Exact names retain VHDL extended identifier delimiters. Ordered scalar recipes
establish whole alias identity. Type layouts and native IDs remain private.
- Opening can retain a bounded index of source payload positions. Small selections
read selected positions in tick order; broad selections and inputs that exceed
the index limit replay the source prefix. Queries assemble selected whole recipes.
A narrow slice still needs its whole vector. Values stay in the source; there is
no retained value history or query checkpoint. Callback termination stops before
the next tick's values.
- The wire does not encode time resolution. Ticks remain unchanged and
[`Metadata::timescale`] returns `None`. Compression containers and unknown
layouts are unsupported. Missing required nested array bounds are malformed.
Empty derived layouts have a checked limit of 1,000,000 scopes.
### FSDB
<details>
<summary>SDK setup, supported values and runtime requirements</summary>
Enable the additive Cargo feature `fsdb-lib` and set `VERDI_HOME` to a local
Verdi installation when building.
- Use Verdi 2021 or newer on Linux x86_64 GNU. Building requires a C++11 compiler,
binutils and zlib development files. Older SDKs can reject newer FSDB format
versions. Use a newer Reader for those files.
- Without the feature, Ondas does not discover an SDK and the backend name
`fsdb-lib` returns [`Error::UnknownBackend`].
- The backend opens files only. Explicit byte input returns
[`Error::UnsupportedInput`]; it creates no temporary file or conversion.
```no_run
# #[cfg(feature = "fsdb-lib")]
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut wave = ondas::open_with("dump.fsdb", "fsdb-lib")?;
let signal = wave.hierarchy().signal("tb.ready")?;
let sample = wave.sample(signal, ondas::Time::from_ticks(10))?;
# Ok(())
# }
```
Input files and the linked SDK installation must remain unchanged and available.
Binaries retain the build-time SDK library paths. Removing those libraries can
prevent the entire executable from starting, even for VCD/FST operations.
The executable cannot handle a missing runtime SDK gracefully.
- Known digital storage preserves bits and source logic states. Real storage maps
to `f64`. NUL-terminated strings preserve ASCII; other bytes return
[`Error::NonAsciiString`]. Embedded-NUL string data and transaction events
are unsupported.
- Normal HDL event records remain occurrences. No-change event initialization
markers are not triggers. Unknown event records and event queries on
SDK-reported dump-off files return errors. Callbacks describe recorded activity,
not physical event counts during initialization or disabled dumping.
- Unsupported SDK data types retain their declarations with [`Encoding::Unsupported`].
Integer ticks and scale factors remain exact. Floating timestamp formats are
rejected rather than rounded.
Independent Reader objects and serialized SDK calls preserve `Waveform: Send + Sync`.
The adapter releases the lock before calling Rust visitors. A callback can
query another waveform. Queries load selected histories. Cold bit-only bounded
queries can seek their entering state and traverse only the requested window. Other cold
queries traverse from the beginning. Records skipped by a seek are not decoded
or validated by the sequential adapter. Vendor loading has its own memory cost.
SDK messages to stdout are disabled for the process. Ondas does not suppress
stderr. To suppress SDK diagnostics, run reads in a separate process and redirect
its stderr.
C++ exceptions become backend errors. The adapter does not contain native
crashes or aborts. SDK permissions and runtime dependencies remain the caller's
responsibility. Ondas distributes no vendor files.
</details>
### WLF
<details>
<summary>SDK setup, supported values and runtime requirements</summary>
Enable Cargo feature `wlf-lib` and use a recent Questa SDK (2020 or newer) on
Linux x86-64 GNU. Set `QUESTA_HOME` to its installation directory when building.
The directory must contain `include/wlf_api.h` and `linux_x86_64/libwlf.so`.
Building requires a C11 compiler and binutils. Verify each selected SDK with
conformance and downstream checks.
SDK headers and vendor binaries are not distributed with Ondas. The compiled shim
is included in the Rust crate.
No separate Ondas shim shared library is required.
```no_run
# #[cfg(feature = "wlf-lib")]
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut wave = ondas::open_with("dump.wlf", "wlf-lib")?;
let clock = wave.hierarchy().signal("top.clock")?;
let sample = wave.sample(clock, ondas::Time::from_ticks(10))?;
# Ok(())
# }
```
The executable retains the SDK library's absolute path. Keep that installation
available at runtime. A missing library can prevent startup even for an
application that opens VCD or FST. Rebuild after moving or changing the SDK;
changing `QUESTA_HOME` after compilation does not switch the linked runtime.
SDK initialization failures after startup return [`Error::BackendUnavailable`].
Input is file-only. Bytes return [`Error::UnsupportedInput`]. Automatic WLF
detection uses the case-insensitive filename extension as a fallback, after
recognized FST/VCD contents. Without the feature, the `wlf-lib` name returns
[`Error::UnknownBackend`] and automatic WLF opening returns [`Error::NoBackend`].
Logic vectors preserve the represented nine-state domain. Native binary64 reals
preserve signed zeros and NaN payloads. Native SystemVerilog strings preserve
ASCII; other bytes return [`Error::NonAsciiString`]. Embedded-NUL contents are
not supported by the current formatter transport. Named events count recorded EVENT callbacks; logging notifications add no
occurrences. Writer collapse settings can remove activity before reading. Unsupported
value classes remain visible and return [`Error::UnsupportedSignal`]. Delayed
logging leaves state missing until its first record. Persistent values hold the
last recorded state over logging gaps and after EOF. This does not describe
unrecorded activity. Event counts do not persist.
SV enums expose full-width bit values and complete native tables through
[`Variable::enumeration`]. Keys preserve leading zeros, signed bit patterns and
X/Z, including variants never recorded in the history. Qualified scalar VHDL
logic types keep one bit. Other qualified VHDL enums use their native ordinal
storage width. SDK array elements are separate declarations; their array
container has no scalar signal. Type names and aggregate packing remain unknown
when the SDK does not establish them. An unavailable or incompatible enum table
stays absent and does not prevent otherwise supported bit queries. The private
SV descriptor layout needs qualification with each selected SDK.
One private worker owns SDK objects and calls on one thread. Rust visitors run
on the caller thread outside native callbacks. Independent waveforms can be
interleaved, moved between threads and queried from callbacks. Cold bit-only
points share a short range read. Unresolved change times use one chronological
pass over the remaining base signals. Cold bit-only windows can read entering
state and traverse only their requested range. Other cold queries read
from the recorded beginning. Records skipped by a seek are not decoded or
validated. Prepared selections can reuse one bounded normalized state snapshot.
The adapter keeps selected current values and counts, and transfers bounded
batches of completed ticks. It does not collect a full history. The SDK keeps its
own caches. It permits one resolution at a time. The worker releases native
query owners before a resolution switch or new header read. One lite namespace
owner stays alive to protect later opens from stale SDK state. SDK initialization
stays active for the process lifetime. A suspended query
reopens its file and replays from its query start, skipping its already returned
completed-tick slots. Logical sessions retain no SDK pointers.
The adapter releases file and query resources after errors, breaks and caller
panic. It does not contain vendor crashes or aborts. SDK diagnostics can appear
on stdout or stderr. Input files must remain unchanged and available.
</details>
## Scope of the library
The API does not model writing or conversion, live ingestion, transactions,
assertions, coverage, design connectivity, async operations, relative hierarchy
paths, dynamic or multidimensional projections, or an expression language. There
is no public backend trait or plugin ABI, global timestamp table, strategy
selection, query capability flags, or format-specific downcasting.
"#]
#![warn(missing_docs)]
#![deny(unsafe_code)]
mod backends;
mod error;
mod hierarchy;
mod query;
mod time;
mod value;
mod waveform;
#[cfg(all(test, feature = "fsdb-lib"))]
#[path = "../tests/support/fsdb_compatibility.rs"]
mod fsdb_compatibility;
pub use error::{
CompositionError, Error, InputKind, LookupError, PathError, PathFormatError, SliceError,
};
pub use hierarchy::{
BitRange, Direction, Encoding, Enumeration, EnumerationVariant, Hierarchy, HierarchyPath, Item,
LogicDomain, Packing, Scope, Signal, Signedness, Variable,
};
pub use query::{Change, Initial, QueryContext, Sample, SampleRef, ScanRef, Selection, Trace};
pub use time::{Time, TimeRange, TimeSpan, TimeUnit, Timescale};
pub use value::{Bits, BitsRef, Logic, Value, ValueRef};
pub use waveform::{
Format, Metadata, Waveform, open, open_bytes, open_bytes_with, open_with, read_metadata,
};
pub type Result<T> = std::result::Result<T, Error>;