FPGA-Neural/CLAUDE.md

# FPGA-Neural — project instructions for Claude Code

Hardware neural accelerator for a custom PCB: bare **Xilinx XC7A100T-CSG324-2**
(Artix-7) chip + real DDR3, designed and assembled by the user themselves —
never a Digilent/dev-board purchase. An ESP32 is the host/central processor,
talking to the FPGA over a dedicated SPI bus (FPGA is slave there) and, via
the FPGA, through to a separate config flash used only for FPGA bootstrapping
(FPGA is master on that second, physically distinct SPI bus).

Active branch: **`v3-artix7`**. `hardware/v3/` is the current, real target.
`hardware/v2/` is the archived ECP5 baseline (frozen, DSP-count-limited,
superseded — do not build on it, some of its RTL is still *reused*
unmodified by v3, e.g. `layer_prefetch_ctrl.v`/`layer_weight_buffer.v`).
`hardware/v1/` is older still, reference only.

## Read first

- `docs/PHYSICAL_REALIZATION.md` — every real pin assignment, part number,
  timing number, and memory-layout convention needed for the physical board
  and for host (ESP32) firmware. Keep it in sync with reality — if a pin
  assignment or timing number changes, update this file in the same commit.
- `docs/ARCHITECTURE_ANALYSIS.md` — real, measured bottleneck analysis
  (DDR3 bandwidth is the real ceiling, not DSP count — see it before
  proposing to scale core count) and ranked recommended interventions.
  Update it whenever a recommendation from it gets built or a new real
  bottleneck is found.
- `hardware/v2/logs/experiments.log` — the real project history, one
  `EXP-NNNN` entry per real experiment/change (context/method/result/
  decision/next_action). Read the tail before starting new work; append a
  new entry for anything non-trivial you do. This log — not memory, not
  chat history — is the authoritative record of what's been tried and why.

## Toolchains (real paths, already working — don't re-diagnose from scratch)

- **Vivado 2026.1**: `source /home/michele/tools_cache/Xilinx/2026.1/Vivado/settings64.sh`,
  then `export LD_LIBRARY_PATH="/home/michele/tools_cache/Xilinx/2026.1/Vivado/lib/lnx64.o/Ubuntu/24:$LD_LIBRARY_PATH"`
  (this machine's Ubuntu is too new for Vivado's own OS detection; the
  LD_LIBRARY_PATH points at Vivado's own bundled compat libs — not a real
  distro package, must be set every session).
- **OSS CAD Suite** (iverilog/vvp for fast plain-Verilog sims, no Xilinx
  primitives): `source /home/michele/tools_cache/oss-cad-suite/environment`.
- Real Vivado project: `Vivado/NeuralProcessor/NeuralProcessor.xpr` — the
  MIG DDR3 IP lives there, real, already generated for the exact part.

## Hard-won lessons (do not re-derive these the slow way)

- **Vivado's imported source copies go stale silently — RTL *and*
  constraint (.xdc) files alike.** If a project file under
  `NeuralProcessor.srcs/sources_1/imports/...` (RTL) or
  `NeuralProcessor.srcs/constrs_1/imports/...` (XDC) was ever edited on
  disk *after* being added to the project, diff it against the live
  `hardware/v3/...` source before trusting any P&R result — `add_files`/
  `update_compile_order` do NOT auto-refresh it, and a stale copy produces
  no error, just silently wrong (old) synthesis/implementation results
  (EXP-0078 for RTL; EXP-0084 for the XDC — the stale constraints file was
  old enough to still have PRE-EXP-0077 pin assignments, predating the
  flash bridge entirely, and its own real bug fixes silently didn't take
  effect across multiple P&R re-runs until the staleness itself was
  diagnosed and fixed). Prefer adding new files so they stay a direct
  reference (check `IS_GLOBAL_INCLUDE`/the file's own path isn't under
  `imports/`) rather than get copied — for BOTH the `sources_1` and
  `constrs_1` filesets. **A real MIG IP regeneration (re-running the
  wizard, even just to change one field like Clock Period) can re-trigger
  a WHOLESALE project source rescan that silently re-imports the ENTIRE
  RTL tree plus constraints back to stale copies in one shot — not just
  the file(s) the regeneration itself touched** (EXP-0086: a second
  wizard run, needed only to revert Clock Period, silently reverted 9
  already-fixed RTL files plus the top XDC all at once). After ANY IP
  regeneration, check every fileset (`get_files -of_objects
  [get_filesets sources_1]` and `constrs_1`) for `*/imports/*` paths
  before trusting the next P&R — don't assume only the previously-fixed
  files are still direct references.
- **Testbench stimulus must use nonblocking assignment (`<=`), not blocking
  (`=`), when driving a DUT's inputs from a separate `always`/`initial`
  block.** Blocking assignment races the DUT's own `posedge`-triggered
  always block under Icarus and can silently corrupt data OR miss a one-shot
  pulse entirely (causing a real hang) — hit and fixed repeatedly (EXP-0073,
  0075, 0077) before this became standing practice. If a new Icarus
  testbench shows shuffled/duplicated fields or an inexplicable hang,
  suspect this class of bug before assuming the RTL is wrong.
  **Same race family, a DIFFERENT real trigger (EXP-0090)**: driving
  stimulus on `@(posedge clk)` — even with the SAME `=`/handshake shape
  already proven safe elsewhere in this project (e.g. `tb_packed_slot.v`'s
  own `job_start` pulse) — still races the DUT's own posedge-triggered
  sampling when a task issuing that pulse is called BACK-TO-BACK with ZERO
  real simulated gap (no natural `while(!done)`-style polling delay between
  calls, e.g. a tight submission loop). Confirmed via real signal tracing:
  every logical push registered as TWO real, identical DUT-side writes.
  Every prior working example of this pulse pattern happened to always have
  a real gap between calls, so the race was never exercised until a tight
  back-to-back loop (`neural_director_grouped.v`'s own test) hit it. Fix:
  drive stimulus changes on `@(negedge clk)` instead — the DUT still
  samples on `posedge`, so a negedge-driven change can never race it,
  regardless of how tightly consecutive pulses are issued.
- **Never use a runtime-indexed part-select** (`data[idx*W +: W]` where `idx`
  is a signal, not a constant) on a wide bus in anything synthesizable — a
  known real Fmax killer (`weight_tile_gather.v`'s own header, EXP-0061).
  Use fixed shift-concat, or (as `act_tile_fetch.v` does, EXP-0079) design
  the memory layout so only a fixed slice is ever needed. The current real
  P&R timing margin is thin (WNS +0.013ns, EXP-0078) — there is no slack to
  absorb a new critical path.
- **A one-shot-pulse requester on a shared/arbitrated bus must see its own
  grant the SAME cycle its own `active` signal first asserts** — a
  registered/one-cycle-late grant silently loses the request forever
  (EXP-0066's own real bug, now a standing design rule for every arbiter/
  requester pair in this project).
- **`xvlog`/`iverilog` need `-sv`/`-g2012`** respectively to accept
  SystemVerilog-only syntax (e.g. `'0`) even in a plain `.v` file — prefer
  just not using SV-only syntax in synthesizable RTL (Vivado's `synth_design`
  has no such escape hatch at all).
- **Verify real component availability (LCSC) before committing to a part**
  — the user has asked for this explicitly more than once. Don't guess
  availability or specs from training data; search when it matters.
- **Real, measured numbers only — never estimate/guess a timing or
  performance figure and present it as fact.** Out-of-context synthesis is
  not a real signoff; only a real in-context `place_design`/`route_design`
  run on the actual top-level module counts. If a number is a projection
  (not measured), say so explicitly and show the real numbers it's built
  from.

## Working discipline

- Fork before promote: don't edit an already-verified, in-use RTL file in
  place for a new experiment — copy/fork it, verify the fork, then decide
  whether to promote it. (Established V2-era convention, still followed in
  V3.)
- One variable at a time: verify a new module in isolation before wiring it
  into a larger system; verify the larger system before trusting a P&R
  number built on top of it.
- Root-cause every anomaly via hierarchical signal tracing — never guess or
  paper over an unexplained result. Several real bugs in this project were
  found exactly this way, not by inspection.
- After ANY RTL change to logic that's part of the real synthesis target
  (`hardware/v3/rtl/n2_system_ddr3_top.v` and its dependents), re-run a real
  P&R before claiming it's still timing-clean — the margin is thin enough
  that this is not optional caution, it's load-bearing.
- Commit messages end with the attribution lines already configured for this
  session (Co-Authored-By + Claude-Session) — keep using them.