FPGA-Neural/docs/FPGA-Neural-Hardware-Design.md

FPGA-Neural — Hardware Design Document

Status: draft, pre-schematic. Component choices below are researched against current distributor listings (2026-09-02) but not yet ordered/prototyped. No PCB layout exists yet.

Goal: a board carrying the project's actual target device (LFE5U-45F-8BG381C) plus the parallel PSRAM the current RTL (rtl/psram_controller.v) is written for, so real hardware exists to run everything already synthesized/benchmarked in this repo.

---

1. Why a new board (not basic-ecp5-pcb)

A reference ECP5 dev board (Matt Venn's basic-ecp5-pcb, OSHWA-approved, in this workspace at ../basic-ecp5-pcb) exists and is a useful source of proven power/config circuitry — but it carries the wrong chip for this project and has no RAM at all:

	basic-ecp5-pcb	This project's target
Device	LFE5U-45F-6BG256C	LFE5U-45F-8BG381C
Package	256-ball CABGA	381-ball CABGA
Speed grade	-6 (slowest ECP5 grade)	-8 (fastest ECP5 grade)
RAM	none (6 PMODs, no memory chip)	parallel PSRAM required

Same die (LFE5U-45F, same 44K LUT / 72 DSP), different package and a materially slower speed grade. All Fmax numbers measured so far in this repo (docs/FPGA-NeuralNetwork-Engine.md §15 "Phase 7 — Optimization") target the -8 grade; they do not directly transfer to a -6 part.

What we reuse from it anyway: the power tree and bitstream-config approach (§4, §5) are package-independent and already validated on real, shipped hardware — no reason to redesign those from scratch.

---

2. I/O pin budget (real ball data, CABGA381)

Extracted from Lattice's own ECP5-45 pinout table (../basic-ecp5-pcb/docs/ECP5Upinouts.ods, sheet ECP5U45Pinout, CABGA381 column) — not estimated. Caveat added 2026-09-03: that spreadsheet is no longer present in this environment, so these per-bank counts could not be re-verified against it. §7's actual pin assignment instead uses Project Trellis's own device database directly (same data nextpnr-ecp5 uses) and gets somewhat lower generic-I/O counts per bank (e.g. 32/33 usable in banks 2/3 vs. 35/36 here) — Trellis's packages/pio_metadata only enumerates programmable I/O, not every ball a full datasheet table would list as "usable I/O" (some datasheet-usable balls may not appear as ordinary PIO sites in Trellis's model). The totals below are kept for historical reference; §7 is the verified source for actual pin placement:

Bank	Usable I/O balls
0	29
1	35
2	35
3	36
6	36
7	35
8	22
40 (config-related)	4
Total usable	~232
Power/ground/NC (remaining of 381 balls)	149

Signal budget this design actually needs:

Function	Pins
PSRAM (psram_a 22b worst case, psram_dq 16b, ce_n/oe_n/we_n/lb_n/ub_n/zz_n 6b)	up to 44 (real usage likely less — see §3, address lines can be trimmed to match actual chip density)
Application SPI (sclk/mosi/miso/cs_n)	4
clk, rst	2
Host attention (irq_n, data_ready_n, added 2026-09-03 — §7)	2
Config SPI (to onboard FLASH)	3 (flash_mosi/flash_miso/flash_cs_n — SCLK shared via USRMCLK, no dedicated pin, confirmed against yosys's own cells_bb.v blackbox; implemented Phases F1-F6)
JTAG (recommended, for bring-up/debug)	4
Total	~59

~59 of ~232 usable I/O used (56 actually placed and place&route-verified in the flash-subsystem synthesis, synth/ecp5/spi_neuron_top_flash/ nextpnr.log) — plenty of headroom (~170+ spare pins) for LEDs, buttons, a debug PMOD-style header, or a second SPI host, without any pin-count pressure. This board does not need to be pin-constrained the way a 256-ball/PMOD-only design would.

---

3. PSRAM subsystem (the piece basic-ecp5-pcb doesn't have)

rtl/psram_controller.v implements an asynchronous parallel interface with page-mode burst reads — address bus, 16-bit data bus, ce_n/oe_n/we_n and byte-lane lb_n/ub_n, plus zz_n — and its timing already hardcodes a 70 ns random-access latency assumption (ACCESS_CYCLES = ceil(70ns × CLK_FREQ_MHZ / 1000)). This is a classic async-SRAM-style bus, not QSPI — most "PSRAM" sold today (including what's on typical ESP32 boards) is serial/QSPI and will not plug into this controller without a rewrite.

Page mode (2026-09-03, psram_page_mode_tb.v): the ISSI part is "asynchronous/page mode", meaning sequential reads inside the same 16-word page (address bits above A[3] unchanged) don't need the full 70 ns each — only tAPA/tPC = 20 ns, once CE#/OE# are already asserted. Earlier revisions of this controller did not use that mode at all — every access, sequential or not, paid the full random-access latency. The controller now:

• Enables page mode on the chip itself at power-up, via the datasheet's software configuration-register sequence (2 dummy reads + 2 writes at the top address, CR = 0x00F0) — page mode is off by default on the real chip, so this step is load-bearing, not cosmetic.
• Keeps CE#/OE# asserted after a read completes (STATE_PAGE_OPEN) instead of closing every single-word transaction; a following read in the same page only pays tAPA; a following read in a different page still avoids a CE# toggle but pays a full tAA for that one word (matches the datasheet: "any change in addresses A[4] or higher initiates a new tAA access time").
• Byte-enable (lb_n/ub_n) changes do not close the page. int8_memory_access.v alternates them on nearly every access (byte-granular reads over the 16-bit bus), so treating that as a close condition — the first implementation attempt — made the real workload slower, not faster (measured regression, corrected before this was documented as done: see docs/FPGA-Neural-Datapatch-Benchmark.md for before/after numbers). Only a WRITE, or holding CE# low for close to the 8 µs tCEM refresh limit, closes the page.
• sim/psram_model.v (the timing-strict simulation model used by every PSRAM-backed testbench) was extended with its own independent tAPA/tAA continuation check, so a passing regression run is a real timing proof, not just a data-match.

Recommended part: ISSI IS66WVE4M16EBLL-70BLI

• 64 Mbit (4M × 16), parallel pseudo-SRAM, async, 70 ns access — matches the controller's timing assumption exactly, no RTL change needed.
• TSOP-44/48 package — hand-solderable-adjacent, real distributor listings (DigiKey, Mouser) at time of writing.
• Address bus (2026-09-02: full addressing, all 22 chip lines wired): the chip is 4M×16 words (8 MB total), needing a real 22-bit word address, A0–A21. ADDR_WIDTH is now 23 bits across every module (rtl/neuron_memory.v, rtl/psram_controller.v, etc. — bumped from the earlier 22-bit/ 4 MiB default specifically to reach the full chip). int8_memory_access.v right-shifts the 23-bit byte address by 1 (addr >> 1) into a 22-bit word address before it reaches psram_controller — that 22-bit word address maps exactly onto the chip's real A0–A21, with nothing left unconnected. Full 8 MB is addressable today, not deferred.

Fallback: ISSI IS61WV6416DBLL / IS61WV102416BLL (true async SRAM, not pseudo-SRAM) — electrically drop-in on the same ce_n/oe_n/we_n/lb_n/ub_n signals, no internal refresh (so zz_n can just be tied inactive), faster than needed (~10 ns), useful if the ISSI PSRAM specifically is out of stock. Smaller density (1–16 Mbit depending on exact part) — fine for this project's current memory footprint (weights/biases/activations for the networks exercised so far are well under 1 MB).

Real part numbers, not yet ordered — verify current stock/pricing before BOM lock.

---

4. Clock

basic-ecp5-pcb uses a fixed 16 MHz MEMS oscillator (SiTime SiT2001B family) — no crystal driver on the ECP5, the clock input must come from an oscillator IC into a PCLK pad.

Recommendation: keep 16 MHz, same SiT2001B family (or SiT1602/SiT8008, same vendor, also in stock). Rationale, not just "reuse what worked":

• No PLL exists anywhere in this project's RTL yet — CLK_FREQ_MHZ is a timing parameter, not a clock generator. Whatever oscillator is fitted drives clk directly.
• Every Fmax measured so far for the full integrated system (spi_neuron_top, Phase 5) sits at 39.5–45 MHz across a seed sweep (docs/FPGA-NeuralNetwork-Engine.md §15 "Phase 7 — Optimization") — confirmed structural, not placement luck. 16 MHz sits well under that with real margin.
• CLK_FREQ_MHZ must be set to match whatever oscillator is actually fitted (16, if this recommendation is taken) — it feeds the PSRAM access-timing formulas directly (§3); using the RTL's default of 80 with a 16 MHz real clock would under-time the PSRAM by 5×.

A higher oscillator (e.g. 25 or 32 MHz) is possible with margin to spare, but revisit once the Phase 7 timing-closure work (docs/FPGA-NeuralNetwork-Engine.md) lands rather than guessing a number now.

---

5. Power

Reuse basic-ecp5-pcb's proven three-rail tree as-is (same device family, same rail requirements regardless of package):

Rail	Value	Part	Load	Status
Core	1.1 V	TLV62568 (buck)	≥600 mA	Confirmed in production, DigiKey/Mouser listed
I/O	3.3 V	TLV62568 (buck)	1 A (all banks + PSRAM + PMODs share this)	Confirmed in production
Auxiliary	2.5 V	TLV73325 (LDO)	10 mA	Confirmed in production

Decoupling: one cap per I/O bank minimum, per Lattice's ECP5 Hardware Checklist (referenced by basic-ecp5-pcb, not re-derived here).

---

6. Configuration (bitstream load)

Reuse basic-ecp5-pcb's SPI-FLASH-boot approach:

• W25Q128JV SPI NOR flash (16 MB) — confirmed in production, multiple package options (WSON, SOIC) currently listed.
• ECP5 reads its bitstream from this flash at power-on (sysCONFIG SPI master mode); no external programmer needed for normal power-up, only for the initial flash write.

Lessons reused from basic-ecp5-pcb's errata (do not re-discover these the hard way):

• Config-mode select pins should tie directly to GND, not through a 10 k resistor — the ECP5 test point is ~1 V, too close to the 3.3 V bank's input threshold through a resistor divider.
• Not every SPI flash that claims QSPI actually has a usable QE (quad-enable) bit in practice — basic-ecp5-pcb hit this with an IS25LP016D and switched to the W25Q12x family instead. Stick with W25Q128JV rather than substituting on price alone.
• The dedicated config-SPI clock pin cannot be reused as a general input post-configuration without extra board-level workaround (basic-ecp5-pcb needed a bodge wire to let a Raspberry Pi talk SPI to the FPGA over the same physical pin used for flash boot). This project's application SPI (spi_neuron_top's sclk/mosi/miso/cs_n, the host-facing protocol in docs/FPGA-NeuralNetwork-Engine.md §8.1) must land on separate, ordinary I/O pins — never the config-SPI pins — precisely to avoid needing that same workaround.

---

7. Signal map — real .lpf, place&route-verified (2026-09-03)

Source of truth changed from the plan in §2: the ../basic-ecp5-pcb/docs/ECP5Upinouts.ods spreadsheet referenced there is no longer present in this environment. The assignment below instead comes directly from Project Trellis's own device database (prjtrellis's database/ECP5/LFE5U-45F/iodb.json) — the same data nextpnr-ecp5 itself uses — joining each CABGA381 ball to its bank and any dual function via pio_metadata. This is real data, not invented numbers, and it has been verified by an actual nextpnr-ecp5 place&route run, not just picked by eye:

nextpnr-ecp5 --45k --package CABGA381 --speed 8 --freq 80 \
  --json synth/ecp5/spi_neuron_top_graph/top.json \
  --lpf synth/ecp5/spi_neuron_top.lpf \
  --textcfg <out>.config

Result: 0 constraint errors, full route completes, Program finished normally (log: synth/ecp5/spi_neuron_top_graph/nextpnr_constrained.log). Fmax with this real, fixed pinout: 54.58 MHz at the time this pinout was first verified (FAIL at the 80 MHz target; the critical path was then the saturation-comparator carry chain in rtl/neuron_parallel.v, unrelated to pin placement). Superseded 2026-09-03 by the timing-closure work in WORKLOG.md ("Timing closure di neuron_parallel"): with the same real pinout, Fmax is now 75.30 MHz (up from 55.59 MHz unconstrained originally) — the pin assignment itself did not need to change, only the RTL critical path did. Further updated 2026-09-03 after adding the irq_n/data_ready_n host attention pins (2 more signals, same bank 7, no other ball reassigned): re-verified with a fresh place&route run, 0 constraint errors, Fmax 73.88 MHz (within the same noise band already characterized for this pin count in WORKLOG.md's timing-closure seed sweep — not a regression). TRELLIS_IO usage: 53/245 (21%) — still confirms the §2 headroom estimate.

Further updated 2026-09-04 after the flash subsystem (Phases F1-F6, WORKLOG.md) added 3 real pins (flash_mosi, flash_miso, flash_cs_n — bank 7, generated additively by tools/pinout/gen_lpf.py, confirmed via git diff on synth/ecp5/spi_neuron_top.lpf to leave every existing ball unchanged; no dedicated flash SCLK pin — it reuses the same USRMCLK primitive already driving the application-SPI/config path, per §7): full-system real Yosys+nextpnr-ecp5 synthesis (synth/ecp5/ spi_neuron_top_flash/nextpnr.log), 0 constraint errors, full route completes, Fmax 66.68 MHz. The critical path is confirmed unchanged from the pre-existing neuron_parallel accumulator carry chain (no flash-subsystem module appears in the reported critical path) — the 66.68 vs 73.88 MHz difference is attributed to placement/routing noise from the added I/O and logic, not a new bottleneck. TRELLIS_IO usage: 56/245 (23%).

Cross-checked against the real Lattice datasheet (2026-09-03, user- provided FPGA-DS-02012-3-4-ECP5-ECP5G-Family-Data-Sheet.pdf): its §4.3.2 "LFE5U" Pin Information Summary table gives, for LFE5U-45 / 381caBGA, GPIO counts per bank of 27/33/32/32/–/33/32/13 (banks 0/1/2/3/4/6/7/8) — this matches the Trellis-derived counts used above exactly on 6 of 7 relevant banks, off by exactly 1 ball on bank 3 (33 in Trellis's model vs 32 in the datasheet, immaterial here since only 33 of that bank's balls were even candidates and none of the 51 actually assigned came from the contested one). Strong independent confirmation that using Trellis's device database in place of the no-longer-available spreadsheet was the right call, not a shortcut that introduced drift.

What the datasheet does NOT have, confirmed by reading all of it (115 pages, §4 "Pinout Information" in full): any ball-by-ball table. §4.1 is purely functional signal descriptions (no ball numbers at all) and §4.3 is only the summary-count table quoted above — Lattice ships the actual per-ball assignment as a separate resource (spreadsheet/pinout file, e.g. the .ods originally referenced, or Diamond/Radiant's own device database), not inside this PDF. This means the config-SPI (PROGRAMN, INITN, DONE, CCLK, CFG[2:0] — the datasheet's "Miscellaneous Dedicated Pins", counted at 7 for this package) and JTAG (TCK/TMS/ TDI/TDO — its "TAP", counted at 4) ball numbers are still not pinned down to specific balls here.

That gap does not block anything in this repo, though: those pins are dedicated/fixed-function silicon, not part of any user netlist — rtl/ spi_neuron_top.v has no TCK/TMS/TDI/TDO/PROGRAMN/etc. ports, so nextpnr- ecp5 never needs a LOCATE for them (confirmed by the 0-error run above, which never mentions them) and no .lpf entry is possible or necessary for them regardless. Their exact ball numbers only matter for PCB schematic capture — routing a JTAG header connector and the SPI config-flash chip — which is the user's own separate, in-progress KiCad work (untracked FPGA-Neural/ directory at the repo root), not an RTL/synthesis deliverable. Downgraded accordingly in the checklist below.

Placement rationale (die-edge geometry from Trellis's globals.json, confirmed by joining ball → (col,row) → bank): banks 2 (die col=90, row 11–32) and 3 (col=90, row 35–68) sit contiguously along the chip's right edge — used together for the whole 44+1-signal PSRAM bus, exactly the "one or two adjacent banks" the appendix asks for. Bank 7 (col=0, row 11–32, the left edge, physically opposite the PSRAM bus) holds the application SPI

• clock/reset, deliberately on the opposite side from PSRAM to keep the two buses from crossing. clk is pinned to H5 (GR_PCLK7_0), a dedicated global-clock pad in bank 7. Plain (no dual-function) balls were preferred first within each bank; where a bank ran out of plain balls (bank 2, for part of psram_dq), the next-best dual-function ball was used as ordinary GPIO — flagged individually below, and confirmed by the actual nextpnr run above to be perfectly usable as such (including the one VREF1_2 ball).

psram_a[22] is a real synthesized port bit (ADDR_WIDTH=23 sizes the byte address everywhere in this design) that is always 0 in practice — see §3: int8_memory_access.v shifts the byte address right by 1 before it reaches the PSRAM, so only 22 bits (psram_a[21:0]) ever carry real address information, matching the chip's actual 4M-word (2²²) capacity. It still needs a physical pin for the tool, given a spare ball, and is a no-connect on the actual board.

Clock / reset:

Signal	Ball	Bank	Note
clk	H5	7	GR_PCLK7_0 — dedicated global clock pad
rst	B4	7

Application SPI:

Signal	Ball	Bank	Note
cs_n	B3	7
miso	A3	7
mosi	C5	7
sclk	B5	7

Host attention pins (added 2026-09-03, active-low, level, driven from already-registered sticky bits — see rtl/spi_neuron_top.v for the exact rationale):

Signal	Ball	Bank	Note
data_ready_n	C3	7	low while a result is waiting to be read (mirrors STATUS.bit1, clear-on-STATUS-read)
irq_n	C4	7	low while graph_engine's load-time guard has tripped (mirrors STATUS.bit2 / §7 of the network-engine spec); clears only on RESET or a fresh graph run_start, NOT on a plain STATUS read

Flash subsystem — runtime SPI to the onboard W25Q128JV (added 2026-09-04, Phases F1-F6 — rtl/spi_flash_master.v, WORKLOG.md; ordinary GPIO, generated the same additive way as every other row here, confirmed by git diff against the pre-flash .lpf to leave every existing ball unchanged):

Signal	Ball	Bank	Note
flash_cs_n	E4	7
flash_miso	D5	7
flash_mosi	D3	7

No flash_sclk ball: SCLK is driven through the USRMCLK primitive, reclaiming the same physical CCLK net already used for bitstream boot — see §6/§9 for the board-level wiring implication (the flash chip's DI/DO/CS pins must be dual-wired to both the dedicated sysCONFIG pins and these 3 ordinary balls).

PSRAM address:

Signal	Ball	Bank	Note
psram_a[0]	E16	2
psram_a[1]	F16	2
psram_a[2]	D18	2
psram_a[3]	E17	2
psram_a[4]	E18	2
psram_a[5]	F18	2
psram_a[6]	F17	2
psram_a[7]	G16	2
psram_a[8]	G18	2
psram_a[9]	H16	2
psram_a[10]	H17	2
psram_a[11]	H18	2
psram_a[12]	J16	2
psram_a[13]	J17	2
psram_a[14]	C20	2
psram_a[15]	D19	2
psram_a[16]	E19	2
psram_a[17]	E20	2
psram_a[18]	F19	2
psram_a[19]	F20	2
psram_a[20]	G20	2
psram_a[21]	H20	2
psram_a[22]	P18	3	always 0 (23-bit byte ADDR_WIDTH / 22-bit real word address, §3) — NC on the board

PSRAM data:

Signal	Ball	Bank	Note
psram_dq[0]	K18	2
psram_dq[1]	C18	2	dual-function ball (URC_GPLL0T_IN), used here as plain GPIO
psram_dq[2]	D17	2	dual-function ball (URC_GPLL0C_IN), used here as plain GPIO
psram_dq[3]	D20	2	dual-function ball (VREF1_2), used here as plain GPIO
psram_dq[4]	G19	2	dual-function ball (GR_PCLK2_1), used here as plain GPIO
psram_dq[5]	J18	2	dual-function ball (GR_PCLK2_0), used here as plain GPIO
psram_dq[6]	J19	2	dual-function ball (PCLKT2_1), used here as plain GPIO
psram_dq[7]	J20	2	dual-function ball (PCLKT2_0), used here as plain GPIO
psram_dq[8]	K19	2	dual-function ball (PCLKC2_1), used here as plain GPIO
psram_dq[9]	K20	2	dual-function ball (PCLKC2_0), used here as plain GPIO
psram_dq[10]	L17	3
psram_dq[11]	M18	3
psram_dq[12]	M17	3
psram_dq[13]	N16	3
psram_dq[14]	N18	3
psram_dq[15]	P17	3

PSRAM control:

Signal	Ball	Bank	Note
psram_ce_n	N17	3
psram_lb_n	T16	3
psram_oe_n	R16	3
psram_ub_n	N19	3
psram_we_n	R17	3
psram_zz_n	N20	3

---

8. Bill of materials (draft)

Ref	Part	Function	Availability
U1	LFE5U-45F-8BG381C	FPGA	Already the project's confirmed target (see main docs, price/stock table)
U2	ISSI IS66WVE4M16EBLL-70BLI	Parallel PSRAM, 64Mb, 70ns	Verified listed, DigiKey/Mouser
U3, U4	TLV62568	Buck converter, core + IO rails	Confirmed in production
U5	TLV73325	LDO, 2.5V aux rail	Confirmed in production
U6	W25Q128JV	SPI NOR flash, config	Confirmed in production, multiple packages
Y1	SiT2001B, 16 MHz	System clock oscillator	Confirmed in production

Not yet specified: exact package/footprint per part, decoupling cap values, JTAG header, PSRAM address-bus trim if a smaller/cheaper density than 4M×16 turns out to be sufficient once real network sizes are decided.

---

9. Open items before schematic capture

• ADDR_WIDTH set to 23 (full 8 MB) across all RTL modules and testbenches, matching the recommended part's real capacity (2026-09-02) — see §3.
• If the fallback true-SRAM part in §3 is used instead (smaller density), decide whether to shrink ADDR_WIDTH back down to match it or keep 23 with the extra range simply unused.
• Real .lpf pin assignment for clk/rst/application SPI/PSRAM (§7, synth/ecp5/spi_neuron_top.lpf), place&route-verified (2026-09-03) — 0 constraint errors; cross-checked against the real Lattice datasheet (§7, matches on 6/7 banks exactly). Fmax 54.58 MHz when this pinout was first verified, 75.30 MHz after the neuron_parallel timing-closure work, 73.88 MHz after adding the host-attention pins, and 66.68 MHz for the current full system including the flash subsystem (§7, 2026-09-04) — see §7 for the full history and why each change is pin-placement noise, not a regression. Config-SPI and JTAG ball numbers are still not pinned down (§7) — confirmed by reading the full real datasheet that it has no per-ball table at all (only functional descriptions and summary counts: TAP=4, misc dedicated=7 for this package), so the actual per-ball assignment remains a separate Lattice resource not available in this environment. This does not block any RTL/synthesis work: those are dedicated/fixed- function pins with no corresponding port in rtl/spi_neuron_top.v, so no .lpf entry is possible or needed for them, and every place&route run above already completes with 0 errors without them. They only matter for PCB schematic capture (JTAG header + config-flash routing) — the user's own separate, in-progress KiCad work, not something this repo's synthesis flow needs to resolve. Distinct from this open item (do not conflate the two): the flash subsystem's own runtime SPI pins (flash_mosi, flash_miso, flash_cs_n — Phases F1-F6, WORKLOG.md) are real, pinned, place&route-verified ordinary GPIO on bank 7 (flash_mosi=D3, flash_miso=D5, flash_cs_n=E4), generated the same way as every other signal in this table. Only SCLK is shared with the dedicated config-boot clock, reclaimed post-configuration via the USRMCLK primitive (confirmed against yosys's own cells_bb.v blackbox) — it needs no .lpf entry of its own, same reasoning as the dedicated pins discussed above. §5's PCB-level implication: the W25Q128JV's DI/DO/CS pins must be wired to both the dedicated sysCONFIG pins (for boot) and these 3 ordinary GPIO balls (for runtime access after configuration completes) — a board-level dual-wiring the same shape as the CCLK-reuse workaround already noted above, not yet reflected in a schematic since none exists yet (see the KiCad item below).
• Confirm PSRAM/SPI signal integrity at whatever clock is actually fitted (§4) — no signal integrity analysis done yet
• JTAG header footprint choice (blocked on the JTAG ball question above)
• KiCad (or other) schematic capture — none exists yet for this device/package combination