Facts verified against RouteWave 2.4.0 and rr 5.1.1 on 2026-10-30.

rr sim run runs a cocotb test and writes the wave. rr sim waves opens that wave in RouteWave. A testbench marks points in simulation time with rr_mark; RouteWave lists them as anchors, and a click on an anchor moves the cursor to its time.

rr sim run writes the wave, the anchor sidecar and the source map; rr sim waves opens them in RouteWave
Files written by rr sim run and read by RouteWave

Requirements

ItemValue
RouteRTL SDKrr 5.1.1
RouteWave2.4.0, started by rr sim waves
Simulatornvc for the source map; the anchors do not depend on the simulator
Testcocotb test under simulation.test_dir of project.yml

The example is an 8-bit pulse counter, pulse_counter, with one test file, sim/cocotb/tests/test_pulse_counter.py.

Testbench markers

rr_mark(label) stores the label with the current simulation time in nanoseconds. emit_ltmeta(dut, wave_path) writes the stored anchors to <wave>.ltmeta.json beside the wave. In rr 5.1.1 the test calls emit_ltmeta itself; without that call no anchor reaches the sidecar.

from pathlib import Path

import cocotb
from cocotb.clock import Clock
from cocotb.triggers import ClockCycles, Timer

import engine.simulation
from sdk.engine.ltmeta import emit_ltmeta
from sdk.engine.ltsync import rr_mark

WAVE = Path(__file__).parents[2] / "waves" / Path(__file__).stem / "pulse_counter.fst"


@cocotb.test()
async def test_burst(dut):
    cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
    dut.rst.value = 1
    dut.pulse_in.value = 0
    await ClockCycles(dut.clk, 4)
    dut.rst.value = 0
    rr_mark("reset released")

    await ClockCycles(dut.clk, 5)
    rr_mark("burst start")
    for _ in range(6):
        dut.pulse_in.value = 1
        await Timer(20, unit="ns")
        dut.pulse_in.value = 0
        await Timer(30, unit="ns")
    rr_mark("burst done")

    await ClockCycles(dut.clk, 3)
    emit_ltmeta(dut, WAVE)
    assert int(dut.count.value) == 6


if __name__ == "__main__":
    engine.simulation.run_simulation(top_level="pulse_counter", module=Path(__file__).stem)

WAVE is the path rr gives the wave of this test: sim/waves/<test module>/<top level>.fst.

Running the simulation

rr sim run test_pulse_counter --wait

--wait makes a queued run return the test's exit code. The run writes three files:

FileContentRead by
pulse_counter.fstSignal valuesRouteWave, on open
pulse_counter.ltmeta.jsonAnchors from rr_markRouteWave, on open
pulse_counter.srcmap.jsonSignal to RTL declaration (nvc only)whereis, sourcepeek, rr wave whereis

The anchors in pulse_counter.ltmeta.json from this test:

"anchors": [
  { "time_ns": 30, "label": "reset released" },
  { "time_ns": 80, "label": "burst start" },
  { "time_ns": 380, "label": "burst done" }
]

Opening the waves

rr sim waves sim/waves/test_pulse_counter/pulse_counter.fst --show clk,rst,pulse_in,cnt
PartEffect
Wave pathThe file to open. Without a path, the newest .fst, .vcd or .ghw under the wave directories.
--showComma-separated names or globs. rr checks them against the wave and passes them to RouteWave as -c "show clk; show rst; show pulse_in; show cnt". A pattern that matches no signal is reported; when none matches, RouteWave is not started.

rr starts RouteWave on the wave. RouteWave reads pulse_counter.ltmeta.json and lists the anchors under Mission Control > Anchors, collapsed by default. A click on an anchor row sets the cursor to the anchor time. When that time lies outside the view or within 10 % of its edges, the view is centred on it; the zoom stays.

RouteWave 2.4.0 opened by rr sim waves: the pulse counter wave, and Mission Control with three anchors from the testbench
RouteWave 2.4.0 started by rr sim waves. The click on the anchor 'burst start' set the cursor to 80 ns.

Items to confirm

ItemObservation
rr sim run <test> --view --show <patterns>Opens the wave after a passing single test through the same launcher as rr sim waves. Not run for this article.
Anchors without emit_ltmetaIn rr 5.1.1 no part of rr sim run writes the rr_mark anchors on its own; the explicit call above is needed.