FPGA-Neural/docs/v2-description.md

FPGA-Neural V2 — Neural Multiprocessor / Dataflow Architecture
Obiettivo

Progettare e implementare una V2 dell'acceleratore neurale FPGA contenuto nel repository:

https://github.com/manvalan/FPGA-Neural

La V2 deve evolvere l'architettura V1 trasformandola da un acceleratore principalmente sequenziale a una Neural Multiprocessor / Dataflow Machine, mantenendo V1 come implementazione di riferimento funzionante.

L'obiettivo non è semplicemente aumentare PARALLEL.

L'obiettivo è costruire un'architettura composta da:

molteplici Neural Processor / Perceptron Processor indipendenti;
un Neural Director / Orchestrator;
un Dependency Manager;
un Memory Manager;
buffer locali e FIFO;
prefetch;
forwarding dei risultati;
pipeline interne ai Neural Processor;
esecuzione concorrente di più neuroni;
gestione dinamica delle dipendenze;
capacità di eseguire reti regolari, DAG, fuzzy network e strutture con dipendenze non strettamente sequenziali.

Il sistema deve essere progettato come una piccola macchina dataflow neurale, non come una semplice versione più larga dell'architettura V1.

1. Regola fondamentale: V1 è il Golden Reference

La V1 funzionante deve essere conservata integralmente.

Non modificare, cancellare o degradare la V1 per implementare la V2.

Struttura obbligatoria:

hardware/
├── v1/
│   ├── rtl/
│   ├── sim/
│   ├── constraints/
│   ├── synthesis/
│   └── ...
│
└── v2/
    ├── rtl/
    ├── sim/
    ├── constraints/
    ├── synthesis/
    ├── reports/
    ├── scripts/
    ├── logs/
    └── docs/

La V1 deve essere utilizzata come:

riferimento funzionale;
riferimento numerico;
riferimento prestazionale;
riferimento per i test bit-exact;
baseline per valutare ogni modifica V2.
2. Hardware target

Target FPGA:

Lattice ECP5U LFE5U-45F-8BG381

La progettazione deve tenere conto delle caratteristiche reali del dispositivo.

Non assumere che una maggiore quantità di DSP/logic implichi automaticamente maggiore prestazione.

Il limite può essere:

timing;
routing;
fanout;
congestione;
memoria;
larghezza dei bus;
mux;
distribuzione dei segnali;
interconnessioni tra blocchi.

Ogni scelta importante deve quindi essere verificata con sintesi e place-and-route reali.

3. Baseline V1

La V1 attuale contiene, tra gli altri:

rtl/neuron_parallel.v
rtl/mac8.v
rtl/mac_unit.v
rtl/neuron_memory.v
rtl/layer_sequencer.v
rtl/graph_engine.v
rtl/act_buffer.v
rtl/psram_controller.v
rtl/int8_memory_access.v
rtl/memory_interface.v
rtl/mem_arbiter.v
rtl/spi_neuron_top.v

La V1 utilizza:

INT8;
accumulazione INT32;
PARALLEL=8;
MAC paralleli;
adder tree bilanciato;
bias;
activation;
saturazione INT8;
memoria PSRAM/CellularRAM esterna.

Dati reali già osservati nella V1:

P16  ≈ 52.13 MHz
P8   ≈ 61.71 MHz
P4   ≈ 75.01 MHz
P2   ≈ 87.88 MHz

in una configurazione isolata N_INPUTS=256.

Nel sistema integrato:

P8 ≈ 65.13 MHz

con failure rispetto a un target di 80 MHz.

Il critical path osservato è principalmente legato alla logica del neuron_parallel e alla sua interconnessione, non al controller PSRAM.

Questi dati devono essere considerati misure reali V1, non risultati V2.

4. Architettura V2

La V2 deve essere organizzata in due piani.

Control Plane
Neural Director
      │
      ├── Scheduler
      ├── Dependency Manager
      ├── Ready Queue
      ├── Waiting Queue
      └── Processor State
Data Plane
                 ┌─────────────────────┐
                 │   Memory Manager    │
                 └──────────┬──────────┘
                            │
               ┌────────────┼────────────┐
               │            │            │
             Buffer       Buffer       Buffer
             Input        Weight       Result
               │            │            │
               └────────────┼────────────┘
                            │
       ┌────────────┬───────┴───────┬────────────┐
       │            │               │            │
      NP0          NP1             NP2          NP3
       │            │               │            │
       └────────────┴───────────────┴────────────┘
                            │
                       Result/Forward

Il numero di processor non deve essere deciso a priori.

Deve essere determinato tramite sweep di sintesi e timing.

5. Neural Processor

Il Neural Processor è l'unità fondamentale della V2.

Ogni processor deve essere autonomo e indipendente.

Un processor esegue un neurone alla volta, ma il datapath interno deve essere pipelineizzato.

Configurazione iniziale:

P_IN = 8

Ogni processor inizialmente deve avere:

8 × INT8 multiplier
balanced adder tree
INT32 accumulator
bias
activation
INT8 saturation
local operand registers/FIFO
job interface
result interface

Pipeline iniziale candidata:

Stage 0  input alignment/register
Stage 1  8 multipliers
Stage 2  adder tree level 1
Stage 3  adder tree level 2
Stage 4  adder tree level 3
Stage 5  accumulator
Stage 6  bias / activation
Stage 7  output / saturation

La pipeline può essere modificata se le simulazioni e il timing dimostrano una soluzione migliore.

L'obiettivo principale è il throughput, non la minima latenza possibile.

6. Neural Processor FSM

Ogni Neural Processor deve avere una macchina a stati chiaramente definita.

Baseline:

NP_IDLE
NP_LOAD_JOB
NP_WAIT_OPERANDS
NP_LOAD_TILE
NP_MAC
NP_ACCUM
NP_NEXT_TILE
NP_FINISH
NP_WRITE_RESULT
NP_DONE
NP_ERROR
NP_IDLE

Processor libero e disponibile.

NP_LOAD_JOB

Caricamento del job descriptor.

Inizializzazione:

node ID;
numero input;
indirizzo input;
indirizzo pesi;
bias;
activation;
tile count;
accumulator.
NP_WAIT_OPERANDS

Attesa degli operandi.

Il processor deve poter rimanere bloccato senza impedire agli altri processor di lavorare.

NP_LOAD_TILE

Caricamento di un tile locale.

NP_MAC

Esecuzione del datapath MAC pipeline.

NP_ACCUM

Aggiornamento dell'accumulatore.

NP_NEXT_TILE

Richiesta del tile successivo.

Il Memory Manager dovrebbe averlo già prefetched.

NP_FINISH

Bias, activation e saturazione.

NP_WRITE_RESULT

Handshake con Memory Manager / result path.

NP_DONE

Il processor ritorna disponibile.

NP_ERROR

Gestione degli errori senza bloccare globalmente il sistema.

7. Interfacce del Neural Processor

Evitare grandi mux dinamici come quelli dell'architettura V1.

Preferire:

valid
ready
data
last

per gli stream.

Input:

operand_valid
operand_ready
input_data
weight_data
tile_last

Output:

result_valid
result_ready
result_data
node_id

La validità deve essere pipelineizzata insieme ai dati.

Non assumere ritardi fissi senza handshake o valid propagation.

8. Neural Processor Array

Creare:

hardware/v2/rtl/neural_processor_array.v

Il modulo deve permettere:

N_PROCESSORS = parametrico
P_IN         = parametrico

Configurazioni iniziali:

1 × P8
2 × P8
4 × P8
8 × P8

Successivamente esplorare configurazioni maggiori se timing e risorse lo consentono.

Esempi teorici:

4 × P8 = 32 MAC/cycle
8 × P8 = 64 MAC/cycle

Questi sono solo valori teorici.

Non presentarli mai come throughput misurato.

9. Neural Director / Orchestrator

Creare:

hardware/v2/rtl/neural_director.v

Il Director controlla l'intero sistema.

Responsabilità:

ricezione dei job;
scansione dei job READY;
scelta del processor libero;
assegnazione;
tracking dello stato dei processor;
gestione delle dipendenze;
rilevamento dei completamenti;
wake-up dei job;
gestione ready queue;
gestione waiting queue;
prevenzione dei deadlock;
massimizzazione dell'utilizzo dei processor.

FSM iniziale:

DIR_IDLE
DIR_SCAN_READY
DIR_ALLOCATE
DIR_WAIT_DEPENDENCY
DIR_MONITOR
DIR_COMPLETE
DIR_WAKEUP
DIR_ERROR

Scheduling iniziale:

first-free

Successivamente valutare:

round-robin
least-loaded
locality-aware
priority-based
dependency-aware

La politica migliore deve essere determinata sperimentalmente.

10. Dependency Manager

Creare:

hardware/v2/rtl/dependency_manager.v

Ogni nodo deve avere almeno:

node_id
state
required_dependencies
resolved_dependencies
producer_information

Esempio:

node 37
required = 4
resolved = 3
state = WAITING

Quando arriva il quarto risultato:

resolved = 4
state = READY

Il nodo può quindi essere assegnato dal Director.

Il sistema deve supportare:

dipendenze multiple;
risultati condivisi;
più consumer;
wake-up;
forwarding;
backpressure.
11. Dataflow e token

Il modello concettuale deve supportare token:

TOKEN
├── node_id
├── value
└── valid

Quando un processor produce un risultato:

Producer
   │
   ├──→ Consumer FIFO
   │
   └──→ Result Buffer

Quando possibile il dato deve essere inoltrato direttamente al consumer senza obbligare il sistema a fare:

processor
→ external memory
→ memory controller
→ buffer
→ processor

Il risultato può essere contemporaneamente:

forwarded;
memorizzato;
utilizzato da più consumer.
12. Memory Manager

Creare:

hardware/v2/rtl/memory_manager.v

Il Neural Processor non deve accedere direttamente alla PSRAM.

Il Memory Manager deve occuparsi di:

input activations;
weights;
results;
prefetch;
buffering;
FIFO;
arbitration;
forwarding;
gestione latenza;
double buffering;
memory request scheduling.

Il processor deve vedere principalmente:

data available

e non:

PSRAM latency
13. Prefetch

Creare:

hardware/v2/rtl/prefetch_engine.v

Usare inizialmente una strategia:

compute tile N
      │
      └── concurrently ──→ prefetch tile N+1

Con double buffering:

Buffer A → COMPUTE
Buffer B → PREFETCH

swap

Buffer B → COMPUTE
Buffer A → PREFETCH

Priorità:

HIGH    operand required now
MEDIUM  next tile
LOW     future tile
14. Buffer

Creare:

hardware/v2/rtl/activation_buffer.v
hardware/v2/rtl/weight_buffer.v
hardware/v2/rtl/result_buffer.v

La profondità deve essere parametrica.

Valutare anche:

FIFO depth
buffer depth
numero porte
BRAM mapping
routing
timing

Non assumere che buffer più grandi siano automaticamente migliori.

15. Memoria esterna

NON iniziare modificando il controller PSRAM.

Mantenere inizialmente il backend esistente.

Astrarre il Memory Manager dal backend:

Memory Manager
      │
      ▼
Memory Backend Interface
      │
      ▼
PSRAM Controller

Solo dopo aver misurato il sistema V2 valutare eventuali alternative:

SRAM;
PSRAM;
SDRAM;
DDR;
QSPI;
altre memorie o risorse esterne.

Qualsiasi modifica hardware esterna deve essere motivata da dati reali.

16. Parallelismo

Due parametri fondamentali:

P_IN
N_PROCESSORS

P_IN indica il numero di MAC paralleli dentro un Neural Processor.

N_PROCESSORS indica quanti Neural Processor operano contemporaneamente.

Eseguire sweep almeno su:

P_IN = 2, 4, 8

e:

N_PROCESSORS = 1, 2, 4, 6, 8, 12, 16...

fino al limite imposto da:

LUT;
FF;
DSP;
BRAM;
routing;
timing.

La configurazione finale deve essere scelta sulla base del throughput effettivo, non dell'utilizzo massimo delle risorse.

17. Dataflow Core

Creare:

hardware/v2/rtl/dataflow_core.v

Il modulo integra:

Neural Director
Dependency Manager
Memory Manager
Prefetch Engine
Neural Processor Array
Activation Buffer
Weight Buffer
Result Buffer

Architettura:

                  JOBS
                   │
                   ▼
          ┌─────────────────┐
          │ Neural Director │
          └───────┬─────────┘
                  │
          ┌───────▼─────────┐
          │   Dependency    │
          │    Manager      │
          └───────┬─────────┘
                  │
                  ▼
          ┌─────────────────┐
          │ Memory Manager  │
          └───────┬─────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
       NP0       NP1       NP...
        │         │         │
        └─────────┼─────────┘
                  │
                  ▼
              RESULTS
18. Scheduling dinamico

Il sistema deve permettere che:

NP0 → node A
NP1 → node B
NP2 → node C
NP3 → WAIT

Se NP3 attende un risultato:

NP3 WAIT

non deve bloccare:

NP0
NP1
NP2

Quando il risultato arriva:

Producer
   ↓
Dependency Manager
   ↓
dependency resolved
   ↓
job READY
   ↓
Director
   ↓
free processor
19. Supporto a reti diverse

L'architettura deve essere sufficientemente generale per supportare:

Layer regolari
input → layer → layer → output
DAG
       ┌── node B ──┐
node A ┤            ├→ node E
       └── node C ──┘
Fuzzy network

con dipendenze irregolari e numero variabile di ingressi.

Cloud / sparse graph

con nodi attivati dinamicamente.

Non costruire il sistema assumendo esclusivamente una rete fully-connected regolare.

20. Simulazione obbligatoria

Ogni componente deve avere un testbench.

Creare:

hardware/v2/sim/
├── tb_neural_processor.v
├── tb_neural_processor_array.v
├── tb_memory_manager.v
├── tb_prefetch_engine.v
├── tb_dependency_manager.v
├── tb_neural_director.v
└── tb_dataflow_core.v

Test obbligatori:

test funzionali;
random test;
extreme INT8;
pipeline;
stall;
backpressure;
dependency;
wake-up;
forwarding;
multi-processor concurrency;
deadlock detection;
data-loss detection;
bit-exact comparison con V1.

Valori INT8 da includere:

-128
-127
-1
0
1
126
127
21. Test bit-exact

Ogni risultato V2 deve essere confrontabile con V1.

Per gli stessi:

inputs
weights
bias
activation
network

deve essere verificato:

V1 result == V2 result

salvo differenze esplicitamente documentate e matematicamente giustificate.

22. Performance simulation

La simulazione deve misurare almeno:

total_cycles
compute_cycles
stall_cycles
memory_wait_cycles
processor_busy_cycles
processor_idle_cycles
completed_neurons
completed_tiles
processor_utilization
memory_utilization
effective_throughput
stall_percentage

Eseguire anche sweep della latenza memoria:

0 cycles
1 cycle
2 cycles
4 cycles
8 cycles
16 cycles

L'obiettivo è misurare quanto efficacemente il prefetch nasconde la latenza.

23. Sintesi e Place & Route

Ogni configurazione deve essere realmente verificata con:

Icarus / Verilator
Yosys
nextpnr-ecp5

Non inventare risultati.

Non stimare il timing come se fosse una misura.

Distinguere sempre:

THEORETICAL
RTL SIMULATION
SYNTHESIS
POST-P&R MEASUREMENT

Il valore Fmax ufficiale della configurazione deve provenire dal place-and-route reale.

24. Benchmark

Per ogni configurazione creare:

hardware/v2/reports/
├── simulation/
├── synthesis/
├── timing/
└── experiments/

Esempio:

hardware/v2/reports/experiments/EXP-0001/
├── experiment.yaml
├── simulation.log
├── synthesis.log
├── timing.log
├── results.txt
└── notes.md

Ogni benchmark deve contenere almeno:

Fmax
processors
P_IN
MAC/cycle
LUT
FF
DSP
BRAM
cycles/neuron
neurons/s
stall %
effective MAC/s
25. LOGGING OBBLIGATORIO
Questa è una regola fondamentale del progetto.

OGNI attività significativa deve essere registrata.

Nessuna modifica, simulazione, sintesi, benchmark, decisione architetturale o errore deve essere perso.

Creare:

hardware/v2/logs/
├── development.log
├── architecture.log
├── simulation.log
├── synthesis.log
├── timing.log
├── benchmark.log
├── decisions.log
├── experiments.log
└── errors.log

Il registro principale deve essere:

hardware/v2/logs/experiments.log

Ogni esperimento deve avere un identificativo univoco:

EXP-0001
EXP-0002
EXP-0003
...

Gli ID non devono essere riutilizzati.

26. Contenuto minimo di ogni log

Ogni evento significativo deve contenere:

timestamp
experiment_id
git_commit
session/agent
module
configuration
action
reason
command
result
errors
decision
next_action

Per synthesis/timing includere anche:

LUT
FF
DSP
BRAM
Fmax
critical path
WNS/TNS se disponibili

Per simulazione:

test
vectors
cycles
PASS/FAIL
bit-exact result
stall cycles
memory wait
utilization
27. Logging delle decisioni

Ogni scelta architetturale importante deve essere registrata in:

hardware/v2/logs/decisions.log

Formato concettuale:

DEC-0001

DATE:
...

DECISION:
Use 4 independent P8 Neural Processors.

WHY:
...

EVIDENCE:
EXP-0001
EXP-0002
EXP-0003

ALTERNATIVES:
P4 × 8
P8 × 4
P16 × 2

RESULT:
...

STATUS:
ACCEPTED

Le decisioni devono essere basate su dati quando possibile.

28. Nessuna sovrascrittura dei risultati

I risultati precedenti non devono essere cancellati o sovrascritti.

Se:

EXP-0017 = PASS
EXP-0018 = FAIL
EXP-0019 = PASS

tutti e tre devono rimanere.

Un risultato negativo è comunque un risultato utile.

Deve essere possibile ricostruire la storia:

idea
↓
implementazione
↓
test
↓
fallimento/successo
↓
modifica
↓
nuovo test
↓
decisione
29. Riproducibilità

Ogni esperimento deve essere riproducibile.

Il log deve permettere di sapere:

quale commit
quale configurazione
quali parametri
quale toolchain
quale comando
quale testbench
quali constraint
quale risultato

Ogni report deve essere associato al commit Git utilizzato.

Se il working tree contiene modifiche non committate, questo deve essere esplicitamente registrato.

30. Regola contro risultati inventati

È vietato presentare dati non misurati come dati reali.

Esempio:

4 × P8 @ 80 MHz = 2.56 GMAC/s

deve essere indicato:

THEORETICAL

Finché non esiste una misura reale.

Un risultato:

Fmax = 83.7 MHz

può essere dichiarato misurato solo se ottenuto da:

nextpnr-ecp5

con relativa configurazione e report salvati.

31. Sweep automatici

Creare:

hardware/v2/scripts/sweep/

Gli script devono poter eseguire automaticamente combinazioni di:

P_IN
N_PROCESSORS
FIFO depth
buffer depth
pipeline configuration

e produrre automaticamente:

simulation
synthesis
place-and-route
timing
resource utilization
benchmark

Ogni configurazione deve generare un proprio:

EXP-XXXX

e registrarlo nei log.

32. Confronto V1 vs V2

Il benchmark finale deve produrre una tabella:

                 V1       V2
------------------------------------
Fmax
LUT
FF
DSP
BRAM
MAC/cycle
cycles/neuron
neurons/s
stall %
memory utilization
processor utilization
effective MAC/s

Ogni numero deve essere classificato come:

THEORETICAL
SIMULATED
SYNTHESIZED
POST-P&R
33. Roadmap di implementazione
M1 — Neural Processor

Implementare:

hardware/v2/rtl/neural_processor.v

P8.

Input forniti direttamente dal testbench.

Obiettivo:

bit-exact V1
pipeline funzionante

Eseguire simulation + synthesis + timing.

M2 — Processor Array

Implementare:

neural_processor_array.v

Testare:

1
2
4
8

processor.

Misurare:

timing;
risorse;
throughput;
utilization.
M3 — Buffers

Implementare:

activation_buffer.v
weight_buffer.v
result_buffer.v
M4 — Memory Manager

Implementare:

memory_manager.v
prefetch_engine.v

Inizialmente utilizzare il backend PSRAM esistente.

M5 — Neural Director

Implementare:

neural_director.v

Scheduling iniziale:

first-free
M6 — Dependency Manager

Implementare:

dependency_manager.v

Aggiungere:

ready;
waiting;
dependency counters;
wake-up;
producer tracking.
M7 — Dataflow Core

Integrare:

dataflow_core.v
M8 — PSRAM integration

Integrare il controller V1 senza modificarlo inizialmente.

Misurare il comportamento reale.

M9 — Full benchmark

Confrontare V1/V2.

M10 — Optimization

Solo sulla base dei dati:

pipeline;
P_IN;
numero processor;
buffer;
FIFO;
scheduling;
prefetch;
routing;
memoria.
34. Principi architetturali non negoziabili
V1 rimane intatta.
V2 vive esclusivamente sotto hardware/v2/....
Nessun risultato inventato.
Ogni misura deve provenire dagli strumenti appropriati.
Ogni modifica deve essere registrata.
Ogni esperimento deve avere un ID.
Nessun risultato precedente deve essere sovrascritto.
Ogni decisione importante deve avere una motivazione.
Ogni benchmark deve essere riproducibile.
Un processor bloccato non deve bloccare gli altri.
Il Neural Processor non deve conoscere direttamente la memoria esterna.
Il Director gestisce WHAT deve essere eseguito.
Il Memory Manager gestisce COME rendere disponibili i dati.
Il Neural Processor gestisce COME eseguire il calcolo.
Ottimizzare il throughput effettivo, non il numero di DSP utilizzati.
Evitare grandi mux e interconnessioni globali quando possibile.
Favorire località fisica e pipeline.
Le configurazioni devono essere esplorate sperimentalmente.
Ogni modifica deve essere confrontata con la baseline.
Il progetto deve mantenere una cronologia completa e ricostruibile dello sviluppo.
35. Filosofia finale

La V2 deve evolvere FPGA-Neural verso:

                 NEURAL DIRECTOR
                       │
          ┌────────────┼────────────┐
          │            │            │
       READY        WAITING      DEPENDENCY
        QUEUE        QUEUE        MANAGER
          │
          ▼
                  MEMORY MANAGER
                       │
             ┌─────────┼─────────┐
             │         │         │
          INPUT      WEIGHT    RESULT
          BUFFER     BUFFER    BUFFER
             │         │         │
             └─────────┼─────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
       NP0            NP1            NP...
        │              │              │
        └──────────────┼──────────────┘
                       │
                  DATAFLOW / FORWARD

Il risultato finale deve essere una macchina neurale parallela e dataflow, capace di mantenere occupati più Neural Processor contemporaneamente, nascondere la latenza della memoria, gestire dipendenze dinamiche e scalare il numero di processor in funzione dei limiti reali dell'ECP5.

Il processo di sviluppo deve essere completamente tracciabile:

IDEA
 ↓
ARCHITECTURE LOG
 ↓
IMPLEMENTATION
 ↓
SIMULATION
 ↓
SYNTHESIS
 ↓
PLACE & ROUTE
 ↓
MEASUREMENT
 ↓
EXPERIMENT LOG
 ↓
DECISION LOG
 ↓
NEXT EXPERIMENT

Non deve esistere una modifica "non registrata", una misura "senza report" o una decisione architetturale "senza motivazione".