michele/FPGA-Neural
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

test: certify mac_unit/mac8 datapath (C.1), confirm real N_INPUTS=0 guard gap

Browse Source 
mac_unit.v: exhaustive unit test (all 65536 (x,w) combinations at
DATA_WIDTH=8, plus 486 boundary acc_in vectors) against an independent
Python oracle (tools/validation/mac_oracle.py). 66022/66022 match, 0
reserves.

mac8.v: first-ever dedicated unit test (previously only indirect
coverage at whatever single PARALLEL neuron_parallel_tb.v happens to
use). Verified at PARALLEL=2/8/32 with structural adversarial vectors
(catches swapped/duplicated tree wiring), 300 random INT8 pairs per
PARALLEL with realistic accumulating acc_in, and worst-case magnitude
adversarial vectors. 939/939 match.

Confirms BUG-002 (N_INPUTS=0 bypasses the N_INPUTS%PARALLEL elaboration
guard) is real, on both simulation and real Yosys synthesis -- root
cause: [DATA_WIDTH*N_INPUTS-1:0] becomes [-1:0] for N_INPUTS=0, which
both tools treat as a genuine 2-bit undriven vector rather than
collapsing to zero width. Includes a documented self-correction: the
first verification attempt produced a false "hang" using an invalid
one-shot late check of a single-cycle done pulse -- caught by
reproducing the same false result on a known-good sanity config before
trusting it.

Full regression re-run clean after adding 3 new testbenches: 36/36 real
tests pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xXuuRUWZScuo1DeYJxs3v
This commit is contained in:
michele
2026-09-04 13:42:57 +02:00
co-authored by Claude Sonnet 5
parent 313a1994a4
commit 20b0b1f4c0
29 changed files with 67675 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sim/int8_memory_access.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:49 2026
Fri Sep 4 13:40:12 2026
$end
$version
Icarus Verilog
sim/int8_psram_integration.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:53 2026
Fri Sep 4 13:40:16 2026
$end
$version
Icarus Verilog
sim/layer.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:54 2026
Fri Sep 4 13:40:17 2026
$end
$version
Icarus Verilog
sim/layer_sequencer.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:54 2026
Fri Sep 4 13:40:17 2026
$end
$version
Icarus Verilog
sim/mac8_tree_tb.v
+165
View File
@@ -0,0 +1,165 @@
`timescale 1ns/1ps
// ================================================================
// MAC8 TESTBENCH -- balanced binary adder tree (certification
// campaign, aspect C.1)
//
// rtl/mac8.v had NO dedicated unit-level testbench before this
// (docs/validation/00-inventario.md §0.4/§0.5): only indirect coverage
// through neuron_parallel_tb.v, always at whatever single PARALLEL that
// testbench happens to use. A tree-wiring bug (swapped/duplicated/
// dropped lane) at a DIFFERENT PARALLEL than what neuron_parallel_tb.v
// exercises would go completely undetected.
//
// Checked at PARALLEL=2, 8 (the module's own default/namesake), and 32
// -- the extremes actually used across this project's own benchmarks
// (docs/FPGA-Neural-Datapatch-Benchmark.md), not just the one value a
// single higher-level test happens to pick.
//
// Oracle: tools/validation/mac_oracle.py's mac8_full() -- an
// independent Python model (two's complement tree-sum from first
// principles). Vectors pre-generated per PARALLEL
// (tools/validation/mac8_tree_p{2,8,32}.hex), three families each:
// 1. Structural (x=[1..PARALLEL], w=1, ascending AND reversed lane
// order): the expected sum PARALLEL*(PARALLEL+1)/2 only comes out
// right if every lane is summed EXACTLY once -- catches a
// swapped/duplicated/dropped tree input that random testing could
// miss by chance (a duplicate+drop pair can cancel out on some
// random inputs but never on this exact structural pattern).
// 2. 300 realistic random INT8 (x,w) pairs per PARALLEL with a
// boundary-swept acc_in -- matches the REAL wiring in
// neuron_parallel.v (acc_in = running accumulator across
// previous MAC groups, NOT hardwired to 0).
// 3. Adversarial worst-case product magnitude
// (x=w=-128 -> +16384/lane, or x=-128,w=127 -> -16256/lane) at
// every lane simultaneously, with boundary acc_in near the
// ACC_WIDTH=32 edge -- confirms the tree's wraparound behavior is
// well-defined two's complement, not X/undefined, even though
// this magnitude is far beyond what any realistic N_INPUTS<=256
// layer would ever accumulate to (documented, not asserted as a
// real operating condition).
// ================================================================
module tb;
localparam DATA_WIDTH = 8;
localparam ACC_WIDTH = 32;
integer total_errors;
integer total_checked;
// ------------------------------------------------------------
// PARALLEL = 2
// ------------------------------------------------------------
localparam P2 = 2;
localparam W2 = 16*P2 + 64;
reg [W2-1:0] vec2 [0:312];
reg signed [DATA_WIDTH*P2-1:0] x_bus2, w_bus2;
reg signed [ACC_WIDTH-1:0] acc_in2;
wire signed [ACC_WIDTH-1:0] acc_out2;
reg signed [ACC_WIDTH-1:0] expected2;
integer li2;
mac8 #(.DATA_WIDTH(DATA_WIDTH), .ACC_WIDTH(ACC_WIDTH), .PARALLEL(P2)) dut2 (
.x_bus(x_bus2), .w_bus(w_bus2), .acc_in(acc_in2), .acc_out(acc_out2)
);
// ------------------------------------------------------------
// PARALLEL = 8 (mac8's own namesake default)
// ------------------------------------------------------------
localparam P8 = 8;
localparam W8 = 16*P8 + 64;
reg [W8-1:0] vec8 [0:312];
reg signed [DATA_WIDTH*P8-1:0] x_bus8, w_bus8;
reg signed [ACC_WIDTH-1:0] acc_in8;
wire signed [ACC_WIDTH-1:0] acc_out8;
reg signed [ACC_WIDTH-1:0] expected8;
integer li8;
mac8 #(.DATA_WIDTH(DATA_WIDTH), .ACC_WIDTH(ACC_WIDTH), .PARALLEL(P8)) dut8 (
.x_bus(x_bus8), .w_bus(w_bus8), .acc_in(acc_in8), .acc_out(acc_out8)
);
// ------------------------------------------------------------
// PARALLEL = 32
// ------------------------------------------------------------
localparam P32 = 32;
localparam W32 = 16*P32 + 64;
reg [W32-1:0] vec32 [0:312];
reg signed [DATA_WIDTH*P32-1:0] x_bus32, w_bus32;
reg signed [ACC_WIDTH-1:0] acc_in32;
wire signed [ACC_WIDTH-1:0] acc_out32;
reg signed [ACC_WIDTH-1:0] expected32;
integer li32;
mac8 #(.DATA_WIDTH(DATA_WIDTH), .ACC_WIDTH(ACC_WIDTH), .PARALLEL(P32)) dut32 (
.x_bus(x_bus32), .w_bus(w_bus32), .acc_in(acc_in32), .acc_out(acc_out32)
);
initial begin
total_errors = 0;
total_checked = 0;
// ---- PARALLEL = 2 ----
$readmemh("tools/validation/mac8_tree_p2.hex", vec2);
$display("--- PARALLEL=2: 313 vectors ---");
for (li2 = 0; li2 < 313; li2 = li2 + 1) begin
for (integer lane = 0; lane < P2; lane = lane + 1) begin
x_bus2[lane*8 +: 8] = vec2[li2][W2-1-16*lane -: 8];
w_bus2[lane*8 +: 8] = vec2[li2][W2-1-16*lane-8 -: 8];
end
acc_in2 = vec2[li2][63:32];
expected2 = vec2[li2][31:0];
#1;
total_checked = total_checked + 1;
if (acc_out2 !== expected2) begin
total_errors = total_errors + 1;
$display("MISMATCH P2 idx=%0d: got=%0d expected=%0d", li2, acc_out2, expected2);
end
end
// ---- PARALLEL = 8 ----
$readmemh("tools/validation/mac8_tree_p8.hex", vec8);
$display("--- PARALLEL=8: 313 vectors ---");
for (li8 = 0; li8 < 313; li8 = li8 + 1) begin
for (integer lane = 0; lane < P8; lane = lane + 1) begin
x_bus8[lane*8 +: 8] = vec8[li8][W8-1-16*lane -: 8];
w_bus8[lane*8 +: 8] = vec8[li8][W8-1-16*lane-8 -: 8];
end
acc_in8 = vec8[li8][63:32];
expected8 = vec8[li8][31:0];
#1;
total_checked = total_checked + 1;
if (acc_out8 !== expected8) begin
total_errors = total_errors + 1;
$display("MISMATCH P8 idx=%0d: got=%0d expected=%0d", li8, acc_out8, expected8);
end
end
// ---- PARALLEL = 32 ----
$readmemh("tools/validation/mac8_tree_p32.hex", vec32);
$display("--- PARALLEL=32: 313 vectors ---");
for (li32 = 0; li32 < 313; li32 = li32 + 1) begin
for (integer lane = 0; lane < P32; lane = lane + 1) begin
x_bus32[lane*8 +: 8] = vec32[li32][W32-1-16*lane -: 8];
w_bus32[lane*8 +: 8] = vec32[li32][W32-1-16*lane-8 -: 8];
end
acc_in32 = vec32[li32][63:32];
expected32 = vec32[li32][31:0];
#1;
total_checked = total_checked + 1;
if (acc_out32 !== expected32) begin
total_errors = total_errors + 1;
$display("MISMATCH P32 idx=%0d: got=%0d expected=%0d", li32, acc_out32, expected32);
end
end
$display("--- TOTAL: checked=%0d errors=%0d ---", total_checked, total_errors);
if (total_errors == 0)
$display("ALL TESTS PASSED (%0d vectors across PARALLEL=2/8/32, 0 mismatches against independent Python oracle)", total_checked);
else
$display("FAILED: %0d/%0d vectors mismatched", total_errors, total_checked);
$finish;
end
endmodule
sim/mac_unit_tb.v
+104
View File
@@ -0,0 +1,104 @@
`timescale 1ns/1ps
// ================================================================
// MAC_UNIT TESTBENCH (certification campaign, aspect C.1)
//
// rtl/mac_unit.v had NO dedicated unit-level testbench before this
// (docs/validation/00-inventario.md §0.4/§0.5): only indirect coverage
// through neuron_parallel_tb.v and friends, where acc_in is always
// hardwired to 0 by mac8.v and a bug isolated to this module would only
// surface if it happened to propagate visibly through the full layer.
//
// Oracle: tools/validation/mac_oracle.py, an independent Python
// reimplementation (two's complement from first principles, not a
// transcription of this RTL) -- see that file's own header. Vectors are
// pre-generated (tools/validation/mac_unit_vectors_*.hex) rather than
// computed at Verilog runtime, so the comparison at each step is purely
// mechanical (no chance of Verilog-side arithmetic accidentally
// re-deriving the same bug the oracle exists to catch).
//
// Coverage: EXHAUSTIVE on (x,w) at DATA_WIDTH=8 -- all 256*256=65536
// combinations, acc_in=0 (matches mac8.v's real usage). Plus a second,
// separate file exercising the module's own full port contract
// (acc_out = acc_in + product for ANY acc_in, not just the acc_in=0 case
// this design happens to use today) across boundary/random acc_in values
// including the four true product-magnitude corners
// (-128*-128, 127*127, -128*127, 127*-128).
// ================================================================
module tb;
localparam DATA_WIDTH = 8;
localparam ACC_WIDTH = 32;
reg signed [DATA_WIDTH-1:0] x;
reg signed [DATA_WIDTH-1:0] w;
reg signed [ACC_WIDTH-1:0] acc_in;
wire signed [ACC_WIDTH-1:0] acc_out;
mac_unit #(.DATA_WIDTH(DATA_WIDTH), .ACC_WIDTH(ACC_WIDTH)) dut (
.x(x), .w(w), .acc_in(acc_in), .acc_out(acc_out)
);
// 80-bit packed vector: x[79:72] w[71:64] acc_in[63:32] expected[31:0]
reg [79:0] exhaustive_vec [0:65535];
reg [79:0] boundary_vec [0:485];
integer i;
integer errors;
integer checked;
reg [7:0] vx;
reg [7:0] vw;
reg [31:0] vacc_in;
reg [31:0] vexpected;
task automatic check_one(input [79:0] packed_vec);
begin
vx = packed_vec[79:72];
vw = packed_vec[71:64];
vacc_in = packed_vec[63:32];
vexpected = packed_vec[31:0];
x = vx;
w = vw;
acc_in = vacc_in;
#1;
checked = checked + 1;
if (acc_out !== $signed(vexpected)) begin
errors = errors + 1;
if (errors <= 20) begin
$display("MISMATCH: x=%0d w=%0d acc_in=%0d -> got=%0d expected=%0d",
$signed(vx), $signed(vw), $signed(vacc_in), acc_out, $signed(vexpected));
end
end
end
endtask
initial begin
errors = 0;
checked = 0;
$readmemh("tools/validation/mac_unit_vectors_exhaustive.hex", exhaustive_vec);
$readmemh("tools/validation/mac_unit_vectors_boundary_accin.hex", boundary_vec);
$display("--- TEST 1: exhaustive (x,w), acc_in=0 -- 65536 combinations ---");
for (i = 0; i < 65536; i = i + 1) begin
check_one(exhaustive_vec[i]);
end
$display(" checked %0d, errors so far %0d", checked, errors);
$display("--- TEST 2: full port contract, boundary/random acc_in -- 486 vectors ---");
for (i = 0; i < 486; i = i + 1) begin
check_one(boundary_vec[i]);
end
$display(" checked %0d total, errors %0d", checked, errors);
if (errors == 0) begin
$display("ALL TESTS PASSED (%0d vectors, 0 mismatches against independent Python oracle)", checked);
end else begin
$display("FAILED: %0d/%0d vectors mismatched", errors, checked);
end
$finish;
end
endmodule
sim/memory_interface.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:54 2026
Fri Sep 4 13:40:17 2026
$end
$version
Icarus Verilog
sim/neuron_memory.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:02 2026
Fri Sep 4 13:40:25 2026
$end
$version
Icarus Verilog
sim/neuron_memory_multi.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:22:58 2026
Fri Sep 4 13:40:21 2026
$end
$version
Icarus Verilog
sim/neuron_parallel.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:02 2026
Fri Sep 4 13:40:25 2026
$end
$version
Icarus Verilog
sim/neuron_parallel_bug002_n_inputs_zero_tb.v
+115
View File
@@ -0,0 +1,115 @@
`timescale 1ns/1ps
// ================================================================
// BUG-002 REGRESSION TRAP (certification campaign, aspect C.1,
// docs/validation/bugs.md) -- N_INPUTS=0 bypasses the elaboration-
// time guard and produces a confirmed, real hang.
//
// rtl/neuron_parallel.v:71's guard is a single condition:
// if (N_INPUTS % PARALLEL != 0) ... force elaboration failure
// For N_INPUTS=0, `0 % PARALLEL == 0` for any PARALLEL != 0 -- the
// guard does NOT fire, yet GROUPS = N_INPUTS/PARALLEL = 0, the exact
// condition the guard's own header comment (lines 55-58) says causes
// a hang. This module DOES compile/elaborate (unlike the two
// deliberate negative tests, neuron_parallel_guard_negative_*_tb.v)
// -- that is itself part of the bug: no elaboration-time protection
// exists for this specific boundary value.
//
// CONFIRMED on BOTH verification planes (§A.4):
// - Simulation (this file): `start` never causes `busy` to assert;
// `done` never pulses. Checked cycle-by-cycle for 200 cycles, not
// a one-shot late check (an early investigation attempt used a
// one-shot check-at-the-end and produced a methodologically
// invalid "hang" verdict even for a KNOWN-GOOD N_INPUTS=2 sanity
// config, because `done` is a documented single-cycle pulse,
// rtl/neuron_parallel.v:207/227 -- see docs/validation/01-datapath.md
// for the full self-correction narrative).
// - Real synthesis: `yosys synth_ecp5` elaborates this exact
// configuration with 0 reported problems. Root cause visible in
// Yosys's own warnings: `x_bus`/`w_bus`, declared
// `[DATA_WIDTH*N_INPUTS-1:0]` = `[-1:0]` for N_INPUTS=0, do NOT
// collapse to a true zero-width bus -- Yosys (and, per this
// simulation, Icarus) interpret a `[-1:0]` range as a genuine
// 2-bit vector (width = |MSB-LSB|+1 = |-1-0|+1 = 2), left
// completely undriven ("Wire ... is used but has no driver").
//
// This test currently PASSES by confirming the bug's exact symptom is
// still present and unchanged -- it is a regression trap for the
// CURRENT, documented-as-open, unfixed behavior (docs/validation/
// bugs.md BUG-002), not a correctness assertion that this behavior is
// desirable. If/when BUG-002 is fixed (e.g. an explicit `N_INPUTS==0`
// elaboration guard is added), THIS test must be rewritten to expect
// the new, fixed behavior instead -- do not "fix" it by loosening the
// check.
// ================================================================
module tb;
localparam DATA_WIDTH = 8;
localparam PARALLEL = 2;
localparam ACC_WIDTH = 32;
reg clk;
initial begin
clk = 1'b0;
forever #5 clk = ~clk;
end
reg rst, start;
wire busy, done;
wire signed [DATA_WIDTH-1:0] y;
integer cyc;
integer errors;
neuron_parallel #(
.DATA_WIDTH(DATA_WIDTH), .N_INPUTS(0), .PARALLEL(PARALLEL), .ACC_WIDTH(ACC_WIDTH)
) dut (
.clk(clk), .rst(rst), .start(start),
.x_bus(), .w_bus(), .bias(8'sd0),
.y(y), .busy(busy), .done(done)
);
initial begin
errors = 0;
$display("--- TEST 1: N_INPUTS=0 elaborates without error (confirms guard gap) ---");
// If this file failed to compile/elaborate, the guard would
// have started covering N_INPUTS=0 too -- that would be a fix
// landing, not a regression. This $display only runs if
// elaboration succeeded, which it must, for the test below to
// even execute.
$display(" elaborated successfully -- guard did NOT fire for N_INPUTS=0 (as of this writing)");
$display("--- TEST 2: start is accepted (busy asserts) within 200 cycles? ---");
rst = 1; start = 0;
repeat(3) @(posedge clk);
rst = 0;
@(posedge clk);
start = 1;
@(posedge clk);
start = 0;
cyc = 0;
while (!done && !busy && cyc < 200) begin
@(posedge clk);
cyc = cyc + 1;
end
if (busy || done) begin
// Behavior CHANGED from the confirmed-broken state -- this
// is the "fix landed" case, not expected today.
$display(" UNEXPECTED (relative to BUG-002 as currently documented): busy=%b done=%b at cycle %0d -- if this is a deliberate fix, update this test's expectations, don't just delete the check.", busy, done, cyc);
errors = errors + 1;
end else begin
$display(" CONFIRMED (matches BUG-002, docs/validation/bugs.md): busy never asserted, done never pulsed in 200 cycles -- start was silently ineffective.");
end
if (errors == 0)
$display("ALL TESTS PASSED (BUG-002 symptom reproduced exactly as documented -- this is a KNOWN, OPEN bug, not a clean bill of health for N_INPUTS=0)");
else
$display("FAILED: %0d unexpected result(s) -- see messages above", errors);
$finish;
end
endmodule
sim/parameter_sweep.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:02 2026
Fri Sep 4 13:40:25 2026
$end
$version
Icarus Verilog
sim/parametric.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:02 2026
Fri Sep 4 13:40:25 2026
$end
$version
Icarus Verilog
sim/psram_controller.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:07 2026
Fri Sep 4 13:40:30 2026
$end
$version
Icarus Verilog
sim/psram_page_mode.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:07 2026
Fri Sep 4 13:40:30 2026
$end
$version
Icarus Verilog
sim/spi_engine.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:07 2026
Fri Sep 4 13:40:30 2026
$end
$version
Icarus Verilog
sim/spi_neuron_top.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:33 2026
Fri Sep 4 13:40:57 2026
$end
$version
Icarus Verilog
sim/spi_neuron_top_graph.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:17 2026
Fri Sep 4 13:40:41 2026
$end
$version
Icarus Verilog
sim/spi_neuron_top_runnetwork.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:28 2026
Fri Sep 4 13:40:52 2026
$end
$version
Icarus Verilog
sim/spi_slave.vcd
+1 -1
View File
@@ -1,5 +1,5 @@
$date
Fri Sep 4 13:23:35 2026
Fri Sep 4 13:40:58 2026
$end
$version
Icarus Verilog