Skip to content

Quickstart

This page takes you from installation to your first wavepeek query.

Install

Install a prebuilt binary. Prebuilt binaries support only VCD/FST.

To install a specific version, see the instructions for the required release on Releases.

Otherwise, follow the instructions below to install the latest version.

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://kleverhq.github.io/wavepeek/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://kleverhq.github.io/wavepeek/install.ps1 | iex"

Cargo is also available as a fallback:

cargo install wavepeek

Or install from source (clone the repository first):

cargo install --path .

Install with FSDB

FSDB support is source-only and requires Linux x86_64 and the Synopsys Verdi FSDB Reader SDK. Before running the command below, set VERDI_HOME to a valid Verdi installation.

cargo install wavepeek --features fsdb

To check whether FSDB is enabled in the current binary, use --help:

$ wavepeek --help | grep FSDB
- FSDB - enabled

Install with SHM

SHM support requires Linux x86_64 GNU and a compatible Xcelium reader (2021 or later). Set XCELIUM_HOME to that installation before building:

cargo install wavepeek --features shm

Keep the selected installation available at runtime. If its libsst2.so has a SONAME, configure the dynamic loader to find the same library. For example:

mkdir -p "$HOME/.local/lib/wavepeek-shm"
ln -sfn "$XCELIUM_HOME/tools/lib/64bit/libsst2.so" "$HOME/.local/lib/wavepeek-shm/libsst2.so"
export LD_LIBRARY_PATH="$HOME/.local/lib/wavepeek-shm${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
wavepeek info --waves recording.shm

Use the complete SHM directory containing its .dsn and .trn files. --features fsdb,shm enables both optional readers. wavepeek --help reports which features are enabled. See Waveform formats for limits.

Setup skill

The wavepeek skill is bundled into the binary. Besides SKILL.md, it includes reference documentation, examples and helper scripts. To extract the skill bundle, use:

wavepeek skill <OUTPUT-DIRECTORY>

Alternatively, copy and paste this into your agent:

Check whether `wavepeek` is installed:

wavepeek --version

If that succeeds, run:

wavepeek skill ./wavepeek-skill

`wavepeek skill <DIRECTORY>` extracts the complete, version-matched skill package into a new or empty directory. Install the entire extracted package according to your agent harness's skill rules. Replace the older skill entirely if the extracted version is newer.

First run

Start with a waveform dump. Example dumps are available from Ondas fixtures. Follow its installation instructions to download and verify selected waveforms.

Check the dump bounds and time unit:

wavepeek info --waves your_waves.fst

Discover the hierarchy:

wavepeek scope --waves your_waves.fst --tree

Next steps

Learn concepts:

Get practical usage examples:

  • Explore dump - get dump bounds, navigate the hierarchy, and search signals.
  • Inspect values - sample values at explicit points and get a table of changes.
  • Evaluate properties - evaluate Boolean expressions and check whether a property holds.
  • Extract transfers - find transfers and get payload data under handshakes and valid/ready strobes.
  • Extract AMBA AXI - map signals, get a table of transfers, and use AXI profiles.
  • Extract AMBA AXI-Stream - map signals, get a table of transfers, and use AXI-Stream profiles.
  • Extract AMBA AHB - map signals, get a table of phase events, and use AHB profiles.
  • Extract AMBA APB - map signals, get a table of phase events, and use APB profiles.
  • Extract AMBA ATB - map signals, get a table of events, and use ATB profiles.