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
28 changes: 28 additions & 0 deletions docs/now/2026-08-23-elab-count-had-a-phantom.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# NOW -- my own ratchet counted 25 errors that do not exist (2026-08-23)

## the instrument (Refs #2325)

- `check_elab_ratchet.py` counted every stderr line containing " error".
iverilog ends a failing file with `N error(s) during elaboration.` -- a
TOTAL, which matched. One phantom per failing module.
- Proof, not inference: after the fix every single module drops by exactly 1,
25 modules do so, and 186 - 161 = 25 = the number of modules that fail to
elaborate. Nothing else moved.
- The published figure 573 -> 186 was inflated at both ends by the same
mechanism. Honest, on this instrument: 161 real errors across 25 of 32
modules. The direction and the proportion survive; the absolute did not.

## the claim inside it

- The docstring said "the remainder is two named design decisions". That was
measured over unbound-identifier errors ONLY (64 of them), and there it is
exact. It was written as if it described all 161.
- The whole remainder, classified: 57 condition-expression errors are
SECONDARY (same source line as an unbound identifier -- 57 of 58; the lone
exception is bridge.v:291), 64 unbound (#2433 strings, #2410 unsized
arrays), 21 whole-array reads, 4 malformed statements, 5 unknown module
types, 2 missing functions.
- The 4 malformed statements are NOT a design decision. A parameter named
`cross` is escaped at its declaration (`\cross `) and emitted bare at its
use, because the part-select path formats the raw base name. That is an
emitter defect and it is filed separately.
45 changes: 37 additions & 8 deletions tools/check_elab_ratchet.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,27 @@
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.
So this gate holds the line per module. It does not demand zero, and the
reason it does not is worth stating accurately, because an earlier version of
this docstring got it wrong. It said "the remainder is two named design
decisions". That was measured over the UNBOUND-IDENTIFIER errors only -- 68 of
them, and there the claim holds exactly (56 string reads, 12 unsized-array
reads, nothing else). It was written as though it described the whole
remainder. The whole remainder, classified:

57 condition expressions -- SECONDARY, same source line as an unbound
identifier above them; they disappear with their cause
64 unbound identifiers -- #2433 (strings) and #2410 (unsized arrays)
21 whole-array reads -- an array used where a value is expected
4 malformed statements -- a keyword-named identifier escaped at its
declaration and not at its use; a real emitter defect, not a decision
5 unknown module types -- self-test modules that never elaborated
2 missing functions
---
161 real errors across 25 of 32 modules

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
Expand All @@ -32,6 +49,11 @@
BASELINE = ROOT / "tools/elab_baseline.txt"
T27C = ROOT / "target/release/t27c"

# iverilog ends a failing file with "N error(s) during elaboration." -- a TOTAL,
# not an error. Counting it added exactly one phantom per failing module, so the
# published figure was 25 too high in both directions (see the module docstring).
SUMMARY = re.compile(r"\d+ error\(s\) during elaboration")


def counts():
"""{module: elaboration error count} over the generated set."""
Expand All @@ -42,7 +64,11 @@ def counts():
capture_output=True,
text=True,
)
n = sum(1 for ln in proc.stderr.splitlines() if " error" in ln)
n = sum(
1
for ln in proc.stderr.splitlines()
if " error" in ln and not SUMMARY.search(ln)
)
out[v.stem] = n
return out

Expand Down Expand Up @@ -108,9 +134,12 @@ def main():
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"
"# the numbers may fall, never rise (#2325). iverilog's own \"N error(s)\n"
"# during elaboration\" summary line is NOT counted -- it is a total, and\n"
"# counting it added one phantom error per failing module.\n"
"# The remainder is not one thing: see the module docstring for the full\n"
"# classification. Two design decisions (#2433, #2410) cover the unbound\n"
"# identifiers; the malformed statements are an emitter defect.\n"
f"# iverilog-version {iverilog_version()}\n"
)
body = "\n".join(f"{k} {v}" for k, v in sorted(now.items()))
Expand Down
59 changes: 31 additions & 28 deletions tools/elab_baseline.txt
Original file line number Diff line number Diff line change
@@ -1,37 +1,40 @@
# 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.
# the numbers may fall, never rise (#2325). iverilog's own "N error(s)
# during elaboration" summary line is NOT counted -- it is a total, and
# counting it added one phantom error per failing module.
# The remainder is not one thing: see the module docstring for the full
# classification. Two design decisions (#2433, #2410) cover the unbound
# identifiers; the malformed statements are an emitter defect.
# iverilog-version 13.0
apb_bridge 5
assembler 5
axi4 3
bootrom 4
bridge 17
apb_bridge 4
assembler 4
axi4 2
bootrom 3
bridge 16
clock_domain 4
crossopt 0
cts 3
dft 7
e2e_demo 3
fifo 3
formal 21
gf16_accel 7
hir 17
cts 2
dft 6
e2e_demo 2
fifo 2
formal 20
gf16_accel 6
hir 16
hw_types 0
linker 5
linker 4
mac 0
memory 6
partition 3
placement 7
power 3
router 9
simulator 3
memory 5
partition 2
placement 6
power 2
router 8
simulator 2
spi 0
stdlib 3
ternary_isa 7
testbench 9
timing 11
stdlib 2
ternary_isa 6
testbench 8
timing 10
top_level 0
uart 0
vcd_trace 15
zerodsp_top 6
vcd_trace 14
zerodsp_top 5
Loading