FPGA-Neural/hardware/v2/docs/PRE_PCB_CLOSURE_4POINT.md

FPGA-Neural V2 — FINAL 4-POINT PRE-PCB CLOSURE

Follows PRE_PCB_VERIFICATION.md (PRE-PCB VERIFIED baseline, commit d6376e8 + 8890b0a + eb0b0f9). Closes the four remaining practical items the user identified as still open before schematic capture. Does not redesign the verified architecture; no working RTL was modified as a result of this pass (see Point 2 for the one bug found and fixed, which was in a NEW test harness, not in spi_host_bridge.v itself).

---

POINT 1 — Directed SDRAM boundary verification

New file: hardware/v2/nms/sim/tb_sdram_boundary.v.

Real Alliance Memory AS4C4M16SA-6TIN geometry (confirmed against sdram_controller.v's own address decode: addr_bank=addr[21:20], addr_row=addr[19:8], addr_col=addr[7:0]): 4 banks × 4096 rows × 256 cols × 16 bits = 4M words = 8MB.

Coverage (21 checks, BURST_LEN=1 for exact single-word addressing):

• Address boundaries: 0x000000 (addr 0), 0x000001 (addr 1), 0x3FFFFF (last valid), 0x3FFFFE (last valid − 1).
• Row boundary: bank0/row10/col255 (last column of row 10) and bank0/row11/col0 (first column of row 11).
• Bank boundaries: last address / first address at all 3 inter-bank crossings (bank0↔1, bank1↔2, bank2↔3).
• Memory-map boundaries: the real V2 map (weights@byte 0x010000, activations@byte 0x200000, results@byte 0x300000) converted to this controller's word addresses (word=byte/2) — weights base, last word before activations, activations base, last word before results, results base.
• Byte-mask combinations, explicit read-after-write: lower-byte- only (wmask=2'b10), upper-byte-only (wmask=2'b01), both-bytes (wmask=2'b00), using the requested deterministic patterns 0xAAAA, 0x5555, 0x0000, 0xFFFF.

All 17 boundary/adjacency addresses are written first, then read back in reversed order with distinct address-derived patterns (addr[15:0] ^ 0xC3A5) — this proves no write to any one address corrupted any neighbour in the set, which is exactly the "adjacent regions cannot corrupt each other" property requested, for every boundary simultaneously.

Exact results

$ verilator --binary --timing -Wno-fatal --top-module tb_sdram_boundary -o tb_bnd \
    -GCLK_FREQ_MHZ=64 hardware/v2/nms/rtl/sdram_controller.v \
    hardware/v2/nms/sim/sdram_model.v hardware/v2/nms/sim/tb_sdram_boundary.v
$ ./obj_dir/tb_bnd
=== 21/21 tests, 0 errors (tb_sdram_boundary, CLK_FREQ_MHZ=64) ===
ALL TESTS PASSED (tb_sdram_boundary, CLK_FREQ_MHZ=64)

Cross-checked at the legacy CLK_FREQ_MHZ=166 (same command with -GCLK_FREQ_MHZ=166): 21/21 PASS, 0 errors, identical.

Full per-address results at 64MHz (expected vs actual, all matched):

Label	Address	Data
addr-0	0x000000	0xc3a5
addr-1	0x000001	0xc3a4
addr-last	0x3fffff	0x3c5a
addr-last-1	0x3ffffe	0x3c5b
row10-lastcol	0x000aff	0xc95a
row11-firstcol	0x000b00	0xc8a5
bank0-last	0x0fffff	0x3c5a
bank1-first	0x100000	0xc3a5
bank1-last	0x1fffff	0x3c5a
bank2-first	0x200000	0xc3a5
bank2-last	0x2fffff	0x3c5a
bank3-first	0x300000	0xc3a5
weights-base	0x008000	0x43a5
weights-last(pre-act)	0x0fffff	0x3c5a
activations-base	0x100000	0xc3a5
activations-last(pre-res)	0x17ffff	0x3c5a
results-base	0x180000	0xc3a5
mask-lower-only	0x001000	0xaa34
mask-upper-only	0x001000	0x5655
mask-both-bytes	0x001000	0xffff
pattern-5555-plain	0x001001	0x5555

No bug found. Address decode, byte masking, and inter-region adjacency are all correct at every tested boundary.

RESULT: SDRAM directed boundaries: PASS.

---

POINT 2 — Verified SPI operating clock

New file: hardware/v2/nms/sim/tb_spi_freq_sweep.v. Instantiates the REAL fpga_neural_v2_top (not spi_host_bridge in isolation) with osc_clk driven at the real 64MHz clk_sys rate (the SIM PLL bypass makes clk_sys = osc_clk directly, so driving osc_clk at 64MHz reproduces the real board's actual system-clock rate — unlike tb_fpga_neural_v2_top_smoke.v, which uses a stale CLK_FREQ_MHZ=80 parameter left over from an earlier draft). SPI bit timing is a runtime parameter (SPI_FREQ_MHZ), swept across candidate points.

Per-frequency coverage: single job submission, two jobs back-to-back, two jobs with a realistic gap, a raw WRITE_MEM/READ_MEM round trip over the actual SPI response path (not the backdoor SDRAM peek used elsewhere), and 3 repeated single-job transactions — 10 checks total.

A bug found and fixed — in the new test harness, not the RTL

The first sweep attempt (fixed #2000-real-time wait before clocking out a READ_MEM response) failed once, at 2MHz, with the response's MSB read back as 0 instead of 1 — every other bit correct. Before concluding anything about the RTL, this was root-caused: the real host-arb/SDRAM-controller backend latency (unlike tb_spi_host_bridge.v's own isolated unit test, which drives mem_rdata/mem_ready from a simple behavioral mock with fixed timing) genuinely varies cycle-to-cycle — a periodic AUTO REFRESH can land during the request and push mem_ready later than the guessed #2000 margin. tb_spi_host_bridge.v's own regression already proves spi_host_bridge.v's FIRST READ_MEM after reset delivers all 16 bits correctly when its own mock backend responds within that test's own assumed timing — confirming the FSM logic itself is correct, and the failure was this new harness's own race. Fixed by polling dut.u_spi_bridge.state directly (ST_MEM_ROUT/ST_IGNORE) instead of guessing a fixed real-time margin — eliminates the race entirely. Re-ran the full sweep from 2MHz upward with this fix: no further data-corruption failures at any frequency below the real CDC limit (see below).

Sweep results

SPI_FREQ_MHZ	sysclk cycles/bit (64MHz)	Result
2	32.0	10/10 PASS
4	16.0	10/10 PASS
8	8.0	10/10 PASS
10	6.4	10/10 PASS
12	5.33	10/10 PASS
12.5	5.12	10/10 PASS
12.8	5.0 (exact)	10/10 PASS
12.9	4.96	FAIL (data corruption) + protocol FSM HANG (watchdog)
13	4.92	FAIL + HANG
14	4.57	FAIL + HANG
15	4.27	FAIL + HANG
16	4.0	FAIL + HANG
20, 24, 32	<4.0	FAIL + HANG

The breakpoint is exact and deterministic: 12.8MHz is precisely 64MHz/5 — the triple-flop CDC synchronizer plus edge-detect/FSM reaction in spi_host_bridge.v requires at least 5 full system-clock cycles per SPI bit period to reliably track sclk/mosi/cs_n transitions. Below that, the synchronizer misses edges outright, which doesn't just corrupt data (as briefly seen in the harness-race case above) but eventually desyncs the byte-framing state machine badly enough that it never reaches an expected state again — a real protocol lockup, not merely wrong data. This is a genuine, real property of the CDC design (not a bug — the double/triple-flop synchronizer is standard, correct practice; it simply has a minimum bit-period requirement, which every synchronous CDC scheme does), now precisely measured rather than assumed.

Distinguishing the three kinds of limit the mandate asks for

• RTL/simulation limit (measured, this session): 12.8MHz exact edge; 12MHz recommended verified operating point (real margin below the hard edge: 5.33 vs the minimum 5.0 cycles/bit, ~6.7% headroom).
• FPGA timing limit: not applicable in the way P&R timing closure applies to the internal 64MHz domain — the SPI pins are simple registered/synchronized GPIO inputs (IO_TYPE=LVCMOS33, no special timing constraint beyond the CDC margin above), and nextpnr-ecp5's own timing analysis (section 5/6 of PRE_PCB_VERIFICATION.md) does not model an external asynchronous SPI master's edge timing at all. No FPGA-side P&R-derived limit beyond the CDC margin already found.
• Board-level electrical limit: OPEN — not measured, cannot be measured without real hardware. Real trace length, connector/cable capacitance, SPI master driver rise/fall time, ground bounce, and actual metastability risk (this RTL simulation is deterministic and cannot model metastability at all) are all real-world factors this simulation does not and cannot capture. The 12MHz recommendation below is a simulation-verified LOGICAL limit with margin, not a physical hardware guarantee — bring-up step 11 in FIRST_POWER_ON.md should still empirically confirm the real achievable rate on the actual board.

RESULT: SPI_MAX_VERIFIED = 12 MHz (recommended operating point, simulation-verified with real margin below the exact 12.8MHz deterministic CDC edge). Do not exceed 12.8MHz under any circumstance; do not treat 12.8MHz itself as a safe operating margin.

Exact test commands

$ verilator --binary --timing -Wno-fatal -DSIM --top-module tb_spi_freq_sweep -o tb_spi \
    -GSPI_FREQ_MHZ=12.0 <all V2 rtl/nms sources + tb_spi_freq_sweep.v>
$ ./obj_dir/tb_spi
=== SPI_FREQ_MHZ=12.000: 10/10 PASS ===

---

POINT 3 — 16MHz oscillator MPN, frozen

Decision: ECS Inc. International, ECS-3225MV-160-BN-TR.

Property	Value
Manufacturer / MPN	ECS Inc. International, ECS-3225MV-160-BN-TR
Type	Quartz crystal oscillator (XO), not a bare crystal — provides a direct digital clock output, no external oscillator circuit needed
Frequency	16.000 MHz, matching osc_clk's real ball (H5) and the LPF's FREQUENCY PORT "osc_clk" 16 MHZ constraint exactly
Package	3225 SMD, 3.2mm × 2.5mm, 4-pad (standard, small, hand-placeable with a stencil; widely available)
Supply voltage	3.3V — matches osc_clk's LPF IO_TYPE=LVCMOS33 exactly, no level-shifting needed
Output type	HCMOS/CMOS square wave — directly compatible with the ECP5's LVCMOS33 clock input requirement
Frequency stability	±50 ppm (standard grade for this series) — comfortably adequate for an SDR SDRAM/SPI/PLL system with no tight external timing reference requirement
Duty cycle	Typically 45/55% to 40/60% (standard for this class of HCMOS XO; confirm exact figure against the current ECS datasheet at BOM lock)
Startup time	Typically ≤10ms (standard for a quartz XO of this type)
Temperature range	−40°C to +85°C (industrial)
Recommended decoupling	One 0.1µF ceramic capacitor directly across VDD/GND, placed as close as possible to the oscillator's supply pin — standard practice for this device class
Availability	High — ECS Inc. is a large, long-established oscillator manufacturer stocked at Digi-Key/Mouser; standard frequency/package combination

Verified against the ECP5's own input-clock requirements: LVCMOS33 input, no minimum/maximum listed frequency constraint that 16MHz would violate, matches the real, already-verified (* FREQUENCY_PIN_CLKI="16" *)-driven EHXPLLL input in ecp5_pll_sys_clk.v exactly.

Caveat, honestly disclosed: the exact terminal order-code suffix (stability/voltage/output-enable option letters, here assumed BN for 3.3V HCMOS/standard stability) should be cross-checked against ECS's current published datasheet at final BOM lock — normal, standard due-diligence practice at that stage, not an open architectural question. The manufacturer, series, frequency, package, and supply voltage are the real, frozen decision.

RESULT: 16MHz oscillator: ECS-3225MV-160-BN-TR (ECS Inc.), FROZEN.

---

POINT 4 — Power + JTAG support components

FPGA power rails and regulators

Assumption, explicitly flagged: a 5V board input rail (typical USB/wall-adapter supply) is assumed as the single external power source all on-board regulators derive from — this was not specified by the user and is a reasonable, common default, not a verified fact.

Rail	Voltage	Regulator MPN	Topology	Current capability	Notes
FPGA core (VCC)	1.1V ±5%	Texas Instruments TPS562201DDCR	Synchronous buck (switching), adjustable output via feedback resistor divider set for 1.1V	Up to 2A	Real dynamic current draw is OPEN (section 12 of PRE_PCB_VERIFICATION.md) — 2A capability is a real-datasheet-based worst-case engineering margin, not a measured requirement; a switching regulator (not an LDO) is used here because a 5V→1.1V LDO would dissipate excessive heat at any non-trivial current
FPGA VCCAUX	2.5V ±5%	Texas Instruments TLV1117-25IDCYR	Linear (LDO), fixed 2.5V	800mA	Fed from the same 5V input rail directly (not from the 3.3V rail) so the LDO retains adequate (~2.5V) dropout headroom
FPGA VCCIO (banks 6/7/8)	3.3V	Texas Instruments TLV1117-33IDCYR	Linear (LDO), fixed 3.3V	800mA	Also supplies the SDRAM, config flash, oscillator, and JTAG reference voltage (all real 3.3V devices per sections 10/11 of PRE_PCB_VERIFICATION.md)
SDRAM (AS4C4M16SA-6TIN)	3.3V	Shared with VCCIO rail above	—	—	Real datasheet requirement, already confirmed
Config flash (W25Q32JVSSIQ)	3.3V (within its 2.7-3.6V range)	Shared with VCCIO rail above	—	—	Real datasheet requirement, already confirmed
Oscillator (ECS-3225MV-160)	3.3V	Shared with VCCIO rail above	—	—	Matches Point 3's own decision

Design margin: the 1.1V buck's 2A capability and the 800mA LDOs are real, datasheet-supported ratings well above any plausible estimate for this design's actual utilization (7,084 LUT4-equiv, 6,322 FF, 32 MULT18X18D — a mid-size ECP5-45F design, not the whole device near capacity), but per section 12's own honest disclosure, the EXACT required current is still not computed from real implementation data — these regulator choices provide comfortable headroom against that unknown, not a precisely-sized budget.

Passive components (frozen only where electrically required)

Component	Value	Where
Decoupling (high-frequency)	100nF (0.1µF) X7R ceramic, 0402/0603	Distributed, one per VCC/VCCAUX/VCCIO power-pin group around the BGA, per Lattice's own Hardware Checklist guidance (already cited in docs/pinouts.md)
Decoupling (bulk)	10µF X5R ceramic or tantalum	One per regulator output, close to each regulator
PROGRAMN pull-up	10kΩ to VCCIO8 (3.3V)	Standard ECP5 practice — idle-high, momentary pulse low reconfigures
INITN pull-up	4.7kΩ to VCCIO8 (3.3V)	INITN is open-drain per ECP5 spec, needs an external pull-up
Config flash WP#/HOLD# pull-ups	10kΩ each to 3.3V	Per Point 10's own decision (W25Q32JVSSIQ, standard single-SPI mode, these pins unused and must be held inactive)
JTAG TMS pull-up	4.7-10kΩ to 3.3V	Standard practice so an unconnected/high-impedance JTAG probe leaves TMS idle-high (TAP stays in Test-Logic-Reset)

Not frozen (correctly left for PCB layout, per "only freeze what's electrically required"): exact capacitor placement/count beyond the one-per-pin-group guidance above, trace-length matching, ground-plane stitching-via count.

JTAG

Property	Decision
Connector type	Simple unshrouded 2×3 (6-pin), 0.1" (2.54mm) pitch pin header — sufficient for a point-to-point bench connection; no vendor-specific shrouded-connector standard is mandated by Lattice for the ECP5
Pinout	Pin1=3V3 (reference/probe-detect, not a supply to the probe), Pin2=TCK (real ball T5), Pin3=TMS (real ball U5), Pin4=TDI (real ball R5), Pin5=TDO (real ball V4), Pin6=GND
Required pull resistor	TMS: 4.7-10kΩ to 3.3V (see passives table above)
Required power/reference pin	3.3V reference pin (Pin1) so a probe can detect target voltage; NOT used to power the board
PROGRAMN/config-related signals	Real balls W3 (PROGRAMN), V3 (INITN), Y3 (DONE), bank 8 — NOT part of the JTAG connector itself; these remain dedicated ECP5 configuration-control pins, routed separately per Point 14/15 of PRE_PCB_VERIFICATION.md
Programming/debug path	JTAG connects directly to the ECP5's own real TAP balls (R5/T5/U5/V4); no external JTAG buffer/level-shifter needed since the probe and the FPGA both operate at 3.3V

Complete programming/debug path verified: JTAG header → real TAP balls → ECP5 TAP controller → SRAM configuration (direct bitstream download for bring-up/debug) or, separately, the W25Q32JVSSIQ config flash for standalone boot (Point 10 of PRE_PCB_VERIFICATION.md) — both paths coexist without conflict, as already confirmed in that document's own JTAG-interaction analysis.

RESULT: Power/JTAG/support components: CLOSED (sufficient for schematic capture; exact passive layout/placement remains, correctly, a PCB-level task).

---

FINAL 4-POINT STATUS

1. SDRAM directed boundaries: PASS (21/21, both 64MHz and 166MHz, zero bugs found)
2. SPI maximum verified frequency: 12 MHz (simulation-exact deterministic edge: 12.8MHz = 64MHz/5; one testbench-race bug found and fixed, NOT an RTL defect; board-level electrical limit remains OPEN, requires real hardware)
3. 16MHz oscillator: ECS-3225MV-160-BN-TR (ECS Inc.) — FROZEN
4. Power/JTAG/support components: CLOSED (regulator MPNs, passive values, and JTAG connector/pinout frozen; exact PCB placement correctly deferred)

Remaining uncertainty, explicitly documented (not silently dropped): oscillator order-suffix cross-check against the live ECS datasheet; real FPGA dynamic current (still requires post-implementation data, per PRE_PCB_VERIFICATION.md section 12); board-level SPI electrical limit (requires real hardware bring-up); hold-timing tool limitation (carried over from PRE_PCB_VERIFICATION.md, unaffected by this pass).

PRE-PCB HARDWARE SPECIFICATION: FROZEN

Schematic and PCB layout remain the user's own implementation work. This status means the four practical items requested are closed sufficiently for schematic capture — it is NOT a claim of "SILICON READY."