V2.0.0 hardware freeze - single SDRAM

FASE #1 hardware freeze for FPGA-Neural V2, N4/P8, single external
SDRAM (Alliance Memory AS4C4M16SA-6TIN) serving weights, activations,
and results through one physical sdram_controller.v instance. Removes
the PSRAM dependency (hardware/v1/rtl/psram_controller.v +
memory_interface.v) from the V2 physical path entirely -- V1 itself
remains fully unmodified, the golden reference.

New RTL: sdram_unified_backend.v (2-way W/AR arbitration over one
SDRAM controller, real per-byte DQM write masking added to
sdram_controller.v for correct single-byte result writes with no
read-modify-write), nms_neural_multiprocessor_sdram_unified.v (the
frozen top-level). Two real bugs found and fixed via full-system
testing before being accepted (ERR-0023): a deadlock and an off-by-one
data-shift bug in the new arbitration logic.

Real results: N=4 and N=2 D-Stress bit-exact (256/256 neurons), 40
real AUTO REFRESH events interleaved with zero corruption, real
Yosys+nextpnr-ecp5 synthesis/P&R for LFE5U-45F-8CABGA381 (149/245
TRELLIS_IO, a real 45-pin reduction from the prior dual-memory
design). Timing is MARGINAL (1/8 P&R seeds >=80MHz), reported honestly
rather than masked by the best seed.

Real, sourced ball-level pinout for the SDRAM bus + clk/rst (39/149
signals, P&R-verified) using the official Lattice ECP5U-45 pinout CSV
found on disk during this step's own pre-commit review -- corrects an
earlier draft that wrongly assumed no real pinout data was available.

Chip readiness: NO. Real, disclosed blockers remain (no physical host
interface exists yet -- the RTL's own reg_* ports are a 110-pin raw
test-harness bus; clock source/PLL decision; power/configuration
component selection) -- see hardware/v2/docs/{HARDWARE_FREEZE,
CHIP_READINESS,OPEN_ITEMS}.md for the complete, itemized status.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xXuuRUWZScuo1DeYJxs3v

hardware/v2/docs/CLOCK_ARCHITECTURE.md

@@ -0,0 +1,104 @@
+# FPGA-Neural V2 — CLOCK ARCHITECTURE
+
+## Status: CRITICAL — real, unresolved oscillator/clock-input mismatch
+
+## What the RTL actually assumes
+
+Every module in the frozen hierarchy (`nms_neural_multiprocessor_
+sdram_unified.v` down to `sdram_controller.v`) takes a **single** `clk`
+input and treats it directly as both the system clock AND the SDRAM
+clock (`CLK_FREQ_MHZ=80` is a pure timing-derivation parameter fed
+into `sdram_controller.v`'s own `ns_to_cycles()` function — it does
+NOT configure a PLL; there is no PLL anywhere in this hierarchy).
+Confirmed mechanically: every real synthesis run this project has
+performed (STEP16 through this freeze) reports `EHXPLLL: 0/4 0%` in
+nextpnr's own device-utilisation output — **zero PLL primitives are
+instantiated**, in any variant, ever.
+
+**This means the design requires a real, external 80MHz (or faster)
+clock source wired directly to the FPGA's clock input pin.**
+
+## The real gap
+
+This project's own memory notes (established in an earlier session,
+before the SDRAM decision) record the confirmed hardware target board
+as using a **16MHz** oscillator. 16MHz ≠ 80MHz, and there is no PLL in
+the current RTL to bridge that gap. **Two mutually exclusive
+resolutions exist, and neither has been chosen:**
+
+1. **Source an oscillator that directly provides ≥80MHz** (a
+   commodity part — plain crystal oscillators at 80, 100, or higher
+   MHz are standard, low-risk components) and retire the 16MHz
+   assumption. Zero RTL change required. Simplest, lowest-risk path.
+2. **Keep the 16MHz oscillator and add a real PLL** (ECP5's own
+   `EHXPLLL` primitive, e.g. 16MHz→80MHz = ×5) to the RTL, with its
+   own real timing constraints (lock time, jitter, generated-clock
+   declaration in the constraints file) — genuinely new RTL/constraint
+   work, not yet done, and not exercised by any of this project's own
+   real synthesis/timing-closure runs to date (every Fmax number in
+   STEP16-18 assumes a clean, ideal `clk` input, not a PLL output with
+   its own jitter/lock-time budget).
+
+**This is an OPEN, real architectural decision, not a detail** — it
+determines whether a new oscillator needs sourcing or a PLL needs
+designing, and affects the CLOCK_SOURCE→FPGA_CLOCK diagram below,
+which cannot be finalized until it is made.
+
+## Clock tree (as far as it CAN be stated today)
+
+```
+[UNRESOLVED: either an 80MHz+ oscillator, or a 16MHz oscillator + PLL]
+        |
+        v
+   FPGA clk pin (ball location: BLOCKER, see PINOUT.md)
+        |
+        v
+   single system clock domain, 80 MHz target
+        |
+        +--> Neural Multiprocessor / Dependency Manager / Director /
+        |    Memory Manager / Neural Processors (all synchronous,
+        |    single clock domain — confirmed, no clock-domain-crossing
+        |    logic exists anywhere in the frozen hierarchy)
+        |
+        +--> SDRAM controller (same clock, no separate SDRAM clock
+             domain — sdram_controller.v drives the SDRAM chip's own
+             CLK pin combinationally/directly from the same system
+             clock; real board layout must still budget for the
+             SDRAM's own real clock-to-pin round-trip delay, which
+             was NOT part of this project's own RTL-simulation/P&R
+             timing closure — flagged as an OPEN ITEM for board bring-
+             up, see FIRST_POWER_ON.md)
+```
+
+## Reset
+
+A single `rst` input, synchronous to `clk` in every module observed
+(no asynchronous reset assertion/de-assertion synchronizer chain was
+found in this session's own lint pass). **Reset release timing/
+synchronization to a real external reset source (power-on reset chip,
+button, or host-driven) has not been designed** — this is a normal,
+solvable board-level concern (a standard POR/supervisor IC), not
+flagged as a blocker, but not yet decided (OPEN ITEM).
+
+## Clock constraints used so far
+
+Every P&R run in STEP16-18 used `nextpnr-ecp5 --freq 80` (a target
+frequency for the placer's own timing-driven effort), NOT a real `.lpf`
+`FREQUENCY` constraint tied to a real pin — because no `.lpf` exists at
+all for any V2 top-level (see PINOUT.md). A real constraints file with
+a proper `FREQUENCY PORT "clk" 80 MHZ;` (or the real achieved-vs-
+required frequency once the oscillator/PLL decision above is made)
+must be written before this can be considered a genuine, board-ready
+clock constraint.
+
+## Summary
+
+| Item | Status |
+|---|---|
+| Single-clock-domain RTL, no CDC logic found | Confirmed by lint, real |
+| PLL present in RTL | **No — confirmed absent (0/4 EHXPLLL in every P&R run)** |
+| Oscillator frequency vs required system clock | **CRITICAL — 16MHz (prior project memory) vs 80MHz (RTL requirement), unresolved** |
+| Oscillator-vs-PLL decision | **OPEN — not made** |
+| Real `.lpf` clock constraint | Partial — `hardware/v2/constraints/v2_unified.lpf` now exists with a frequency constraint and clk/rst ball reuse from V1; full ball-level pinout for the remaining 147 signals is still blocked (see PINOUT.md) |
+| Reset synchronization to a real external source | OPEN, not yet designed (not a hard blocker) |
+| SDRAM clock-to-pin board-level timing budget | OPEN — not part of RTL-level timing closure |