From 9c3d2f36a6c6e887e3533ca32db6199d525df0fc Mon Sep 17 00:00:00 2001 From: DoubleGate Date: Thu, 20 Aug 2026 20:21:56 -0400 Subject: [PATCH] docs(mister): name the device-under-test repository, now that it exists The spec described a "sibling repository (`RustyNES_MiSTer`)" with no link, because at the time there was nothing to link to. There is now: https://github.com/doublegate/RustyNES_MiSTer, private. Two additions beyond the URL, both about things a reader of this document needs and could not previously get. THE CROSS-REPOSITORY COUPLING IS NAMED, BECAUSE BREAKING IT IS SILENT `tb/checkpoint.h` over there reimplements `Observable::encode` from here, and `tb/checkpoint_selftest.cpp` asserts it against the same hardcoded vector `the_wire_encoding_is_pinned_to_a_fixed_vector` pins on this side. That pairing is the entire guard against the top-ranked risk at this rung: a packing disagreement between the two halves produces a hash mismatch indistinguishable from a wrong DUT, and it would be debugged as one. So the document now states plainly that changing `encode` here without changing `checkpoint.h` there breaks co-simulation in the way that is hardest to diagnose, and that the selftest is the first thing to run after touching either. A coupling that spans two repositories has nothing mechanical watching it, which is exactly why it has to be written where the person editing the encoding will read it. Verified rather than asserted before writing it down: both files were parsed and their pinned vectors compared byte for byte. rust: 16 bytes 08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00 cpp : 16 bytes 08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00 and the selftest re-run against merged main, all five checks green. Worth recording how that nearly went wrong: the first comparison was a `grep -A4` over the Rust array, which returned three bytes -- rustfmt had reformatted the literal one element per line, so the context window was too small. Three bytes against sixteen reads as a mismatch. The published comparison parses both literals properly instead. THE LICENCE HEDGE IN ADR 0037 IS RESOLVED, AND INVERTED ADR 0037 recorded that a GPL-2.0-ONLY file anywhere in the MiSTer framework's sys/ would force the RTL to GPL-2.0-or-later, and that the tabulation had to happen before any RTL existed. It has: all 57 files read and classified. There is no GPL-2.0-only file. Four are GPL-3.0-OR-LATER, and one of them is hps_io.sv, which is how a core receives a ROM and reaches the OSD -- no core functions without it. GPL-2.0-or-later combines upward into GPL-3; GPL-3.0-or-later does not reduce. The combined bitstream must therefore be GPL-3.0-or-later, which is already this project's licence. The hedge is inverted by the evidence rather than confirmed by it, and the decision is made with zero lines of RTL written rather than ten thousand -- which was the entire point of ordering the audit first. Docs only. No source, no manifests, no core. --- docs/mister.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/mister.md b/docs/mister.md index 373ae1d5..4ef82f71 100644 --- a/docs/mister.md +++ b/docs/mister.md @@ -6,6 +6,7 @@ change to `crates/rustynes-cosim` or the golden formats it emits. **Decision record:** [ADR 0037](adr/0037-mister-fpga-core-independent-hdl-implementation.md). **Execution plan:** [`to-dos/plans/v2.5.0-fabric-plan.md`](../to-dos/plans/v2.5.0-fabric-plan.md). **Research archive:** [`to-dos/plans/research/v2.5.0-research-mister-fpga.md`](../to-dos/plans/research/v2.5.0-research-mister-fpga.md). +**Device-under-test:** (private). --- @@ -16,9 +17,33 @@ by Quartus 17.0.2 into a Cyclone V bitstream; Rust does not become a bitstream. What the "Fabric" line builds is a **new NES implementation in SystemVerilog, written from public hardware documentation**, in a sibling repository -(`RustyNES_MiSTer`), with **RustyNES as its verification oracle**. This document -specifies the boundary between the two - the one part that lives in this -repository. +([`doublegate/RustyNES_MiSTer`](https://github.com/doublegate/RustyNES_MiSTer), +private), with **RustyNES as its verification oracle**. This document specifies +the boundary between the two - the one part that lives in this repository. + +The sibling repository holds the harness at rung 0 and **no RTL**, which is the +ladder's design rather than a gap: the testbench must be shown able to recognise +agreement before anything is compared. Two of its files matter to readers of +this document, because they are the other half of what is specified here. + +`tb/checkpoint.h` reimplements this repository's checkpoint encoding in C++, and +`tb/checkpoint_selftest.cpp` asserts it against **the same hardcoded vector** +`the_wire_encoding_is_pinned_to_a_fixed_vector` pins on this side. That pairing +is the whole guard against the top-ranked risk at this rung: a packing +disagreement between the two halves produces a hash mismatch that is +indistinguishable from a wrong DUT, and would be debugged as one. **Changing +`Observable::encode` here without changing `checkpoint.h` there breaks +co-simulation in the way that is hardest to diagnose** - so the selftest is the +first thing to run after touching either. + +Its licence audit also settled a question this side had left open. ADR 0037 +recorded that a GPL-2.0-**only** file anywhere in the MiSTer framework's `sys/` +would force the RTL to GPL-2.0-or-later. All 57 files were read: **there is no +such file**, and four are GPL-3.0-or-later - including `hps_io.sv`, which no core +functions without. GPL-2.0-or-later combines upward and GPL-3.0-or-later does not +reduce, so the combined bitstream must be **GPL-3.0-or-later**, which is already +this project's licence. The hedge is inverted by the evidence rather than +confirmed by it. ## The firewall applies to HDL