ondas 1.0.2

Read-only, format-independent waveform analysis library
Documentation
#![doc = r#"
# Ondas

Ondas is a Rust library for reading waveform files and analyzing signal values.
Use it to browse a design's hierarchy, sample signals at a given time, or process
changes over a time range. The same API works across supported formats. The
library does not write or convert waveforms.

## Supported formats

A backend is the reader that opens a source and retrieves its recorded values.
Ondas uses one backend per opened waveform. Backend types, reader-specific
handles, native callbacks and format-local indices stay private.

| Format | Backend | Input | Availability |
|---|---|---|---|
| FST | `fst-lib` | Files and shared in-memory bytes | Included; uses `fst-reader` 0.17.0 |
| VCD | `vcd-native` | Files and shared in-memory bytes | Included; reads VCD directly without conversion |
| FSDB | `fsdb-lib` | Files only | Optional Cargo feature; requires a local FSDB Reader SDK |

Other formats have no reader in this release. The minimum supported Rust version
is 1.88. See [reader details](#reader-details) for format limits and FSDB setup.
In particular, the FST reader can panic on malformed input; it is not a hardened
parser for untrusted files.

## 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`] |
| Keep the state and changes over a range | [`Waveform::trace`], [`Waveform::traces`] or [`Selection::traces`] |
| 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 or batch query when you already know the observation time.
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. 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 and traces return no partial collection.

## 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.

- The reader preserves aliases, exact ranges, nine-state bits, real signed zero,
  strings and ordinary repeated events. Strings use reversible Latin-1 decoding,
  including escapes, NUL and padding. 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.

- String bytes map reversibly to Unicode U+0000 to U+00FF (Latin-1), including NULs
  and padding. The adapter does not guess whether a byte sequence is UTF-8.
- 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>

### 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 use reversible Latin-1. 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 diagnostics may appear on stdout/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>

## 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;

/// Errors and input kinds used by path, hierarchy, slicing, and waveform operations.
pub use error::{Error, InputKind, LookupError, PathError, PathFormatError, SliceError};
/// Types describing waveform hierarchy and queryable signals.
pub use hierarchy::{
    BitRange, Direction, Encoding, Enumeration, EnumerationVariant, Hierarchy, HierarchyPath, Item,
    LogicDomain, Packing, Scope, Signal, Signedness, Variable,
};
/// Owned and borrowed waveform query results.
pub use query::{Change, Initial, QueryContext, Sample, SampleRef, ScanRef, Selection, Trace};
/// Time values, ranges, spans, units, and scales.
pub use time::{Time, TimeRange, TimeSpan, TimeUnit, Timescale};
/// Owned and borrowed waveform signal values.
pub use value::{Bits, BitsRef, Logic, Value, ValueRef};
/// Waveform sources, metadata, formats, and opening functions.
pub use waveform::{
    Format, Metadata, Waveform, open, open_bytes, open_bytes_with, open_with, read_metadata,
};

/// A result returned by waveform opening and query operations.
pub type Result<T> = std::result::Result<T, Error>;