FPGA-Neural/WORKLOG.md

WORKLOG

Fase: Setup sessione debug neuron_memory (2026-09-02)

• 2026-09-02T00:00 — [FASE 0] — Avviata sessione di debug su neuron_memory. Contesto fornito dall'utente: core di calcolo (neuron_parallel, mac8, mac_unit) considerato corretto e non da toccare; neuron_memory gestisce solo N_NEURONS=1; bug noto in sim/neuron_memory_tb.v su preload_vector/preload_weights (usavano base + (k>>1) invece di (base>>1) + (k>>1)).
• 2026-09-02T00:01 — [FASE 0] — git status: modifiche non committate su sim/neuron_memory.vcd, sim/neuron_memory_sim, sim/neuron_memory_tb.v (working tree su main).
• 2026-09-02T00:02 — [FASE 0] — git diff sim/neuron_memory_tb.v: confermato che il fix (base >> 1) + (k >> 1) è già presente nel working tree (non committato) sia in preload_vector che preload_weights. Aggiunto anche un nuovo task preload_x_pattern e un nuovo TEST 0 "PATTERN X=1..32" (somma 1..32 = 528, atteso saturato a 127).
• 2026-09-02T00:03 — [FASE 0] — Creato branch fix/neuron-memory-debug da main (non si lavora su main).
• 2026-09-02T00:04 — [FASE 0] — Letto rtl/neuron_memory.v per intero: FSM IDLE->READ_X->READ_W->READ_BIAS->START_N->WAIT_N. Nota: access_mem_rdata ricostruisce una parola a 16 bit da un singolo byte (mem_rdata esterno a 8 bit) usando access_addr[0] come selettore, per poi essere ri-decodificata dentro int8_memory_access con addr_reg[0] catturato alla request. Da verificare se il timing di access_addr (che avanza al prossimo indice nello stesso colpo di clock in cui access_ready viene consumato) possa disallinearsi da addr_reg[0] interno a int8_memory_access.
• 2026-09-02T00:05 — [FASE 0] — Letto rtl/int8_memory_access.v per intero: FSM IDLE/WAIT, converte addr byte->word (addr>>1), seleziona lb_n/ub_n in base a addr[0], estrae byte da mem_rdata in base a addr_reg[0] (registrato alla request, non al momento della ready) — quindi il rischio di disallineamento sopra ipotizzato non sussiste per l'estrazione interna a int8_memory_access, ma resta da verificare access_mem_rdata lato neuron_memory che usa access_addr[0] corrente (non registrato) nello stesso ciclo in cui int8_memory_access è ancora in STATE_WAIT.
• 2026-09-02T00:06 — [FASE 0] — Letto sim/neuron_memory_tb.v per intero: testbench end-to-end con memory_interface + psram_controller + psram_model reali (non mock), mux a singolo master (TB preload vs neuron_memory), 5 test (PATTERN, SUM, SATURATION, RELU, BIAS=10).
• 2026-09-02T00:10 — [FASE 1] — Compilato: iverilog -g2012 -o sim/neuron_memory_sim rtl/*.v sim/psram_model.v sim/neuron_memory_tb.v. Nessun errore/warning.
• 2026-09-02T00:11 — [FASE 1] — Eseguito: vvp sim/neuron_memory_sim. Risultato: TUTTI I 5 TEST PASSANO (PATTERN X=1..32 -> y=127 saturato correttamente; SUM=32 -> y=32; SATURATION -> y=127; RELU -> y=0; BIAS=10 -> y=42). Conferma che il fix (base>>1)+(k>>1) già presente nel working tree risolve correttamente l'indirizzamento byte->word nel preload e che neuron_memory.v (non modificato in questa sessione) è funzionalmente corretto per N_NEURONS=1 con questo pattern di test.
• 2026-09-02T00:12 — [FASE 1] — Analisi manuale del timing dell'handshake req/ready tra neuron_memory.v e int8_memory_access.v (in particolare access_mem_rdata che ricostruisce la word a 16 bit usando access_addr[0] corrente, non registrato): il redirect avviene un ciclo dopo che access_req diventa 1 quando access_ready è ancora alto, quindi access_addr non è stato ancora aggiornato al nuovo indice nel ciclo in cui access_mem_rdata viene consumato da int8_memory_access — nessuna race identificata. Confermato empiricamente anche dal test PATTERN X=1..32 che esercita 32 letture byte consecutive con parità alternata (indirizzi pari/dispari) e produce la somma corretta (528, satura a 127).
• 2026-09-02T00:15 — [FASE 2] — Eseguita regressione sugli altri testbench del repo per verificare che non ci fossero altri "test già eseguiti" rilevanti da esaminare:
  • int8_memory_access_tb: PASS (tutti i sotto-test)
  • memory_interface_tb: PASS
  • psram_controller_tb: PASS (2048 transazioni stress + byte enable)
  • int8_psram_integration_tb: PASS (incl. 2048 stress)
  • parametric_tb (256x4, PARALLEL=32): PASS (N0..N3, incl. ReLU e saturazione)
  • layer_tb: FALLISCE in elaborazione — parameter FRAC_BITS not found in tb.dut. Il testbench referenzia un parametro FRAC_BITS non più presente in rtl/layer.v (probabile debito tecnico da refactor precedente, indipendente da neuron_memory).
  • neuron_parallel_tb: FALLISCE in elaborazione — stesso errore, parameter FRAC_BITS not found in tb.dut, riferito a rtl/neuron_parallel.v.
  • NOTA: questi due fallimenti sono preesistenti e non toccano i file modificati in questa sessione (sim/neuron_memory_tb.v). Non risolti in questa sessione perché fuori scope dichiarato (debug neuron_memory); da segnalare all'utente.
• 2026-09-02T00:20 — [FASE 3] — CONCLUSIONE: il bug indirizzamento byte/word nei task preload_vector/preload_weights di sim/neuron_memory_tb.v era l'unico difetto riscontrato nel percorso neuron_memory; risulta già corretto nel working tree e validato con successo da tutti e 5 i test (incl. il nuovo test PATTERN aggiunto). Nessun bug residuo individuato in rtl/neuron_memory.v o rtl/int8_memory_access.v per il caso N_NEURONS=1. Procedo al commit del fix sul branch fix/neuron-memory-debug.