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.
Requirements
| Item | Value |
|---|---|
| RouteRTL SDK | rr 5.1.1 |
| RouteWave | 2.4.0, started by rr sim waves |
| Simulator | nvc for the source map; the anchors do not depend on the simulator |
| Test | cocotb 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:
| File | Content | Read by |
|---|---|---|
pulse_counter.fst | Signal values | RouteWave, on open |
pulse_counter.ltmeta.json | Anchors from rr_mark | RouteWave, on open |
pulse_counter.srcmap.json | Signal 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
| Part | Effect |
|---|---|
| Wave path | The file to open. Without a path, the newest .fst, .vcd or .ghw under the wave directories. |
--show | Comma-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.

Items to confirm
| Item | Observation |
|---|---|
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_ltmeta | In rr 5.1.1 no part of rr sim run writes the rr_mark anchors on its own; the explicit call above is needed. |