svw — Terminal Waveform Viewer

What is svw?

svw is an interactive digital waveform viewer that runs entirely in your terminal. Point it at a simulation dump and debug right where you already work — over SSH, inside CI containers, or next to your editor — with the same focused workflow.

Open VCD, EVCD and FST waveforms without extra setup. Read digital and real-valued signals clearly, then move through the design with familiar commands, search, markers and shortcuts.

User-controlled FSDB bridge

FSDB commands are always available, while access to a local reader remains entirely under the user's control. The svw download contains neither a reader SDK nor a bridge dynamic library.

⊘

No bundled reader

svw neither links nor searches for reader libraries. Distribution gates reject reader dependencies, symbols, paths, runtime search paths and packaged libraries.

⇥

Explicit activation

The user builds the open bridge and its loader host locally, then selects the library's absolute path with SVW_FSDB_BRIDGE. There is no FSDB build switch.

◇

Isolated, bounded protocol

Only the isolated native host loads the selected bridge and resolves its single versioned C ABI. The fully static main process exchanges bounded, read-only typed waveform records with it.

export SVW_FSDB_BRIDGE=/absolute/path/to/libsvw-wave-bridge.so
svw wave.fsdb

Why svw?

▤

Pure terminal

Work naturally in local shells, SSH sessions and containers. Crisp waveform graphics, responsive interaction, mouse controls and colors adapt smoothly to the terminal at hand.

◇

Vim-style UI

Modal keymaps, a : command line, a fuzzy signal picker with live waveform preview, and a discoverable leader menu keep common actions close at hand.

⌘

User-owned Tcl UI

Load an explicit out-of-process Tcl plugin to add retained widgets, rearrange the native frame, or take over the complete TUI through a bounded, versioned API.

🤖

Headless for AI agents

Use repeatable command workflows, focused JSON/TUI queries and connected agent sessions. Pi Agent integration is included with the installation.

≋

Compare & analyze

Diff two dumps on an exact shared timeline, generate switching activity, value, transaction and assertion reports, and load UCIS coverage — all without leaving the terminal.

In practice

Start with two built-in svw workflows: waveform comparison and active-driver analysis. The third shows how an explicitly loaded protocol plugin extends svw for project-specific checks.

Built-in waveform comparison

The passing and failing dumps disagree. Where did they diverge?

Two simulations can contain the same hierarchy and thousands of transitions, making side-by-side visual comparison slow and easy to misread.

Result: compare both dumps on one exact timeline, report value and structural differences, mark the first mismatch, and jump between later mismatches without a plugin.

Built-in design debug

The value is wrong. Which assignment actually drove it?

A net may have several static drivers, generate branches, or mux conditions. Reading every candidate in source does not tell you which one was active at the failing cycle.

Result: use svw's built-in active-driver analysis to evaluate the selected time, narrow the candidate assignments, and open source-backed evidence for the driving path.

Plugin extension

The transfer timed out. Which cycle broke the contract?

This example explicitly loads a Tcl plugin to extend svw with project-specific protocol rules. A timeout says that progress stopped, but not whether valid, ready, payload, or a sideband failed first.

Result: identify the first violating cycle—payload changing while stalled or valid dropping before a handshake—retain accepted transfers, then jump to the exact evidence.

Protocol checking is the plugin extension here; compare and active-driver are native svw commands. See the plugin workflow and the command tutorial for exact inputs.

Download & install

Install the latest svw release with one command. Currently supported: macOS (Apple silicon) and Linux (x86_64).

SUPPORTED macOS (Apple silicon)Linux (x86_64) $ curl --proto '=https' --tlsv1.2 -LsSf https://svw.run/install.sh | sh

Then open any waveform:

svw wave.vcd        # or wave.fst — format auto-detected
svw --headless wave.vcd < script.svwcmd   # scriptable, CI-friendly

The installation also includes agent workflows, configuration examples and the Pi Agent integration.

For the clearest display, use a modern monospaced terminal font with broad symbol coverage. The recordings use the same recommended setup.

Made for agents, not just humans

svw treats AI coding assistants as first-class users. They can inspect waveform context and return concise JSON or visual TUI evidence for review.

# one-shot JSON or TUI evidence, composable from any shell
svw agent wave.fst info
svw agent wave.fst signals clk 10
svw agent wave.fst render 0 200 top.clk top.state --color ansi --view wave

# connected agent session
svw mcp wave.fst

Agents can search signals, inspect values and changes, compare results and return bounded evidence. Pi Agent integration adds a full-color waveform view alongside the result — see the AI agents page.

Documentation

Two tracks, depending on who is driving the terminal.

☰

For humans

The command tutorial documents every : command — signals, markers, zoom, search, expressions, virtual buses, coverage, simulator control — each with a copy-pasteable snippet and a recorded terminal demo played in the browser.

Open the command tutorial

🤖

For AI agents

The agent guide covers the scriptable --headless mode and the svw agent one-shot JSON/TUI query CLI — the interfaces intended for coding agents and automated jobs.

Open the agent guide