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

feat(v2): scaffold hardware/v1 frozen baseline + M1 Neural Processor

Browse Source 
Begins the V2 Neural Multiprocessor / Dataflow architecture per
docs/v2-description.md, per explicit user request to freeze V1 and
start V2 development, copying from V1 what's needed.

Scaffold:
- hardware/v1/: byte-exact, read-only copy of the current V1 codebase
  (rtl, testbenches, tools, constraints, a representative subset of
  synthesis results, and reference docs) -- verified identical via
  diff/cmp against the live top-level tree before being made
  filesystem-read-only. The live top-level tree is untouched and
  remains the project's "production" V1 (see hardware/v1/README.md
  and hardware/v2/logs/decisions.log DEC-0001 for why copy-not-move).
- hardware/v2/: mandatory structure (rtl/sim/constraints/synthesis/
  reports/scripts/logs/docs) plus the full logging system required by
  the spec (development/architecture/simulation/synthesis/timing/
  benchmark/decisions/experiments/errors.log).

M1 -- Neural Processor (hardware/v2/rtl/neural_processor.v):
- 8-stage pipelined perceptron unit (P_IN=8): input align, 8
  multipliers, 3-level adder tree, accumulator, bias+activation, INT8
  saturation. Genuine 1-tile/cycle throughput, not just a wider
  combinational datapath.
- 7-state FSM (NP_IDLE..NP_ERROR per docs/v2-description.md §6, with
  4 baseline states merged into NP_WAIT_OPERANDS -- see
  decisions.log DEC-0002); valid/ready/data/last stream interfaces
  per §7.
- Bit-exact vs the frozen hardware/v1/rtl/neuron_parallel.v + mac8.v
  + mac_unit.v: 7/7 tests pass (hardware/v2/sim/tb_neural_processor.v),
  covering regular/mixed-sign/extreme-INT8 vectors, both activations,
  a zero-idle-gap back-to-back-tiles throughput check, and an 8-tile
  job -- verified with Verilator (see below for why).
- Real synthesis + place&route (Yosys + nextpnr-ecp5): 0 CHECK
  problems, Fmax 183.12 MHz at ACC_WIDTH=32 (PASS at 80MHz, ~3x V1's
  isolated PARALLEL=8 Fmax of 61.71 MHz) and 176.21 MHz at ACC_WIDTH=24
  (a user-requested comparison experiment, also bit-exact-verified;
  see experiments.log EXP-0001/EXP-0002 and benchmark.log).

Three real bugs found and resolved during M1 development (full
diagnostic record in errors.log):
- Two independent, reproducible Icarus Verilog v13.0 scheduling
  defects (ERR-0001, ERR-0002) that silently produced wrong simulation
  results for standard sequential Verilog -- confirmed via Verilator
  5.050 giving correct results on the same minimal repros. Verilator
  is now the trusted simulator for hardware/v2/ (decisions.log
  DEC-0004); Icarus's affected protocol-violation check was removed
  from the RTL and deferred architecturally to the Neural Director
  (DEC-0003) rather than chased further.
- One real RTL bug (ERR-0003): last0 wasn't gated like valid0,
  letting a "last tile" tag leak into the pipeline ahead of its
  actual valid tile on back-to-back jobs. Fixed and verified.

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-05 14:06:53 +02:00
co-authored by Claude Sonnet 5
parent 07a48e401f
commit dc0b331d3e
161 changed files with 1151210 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
hardware/v2/sim/tb_neural_processor.v
+320
View File
@@ -0,0 +1,320 @@
`timescale 1ns/1ps
// ============================================================
// M1 testbench (docs/v2-description.md §20/§21): hardware/v2/rtl/
// neural_processor.v vs the frozen V1 golden reference
// (hardware/v1/rtl/neuron_parallel.v + mac8.v + mac_unit.v),
// instantiated side by side and driven with IDENTICAL operands, then
// compared bit-exact.
//
// V1's neuron_parallel presents its whole N_INPUTS-wide input/weight
// bus at once (single `start` pulse); V2's neural_processor streams
// P_IN-wide tiles with a valid/ready/last handshake. This testbench
// bridges the two: it holds the full N_INPUTS-wide vector locally and
// feeds it to V1 in one shot while streaming it to V2 tile-by-tile,
// then asserts V1.y === V2.result_data for every case.
//
// Coverage (§20):
// - functional: regular positive/negative/mixed vectors, several
// N_INPUTS/tile counts;
// - extreme INT8 (§20 list): -128, -127, -1, 0, 1, 126, 127, and an
// all-poison saturating case;
// - both activations (ACT_NONE, ACT_RELU);
// - back-to-back jobs with NO idle gap (throughput check: a new
// job's first tile is presented the very cycle after the previous
// job's NP_DONE), proving tiles can stream without the outer FSM
// stalling between jobs.
//
// NOT covered here: operand-arrival protocol misuse (an operand sent
// while this processor cannot consume it). See
// hardware/v2/logs/decisions.log DEC-0003 -- that check was removed
// from neural_processor.v after triggering a reproducible Icarus
// Verilog v13.0 evaluation bug (hardware/v2/logs/errors.log ERR-0002)
// and is deferred to the Neural Director (M5), the actual owner of
// operand-issue arbitration.
//
// Icarus Verilog v13.0 toolchain note (hardware/v2/logs/errors.log
// ERR-0001): a task (or any named `begin:label` block) whose FIRST
// executable statement is a blocking assignment, called immediately
// after a time-consuming statement in the caller with no intervening
// `@(posedge clk)`, can silently fail to make that assignment visible
// to other modules at the next clock edge (reproduced in isolation
// down to a 3-line task; fixed by always beginning such a task with an
// explicit `@(posedge clk);` before its first assignment). run_case
// below follows this rule -- the same defensive convention already
// used throughout hardware/v1/sim's own tasks (e.g.
// neuron_parallel_tb.v's run_neuron), which is why V1's own tests were
// never affected.
// ============================================================
module tb;
localparam DATA_WIDTH = 8;
localparam P_IN = 8;
localparam ACC_WIDTH = 32;
localparam MAX_N = 64; // largest N_INPUTS exercised in this tb
reg clk, rst;
initial begin clk = 0; forever #5 clk = ~clk; end
integer errors;
integer tests;
// ---------------- V1 golden reference ----------------
reg v1_start;
reg signed [DATA_WIDTH*MAX_N-1:0] v1_x_bus, v1_w_bus;
reg signed [DATA_WIDTH-1:0] v1_bias;
reg [1:0] v1_activation;
reg [15:0] v1_n_inputs_real;
wire v1_busy, v1_done;
wire signed [DATA_WIDTH-1:0] v1_y;
neuron_parallel #(
.DATA_WIDTH(DATA_WIDTH), .N_INPUTS(MAX_N), .PARALLEL(P_IN), .ACC_WIDTH(ACC_WIDTH)
) v1_dut (
.clk(clk), .rst(rst), .start(v1_start),
.x_bus(v1_x_bus), .w_bus(v1_w_bus), .bias(v1_bias),
.activation(v1_activation), .n_inputs_real(v1_n_inputs_real),
.y(v1_y), .busy(v1_busy), .done(v1_done)
);
// ---------------- V2 neural_processor under test ----------------
reg job_valid;
wire job_ready;
reg [15:0] job_node_id;
reg signed [DATA_WIDTH-1:0] job_bias;
reg [1:0] job_activation;
reg operand_valid;
wire operand_ready;
reg signed [DATA_WIDTH*P_IN-1:0] input_data, weight_data;
reg tile_last;
wire result_valid;
reg result_ready;
wire signed [DATA_WIDTH-1:0] result_data;
wire [15:0] result_node_id;
wire [3:0] np_state;
wire np_error;
neural_processor #(
.DATA_WIDTH(DATA_WIDTH), .P_IN(P_IN), .ACC_WIDTH(ACC_WIDTH)
) v2_dut (
.clk(clk), .rst(rst),
.job_valid(job_valid), .job_ready(job_ready),
.job_node_id(job_node_id), .job_bias(job_bias), .job_activation(job_activation),
.operand_valid(operand_valid), .operand_ready(operand_ready),
.input_data(input_data), .weight_data(weight_data), .tile_last(tile_last),
.result_valid(result_valid), .result_ready(result_ready),
.result_data(result_data), .result_node_id(result_node_id),
.np_state(np_state), .np_error(np_error)
);
// local operand storage for one case (up to MAX_N elements)
reg signed [DATA_WIDTH-1:0] xmem [0:MAX_N-1];
reg signed [DATA_WIDTH-1:0] wmem [0:MAX_N-1];
integer i;
integer watchdog;
integer n_inputs;
integer n_tiles;
integer t, k;
reg signed [DATA_WIDTH-1:0] v2_result_captured;
reg v1_done_captured, v2_valid_captured;
integer v2_cycles;
task automatic run_case(
input integer n, // real number of inputs (multiple of P_IN)
input signed [DATA_WIDTH-1:0] bias,
input [1:0] activation,
input signed [DATA_WIDTH-1:0] expect_y,
input [15:0] node_id
);
begin
@(posedge clk); // see toolchain note in the file header -- always sync first
tests = tests + 1;
n_inputs = n;
n_tiles = n / P_IN;
// ---- drive V1 ----
v1_x_bus = {DATA_WIDTH*MAX_N{1'b0}};
v1_w_bus = {DATA_WIDTH*MAX_N{1'b0}};
for (i = 0; i < n_inputs; i = i + 1) begin
v1_x_bus[i*DATA_WIDTH +: DATA_WIDTH] = xmem[i];
v1_w_bus[i*DATA_WIDTH +: DATA_WIDTH] = wmem[i];
end
v1_bias = bias;
v1_activation = activation;
v1_n_inputs_real = n_inputs[15:0];
v1_start = 1;
@(posedge clk);
v1_start = 0;
watchdog = 0;
while (!v1_done && watchdog < 200) begin
@(posedge clk);
watchdog = watchdog + 1;
end
v1_done_captured = v1_done;
if (!v1_done) begin
$display("FAIL n=%0d: V1 reference did not complete (watchdog)", n_inputs);
errors = errors + 1;
end
// ---- drive V2 (streamed, P_IN-wide tiles) in parallel
// with issuing the job descriptor ----
job_node_id = node_id;
job_bias = bias;
job_activation = activation;
job_valid = 1;
while (!job_ready) @(posedge clk); // wait for NP_IDLE before the handshake edge
@(posedge clk); // handshake: job_valid & job_ready both true on this edge
job_valid = 0;
for (t = 0; t < n_tiles; t = t + 1) begin
input_data = {DATA_WIDTH*P_IN{1'b0}};
weight_data = {DATA_WIDTH*P_IN{1'b0}};
for (k = 0; k < P_IN; k = k + 1) begin
input_data[k*DATA_WIDTH +: DATA_WIDTH] = xmem[t*P_IN + k];
weight_data[k*DATA_WIDTH +: DATA_WIDTH] = wmem[t*P_IN + k];
end
tile_last = (t == n_tiles - 1);
operand_valid = 1;
while (!operand_ready) @(posedge clk); // wait for NP_WAIT_OPERANDS
@(posedge clk); // handshake edge
end
operand_valid = 0;
tile_last = 0;
result_ready = 1;
v2_cycles = 0;
while (!result_valid && v2_cycles < 200) begin
@(posedge clk);
v2_cycles = v2_cycles + 1;
end
v2_valid_captured = result_valid;
if (!result_valid) begin
$display("FAIL n=%0d: V2 neural_processor did not produce result_valid (watchdog)", n_inputs);
errors = errors + 1;
end else begin
v2_result_captured = result_data;
@(posedge clk); // let result_valid clear (NP_WRITE_RESULT -> NP_DONE)
end
if (v1_done_captured && v2_valid_captured) begin
if (v1_y !== v2_result_captured) begin
$display("FAIL n=%0d bias=%0d act=%0d: V1.y=%0d V2.result=%0d MISMATCH (expected both == %0d)",
n_inputs, bias, activation, v1_y, v2_result_captured, expect_y);
errors = errors + 1;
end else if (v1_y !== expect_y) begin
$display("FAIL n=%0d: V1/V2 agree (%0d) but disagree with hand-computed expectation %0d",
n_inputs, v1_y, expect_y);
errors = errors + 1;
end else begin
$display("PASS n=%0d bias=%0d act=%0d: V1.y=V2.result=%0d (bit-exact, matches hand-computed expectation)",
n_inputs, bias, activation, v1_y);
end
end
// let both DUTs return fully idle before the next case
while (!job_ready || np_state !== 4'd0) @(posedge clk);
end
endtask
// Compute the exact expected saturated/activated result in Verilog
// integer math (independent "third oracle", not derived from
// either DUT), used for a handful of hand-picked cases below.
function automatic signed [DATA_WIDTH-1:0] expect_relu(input integer acc, input integer bias);
integer s;
begin
s = acc + bias;
if (s <= 0) expect_relu = 0;
else if (s > 127) expect_relu = 127;
else expect_relu = s[DATA_WIDTH-1:0];
end
endfunction
function automatic signed [DATA_WIDTH-1:0] expect_none(input integer acc, input integer bias);
integer s;
begin
s = acc + bias;
if (s > 127) expect_none = 127;
else if (s < -128) expect_none = -128;
else expect_none = s[DATA_WIDTH-1:0];
end
endfunction
integer acc_calc;
initial begin
errors = 0;
tests = 0;
rst = 1;
v1_start = 0; v1_x_bus = 0; v1_w_bus = 0; v1_bias = 0; v1_activation = 1; v1_n_inputs_real = 0;
job_valid = 0; job_node_id = 0; job_bias = 0; job_activation = 1;
operand_valid = 0; input_data = 0; weight_data = 0; tile_last = 0;
result_ready = 0;
repeat(4) @(posedge clk);
rst = 0;
@(posedge clk);
// ---- TEST 1: regular positive vector, 16 inputs, ACT_RELU ----
for (i = 0; i < 16; i = i + 1) begin xmem[i] = 3; wmem[i] = 2; end
acc_calc = 16 * 3 * 2; // 96
run_case(16, 8'sd0, 2'd1, expect_relu(acc_calc, 0), 16'd1);
// ---- TEST 2: mixed sign, 32 inputs, ACT_NONE, negative bias ----
for (i = 0; i < 32; i = i + 1) begin
xmem[i] = (i % 2 == 0) ? 8'sd5 : -8'sd5;
wmem[i] = 8'sd4;
end
acc_calc = 0; // alternating +20/-20 cancels exactly over 32 terms
run_case(32, -8'sd10, 2'd0, expect_none(acc_calc, -10), 16'd2);
// ---- TEST 3: extreme INT8 values (docs/v2-description.md §20) ----
// -128 * 127 summed across all 8 lanes of a single tile, ACT_NONE
// (deliberately saturating, both directions exercised via bias).
xmem[0]=-8'sd128; wmem[0]=8'sd127;
xmem[1]=-8'sd127; wmem[1]=8'sd1;
xmem[2]=-8'sd1; wmem[2]=8'sd1;
xmem[3]=8'sd0; wmem[3]=8'sd127;
xmem[4]=8'sd1; wmem[4]=8'sd1;
xmem[5]=8'sd126; wmem[5]=8'sd1;
xmem[6]=8'sd127; wmem[6]=8'sd1;
xmem[7]=8'sd127; wmem[7]=8'sd127;
acc_calc = (-128*127) + (-127*1) + (-1*1) + (0*127) + (1*1) + (126*1) + (127*1) + (127*127);
run_case(8, 8'sd0, 2'd0, expect_none(acc_calc, 0), 16'd3);
run_case(8, 8'sd0, 2'd1, expect_relu(acc_calc, 0), 16'd4);
// ---- TEST 4: n_inputs=0 is NOT exercised here (P_IN>0 always
// required in V2 -- a job with zero tiles is a protocol
// question for the Neural Director, not this unit; V1's
// BUG-003/004 zero-input edge cases are V1-specific fixes,
// out of scope for M1's bit-exact comparison). ----
// ---- TEST 5: back-to-back jobs, no idle gap between them
// (throughput check) ----
for (i = 0; i < 8; i = i + 1) begin xmem[i] = 1; wmem[i] = 1; end
acc_calc = 8;
run_case(8, 8'sd0, 2'd1, expect_relu(acc_calc, 0), 16'd5);
for (i = 0; i < 8; i = i + 1) begin xmem[i] = 2; wmem[i] = 2; end
acc_calc = 8*4;
run_case(8, 8'sd0, 2'd1, expect_relu(acc_calc, 0), 16'd6);
// ---- TEST 6: 64-input job (8 tiles), ACT_RELU ----
for (i = 0; i < 64; i = i + 1) begin xmem[i] = 1; wmem[i] = 1; end
acc_calc = 64;
run_case(64, 8'sd5, 2'd1, expect_relu(acc_calc, 5), 16'd7);
// TEST 7 (protocol-violation negative test) removed -- see
// decisions.log DEC-0003 and the file header note above.
$display("========================================");
if (errors == 0)
$display("ALL %0d TESTS PASSED (bit-exact vs hardware/v1 golden reference)", tests);
else
$display("FAILED: %0d/%0d test(s) had errors -- see messages above", errors, tests);
$display("========================================");
$finish;
end
endmodule