From 3b1a7a2fb3058601092927261d2c7ffa03894747 Mon Sep 17 00:00:00 2001 From: R0ck Date: Fri, 30 Oct 2026 17:37:00 +0000 Subject: [PATCH] Document the opt-in Renode lockstep and what it does and does not change. --- pages/emulation.md | 30 ++++++++++++++++++++++++++++++ pages/timing.md | 6 ++++++ 2 files changed, 36 insertions(+) diff --git a/pages/emulation.md b/pages/emulation.md index 7eedf58..6f8361c 100644 --- a/pages/emulation.md +++ b/pages/emulation.md @@ -252,6 +252,36 @@ produce the same result. Emulation is therefore used to verify that a release works, and [native firmware](native-vs-emulated.html) is used for anything that is measured. +### Lockstep under Renode + +An nRF52 board under Renode can instead be run from the engine's clock. It is +opt-in, set in the environment the workbench starts from: + + MESHBENCH_RENODE_LOCKSTEP=1 meshbench + +With it set, three things change for every Renode board: + +- **The CPU advances only as far as the engine asks.** A clock entry in the + machine's own virtual time ticks the radio chip once a millisecond, then + holds the CPU until the engine grants the next millisecond. Renode's virtual + time comes from the instructions executed, so the CPU and the chip step with + the engine rather than with the host. +- **Idle time is skipped** rather than waited out on the host clock, since in + lockstep the engine is the clock. +- **The machine's random numbers are seeded from the node.** The nRF52's RNG + peripheral is where MeshCore draws its jitter from, and unseeded it gives a + fresh stream every run. + +Two idle runs of two RAK4631 repeaters in lockstep give byte-identical event +logs and identical chip counters. + +**It does not make a run reproducible, and `sim.state` still says so.** Console +input reaches the board's UART over a socket on the wall clock, so the lines +provisioning types at boot and any `console.type` land wherever the machine +happens to be, and a loaded machine moves them. Lockstep is also slower: about +five times real time for two boards. QEMU boards are not affected by the +setting and still run free. + ## Assigning an emulated build In the firmware library, board images are listed alongside native builds. `use diff --git a/pages/timing.md b/pages/timing.md index a934ebc..0d480ea 100644 --- a/pages/timing.md +++ b/pages/timing.md @@ -48,6 +48,12 @@ property of emulation, not a defect. Measure with [native firmware](native-vs-emulated.html); use emulation to check that a release boots and transmits. +An nRF52 board under Renode can be run in +[lockstep with the engine](emulation.html#lockstep-under-renode), which steps +its CPU and radio chip with the engine's clock. Console input still arrives on +the wall clock, so a run with an emulated node is reported as not reproducible +either way. + ## Speed control The toolbar's speed control scales how fast simulated time is chased. It