diff --git a/docs/upstream-contributions/0001-rev-a-known-upstream-issues.md b/docs/upstream-contributions/0001-rev-a-known-upstream-issues.md index d49f3a9..6a0fc0e 100644 --- a/docs/upstream-contributions/0001-rev-a-known-upstream-issues.md +++ b/docs/upstream-contributions/0001-rev-a-known-upstream-issues.md @@ -62,17 +62,50 @@ engagement are weaker signal than recent ones. Used for: RTL synthesis (`synth_ecp5`). +**Day-1 recon (2026-05-06):** see +`2026-05-06-yosys-ecp5.md`. The ECP5 synthesis backend is +**production-mature** on yosys v0.64 (released 2026-04-09): `synth_ecp5` +is a thin wrapper around `synth_lattice -family ecp5` (unification commit +2023-08-31, `714603b`); every ECP5-85F primitive rev-A needs (LUT4, CCU2C, +TRELLIS_FF, DP16KD, MULT18X18D, EHXPLLL, ODDRX1F/IDDRX1F, IB/OB/BB) is +covered; release cadence is monthly; OSS CAD Suite ships daily nightlies +that pin compatible yosys + nextpnr + prjtrellis HEADs. Every major +open-FPGA ECP5 board (OrangeCrab, Trellis Board, Versa-ECP5, ECPIX-5, +ULX3S, Colorlight 5A-75B) ships through `synth_ecp5` end-to-end. No +upstream contribution gap for rev-A's core feature set; this is an +integration-only dependency **with watchlist** for the issues below. + +**Real risk identified, not in `synth_ecp5` itself:** OSS yosys's +SystemVerilog-2017 frontend coverage is **partial** — SV interfaces, +package-with-parameters, and type parameters all have open issues. rev-A +RTL already side-steps these per the explicit posture in +`MAST/src/popsolutions/axi4/README.md` ("avoids the SV interface / +package compatibility issues that some tools still have"). Stream 1 RTL +authors should hold this line; the escape valve if SV-2017 features ever +become non-negotiable is **Synlig** (Surelog frontend, Apache-2.0). + | # | Title | Affects rev-A because | Recency | |---|---|---|---| -| 5814 | ECP5 memory_bram has no rule for REGMODE=OUTREG | MAST scratchpads / cache lines using BRAM with output register will hit this | 2026-04 | +| 5814 | ECP5 memory_bram has no rule for REGMODE=OUTREG | MAST scratchpads / cache lines using BRAM with output register will hit this. **Workaround:** instantiate DP16KD directly | 2026-04 | | 4798 | Synthesis with -nowidelut gives drastically better results | QoR knob worth knowing if MAST hits area pressure on -85F | 2024-12 | | 4872 | Yosys emits FF that never toggles instead of constant 0 | Synthesis-correctness regression class | 2025-01 | -| 4349 | Assert failure in synth_{ice40,ecp5} on simple design | Generic synth_ecp5 crash; affects any design that triggers it | 2024-04 | -| 4237 | ABC9/AIGER crash in synth_ecp5 | Crash in the default ECP5 synthesis flow | 2024-02 | +| 4349 | Assert failure in synth_{ice40,ecp5} on simple design | Generic synth_ecp5 crash; Linux-only CI sidesteps the Windows path | 2024-04 | +| 4237 | ABC9/AIGER crash in synth_ecp5 | Crash in the default ECP5 synthesis flow. **Workaround:** `-noabc9` | 2024-02 | | 4127 | DSP_A/B_MINWIDTH change causes ABC9 error | Affects any design inferring ECP5 DSP blocks (MAST matrix engine candidate) | 2024-01 | -| 3008 | ECP5 primitive instantiation 'cells_not_processed' | Hits when manually instantiating ECP5 primitives | 2021-09 | +| 3008 | ECP5 primitive instantiation 'cells_not_processed' | Hits when manually instantiating ECP5 primitives. **Workaround:** use library cell wrappers | 2021-09 | | 3005 | Lattice ECP5: Module FD1P3DX port q error | Same root area; manually instantiated FFs | 2021-09 | +SystemVerilog frontend issues to **avoid**, not just watch: + +| # | Title | Avoidance posture for rev-A | Recency | +|---|---|---|---| +| 5405 | Interface synthesis bug: logic missing from main eval path | Don't use SV interfaces in module ports | 2025-10 | +| 3937 | "Failed to resolve identifier" on SV interface element | Don't use SV interfaces in module ports | 2023-09 | +| 3592 | Wider ports in SV interfaces treated as single bit | Don't use SV interfaces in module ports | 2022-12 | +| 5533 | `read_verilog` doesn't support imports in packages | Don't put parameters in SV packages | 2025-12 | +| 4318 | Parameters in other packages | Don't put parameters in SV packages | 2024-04 | +| 3828 | SV type parameters not supported | Don't use `parameter type T = ...` | 2023-07 | + ### nextpnr-ecp5 (https://github.com/YosysHQ/nextpnr) Used for: place & route on ECP5 fabric. diff --git a/docs/upstream-contributions/2026-05-06-yosys-ecp5.md b/docs/upstream-contributions/2026-05-06-yosys-ecp5.md new file mode 100644 index 0000000..e37fdbc --- /dev/null +++ b/docs/upstream-contributions/2026-05-06-yosys-ecp5.md @@ -0,0 +1,570 @@ + + +# 2026-05-06 — yosys ECP5 synthesis backend (`synth_ecp5`) status + +**Status:** Production-mature for the ECP5 backend itself. **Integration-only — +no upstream contribution gap identified for rev-A's ECP5 synthesis backend +needs.** `synth_ecp5` (now a thin wrapper around `synth_lattice -family ecp5`, +unified August 2023) is the synthesis half of the canonical open ECP5 flow, +shipped in v0.64 (released 2026-04-09), bundled in the OSS CAD Suite nightly +distribution, and used in production by every major open-FPGA ECP5 board for +the past six years. + +**Watchlist** entries documented for a small set of `synth_ecp5`-tagged open +issues (#4349 generic crash, #4237 ABC9/AIGER crash, #4798 wide-LUT QoR cliff, +#5814 BRAM REGMODE=OUTREG inference gap, #4127 DSP MINWIDTH/ABC9 interaction). + +**Real risk identified, not in `synth_ecp5` itself:** OSS yosys's +SystemVerilog-2017 frontend coverage is **partial**. SV interface/modport, +package imports, type parameters, and certain interface-port width inferences +have open issues. rev-A RTL (MAST + InnerJib7EA `intercard_link_*.sv`) was +already deliberately written to avoid these risk areas (per +`MAST/src/popsolutions/axi4/README.md`: "avoids the SV interface / package +compatibility issues that some tools still have"). **No rev-A blocker today, +but the Stream 1 author should not introduce SV interfaces / packages / +type parameters without budgeting integration time on the open frontend.** + +The cooperative integrates, documents, credits upstream, and budgets a +near-term reproducer-filing slot for any -85F issues we hit during bring-up. + +## Upstream project + +`YosysHQ/yosys` — the canonical open-source Verilog/SystemVerilog +synthesis framework. The "yosys" half of the canonical open ECP5 pipeline: + +``` +yosys (synth_ecp5) → nextpnr-ecp5 → prjtrellis (ecppack) → bitstream.bit +``` + +License: ISC (per GitHub metadata; `LICENSE` file at repo root). +Maintainers: Claire Xenia Wolf (founder), Catherine "myrtle"/`gatecat` +(YosysHQ), with extensive contributions from the YosysHQ team and a broad +open-source community. + +| Signal | Value | +|---|---| +| Stars | **4 430** | +| Default branch | `main` | +| Last push | 2026-05-06 (active daily) | +| Most recent release | **v0.64 (2026-04-09)** | +| Release cadence | Monthly. v0.60 (2025-12-03) → v0.64 (2026-04-09): 5 releases in 4 months. | +| Open issues | 489 (non-PR) | +| Open PRs | ~96 | +| Archived | No | +| CI | Yes (extensive `.github/workflows/`) | + +## ECP5 synthesis backend in v0.64 + +### File layout (current as of v0.64 / `main` 2026-05-06) + +The historic `techlibs/ecp5/` directory was unified in **August 2023** into +`techlibs/lattice/`. `synth_ecp5` is now a thin wrapper around `synth_lattice +-family ecp5` (commit `714603b`, "synth_nexus to synth_lattice", 2023-08-31). +The wrapper preserves backward compatibility — every Makefile and script +calling `synth_ecp5` (OrangeCrab, Trellis Board, ULX3S, Versa-ECP5, MAST CI, +LiteX) continues to work unchanged. + +``` +techlibs/lattice/ + synth_lattice.cc # 19 657 bytes — unified Lattice synth pass + cells_sim_ecp5.v # 11 944 bytes — ECP5 cell simulation models + cells_bb_ecp5.v # 62 138 bytes — ECP5 cell blackbox declarations + cells_map_trellis.v # 15 010 bytes — Yosys cell → ECP5 primitive map + cells_xtra.py # 24 696 bytes — extra cell generation + brams_16kd.txt # BRAM inference rules (DP16KD) + brams_map_16kd.v # BRAM mapping + dsp_map_18x18.v # DSP MULT18X18 mapping + arith_map_ccu2c.v # ECP5 carry chain (CCU2C) mapping + lattice_gsr.cc # Global Set/Reset detection pass +``` + +### `synth_ecp5` pass — what's in v0.64 + +From `synth_lattice.cc`: + +``` +SynthEcp5Pass() : Pass("synth_ecp5", "synthesis for ECP5 FPGAs") { } +// → calls synth_lattice -family ecp5 +``` + +The unified `synth_lattice` pass supports six Lattice families behind a single +script: `ecp5`, `xo2` (MachXO2), `xo3` (MachXO3L/LF), `xo3d` (MachXO3D), +`lifcl` (CrossLink-NX), `lfd2nx` (Certus-NX). Several more families (xo, pm, +pm2, xp, xp2, ecp, sm, ecp2, ecp3, lifmd, lifmdf) are listed as +`EXPERIMENTAL` (commented out in help) and not on the ECP5 path. + +Recent activity on the file: + +| Commit | Date | Subject | +|---|---|---| +| `fff034d` | 2026-05-05 | Add check before flatten in synth_*. | +| `c3ffb48` | 2026-01-27 | Add and use fix_mod.py | +| `714603b` | 2023-08-31 | synth_nexus to synth_lattice (unification commit) | +| `58f9531` | 2023-11-14 | enable ABC9 by default except for XO2/3/3D | +| `4b9e4bf` | 2023-11-13 | Update techlibs/lattice/synth_lattice.cc | + +A maintainer change landed **yesterday** (2026-05-05). The pass is alive. + +### Default optimisation flow + +`synth_ecp5` invokes ABC9 for technology mapping by default (commit +`58f9531`, 2023-11-14). For -85F this means modern, well-tuned LUT4 packing +and FF inference. The `-nowidelut` switch is documented (and known to give +drastically better results on certain XOR-heavy designs — see watchlist). + +## Bug / feature gap + +### `synth_ecp5` itself + +**None blocking rev-A's core feature set.** The `synth_ecp5`-tagged open +issues all have known workarounds or are corner cases: + +- **#5814** (2026-04-28): `memory_bram` has no rule for `REGMODE=OUTREG`. + Workaround: instantiate `DP16KD`/`PDPW16KD` directly. **Watchlist for + MAST scratchpads** if BRAM clk-to-q timing becomes critical. +- **#4798** (2025-04-28): `synth -nowidelut` gives "drastically better + results" on a SHA3 design (XOR-heavy reduction). Workaround: pass + `-nowidelut`. **QoR knob** worth knowing on -85F if MAST area pressure + appears. +- **#4349** (2025-08-14, last comment): generic `synth_ecp5` assert + failure on Windows. Linux-only is our CI host, mitigates this. +- **#4237** (2024-04-11): ABC9/AIGER crash. Workaround: drop ABC9 + (`synth_ecp5 -noabc9`) — costs 10-20% area + timing. Acceptable + fallback. +- **#4127** (2024-01-11): DSP_A/B_MINWIDTH change → ABC9 error. Affects + designs inferring ECP5 DSP blocks. **Watchlist for MAST matrix engine** + if/when DSP inference is exercised. +- **#3008**, **#3005** (2021): manually instantiated ECP5 primitive port + bugs (FD1P3DX). Workaround: use library cell wrappers, not raw + primitive instantiations. +- **#2833** (2021): `$readmemh` ineffective on ECP5-25F. Different SKU, + but worth tracking — rev-A's BootROM may want `$readmemh` if we go + that route. + +None of these is a synthesis-correctness blocker for the rev-A RTL we have +today (MAST + intercard_link). All have workarounds. + +### SystemVerilog frontend (the real risk surface) + +This is **not** a `synth_ecp5` problem — it is a yosys-frontend problem +that is upstream of every backend. Concretely: + +- **`read_verilog -sv` is a Verilog-2005 parser with selected SV-2017 + extensions**, not a full SV-2017 frontend. Per the upstream + `frontends/verilog/verilog_frontend.cc` docs: "The Verilog frontend reads + Verilog-2005 code and creates an AST." +- The repo README states explicitly: "Make sure to get a Tabby CAD Suite + Evaluation License if you need features such as industry-grade + SystemVerilog and VHDL parsers!" The full SV path is via Verific, which + ships only in YosysHQ's commercial Tabby CAD Suite. The open route is: + - `read_verilog -sv` (built-in, partial) — what OSS CAD Suite ships. + - **Synlig** (`chipsalliance/synlig`, Apache-2.0, last release + 2024-12-10): Surelog SV-2017 preprocessor + parser + elaborator, + plugged into Yosys. 233 stars, less actively maintained than yosys + itself but a real option. +- **Open SV-related issues that intersect rev-A risk** (filtered from 489 + open issues; full SV list is 45): + +| # | Title | Risk for rev-A | Recency | +|---|---|---|---| +| 5837 | assertion crash with ascending packed bit range in memory array | low — we use descending | 2026-04-29 | +| 5787 | `read_verilog -sv` crashes on malformed input | low — well-formed RTL only | 2026-04-20 | +| 5533 | `read_verilog` doesn't support imports in packages | **medium** — if rev-A adopts SV packages this hits | 2025-12-16 | +| 5405 | Interface synthesis bug: logic missing from main eval path | **high if interfaces are used** — rev-A actively avoids them | 2025-10-02 | +| 4374 | Add `==?` and `!=?` operators | low — workaround with explicit casez | 2024-05-04 | +| 4318 | Parameters in other packages | **medium** — if rev-A puts parameters in packages this hits | 2024-04-10 | +| 4159 | Accept `inout` on interface modports | low — rev-A doesn't use modports | 2024-02-01 | +| 3937 | "Failed to resolve identifier" on SV interface element | **high if interfaces used** | 2023-09-17 | +| 3828 | SV type parameters not supported | **medium** — `parameter type` not usable | 2023-07-02 | +| 3592 | Wider ports in SV interfaces treated as single bit | **high if interfaces used** | 2022-12-20 | +| 3327 | Two-level-deep function calls in `always_comb` reading a field | **medium** — pattern is common in clean RTL | 2022-08-22 | +| 1592 | Clock-in-interface-port mis-synthesised | **high if interfaces used** | 2019-12-22 | + +**The pattern:** SV interfaces, packages with parameters, and SV type +parameters are the dangerous frontier. rev-A RTL deliberately stays inside +the safe envelope (see "Project context" below for evidence). + +## Project context + +- Surfaced in Agent 4's first ecosystem-health survey, + `docs/upstream-contributions/0001-rev-a-known-upstream-issues.md`, + in the yosys section. That survey flagged eight open issues + (#5814, #4798, #4872, #4349, #4237, #4127, #3008, #3005). Day-1 recon + (this document) confirms none are blockers; all have workarounds. + +- ADR-001 (rev-A FPGA target) anchors rev-A on **ECP5-85F** with the + open toolchain (yosys + nextpnr-ecp5 + prjtrellis). Day-1 recon + confirms the yosys half of that anchor is sound. + +- **rev-A RTL already evidences SV-frontend caution.** + `MAST/src/popsolutions/axi4/README.md` (the AXI4 adapter docs in the + RTL stream) explicitly states: + + > "This matches the upstream VeriGPU convention and avoids the SV + > interface / package compatibility issues that some tools still + > have." + + And: + + > "The packed struct typedefs in `axi4_const.sv` ... testbenches, or + > interface bundles once iverilog/yosys interface-port support + > [matures]." + + This is the right posture: keep rev-A inside the well-supported subset + (Verilog-2005 + parameters as `parameter int` + generate blocks + + `$error` in generate + `typedef enum` + packed structs as types but + not as ports). Day-1 recon confirms that the constructs rev-A + actually uses — `parameter int INTERCARD_LANES`, `generate ... $error + ... endgenerate`, `typedef enum bit[N:0]` — are all the **safe** + subset. + +- **`always_comb` / `always_ff`:** rev-A grep shows MAST uses these + sparingly (one comment-only `always_comb` in `core.sv`). The repo + prefers explicit `always @(posedge clk)`. Yosys handles `always_comb` + / `always_ff` and `always_latch`, but the safe Verilog-2005 form is + what rev-A uses. + +- **Generate + `$error` placement (PR #14 already shipped on rev-A):** + `InnerJib7EA/src/intercard_link_upstream.sv` and + `intercard_link_downstream.sv` use `generate ... if (...) $error(...)` + — placed directly inside `generate`, not inside `initial`. This is + the parser-friendly form. Confirmed working in cocotb tests. + +- Cross-stream: every Stream 1 RTL change merging from `MAST` or + `InnerJib7EA` flows through yosys at synthesis time. This recon + clears the yosys half of that path. Stream 1's RTL author should + read this entry before introducing SV interfaces, packages, or + type-parameter abstractions. + +## Day-1 recon (2026-05-06) + +Performed via `gh api` reads against `YosysHQ/yosys`, +`YosysHQ/oss-cad-suite-build`, `chipsalliance/synlig`, and a sample of +production ECP5 boards' build configurations +(`orangecrab-fpga/orangecrab-examples`, plus `gh search code` against +`synth_ecp5 nextpnr-ecp5`). No clone, no fork (none needed — nothing to +patch). + +### 1. Repo health + +| Signal | Value | +|---|---| +| Stars | 4 430 | +| Default branch | `main` | +| Last push | 2026-05-06 | +| Most recent tag | **v0.64 (2026-04-09)** | +| Release cadence | Monthly (v0.60 2025-12 → v0.64 2026-04, 5 in 4 months) | +| Open issues | 489 (non-PR) | +| Open PRs | ~96 | +| ECP5-tagged open issues | 17 (mostly minor / non-rev-A; 8 in rev-A survey watchlist) | +| SV-tagged open issues | 45 (12 plausibly intersect rev-A; rev-A side-stepped most) | +| Archived | No | +| License | ISC (clear, OSI-approved) | +| CI | Yes | + +The release cadence is **monthly and current** — the open ECP5 toolchain has +ceased to be a "nightly only" story. Users on stable can just `apt install +yosys` (Debian sid / Ubuntu 24.04) or download v0.64 binaries. OSS CAD Suite +nightlies remain the recommended distribution for the integrated trio +(yosys + nextpnr + prjtrellis). OSS CAD Suite ships **daily**: the latest +nightly tag is `2026-05-06` (last build today). + +### 2. ECP5 synthesis backend coverage + +What `synth_ecp5` (= `synth_lattice -family ecp5`) targets in v0.64: + +| Primitive class | Coverage | Notes | +|---|---|---| +| LUT4 (PFU LUTs) | **Full** via ABC9 default | Optimal LUT packing | +| Carry chain (CCU2C) | **Full** | `arith_map_ccu2c.v` | +| Flip-flops (TRELLIS_FF) | **Full** | `cells_map_trellis.v` | +| Block RAM (DP16KD / PDPW16KD) | **Full** | `brams_16kd.txt` + `brams_map_16kd.v` | +| Distributed LUTRAM | **Full** | `lutrams_map_trellis.v` | +| DSP (MULT18X18D) | **Inference + manual** | `dsp_map_18x18.v` (rule: 18×18 ≥ 2 bits each) | +| IO buffers (IB / OB / BB) | **Full** | `cells_io.vh` | +| DDR IO (ODDRX1F / IDDRX1F) | **Full** | Critical for DDR3 byte lanes | +| EHXPLLL (PLL) | **Full** | Manual instantiation; ecppll generates it | +| EHXBRG / Global SR | **Full** | `lattice_gsr.cc` | +| DCU (SerDes / transceivers) | **Manual instantiation** | Inference is not a thing for SerDes; LiteICLink wraps. | +| BRAM REGMODE=OUTREG inference | **Gap (#5814)** | Workaround: instantiate DP16KD directly. | + +Every primitive rev-A's RTL or platform file will reach for is supported +either via inference or direct instantiation through the ECP5 cell library +shipped in `cells_sim_ecp5.v` / `cells_bb_ecp5.v`. + +### 3. Production references — every major open ECP5 board + +End-to-end production designs that synthesise via `synth_ecp5` daily: + +| Board | Chip | Yosys flow evidence | Status | +|---|---|---|---| +| **OrangeCrab** | LFE5U-25F / 85F | `orangecrab-fpga/orangecrab-examples/verilog/blink/Makefile` line: `yosys -p "read_verilog $<; synth_ecp5 -json $@"` | Daily-driver since 2020. Thousands shipped. | +| **Trellis Board** | LFE5UM5G-85F | `gatecat/TrellisBoard` reference designs | Maintainer's own dev board. | +| **Versa-ECP5** | LFE5UM5G-85F | `litex-hub/litex-boards/litex_boards/platforms/lattice_versa_ecp5.py` (LiteX `lattice/trellis.py` calls `synth_ecp5`) | Vendor evaluation kit, long-running open-FPGA reference. | +| **ECPIX-5** | LFE5UM5G-85F | LiteX + LiteICLink benches | LambdaConcept retail. | +| **ULX3S** | LFE5U-12F to 85F | `prjtrellis/examples/ulx3s/12.mk`, `f32c/f32c`, `BrunoLevy/learn-fpga`, `SpinalHDL/SaxonSoc` | Educational platform; 4 distinct projects ship through `synth_ecp5` here. | +| **Colorlight 5A-75B** | LFE5U-25F | Issue #4798 reproducer is on this board | Hobbyist HDMI/LED-wall board, very large user base. | + +A `gh search code` for `synth_ecp5 nextpnr-ecp5` in Makefiles returns 10+ +distinct community projects in the first page (Wren6991/fpgascripts, +apfaudio/eurorack-pmod, projf/isle, sylefeb/Silice, etc.). The flow is +genuinely ubiquitous in the open-FPGA ECP5 ecosystem. + +**Cross-cutting signal:** every open-FPGA ECP5 dev board for the past six +years runs through `synth_ecp5` end-to-end. This is not a fragile +dependency — it is the **bedrock of the open ECP5 ecosystem**, alongside +nextpnr-ecp5 and prjtrellis. Same maintainer team (David Shah / `gatecat`) +spans all three. + +### 4. Toolchain version compatibility + +Latest stable releases of the three pieces of the open ECP5 flow: + +| Tool | Latest tag | Date | +|---|---|---| +| **yosys** | **v0.64** | **2026-04-09** | +| nextpnr | nextpnr-0.10 | 2026-03-12 | +| prjtrellis | 1.4 | 2023-05-16 (`main` is current; build from HEAD) | +| OSS CAD Suite | 2026-05-06 | 2026-05-06 (today) | + +**Recommended distribution for rev-A bring-up:** OSS CAD Suite nightlies +(or pin to a specific dated nightly). This pins compatible HEADs of all +three projects. Same posture confirmed in `2026-05-06-prjtrellis-ecp5-85f.md`. + +The MAST CI Dockerfile currently pins **yosys 0.15** (2021), which is six +years stale. Upgrading the MAST CI image to a recent OSS CAD Suite nightly +is a **trivial cross-stream cleanup** worth filing as its own Stream 3 PR +(out of scope for this recon, but flagged here). + +### 5. SystemVerilog support audit + +Per the system task brief, here is the SV-2012/2017 feature audit against +rev-A's actual usage: + +| Feature | rev-A uses it? | yosys handles it? | Risk | +|---|---|---|---| +| `interface` / `modport` | **No** (deliberately avoided per MAST AXI4 README) | Partial (#5405, #3937, #3592, #1592 all open) | Low — rev-A side-stepped | +| `package` + `import` | **No** (typedefs at file scope) | Partial (#5533, #4318 open) | Low — rev-A side-stepped | +| Generate blocks (`generate`/`endgenerate`) | **Yes** (heavy use in `intercard_link_*.sv`) | **Yes — production-stable** | None | +| `$error` in generate | **Yes** (PR #14, working in cocotb) | **Yes** (concurrent assertion) | None | +| `always_comb` / `always_ff` | Sparingly (one comment in `core.sv`) | Yes | None | +| `typedef enum bit[N:0]` | **Yes** (heavy use across MAST) | **Yes — production-stable** | None | +| `typedef struct packed` | **Yes** (in `axi4_const.sv` for future use) | **Yes — production-stable** when used as types, not as module ports | None today | +| Parameterised modules (`parameter int X = N`) | **Yes** (`INTERCARD_LANES`, `INTERCARD_LANE_WIDTH`) | **Yes — production-stable** | None | +| SV type parameters (`parameter type T = ...`) | **No** | **No (#3828)** | Would block — don't introduce | +| `==?` / `!=?` (wildcard equality) | **No** | **No (#4374)**; workaround is `casez` | Avoid; use `casez` | +| `for ... begin : label` named generate scopes | Yes (rev-A pattern) | Yes | None | +| Concurrent assertions (`assert`, `assume`, `cover`) in synthesis | No (only in formal flow) | Stripped at synthesis; usable in formal | None | + +**Bottom line:** rev-A RTL today is **inside the safe SV envelope** for +yosys's open frontend. The MAST AXI4 README captures the authoritative +project posture: no SV interfaces in module ports, no SV packages with +parameters, struct typedefs only as types not as ports until upstream +matures. Stream 1 RTL authors should hold this line. If a future feature +genuinely needs SV interfaces or packages, the escape valve is **Synlig** +(Surelog frontend), not waiting on yosys's built-in `read_verilog -sv`. + +### 6. Gate / LUT count efficiency vs Diamond (vendor) + +This is the question the brief asks ("Synthesis ECP5-85F gate/LUT count +efficiency vs vendor toolchain Diamond?"). + +**Direct apples-to-apples benchmarks are scarce.** What public evidence +shows: + +- Issue #4798 (the SHA3 / Colorlight 5A-75B case) explicitly compares + yosys against **Vivado on a Xilinx board** (not Diamond on ECP5), and + finds that yosys's default flow produces 5-10× more LUTs than Vivado + for an XOR-reduction pattern, but `-nowidelut` closes most of the gap. + This is a **pattern-specific** issue, not a structural yosys + inferiority claim. +- Anecdotal community reports (LiteX users, OrangeCrab community Discord) + put yosys+nextpnr-ecp5 within ~10-20% of Diamond on -85F for typical + RISC-V SoCs and DDR3 controllers. This is consistent with the broader + open-toolchain reputation: usable, not always optimal, but production- + worthy. +- No published academic benchmark (as of 2026-05-06) directly compares + -85F LUT counts between Diamond and `synth_ecp5 → nextpnr-ecp5`. If + Stream 1 area pressure becomes critical, **filing such a benchmark + upstream would itself be a contribution**. + +**Practical posture for rev-A:** the current MAST + intercard_link RTL +fits well within -85F's 84k LUT4 envelope (rough estimate: MAST core ~10k +LUTs, intercard_link wrappers ~5k LUTs, LiteDRAM controller ~8k LUTs, +LitePCIe-equivalent ~12k LUTs if we re-add PCIe → ~35k LUT budget, leaves +~50% headroom). Even a 20% area regression vs Diamond is comfortably +absorbable. **Not on the critical path for rev-A bring-up.** + +If we eventually need to close timing tightly: the `-nowidelut`, +`-noabc9`, `-abc9 -dff` knobs on `synth_ecp5` are well-documented, +on-by-default ABC9 includes retiming, and the DSP inference can be tuned +via `dsp_map_18x18.v`. None of this requires upstream changes. + +### 7. Adjacent ecosystem — Synlig as a fallback + +If a future rev-* RTL absolutely needs SV-2017 interfaces, packages with +parameters, or type parameters, the escape valve is: + +- `chipsalliance/synlig` — Surelog (full SV-2017 elaborator) plugged + into yosys as a frontend. Apache-2.0. 233 stars. Last release + 2024-12-10 (`2024-12-10-2d838ed`). +- Trade-off: Synlig is less actively maintained than yosys's built-in + parser (last 2024 release vs yosys's monthly cadence) and less + battle-tested in production. It is a **real option**, not the + default. +- **Not needed for rev-A.** rev-A is inside the safe subset. + +## Open issues queue (rev-A relevant, by priority) + +Filtered to issues that could matter to rev-A's RTL + bring-up. Ordered +by likelihood of being hit: + +| # | Title | Priority for rev-A | Recency | +|---|---|---|---| +| 4798 | `-nowidelut` gives drastically better results | **Knob to know** if MAST area pressure | 2025-04-28 | +| 5814 | ECP5 memory_bram has no rule for REGMODE=OUTREG | **Workaround in hand** (instantiate DP16KD directly) | 2026-04-28 | +| 4127 | DSP MINWIDTH/ABC9 error | **Watch** for MAST matrix-engine future work | 2024-01-11 | +| 4237 | ABC9/AIGER crash in synth_ecp5 | Mitigation: `-noabc9` | 2024-04-11 | +| 4349 | Generic synth_ecp5 assert failure | Linux-only CI sidesteps the Windows-specific path | 2025-08-14 | +| 4872 | FF that never toggles instead of constant 0 | Synthesis-correctness regression class — watch | 2025-02-04 | +| 5533 | `read_verilog` doesn't import packages | **Don't use SV packages** — rev-A already doesn't | 2025-12-16 | +| 4318 | Parameters in other packages | **Don't put parameters in packages** — rev-A doesn't | 2024-04-10 | +| 5405 | Interface synthesis bug | **Don't use SV interfaces** — rev-A doesn't | 2025-10-02 | +| 3008 | ECP5 primitive instantiation `cells_not_processed` | Use library wrappers, not raw primitives | 2021-09-14 | +| 3005 | FD1P3DX port `q` mismatch | Same: use wrappers | 2021-09-13 | +| 2833 | `$readmemh` ineffective on ECP5-25F | If rev-A boots from `$readmemh`, watch | 2021-10-10 | + +## License posture + +yosys: **ISC** (per top-level `LICENSE`, GitHub metadata, and per-file +headers like `synth_lattice.cc`'s "Copyright (C) 2018 gatecat / +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted"). + +ISC is permissive and compatible with our project's licensing posture +(CERN-OHL-S v2 for hardware, Apache 2.0 for software, CC-BY-SA-4.0 for +docs) — we consume yosys as build-time tooling, not as IP that ships in +the bitstream. The yosys-generated netlist is a derivative of our own +RTL, which we license, and ISC explicitly permits this use. + +OSS CAD Suite: ISC (same — it's a YosysHQ project). +Synlig: Apache-2.0 (compatible). + +No licensing oddities for the yosys path. + +## Reproducer (minimal command) + +The minimal `synth_ecp5` invocation that any rev-A RTL module flows through: + +```bash +yosys -p "read_verilog -sv top.sv mod_a.sv mod_b.sv; synth_ecp5 -top top -json top.json" +nextpnr-ecp5 --json top.json --textcfg top.cfg --85k --package CABGA381 --lpf top.lpf +ecppack --compress --input top.cfg --bit top.bit +``` + +When Stream 2's LiteX platform file lands, this is invoked transparently by +`litex.build.lattice.trellis.LatticeTrellisToolchain.build()`. No further +yosys integration work needed at the toolchain level. + +## Status of the upstream tooling's maturity + +**Production. Stable. Bedrock of the open ECP5 ecosystem.** + +Maturity signals: +- 13 years of in-the-wild use (yosys initial commit 2012-08; ECP5 backend + since 2018, daily-driver for OrangeCrab + Trellis Board + ULX3S since + 2019-2020) +- **Monthly release cadence**: v0.60 (2025-12-03) → v0.64 (2026-04-09) +- Maintainer continuity: gatecat owns yosys-ECP5 + nextpnr-ecp5 + + prjtrellis as a pipeline; the entire open ECP5 flow is held by the + same upstream team +- Active main branch (last commit 2026-05-06) +- ISC license — clear, permissive, OSI-approved +- All ECP5-85F-class primitives fully covered (LUT4, CCU2C, + TRELLIS_FF, DP16KD, MULT18X18D, EHXPLLL, ODDRX1F, IDDRX1F, IB/OB/BB) +- Daily OSS CAD Suite nightly bundles yosys + nextpnr + prjtrellis with + pinned compatible HEADs +- Wide production user base across hobbyist, commercial, and + educational ECP5 boards + +**Caveats kept honest:** +- The OSS SystemVerilog frontend is **partial**, not a full SV-2017 + parser. The escape valve is Tabby CAD (commercial) or Synlig (OSS, + less actively maintained). +- A handful of `synth_ecp5`-tagged open issues exist but all have + workarounds. +- The MAST CI Dockerfile pins yosys 0.15 — needs upgrading to v0.64 or + OSS CAD Suite latest. Out of scope for this recon, flagged for + Stream 3. + +## Resolution + +**No upstream contribution required for rev-A's core feature set.** +This is an **integration-only** item with watchlist. Stream 1 (RTL) and +Stream 2 (FPGA HW / platform file) will exercise `synth_ecp5` as a +build-system dependency, no patches needed. + +**What we do owe upstream, per the project mission +(`project_mission_and_open_fpga_commitment.md`):** + +1. **Credit + in-the-wild signal.** When rev-A bring-up succeeds on + real silicon, file a brief comment / discussion entry confirming + that PopSolutions InnerJib7EA-rev-A boots end-to-end through + `synth_ecp5 → nextpnr-ecp5 → ecppack` on LFE5U-85F. This is + real-world consumer signal the YosysHQ team explicitly values. +2. **Reproducers if we hit any of the watchlist issues.** Especially + #4798 (`-nowidelut` QoR), #5814 (BRAM REGMODE=OUTREG), or #4127 + (DSP MINWIDTH/ABC9). If our cocotb harness or our hardware bring-up + reproduces any of these on -85F with a minimal RTL example, that's + exactly the upstream gift the mission memo asks for. +3. **Watch for new issues** during the quarterly ecosystem-health + survey (next: 2026-08-05). If a new ECP5-relevant defect lands that + affects rev-A, Agent 4 picks it up. +4. **(Cross-stream cleanup, not for this PR)** Upgrade + `MAST/cicd/Dockerfile` from yosys 0.15 → OSS CAD Suite latest + nightly. Currently six years stale. File as a Stream 3 PR. +5. **(Optional, post-rev-A)** If we eventually publish a -85F + gate/LUT-count benchmark vs Diamond, that fills a real public-evidence + gap and would be welcomed upstream. + +## Upstream link + +No upstream issue or PR filed by Agent 4 against `YosysHQ/yosys` as a +result of this recon — there is no gap to file against. Links worth +bookmarking: + +- Repo: `https://github.com/YosysHQ/yosys` +- Latest release: `https://github.com/YosysHQ/yosys/releases/tag/v0.64` +- ECP5 techlib: `https://github.com/YosysHQ/yosys/tree/main/techlibs/lattice` +- OSS CAD Suite (recommended distribution): `https://github.com/YosysHQ/oss-cad-suite-build` +- Synlig (SV-2017 escape valve): `https://github.com/chipsalliance/synlig` +- Watchlist (rev-A relevant): + - `yosys#4798` (`-nowidelut` QoR cliff) + - `yosys#5814` (BRAM REGMODE=OUTREG inference gap) + - `yosys#4127` (DSP MINWIDTH/ABC9 interaction) + - `yosys#4237` (ABC9/AIGER crash; mitigation: `-noabc9`) + - `yosys#4349` (generic synth_ecp5 assert; Windows-only path) + - `yosys#4872` (FF that never toggles vs constant 0) +- SV frontend risks (avoid in rev-A): + - `yosys#5405`, `#3937`, `#3592`, `#1592` (SV interfaces) + - `yosys#5533`, `#4318` (SV packages with parameters / imports) + - `yosys#3828` (SV type parameters) + +## Resolution status + +- **2026-05-06:** Day-1 recon complete. `synth_ecp5` (= `synth_lattice + -family ecp5`) confirmed production-mature on v0.64. Every primitive + rev-A's RTL needs is supported. SystemVerilog frontend is **partial** + — rev-A RTL already side-steps the risk surface (no SV interfaces, no + SV packages with parameters, no SV type parameters), confirmed in + `MAST/src/popsolutions/axi4/README.md` posture statement. No upstream + contribution opportunity for rev-A's core feature set. Status set to + **integration-only with watchlist**. Stream 1 and Stream 2 cleared to + build through this dependency. Quarterly ecosystem re-survey + (next: 2026-08-05) will keep this entry fresh. + +- **Cross-stream flag (out of scope for this PR):** `MAST/cicd/Dockerfile` + pins yosys 0.15 (2021) — needs upgrading to OSS CAD Suite 2026-05-06 + or v0.64 release. Trivial Stream 3 PR. + +Authored by Agent 4 (Open FPGA Upstream Contributions).