fix(hw): intercard_link width-guard fires at elaboration (was simulation-only)

[marcos-mendez]

Summary

Closes #12.

PR #11 placed the MAST #14 width-contract guard inside initial $error
blocks. Verilator --lint-only does not execute initial blocks, so a
future violation of INTERCARD_LANES * INTERCARD_LANE_WIDTH == 128 would
have lint-passed silently. Today the contract is satisfied, so the gap was
masked.

Option chosen: A (bare $error in generate body)

The issue offered three options (A: bare $error in generate, B: negative-
width wire trick, C: switch lint script to --binary). I tested Option A
against Verilator 5.048 first because it's the cleanest IEEE 1800-2012
construct and required no script changes.

Verilator 5.048 accepts $error directly inside a generate-if body
without --assert, surfaces it as %Warning-USERERROR, and exits
non-zero. Verified — no need to fall back to B or C.

Applied to BOTH sites the issue identified:

• src/intercard_link.sv — production module's internal width-guard
  (lines ~80-92, formerly initial begin if (...) $error ... end)
• verif/intercard_link/test_widths.sv — testbench's elaboration-time
  guard (lines ~59-72, formerly initial $error in generate)

The "OK" branch in test_widths.sv keeps initial $display because
that path is purely observational (only meaningful under --binary,
and under --lint-only it's a harmless no-op).

Verification (mandatory per issue)

1. Default-parameter case must still PASS

$ bash verif/intercard_link/run_lint.sh
[run_lint] verilator Verilator 5.048 2026-04-26 rev v5.048
[run_lint] linting .../src/intercard_link.sv with top .../test_widths.sv
- V e r i l a t i o n   R e p o r t: Verilator 5.048 2026-04-26 rev v5.048
- Verilator: Built from 0.050 MB sources in 3 modules ...
[run_lint] PASS — intercard_link elaborates with INTERCARD_BUS_WIDTH = 128
EXIT=0

2. Contract violation must FAIL (the crisp proof issue #12 asked for)

I created verif/intercard_link/test_widths_violation.sv (NOT committed,
deleted before commit) instantiating intercard_link #(.INTERCARD_LANES(8), .INTERCARD_LANE_WIDTH(32)) — 8 * 32 = 256 != 128, contract broken.

$ verilator --lint-only --top-module test_widths_violation -Wall \
    -Wno-DECLFILENAME -Wno-UNUSED \
    src/intercard_link.sv verif/intercard_link/test_widths_violation.sv
%Warning-USERERROR: src/intercard_link.sv:89:13: intercard_link: INTERCARD_LANES (8) * INTERCARD_LANE_WIDTH (32) = 256, expected 128 (MAST #14 contract).
                                               : ... note: In instance 'test_widths_violation.u_violation'
   89 |             $error("intercard_link: INTERCARD_LANES (%0d) * INTERCARD_LANE_WIDTH (%0d) = %0d, expected 128 (MAST #14 contract).",
      |             ^~~~~~
                    ... For warning description see https://verilator.org/warn/USERERROR?v=5.048
%Error: Exiting due to 1 warning(s)
EXIT=1

Captured violation evidence:

• Exit code: 1 (non-zero — would fail CI)
• First error line: %Warning-USERERROR: src/intercard_link.sv:89:13: intercard_link: INTERCARD_LANES (8) * INTERCARD_LANE_WIDTH (32) = 256, expected 128 (MAST #14 contract).

The temp file was deleted before commit; not in the diff.

Out of scope (per issue)

No changes to: connector pinout, SV stub body, ADRs, KiCad files,
run_lint.sh. Only the two files with the broken guard.

Test plan

• bash verif/intercard_link/run_lint.sh exits 0 on default params
• verilator --lint-only exits non-zero when contract is violated
  (LANES=8) — captured above
• SPDX headers preserved on both files
• DCO sign-off present
• No changes to out-of-scope artifacts
• CI green (will appear after PR creation)

🛠 Stream 2 / Agent 2 (FPGA Hardware)

[marcos-mendez]

Review by Agent R

Verdict: APPROVE
Severity counts: CRITICAL=0 HIGH=0 MEDIUM=0 LOW=0

Pre-review gates (5d5fbb6e)

• CI: Verilator + cocotb tests SUCCESS
• Mergeable: yes
• DCO sign-off + SPDX preserved
• 21+/7- (small surgical change to 2 files)

Independent verification by Agent R

• Default lint: bash verif/intercard_link/run_lint.sh → PASS — intercard_link elaborates with INTERCARD_BUS_WIDTH = 128 (Verilator 5.048)
• Violation case: Built a tmp TB with intercard_link #(.INTERCARD_LANES(8)) and ran verilator --lint-only. Output:

  %Warning-USERERROR: src/intercard_link.sv:89:13: intercard_link: INTERCARD_LANES (8) * INTERCARD_LANE_WIDTH (32) = 256, expected 128 (MAST #14 contract).
  

  Verilator surfaces USERERROR as fatal by default → exit non-zero (Agent 2 captured exit 1 without -Wno-fatal). The guard now genuinely fires at elaboration, not just at simulation. Issue [hw] intercard_link width-guard does not fire under verilator --lint-only #12's gap is closed.

Option A choice rationale (accepted)

Bare $error directly in generate-if body without initial wrapper is the IEEE 1800-2012 elaboration-time form. Cleanest of the three options proposed in #12 — no negative-width tricks, no --binary switch needed.

Useful agent gotcha (worth memory)

Agent 2 noted Verilator's pragma scanner is text-based — wrapped // comments containing /* verilator …-style sequences trip BADVLTPRAGMA. Worth keeping in mind for future hw doc-comments. Not memory-worthy on its own (Verilator-specific, low-recurrence) but useful context.

Action

Merging via two-step. Forgejo sync follows.

Authored by Agent R (Reviewer).