FPGA-Neural/docs/validation/bugs.md

# Registro bug — campagna di ri-certificazione FPGA-Neural

Formato per ogni voce: severità, sintomo, causa radice, evidenza (file:riga / comando/log
citabile), stato, test di regressione che lo blocca (se risolto) o che lo riprodurrebbe (se
aperto). Aggiornato incrementalmente man mano che avanzano gli aspetti C.1–C.14.

Severità: **CRITICA** (corrompe dati/hang in scenari raggiungibili), **MEDIA** (comportamento
scorretto in casi limite plausibili ma rari), **BASSA** (difetto reale ma senza impatto
funzionale pratico), **INFO** (non un bug: gap di copertura, ambiguità documentale/naming).

---

## Aperti

### BUG-001 (INFO, non ancora classificato) — `sim/top.v` non compila contro l'RTL corrente

- **Sintomo**: `iverilog` fallisce con `parameter FRAC_BITS not found in top.dut`.
- **Causa radice**: `sim/top.v` è un residuo della versione Q8.8 a virgola fissa del
  progetto, mai aggiornato dopo la conversione a INT8 puro (Fase 6, vedi
  `docs/validation/00-inventario.md` §0.2).
- **Evidenza**: `iverilog -g2012 -o /tmp/topcheck.out rtl/neuron_parallel.v rtl/mac8.v rtl/mac_unit.v sim/top.v` → 2 errori di elaborazione.
- **Impatto**: nessuno sulla regressione (il file non è referenziato da alcun testbench o
  tool) — è dead code, non un difetto funzionale del design.
- **Stato**: aperto, non corretto per policy §E (analisi separata dalla correzione). Azione
  proposta: rimuovere il file o aggiornarlo, decisione da confermare con l'utente.

### BUG-002 (MEDIA, CONFERMATO su sim + sintesi reale) — `N_INPUTS=0` bypassa il guard, `start` viene silenziosamente ignorato

- **Sintomo confermato** (non più un'ipotesi — vedi `docs/validation/01-datapath.md` §1.4 per
  la narrativa completa, incl. un falso positivo iniziale nella mia stessa metodologia di
  test, corretto e ridocumentato per trasparenza): con
  `neuron_parallel #(.N_INPUTS(0), .PARALLEL(P))`, il guard elaboration-time
  (`rtl/neuron_parallel.v:71`, `if (N_INPUTS % PARALLEL != 0)`) **non scatta** (`0 % P == 0`
  per ogni `P`), il modulo **elabora con successo** (sia in simulazione Icarus sia in sintesi
  reale Yosys, 0 problemi CHECK). A runtime: `start` viene accettato ma **`busy` non si alza
  mai e `done` non pulsa mai** — non l'hang "busy resta alto per sempre" descritto nel
  commento originale del guard (righe 55-58), un sintomo diverso, osservato per la prima
  volta in questa campagna.
- **Causa radice, confermata (non più ipotesi)**: `x_bus`/`w_bus` sono dichiarati
  `[DATA_WIDTH*N_INPUTS-1:0]`, che per `N_INPUTS=0` diventa `[-1:0]` — un range che **non
  collassa a larghezza zero**: sia Icarus sia Yosys lo trattano come un vettore reale a
  **2 bit** (larghezza = |MSB-LSB|+1 = 2), lasciato non pilotato. Confermato dai warning di
  Yosys: `Wire ...x_bus[1] is used but has no driver` (×2, per x_bus e w_bus).
- **Evidenza**:
  - `iverilog -g2012 -o /tmp/n0proper.out rtl/neuron_parallel.v rtl/mac8.v rtl/mac_unit.v sim/neuron_parallel_bug002_n_inputs_zero_tb.v && vvp /tmp/n0proper.out` → conferma il sintomo, ogni volta.
  - `yosys -p "synth_ecp5 -json /tmp/n0.json -top n0_synth_wrap" rtl/neuron_parallel.v rtl/mac8.v rtl/mac_unit.v <wrapper>` → **0 problemi CHECK**, 4 warning "no driver" su x_bus/w_bus[1:0].
  - Test di regressione permanente: `sim/neuron_parallel_bug002_n_inputs_zero_tb.v`.
- **Impatto pratico**: `N_INPUTS` è un parametro Verilog fissato in fase di sintesi (non un
  registro configurabile via SPI a runtime) — per essere raggiunto, qualcuno deve
  deliberatamente istanziare il modulo con `N_INPUTS=0`, cosa che non ha senso semantico per
  un layer reale. Rischio quindi basso in pratica (nessun percorso runtime/host-controllato
  può innescarlo), ma è un buco reale e confermato nella protezione, non solo teorico.
- **Fix proposto** (non applicato — analisi separata dalla correzione, §E del prompt di
  certificazione): estendere il guard a `if (N_INPUTS == 0 || N_INPUTS % PARALLEL != 0)`.
- **Stato**: **APERTO, confermato, non corretto.**

### BUG-003 (MEDIA, CONFERMATO ma NON pienamente caratterizzato) — `n_inputs_real=0` a runtime, comportamento incoerente tra ripetizioni

- **Sintomo**: con `N_INPUTS=32, PARALLEL=8` validi a compile-time (nessun problema di
  larghezza `[-1:0]`, a differenza di BUG-002), impostando `n_inputs_real=0` a runtime (lo
  stesso percorso raggiungibile dall'host via `SET_BASE sel=7`) il comportamento osservato
  **varia tra ripetizioni quasi identiche dello stesso test**: a volte `start` viene
  accettato ma `busy`/`done` non si muovono mai più (hang), a volte l'operazione completa
  normalmente ma processa l'INTERA larghezza di build invece di zero elementi (limite
  ignorato silenziosamente, stessa classe di BUG-004). Vedi `docs/validation/
  02-runtime-width.md` §2.3 per la registrazione completa di ogni singola ripetizione e dei
  suoi risultati, riportati senza scartare quelli "scomodi".
- **Causa radice**: **non isolata con certezza** entro il tempo ragionevole per questa
  campagna. Analisi aritmetica plausibile (non confermata come spiegazione completa): per
  questa build `GROUP_INDEX_WIDTH=2` bit, quindi `groups_real[1:0]-1` per `groups_real=0`
  avvolge al valore 3 (raggiungibile da un contatore a 2 bit, a differenza del contatore a
  1 bit di BUG-002) — spiegherebbe l'esito "limite ignorato" come esito aritmeticamente
  atteso, ma non spiega perché in alcune ripetizioni compaia invece un hang vero. Esclusi
  esplicitamente: propagazione di X in simulazione (verificato inizializzando ogni registro
  prima di qualunque reset, il comportamento non cambia), e una dipendenza semplice
  dall'ordine delle chiamate (una sequenza valida→zero non blocca; una sequenza
  zero→zero→zero blocca dalla seconda chiamata in poi, non dalla prima — non un pattern
  semplice "prima volta sicura, poi no").
- **Impatto pratico**: come BUG-002, `n_inputs_real=0` non ha senso semantico per una rete
  reale, ma a differenza di BUG-002 questo valore **è raggiungibile a runtime da un host via
  SPI** senza bisogno di una nuova sintesi — un host con un bug che calcola erroneamente
  `n_inputs_real=0` per un caso limite (es. un layer con zero neuroni in una topologia
  degenere) potrebbe innescarlo, con un esito imprevedibile tra hang e risultato
  silenziosamente sbagliato.
- **Stato**: **APERTO, confermato come comportamento scorretto in ogni caso osservato, ma
  meccanismo esatto NON isolato** — dichiarato esplicitamente come limite di questa verifica
  (§A.5), non presentato come pienamente compreso. Richiederebbe un'indagine dedicata
  (probabilmente a livello gate/timing reale, non solo comportamentale) per chiudere con
  certezza il meccanismo, non solo il sintomo.

### BUG-004 (MEDIA, CONFERMATO scorretto, NON pienamente caratterizzato) — `n_neurons_real=0` non blocca, ma non fa nemmeno quello che ci si aspetterebbe in modo coerente

- **Sintomo**: a `rtl/neuron_memory.v`, con `n_neurons_real=0`, l'operazione **completa
  sempre normalmente** (mai un hang, a differenza di BUG-002/003) — ma il numero di cicli
  impiegato **non è coerente tra build diverse**: per `N_NEURONS=2` (`NEURON_INDEX_WIDTH=1`
  bit) impiega **esattamente** lo stesso numero di cicli di `n_neurons_real=2` (114=114,
  suggerendo che il limite venga ignorato e processi tutto), mentre per `N_NEURONS=3`
  (`NEURON_INDEX_WIDTH=2` bit) impiega **196 cicli — più della build completa a 3 neuroni
  (155)**, un terzo valore che non corrisponde né a "zero neuroni" né a "tutti i neuroni".
  In ogni caso testato: nessun errore, nessun timeout — un host che chiede zero neuroni
  riceve sempre un completamento dall'aspetto normale ma su un conteggio/dato diverso da
  quanto richiesto, e il conteggio esatto varia con `N_NEURONS`.
- **Causa radice**: non isolata bit-per-bit (a differenza di BUG-002). Ipotesi coerente con
  BUG-003: l'aritmetica di avvolgimento (`neuron_index == n_neurons_real[W-1:0]-1`) per
  `n_neurons_real=0` produce un valore di terminazione che, per coincidenza di larghezza,
  corrisponde al conteggio pieno invece che a "termina subito".
  Vedi `docs/validation/02-runtime-width.md` §2.5.
- **Impatto pratico**: come BUG-002/003, richiede che l'host imposti deliberatamente (o per
  bug proprio) `n_neurons_real=0` — non raggiungibile da un input esterno arbitrario, ma
  raggiungibile da un bug nel software host senza bisogno di ricompilare il bitstream.
- **Stato**: **APERTO, confermato, causa esatta non isolata** (stesso limite dichiarato di
  BUG-003).

### BUG-005 (CRITICA, CONFERMATO) — `RUN_NETWORK(0)` esegue 256 layer fasulli leggendo dati arbitrari come descrittori

- **Sintomo**: `rtl/layer_sequencer.v` documenta `run_num_layers` come "1..N_LAYERS" ma
  **non esiste alcun guard**, né a tempo di elaborazione né a runtime, che lo imponga.
  `layer_idx` (riga 121) è un registro a 8 bit PIENO (non ristretto come il
  `group_index` a 1 bit di BUG-002) — per `run_num_layers=0`, la condizione di
  terminazione `layer_idx == num_layers_reg-1` (riga 303) avvolge a `layer_idx==255`, un
  valore che il contatore RAGGIUNGE naturalmente contando da 0. Risultato confermato
  empiricamente: **`RUN_NETWORK(0)` non si blocca — esegue tutti e 256 gli indici di
  layer possibili** (21761 cicli in simulazione) prima di terminare, ciascuno leggendo 11
  byte di "descrittore" da `table_base + layer_idx×11` — ben oltre la vera tabella
  descrittori (dimensionata per il build reale, tipicamente poche decine di byte) — e
  interpretando dati PSRAM arbitrari (pesi, altri dati di rete, o memoria non
  inizializzata) come indirizzi/parametri di layer validi, eseguendo run reali di
  `neuron_memory` con quei parametri e **scrivendo i risultati nei buffer ping-pong a
  indirizzi derivati da quei dati arbitrari**.
- **Causa radice**: nessun guard su `run_num_layers`, né a tempo di elaborazione (come
  invece esiste per `N_INPUTS%PARALLEL` in `neuron_parallel.v`) né a runtime (come invece
  esiste, sia pure incompleto, per `n_inputs_real`/`n_neurons_real`, BUG-003/004).
- **Evidenza**: `sim/layer_sequencer_bug005_zero_layers_tb.v` — `iverilog -g2012 -o /tmp/ls0.out rtl/layer_sequencer.v sim/layer_sequencer_bug005_zero_layers_tb.v && vvp /tmp/ls0.out` →
  `dut.layer_idx` termina a 255, non a 0.
- **Impatto pratico**: **più severo di BUG-002/003/004** — raggiungibile con un singolo
  opcode SPI documentato (`RUN_NETWORK`, `num_layers=0`) senza bisogno di ricompilare il
  bitstream né di impostare un valore "runtime" degenere in un percorso secondario; il
  rischio non è solo un risultato sbagliato o un hang, ma **scritture reali in PSRAM a
  indirizzi non controllati**, derivati da dati che non erano mai stati pensati per essere
  interpretati come indirizzi.
- **Fix proposto** (non applicato — analisi separata dalla correzione): guard a runtime in
  `layer_sequencer.v` analogo a quello di `neuron_parallel.v`, es. rifiutare
  `run_num_layers==0` prima di avviare la sequenza (riportando un errore osservabile invece
  di procedere).
- **Stato**: **APERTO, confermato, causa isolata con certezza** (a differenza di
  BUG-003/004, qui il meccanismo esatto è stato individuato precisamente, non solo il
  sintomo).

### BUG-006 (BASSA, stessa causa radice di BUG-005, protezione incidentale) — `num_neurons_graph=0` in `graph_engine.v`

- **Sintomo/causa radice**: identica struttura a BUG-005 — `neuron_idx`
  (`rtl/graph_engine.v:159`) è un registro a 16 bit pieni, `num_neurons_graph=0` fa
  avvolgere la condizione di terminazione a un valore (65535) che il contatore raggiunge
  naturalmente. Nessun guard esplicito su `num_neurons_graph`.
- **Differenza da BUG-005**: `graph_engine` ha già un guard runtime per-edge
  (`src_id>=out_id`/`out_id>=N_TOTAL` → `err`) che, **come effetto collaterale non
  progettato per questo scopo**, cattura la maggior parte dei pattern di dati spazzatura
  molto rapidamente — verificato con un pattern non banale: `err` a 58 cicli, non 65536.
  `layer_sequencer.v` non ha alcuna protezione equivalente.
- **Evidenza**: `sim/graph_engine_bug006_zero_neurons_probe_tb.v` — finestra di 5000 cicli,
  non fatto girare a completamento (limite dichiarato, vedi
  `docs/validation/06-graph-engine.md` §6.2).
- **Impatto pratico**: basso ma non nullo — la protezione osservata è incidentale, non
  garantita per ogni possibile contenuto PSRAM. Il buco strutturale è reale.
- **Stato**: **APERTO**, severità inferiore a BUG-005 per la protezione incidentale
  osservata, non pienamente verificato su ogni pattern di dati possibile.

---

## Risolti

(nessuno ancora in questa campagna — la Fase 0 è analisi/inventario, non correzione)

---

## Non-bug (falsi positivi trovati e chiusi durante l'analisi)

Voci che sono sembrate anomalie a un primo controllo automatico ma si sono rivelate corrette
per progetto una volta letto il codice/intento — riportate per trasparenza sul processo, non
perché siano difetti.

- **`neuron_parallel_guard_negative_{degenerate,nonmultiple}_tb.v` "falliscono a compilare"**:
  comportamento corretto e intenzionale (test negativi, la mancata compilazione è il PASS).
  Vedi `docs/validation/00-inventario.md` §0.5.
- **`graph_engine_bandwidth_tb.v` "nessun verdetto PASS/FAIL"**: è un benchmark per
  progetto, non un test di correttezza. Vedi §0.3/§0.5 dell'inventario.
- **C.1 (falso "hang" iniziale, `neuron_parallel` config nota-buona)**: controllo tardivo e
  singolo di `done` (impulso di un solo ciclo) in uno script bespoke — non un problema
  dell'RTL. Vedi `docs/validation/01-datapath.md` §1.4.
- **C.2 (falso "hang" per `n_inputs_real=17`)**: stesso tipo di errore in un secondo script
  bespoke diverso da quello già provato — corretto riusando lo schema affidabile. Vedi
  `docs/validation/02-runtime-width.md` §2.2.
- **C.3 (falsi mismatch su 2048 controlli + un falso fallimento di round-trip)**: nel nuovo
  `sim/int8_memory_access_bytelane_tb.v`, un controllo dei segnali nello stesso passo di
  simulazione del loro aggiornamento non-bloccante (leggeva il valore dell'iterazione
  precedente), e uno stub di memoria comportamentale che ignorava le byte-lane
  `mem_lb_n`/`mem_ub_n` durante la scrittura. Entrambi difetti della testbench, non
  dell'RTL — vedi `docs/validation/03-memoria.md` §3.1.
- **C.4 (`mem_arbiter` mai concedeva nulla nella mia prima testbench)**: assegnazioni
  bloccanti per ritirare le richieste dei "perdenti" nello stesso fronte di clock che
  doveva concedere la richiesta — race reale con il blocco sincrono del DUT. Diagnosticato
  con `dut.owner` mai uscito da `SEL_NONE`. Corretto passando ad assegnazioni non bloccanti.
  Vedi `docs/validation/04-arbiter.md` §4.1.