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

FPGA-Neural V2 — CLOCK ARCHITECTURE

SUPERSEDED. This document predates the real EHXPLLL PLL (ecp5_pll_sys_clk.v) that resolves the mismatch described below. See PRE_PCB_VERIFICATION.md \S3 for the current, verified clock/reset status (PASS). Left in place as a historical record of the architectural decision that led to adding the PLL.

Status (HISTORICAL): 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