Skip to main content

Waveform Viewer

rb wave opens a test waveform in Surfer. With the RTL Buddy Surfer fork and the nvim plugin it also navigates to source, annotates signals with live values, and adds signals from the editor.

Install Surfer​

Mainline Surfer is enough to view FST and VCD files. Live editor annotation needs the rtl-buddy branch of the RTL Buddy Surfer fork:

git clone https://github.com/rtl-buddy/surfer.git ../surfer
cd ../surfer
git checkout rtl-buddy
cargo build --release

Put the binary on PATH or set its path in cfg-surfer.

Open a test waveform​

Run from a suite that contains tests.yaml:

uv run rb wave basic
uv run rb wave basic --resim

rb wave opens the newest supported FST or VCD under the test's artefacts. If none exists it first runs the test in debug mode; --resim always reruns the test. If basic.surfer exists beside tests.yaml, it is passed to Surfer as the initial signal layout.

Configure Surfer and the editor​

Add a named cfg-surfer entry to root_config.yaml and route it from the active platform:

cfg-platforms:
  - os: osx
    unames: [Darwin]
    builder: verilator
    surfer: surfer-default

cfg-surfer:
  - name: surfer-default
    path: ../surfer/target/release/surfer
    wcp-port: 0
    editor-cmd: nvim +%l %f
    editor-terminal: tmux
    editor-sock: ~/.local/share/rtl-buddy/wave-nvim.sock
    ctrl-sock: ~/.local/share/rtl-buddy/wave-ctrl.sock
  • %f and %l in editor-cmd expand to the source file and line.
  • wcp-port: 0 lets the OS pick a free port.
  • editor-sock enables nvim reuse and annotations.
  • ctrl-sock enables editor-to-Surfer actions.

With another editor, omit both sockets to get one-way source navigation. See YAML Formats for all fields.

Install the nvim integration​

rb nvim-install
rb nvim-install --update

This installs a compatible revision of rtl-buddy-nvim and writes an auto-loaded setup file, so init.lua needs no change. It needs Git and network access. For an offline checkout:

rb nvim-install --source /path/to/rtl-buddy-nvim --ref <branch>

--force replaces a broken install. In nvim, :checkhealth rtlbuddy verifies the hub, language-server and wave integration.

In Surfer, select a signal to set the active instance scope, then choose Go to declaration. The editor opens the declaration and annotates the signals in that scope with their values at the waveform cursor. Moving the cursor refreshes the annotations.

To annotate only the selected signal:

rb wave basic --focused-signal

With ctrl-sock set, put the nvim cursor on a signal and press <leader>wa to add it to Surfer. Select a Surfer signal first so the scope is unambiguous.

If the nvim socket is stale, the next navigation request starts a new editor. If the plugin is missing, rb wave warns and continues without annotations.

Open a formal counterexample​

uv run rb wave-fpv demo_fpv_counter_safety

rb wave-fpv reads fpv.yaml, finds the first counterexample trace under the verification's artefacts, and opens it in the configured Surfer entry. Use -c for another config and --surfer <name> to override the routing. There is no editor annotation, so mainline Surfer works.

It fails with a message if the verification has not run, passed without a counterexample, or produced no trace.

Use correct time units​

Three interfaces use three units. Convert between them; never pass a value across unchanged.

  • pywellen signal reads use waveform timescale ticks. Convert with Waveform.timescale.
  • Hub and WCP navigation, including rb hub send wave-cursor and wave-zoom, use femtoseconds.
  • Surfer command files use waveform ticks.

With a 10 ps waveform tick, 95 ns is 9,500 ticks and 95,000,000 fs.

Use the coordination hub​

When the hub is running, rb wave connects automatically. It shares cursor, scope, selection and waveform values with other peers and accepts hub requests to navigate and curate the displayed signals. Without a reachable hub, waveform viewing and editor annotation work standalone.