Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/fpga-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -752,6 +752,14 @@ jobs:
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Result:** $pass passed, $fail failed" >> $GITHUB_STEP_SUMMARY

- name: Elaboration errors may fall, never rise
run: |
# #2325: 573 -> 186 across three emitter classes in one evening. The
# conformance job executes two modules; the other thirty are only
# yosys-linted, and yosys accepts many references iverilog rejects --
# so without this ratchet the win can slide back invisibly.
python3 tools/check_elab_ratchet.py

- name: A vector case must carry data, not only prose
run: |
# #2241: 412 of 512 cases carry an id and a sentence and nothing else.
Expand Down
17 changes: 17 additions & 0 deletions docs/now/2026-08-23-elaboration-errors-may-fall-never-rise.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# NOW -- elaboration errors may fall, never rise (2026-08-23)

## the 573 -> 186 win is now held by a per-module ratchet (Refs #2325)

- Three emitter classes took the 32-module fpga set from 573 iverilog
elaboration errors to 186 in one evening. Nothing held that: the conformance
job executes two modules, and the other thirty are only yosys-linted -- and
yosys accepts many references iverilog rejects, which is how the class grew
unseen in the first place.
- tools/check_elab_ratchet.py records the count PER MODULE and fails when any
module gains errors, naming the module and both numbers. It does not demand
zero: the remainder is two named design decisions (string comparison in
hardware; unsized array params, #2410). Skips cleanly without iverilog.
- Negative control, done twice because the first attempt was a no-op that
silently "passed": lowering one module's baseline by 3 now prints
"WORSE memory: 3 -> 6" and exits 1; restoring returns 0. A control that
does not fire is not a control.
130 changes: 130 additions & 0 deletions tools/check_elab_ratchet.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
#!/usr/bin/env python3
"""Elaboration errors may fall, never rise (#2325).

The generated Verilog of the 32-module fpga set went from 573 iverilog
elaboration errors to 186 in one evening, across three emitter classes:
string fields poisoning a whole struct (#2424), fields of array elements of a
struct flattening to an empty base (#2325), and unannotated locals losing the
type they were copied from. Nothing prevents that from sliding back: the
conformance job compiles two modules, and the other thirty are only linted by
yosys, which accepts many references iverilog rejects.

So this gate holds the line per module. It does not demand zero -- the
remainder is two named design decisions (string comparison in hardware; unsized
array params, #2410). It fails when any module gains errors, and asks you to
record the win when a module loses them.

tools/check_elab_ratchet.py # verify
tools/check_elab_ratchet.py --update-baseline # after a deliberate change

Requires iverilog and a built t27c; skips cleanly (exit 0) when either is
missing, so a Rust-only checkout is never blocked by it -- the same contract
emit-bitexact-gate.yml uses.
"""
import pathlib
import shutil
import subprocess
import sys

ROOT = pathlib.Path(__file__).resolve().parent.parent
GEN = ROOT / "build/fpga/generated"
BASELINE = ROOT / "tools/elab_baseline.txt"
T27C = ROOT / "target/release/t27c"


def counts():
"""{module: elaboration error count} over the generated set."""
out = {}
for v in sorted(GEN.glob("*.v")):
proc = subprocess.run(
["iverilog", "-g2012", "-DSIMULATION", "-o", "/dev/null", str(v)],
capture_output=True,
text=True,
)
n = sum(1 for ln in proc.stderr.splitlines() if " error" in ln)
out[v.stem] = n
return out


def baseline():
if not BASELINE.exists():
return {}
d = {}
for ln in BASELINE.read_text().splitlines():
ln = ln.strip()
if not ln or ln.startswith("#"):
continue
name, _, num = ln.rpartition(" ")
try:
d[name.strip()] = int(num)
except ValueError:
continue
return d


def main():
if not shutil.which("iverilog") or not T27C.exists():
print("SKIP: iverilog or target/release/t27c missing")
return 0

gen = subprocess.run(
[str(T27C), "fpga-build", "--smoke"], capture_output=True, text=True
)
if gen.returncode != 0:
print(gen.stderr.strip()[-600:])
print("t27c fpga-build --smoke failed")
return 1

now = counts()
total = sum(now.values())

if "--update-baseline" in sys.argv:
header = (
"# iverilog elaboration errors per generated module. This is a RATCHET:\n"
"# the numbers may fall, never rise (#2325). The remainder is two named\n"
"# design decisions -- string comparison in hardware, and unsized array\n"
"# params (#2410) -- not an oversight.\n"
)
body = "\n".join(f"{k} {v}" for k, v in sorted(now.items()))
BASELINE.write_text(header + body + "\n")
print(f"baseline updated: {len(now)} modules, {total} errors")
return 0

base = baseline()
if not base:
print("no baseline; run --update-baseline once")
return 1

worse, better, new = [], [], []
for m, n in sorted(now.items()):
if m not in base:
new.append((m, n))
elif n > base[m]:
worse.append((m, base[m], n))
elif n < base[m]:
better.append((m, base[m], n))

print(f"elaboration errors: {total} (baseline {sum(base.values())})")
for m, b, n in better:
print(f" BETTER {m}: {b} -> {n}")
for m, n in new:
print(f" NEW {m}: {n} errors, not in baseline")
for m, b, n in worse:
print(f" WORSE {m}: {b} -> {n}")

if worse or new:
print()
print("A module gained elaboration errors. Generated Verilog that iverilog")
print("cannot elaborate cannot be simulated, so its vectors can never run.")
print("If the increase is deliberate: tools/check_elab_ratchet.py --update-baseline")
return 1
if better:
print()
print("Modules improved. Record it: tools/check_elab_ratchet.py --update-baseline")
return 1
print("OK: no module gained elaboration errors")
return 0


if __name__ == "__main__":
sys.exit(main())
36 changes: 36 additions & 0 deletions tools/elab_baseline.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# iverilog elaboration errors per generated module. This is a RATCHET:
# the numbers may fall, never rise (#2325). The remainder is two named
# design decisions -- string comparison in hardware, and unsized array
# params (#2410) -- not an oversight.
apb_bridge 5
assembler 5
axi4 3
bootrom 4
bridge 17
clock_domain 4
crossopt 0
cts 3
dft 7
e2e_demo 3
fifo 3
formal 21
gf16_accel 7
hir 17
hw_types 0
linker 5
mac 0
memory 6
partition 3
placement 7
power 3
router 9
simulator 3
spi 0
stdlib 3
ternary_isa 7
testbench 9
timing 11
top_level 0
uart 0
vcd_trace 15
zerodsp_top 6
Loading