Metadata-Version: 2.4
Name: vcd-tools
Version: 0.2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Summary: Fast VCD analysis tools with reusable queries and native Unix server mode
Keywords: vcd,eda,simulation,waveform,hardware
Author-email: Ronan Barzic <rbarzic@gmail.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/rbarzic/vcd_tools_rs/issues
Project-URL: Homepage, https://github.com/rbarzic/vcd_tools_rs
Project-URL: Repository, https://github.com/rbarzic/vcd_tools_rs

# vcd_tools_rs

Fast streaming VCD (Value Change Dump) analysis tool and Python library, written in Rust.

Provides commands to list signals, query metadata, extract time/value pairs, count toggles, search for value occurrences, and diff two VCD files — all with a memory-efficient streaming parser.

## FST implementation status

First-class FST support is being developed on the `fst-support` branch. The current implementation foundation includes:

- the pure-Rust `fst-reader` 0.17 backend dependency;
- content-based VCD/FST format detection through the Rust API;
- explicit format assertions and deterministic mismatch errors;
- parser-panic containment, bounded error text, an 8 GiB detection limit, and rejection of whole-file gzip-wrapped FST;
- a reproducible generated FST fixture with a committed semantic oracle.

The existing CLI, Python functions, server, comparison engine, and `OpenedVcd` remain VCD-only at this stage. Do not assume that a released `vcd_tools_rs` binary accepts FST merely because the Rust detection API is present. User-facing FST support will be documented when the `OpenedFst` and `OpenedWaveform` query backends are implemented.

Current additive Rust API:

```rust
use vcd_tools_rs::{detect_waveform_format, WaveformFormatHint};

let format = detect_waveform_format("simulation.fst", WaveformFormatHint::Auto)?;
println!("{format}"); // "fst" or "vcd"
```

Detection uses file contents, not the extension. It classifies and validates the input at detection time; a later consumer must still open and validate its own file generation. See [`FST_PLAN.md`](FST_PLAN.md) and the [FST architecture](docs/design/fst-support-architecture.md) for implementation status and supported-subset decisions.

## Installation

### Option 1: pip (Python users)

Installs the `vcd_tools_rs` command and the `vcd_tools` Python module:

```sh
pip install vcd-tools
```

The `vcd_tools_rs` CLI is backed by the compiled Rust extension, so performance is equivalent to the native binary.

### Option 2: Precompiled binaries

Download for your platform from [GitHub Releases](https://github.com/rbarzic/vcd_tools_rs/releases):

| Platform | Archive |
|----------|---------|
| Linux x64 | `vcd_tools_rs-vX.X.X-x86_64-unknown-linux-gnu.tar.gz` |
| Linux ARM64 | `vcd_tools_rs-vX.X.X-aarch64-unknown-linux-gnu.tar.gz` |
| macOS Intel | `vcd_tools_rs-vX.X.X-x86_64-apple-darwin.tar.gz` |
| macOS Apple Silicon | `vcd_tools_rs-vX.X.X-aarch64-apple-darwin.tar.gz` |
| Windows x64 | `vcd_tools_rs-vX.X.X-x86_64-pc-windows-msvc.zip` |

```sh
tar xzf vcd_tools_rs-vX.X.X-x86_64-unknown-linux-gnu.tar.gz
./vcd_tools_rs --help
```

### Option 3: Build from source

```sh
cargo build --release
# optional: install into ~/.cargo/bin
cargo install --path .
```

---

## CLI usage

```sh
# List signals (optional substring filter)
vcd_tools_rs list simulation.vcd [--filter clk]

# File metadata (signal count, timescale, time bounds)
vcd_tools_rs meta simulation.vcd [--pretty]

# Extract time/value pairs for selected signals
vcd_tools_rs extract simulation.vcd \
  --signal "tb.clk" --signal "tb.rst_n" \
  --start 0 --end 1000000 \
  [--signals-file signals.txt] [--pretty]

# Count value transitions per signal
vcd_tools_rs toggle simulation.vcd \
  --signal "tb.clk" --signal "tb.counter[7:0]" \
  [--start 0 --end 500000]

# Find the Nth occurrence of a signal value
vcd_tools_rs find simulation.vcd \
  --signal "tb.clk" --value 1 --occurrence 3

# Compare two VCD files
vcd_tools_rs compare reference.vcd actual.vcd \
  [--max-mismatches 10] [--ignore-unknown] [--output json|compact]

# Experimental local query server (Unix native build or Unix PyPI wheel)
mkdir -m 700 /tmp/vcd-tools-$USER
vcd_tools_rs serve simulation.vcd \
  --socket /tmp/vcd-tools-$USER/server.sock
```

Global flags: `--pretty` (table output), `--log-level` (`error`/`warn`/`info`/`debug`).

### Experimental server availability

Server mode is available from native Unix builds, Linux/macOS release archives, and Unix PyPI wheels. It binds one VCD to an owner-only Unix-domain socket and supports `ping`, `describe`, `list`, `metadata`, `extract`, `find`, `toggles`, and `cancel` using protocol v1 JSON Lines.

After `pip install vcd-tools`, the same command is available on Unix:

```sh
mkdir -m 700 /tmp/vcd-tools-$USER
vcd_tools_rs serve simulation.vcd --socket /tmp/vcd-tools-$USER/server.sock
```

The socket parent directory must already exist, be owned by the current user, and have no group/other permissions. Windows does not expose this Unix socket mode.

See [the protocol contract](docs/design/unix-json-protocol-v1.md) for request schemas and limits.

See [CLI_REFERENCE.md](CLI_REFERENCE.md) for the complete option reference.

### Signals file

One signal name per line. Lines starting with `#` and inline `#` comments are ignored:

```text
# signals.txt
tb.U_CHIP.counter[7:0]
tb.U_CHIP.enable
tb.clk          # clock signal
```

---

## Python API

After `pip install vcd-tools`:

```python
import vcd_tools

# List signals
signals = vcd_tools.list_signals("simulation.vcd")
signals = vcd_tools.list_signals("simulation.vcd", filter="clk")

# Metadata
meta = vcd_tools.metadata("simulation.vcd")
# → {"signal_count": 42, "timescale": "1 ns", "start_time": 0, "end_time": 1000000}

# Extract time/value pairs
values = vcd_tools.extract("simulation.vcd",
                           signals=["tb.clk", "tb.rst_n"],
                           start=0, end=500000)
# → [{"signal": "tb.clk", "time": 0, "value": "0"}, ...]

# Count toggles
counts = vcd_tools.toggles("simulation.vcd", signals=["tb.clk"])
# → {"tb.clk": 500}

# Find Nth occurrence of a value
result = vcd_tools.find("simulation.vcd",
                        signal="tb.clk", value="1", occurrence=3)
# → {"found": True, "signal": "tb.clk", "time": 30, "value": "1"}

# Compare two VCD files
diff = vcd_tools.compare("reference.vcd", "actual.vcd",
                         max_mismatches=10, ignore_unknown=True)
# → {"passed": False, "total_mismatches": 3,
#    "mismatches": [{"signal": ..., "time": ..., "value1": ..., "value2": ...}], ...}
```

All functions raise `RuntimeError` on VCD parse errors or missing signals.

---

## vcd2trace (RISC-V trace extraction)

`vcd2trace` recreates a RISC-V architectural trace from a VCD file (Aldebaran-style format).

```sh
# Default signal paths
vcd2trace simulation.vcd --output trace.txt

# Override paths via JSON
vcd2trace simulation.vcd \
  --signal-path examples/signal_paths.json \
  --output trace.txt
```

See [CLI_REFERENCE.md](CLI_REFERENCE.md#vcd2trace) for the full signal path reference.

---

## Tests

```sh
cargo test
```

Tests use `tests/waveform.vcd` as the reference fixture.

## Notes

- Large VCDs are streamed from disk; header scope names are sanitized to tolerate special characters.
- Release builds (`cargo build --release`) provide the best performance (~6× faster than Python VCD parsers in local measurements).
- The pip-installed `vcd_tools_rs` command is a Python entry point backed by the same compiled Rust code; there is no performance difference vs. the native binary.

