RTL conventions: mirrored include↔rtl↔tb tree, interface taxonomy, ordered filelists, enforced lint (additive)

[themoddedcube]

Adopt four RTL-organization conventions (borrowed from Purdue-SoCET/atalla, adapted to our monorepo + golden-model discipline) to make the codebase legible for a large incoming new-member cohort. Fully additive — no existing block file was moved, renamed, or edited. Nothing here touches the timing-closed RTL.

What's here

• docs/rtl_conventions.md — canonical write-up of all four conventions (deep on the mirrored tree: the shared-subpath layout, generic Make mechanics, the _if/_pkg/_params taxonomy + modport a_b rule, one-.f-for-sim-and-harden, and a SHALL/SHOULD/MAY style guide).
• docs/rtl_conventions_template/ — a runnable worked example (regadd) in the mirrored include/ rtl/ tb/ layout with a generic make lint/test MOD=…. Verified: make test MOD=regadd PASSes (4 seeds, bit-exact vs a Python golden, iverilog 12 + cocotb 2.0.1).
• scripts/check_block_structure.py — opt-in advisory --check-rtl-conventions scan (new ADVISE level that never gates, even under --strict); default behavior unchanged, existing blocks won't fail.
• .github/workflows/rtl-lint.yml — Verilator --lint-only gate, non-blocking initially (continue-on-error, LINT_BLOCKING=0) so it can't red-wall proven blocks; documented switch to make it blocking once RTL is lint-clean.
• DECISIONS.md — adoption line (2026-08-01).

The four conventions

1. Mirrored include ↔ rtl ↔ tb subpath tree + generic make test MOD=… targets.
2. Interface taxonomy: <mod>_if.sv / <block>_pkg.svh / <mod>_params.svh, ifndef guards, modport a_b naming.
3. Per-top ordered .f filelists consumed by both iverilog and LibreLane.
4. A written style guide, enforced by a CI lint gate.

Honest caveats

• Icarus 12 can't take a SV interface/modport as a module port (only instantiate it) — same reason existing blocks use flat leaf ports. The runnable template keeps flat ports with the _if as harness fabric; the _if/modport taxonomy ships as the reviewed contract (Verilator/LibreLane accept modport ports).
• Verilator couldn't be installed on the dev box (no root), so the lint flags are standard-but-unverified there — hence the gate ships advisory/non-blocking until confirmed on a machine with verilator.

Deliberately NOT done (follow-ups)

• Migrating existing blocks (kve/tiu/acu/…) to the mirrored tree — disruptive; a separate per-block effort with sign-off reproduced.
• Flipping the lint/structure gates to blocking once tracked RTL is lint-clean (documented switch).

Companion to the lambda-onboarding wiki, which documents these same conventions for new members.

🤖 Generated with Claude Code