FPGA-Neural/docs/FPGA-Neural-Flash-Subsystem-Verification.md

Sottosistema flash — documento di verifica (F1-F6)

Questo documento consolida, per modulo, cosa è verificato, come, contro quale oracolo, e cosa NON è coperto — il deliverable richiesto esplicitamente da §9 del prompt di fase. La narrazione cronologica completa (inclusi i bug trovati e corretti, con la loro esatta diagnosi) resta in WORKLOG.md; questo documento è il riferimento strutturato, non una sostituzione.

Standard applicato ovunque (§A del prompt di fase): oracolo indipendente dal design (mai auto-referenziale), due piani di verifica (simulazione Icarus + sintesi/place&route reale Yosys+nextpnr-ecp5), test avversari oltre al caso positivo, tracciabilità delle fonti.

---

rtl/spi_flash_master.v — master SPI verso la flash (F1)

Cosa è coperto: RDID, READ, WREN, PP (incl. la regola "solo AND, mai OR" del datasheet), SE, RDSR-1; gestione USRMCLK per CCLK post-configurazione; opcode non implementato non causa hang.

Come: sim/spi_flash_master_tb.v, 5 test contro sim/flash_model.v.

Oracolo: (1) valore JEDEC ID scritto indipendentemente nel testbench, dal datasheet W25Q128JV(-DTR) §8.1.1 p.24 — non letto dalla costante di flash_model.v; (2) per READ, un pattern piantato via riferimento gerarchico DIRETTAMENTE in flash_model.mem[], mai passato per l'RTL sotto test; (3) per PP AND-only, un secondo programma con 0xFF che NON deve alterare il primo valore (TEST3b) — distingue la regola vera da un "program sovrascrive" ingenuo che passerebbe un test più debole.

Test avversari: opcode illegale (0xAB, comando reale W25Q128JV ma non implementato) → nessun hang, il master shifta un numero fisso di bit indipendentemente dalla semantica.

Sintesi reale: yosys synth_ecp5 (0 problemi) + nextpnr-ecp5 reale, modulo isolato: Fmax 181.72 MHz (PASS a 80MHz), USRMCLK 1/1 piazzata.

NON coperto (§A.6): nessun test di power-loss (arriva a livello catalogo, F4); nessun timeout RDSR a questo livello (responsabilità del chiamante, F3); nessuna verifica elettrica/analogica reale (setup/hold, rise/fall) — solo comportamentale; polarità di USRMCLKTS basata sulla convenzione open-source comune, non verificata contro la Technical Note Lattice primaria (non presente nel set documentale locale).

---

sim/flash_model.v — modello comportamentale della flash (SOLO simulazione)

Cosa modella: erase→0xFF, program solo AND, WIP/WEL, timing tPP/tSE ai valori MAX del datasheet (non TYP — un design che funziona solo col caso tipico non è corretto), power-loss hook (forzatura di pending_pp/pending_se/busy via riferimento gerarchico).

Oracolo per ogni regola: citazione diretta del datasheet W25Q128JV(-DTR) locale, §/pagina specifica per ogni regola (vedi commenti nel sorgente).

Discrepanza dichiarata: il PDF locale è titolato "W25Q128JV-DTR" (variante Double Transfer Rate), non il part number liscio "W25Q128JV" del BOM reale (docs/FPGA-Neural-Hardware-Design.md §6/§7). Il set di istruzioni standard-SPI e i timing §9.6 sono condivisi da tutta la famiglia (validi senza riserve); il JEDEC ID invece NO — il modello usa EF4018h (part liscio, pubblicamente documentato) non EF7018h (quello di questo PDF specifico). Il bring-up su hardware reale deve confermare l'RDID effettivo.

NON coperto (§A.6): Fast/Dual/Quad/QPI/DTR (fuori scope, solo SPI standard usato); bit di protezione/Individual Block Lock (fuori scope, la flash è esclusiva della FPGA); timing elettrico reale; il power-loss simulato rappresenta solo "operazione mai committata", non "committata a metà" (limite del modello, dichiarato).

---

rtl/flash_copy_engine.v — copy engine LOAD/SAVE/ERASE (F2/F3/F5)

Cosa è coperto: DIR_LOAD (flash→PSRAM, chunking automatico oltre 65535B), DIR_SAVE (PSRAM→flash, erase-before-write, loop Page Program ≤256B, poll WIP), DIR_ERASE (erase settore standalone, F5).

Come: sim/flash_copy_engine_load_tb.v (5 test), sim/flash_copy_engine_save_tb.v (5 test), sim/flash_copy_engine_erase_tb.v (3 test) — stack PSRAM reale (mem_arbiter → int8_memory_access → memory_interface → psram_controller → psram_model), non un modello semplificato.

Oracolo: dati piantati indipendentemente in flash_model.mem[] (LOAD) o letti direttamente da lì dopo una SAVE (non passati per l'RTL sotto test in nessuno dei due sensi); per la regola AND-only, un settore pre-avvelenato con un pattern diverso da quello salvato, verificando che la coda non scritta torni a 0xFF (prova un erase reale, non solo un program sopra il vecchio contenuto).

Test avversari: lunghezza fuori range (flash e PSRAM), len==0, blocco non allineato al settore (SAVE/ERASE), blocco che attraversa un confine di pagina 256B (300 byte, 2 pagine), contesa reale dell'arbitro con un master a priorità più alta durante un intero LOAD, WIP prolungato (forzato via hook power-loss, nessun timeout — poll continua, completa quando WIP si libera davvero).

Due bug trovati e corretti durante il bring-up (dettagli completi in WORKLOG.md, F2):

1. Bug pre-esistente in rtl/psram_controller.v (non del sottosistema flash): richieste arrivate durante i primi ~150µs dopo reset venivano perse silenziosamente, e la sequenza interna di configurazione del chip generava impulsi mem_ready spuri. Rischio reale per lo scenario "boot standalone da flash" per cui esiste questo sottosistema. Corretto con coda per richieste precoci + guardia sugli impulsi spuri.
2. Bug nel nuovo codice: d_req verso l'arbitro PSRAM era un impulso di un ciclo, perdibile in caso di contesa esatta con un'altra porta. Corretto rendendolo un segnale di livello tenuto alto finché non viene servito davvero (con un secondo sotto-bug — race sul ciclo esatto di rilascio dell'arbitro — trovato e corretto nello stesso giro).

Sintesi reale: yosys synth_ecp5 pulito + nextpnr-ecp5 reale, modulo isolato: F2 172.98 MHz, F3 158.28-158.55 MHz (PASS a 80MHz, numeri di solo modulo).

NON coperto (§A.6): blocco >65535B a piena dimensione (chunking implementato e ragionato, non esercitato a piena scala per tempo di simulazione); due SAVE consecutive su settori adiacenti (non richiesto per queste fasi).

---

rtl/crc32.v — CRC32 (F4)

Cosa è coperto: algoritmo CRC32 riflesso standard (IEEE 802.3/zlib, polinomio 0xEDB88320).

Come: sim/crc32_tb.v, 4 test.

Oracolo — TRE fonti indipendenti: (1) identità matematica del messaggio vuoto (init XOR final = 0); (2) valore di controllo testuale standard pubblicato "123456789" → 0xCBF43926 (citato in ogni tabella di riferimento CRC32, non calcolato da nessuno dei due lati); (3) tools/flash_catalog/oracle.py, che usa zlib.crc32 della libreria standard Python — implementazione completamente separata, non derivata dalla stessa comprensione di design.

NON coperto: nessuna verifica di throughput/pipeline (l'accumulatore è un aggiornamento combinazionale per byte, non un collo di bottiglia dato il ritmo flash/PSRAM molto più lento).

---

rtl/flash_slot_manager.v — catalogo a slot fissi (F4/F5)

Cosa è coperto: CAT_READ (ricarica il catalogo on-chip da flash), CAT_WRITE_SLOT (registra/aggiorna una voce, persiste l'intero catalogo), LOAD_SLOT/SAVE_SLOT (risolvono lo slot dal catalogo on-chip, CRC calcolato dal vero stream di byte), più i 3 opcode raw (F5: FLASH_READ_BLOCK/FLASH_WRITE_BLOCK/FLASH_ERASE, pass-through diretto senza catalogo/CRC).

Come: sim/flash_slot_manager_tb.v (6 test, F4), sim/flash_slot_manager_raw_tb.v (4 test, F5) — stesso stack PSRAM reale.

Oracolo: tools/flash_catalog/oracle.py — layout byte del catalogo e CRC32 di riferimento, confrontati byte-a-byte contro i byte REALI persistiti in flash_model.mem[] (non contro il decode dell'RTL stesso).

Test avversari: CRC corrotto (un bit capovolto direttamente in flash_model.mem[]) → LOAD_SLOT rifiuta; slot mai salvato → LOAD_SLOT rifiuta immediatamente, nessuna transazione tentata (sentinella PSRAM intatta); power-loss simulato durante il Sector Erase di una SAVE_SLOT (hook di flash_model.v, settore pre-avvelenato con pattern diverso) — il motore "completa con successo" secondo RDSR (nessun modo per saperlo altrimenti), ma il CRC persistito non combacia più coi byte reali (mai davvero cancellati) → una LOAD_SLOT successiva lo rileva. Dimostra che il meccanismo di rilevamento dipende dal CRC sui byte realmente committed, non da un segnale di completamento che può mentire.

Bug trovato e corretto in revisione (prima di ogni simulazione): condizione di aggiornamento del CRC basata su fce_d_req && d_ready — contraddizione logica sempre falsa, dato come flash_copy_engine.v definisce il proprio d_req. Corretta in fce_busy && d_ready. Decode di una voce di catalogo inizialmente incompleto (solo offset). Gap trovato in revisione durante F5: SAVE_SLOT non controllava fce_err prima di marcare il catalogo valido.

Sintesi reale: yosys synth_ecp5 pulito (0 problemi CHECK). Place&route reale a livello di modulo isolato NON eseguibile per questo modulo specifico (253 bit di porte a livello di modulo superano i 245 pin fisici del package — artefatto del testare un modulo interno come top fittizio, non un problema del design); la vera verifica di piazzamento arriva con l'integrazione in spi_neuron_top (F5, sotto).

NON coperto (§A.6): due slot che si sovrappongono in flash (responsabilità dell'host, che governa offset/length via CAT_WRITE_SLOT); CATALOG_PSRAM_ADDR è una convenzione non imposta altrove — vedi §5 "limiti host" sotto per la conseguenza reale di questo limite.

---

rtl/spi_engine.v — opcode SPI del sottosistema flash (F5)

Cosa è coperto: decodifica degli 8 opcode (0x40-0x47), accumulatore di payload condiviso, STATUS esteso (bit3=flash_err_sticky, bit4=flash_busy), done_event corretto per includere il completamento flash come sorgente indipendente dall'inferenza.

Come: sim/spi_neuron_top_flash_tb.v (test end-to-end via SPI reale bit-banged) + regressione di sim/spi_engine_tb.v (esistente, invariato).

Oracolo: derivazione a mano bit-per-bit di ogni campo del payload (stesso metodo di F1), verificata via traccia diretta dei valori decodificati (flash_op_code/flash_slot_id/ecc.) prima di fidarsi del comportamento a valle.

Bug trovato DALLA REGRESSIONE, non dalla progettazione (motivo per cui va sempre rieseguita, mai solo assunta): la prima versione di done_event sostituiva un multiplexer a priorità ESISTENTE (che maschera deliberatamente gli nm_done intermedi durante una RUN_NETWORK multi-layer) con un OR piatto — sim/spi_engine_tb.v ha fallito immediatamente ("done bit set by an intermediate nm_done"). Corretto preservando la maschera esistente INVARIATA e aggiungendo flash_done come sorgente OR separata, fuori dalla maschera.

NON coperto: nessuna verifica formale di tutte le 2^N combinazioni di byte payload malformati (fuori scope — i test coprono il caso positivo e gli specifici casi avversari già verificati ai livelli sottostanti, che l'SPI framing si limita a inoltrare fedelmente).

---

rtl/spi_neuron_top.v — integrazione finale (F5)

Cosa è coperto: istanziazione di flash_slot_manager, nuovi pin fisici (flash_mosi/flash_miso/flash_cs_n, distinti dai pin SPI host), Port D dell'arbitro collegata (non più tied-off), pinout reale rigenerato.

Come: sim/spi_neuron_top_flash_tb.v, 4 test sopra lo STACK COMPLETO REALE.

Il test end-to-end richiesto esplicitamente da §6 del piano: netasm → WRITE_RAM → SAVE_SLOT → (sovrascrittura PSRAM con garbage) → LOAD_SLOT → RUN_NETWORK → READ_RAM = 126 — lo stesso valore atteso indipendente già usato in sim/graph_engine_tb.v/ sim/spi_neuron_top_graph_tb.v (esempio da manuale §3), non ri-derivato.

Tre intoppi reali nella costruzione del test, nessun bug RTL (dettagliati in WORKLOG.md, F5): collisione PSRAM tra il blob di rete e CATALOG_PSRAM_ADDR di default; --parallel di netasm non corrispondente al PARALLEL reale dell'hardware; netasm incorpora indirizzi ASSOLUTI (non relativi) nella tabella descrittore, quindi spostare il blob compilato richiede rigenerarlo con --table-base/--edges-base corrispondenti — un mismatch qui produce un risultato "riuscito" (STATUS pulito, nessun errore) ma completamente sbagliato, senza alcun sintomo hardware-visibile.

Sintesi reale, livello di SISTEMA COMPLETO (prima volta per il sottosistema flash integrato): 0 errori di vincolo, 56/56 celle piazzate. Fmax 66.68 MHz (FAIL a 80MHz, atteso — percorso critico verificato esplicitamente IDENTICO a quello già noto dalla Fase 7, neuron_parallel's catena di riporto dell'accumulatore, NESSUN modulo flash coinvolto). Il calo dai 73.88MHz precedenti è rumore di piazzamento (banda già caratterizzata), non una regressione — confermato dal percorso critico invariato.

Occupazione (sistema completo): TRELLIS_IO 56/245 (22%), TRELLIS_FF 4855/43848 (11%), TRELLIS_COMB 9060/43848 (20%), DP16KD 2/108, MULT18X18D 16/72, USRMCLK 1/1 (100%) — nessuna pressione sulle risorse del dispositivo.

---

Scoperta trasversale: limite reale di WRITE_RAM/READ_RAM (non specifica alla flash)

Durante il bring-up del test end-to-end (F5) è emerso che WRITE_RAM/READ_RAM (opcode esistenti, PRE-esistenti a questa intera sessione, mai modificati) non hanno alcun backpressure verso il master SPI — limite già dichiarato nell'header di spi_engine.v ma la cui conseguenza pratica (corruzione silenziosa dei dati, non un hang, non un errore) non era mai stata esposta prima. È emersa a causa del fix CORRETTO su psram_controller.v (sopra): un bug pre-esistente diverso mascherava accidentalmente il rischio, dando all'host "fortunatamente" abbastanza poco tempo da non disallinearsi. Rischio reale per QUALUNQUE host che emetta WRITE_RAM/READ_RAM troppo presto dopo il reset (entro il power-up ~150µs di psram_controller), non solo per i test di questa sessione. Mitigazione applicata qui: ogni testbench aspetta esplicitamente psram_ctrl.state == STATE_IDLE prima del primo accesso PSRAM. Non risolto nell'RTL (fuori scope per il sottosistema flash — richiederebbe un vero protocollo di backpressure): dichiarato come rischio aperto, non nascosto.

---

Latenze reali misurate (F6)

Metodologia (dichiarata esplicitamente, §A.5): simulare l'intera attesa WIP a scala temporale reale con il vero loop di poll RDSR si è rivelato impraticabile — a timing reale, coprire un'attesa di 400ms con poll a ritmo SPI reale richiede circa 100.000+ transazioni di poll, decine di milioni di eventi Icarus, oltre il limite pratico di tempo macchina (limite del simulatore, non dell'hardware — un poll reale su silicio non costa tempo di simulazione). Approccio usato: la fase di "issue" (WREN+SE/PP, limitata dal clock SPI) è misurata direttamente in simulazione (accurata indipendentemente dalla scala temporale del modello flash, che scala solo l'attesa WIP successiva); la durata dell'attesa WIP stessa è presa dal valore MAX del datasheet (già citato in sim/flash_model.v, §9.6 p.90), sommata analiticamente. Misurato con sim/flash_latency_bench.v.

Operazione	@16MHz	@80MHz
ERASE (un settore 4KB)	400.014 ms	400.003 ms
SAVE (256B, incl. proprio erase)	403.019 ms	403.004 ms
LOAD (4096B)	8.713 ms (0.470 MB/s)	1.743 ms (2.351 MB/s)

ERASE/SAVE sono dominati quasi interamente dal timing interno della flash (tSE_MAX=400ms, tPP_MAX=3ms — fisici, indipendenti dalla frequenza host); LOAD è invece puramente limitato dal clock SPI (nessuna attesa WIP per READ, §8 intro p.24 del datasheet) — la banda scala linearmente con la frequenza, come atteso fisicamente.

---

Riepilogo regressione (F6)

Tutti i 33 testbench del progetto (incluse le 2 varianti negative attese fallire in elaborazione) — PASS, nessuna regressione, eseguiti dopo ogni modifica significativa durante l'intera sessione, non solo alla fine.