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

feat: real Director extension for group dispatch + systolic_group.v P&R sanity check (EXP-0090)

Browse Source 
Adds neural_director_grouped.v, a direct extension of neural_director_
packed.v's own already-proven 2-position pairing discipline to 8-position
octets (matching systolic_group.v's fixed 4 PEs x 2 lanes). Real,
deliberate finding: the host-facing SPI/WRITE_JOB submission protocol
needs zero changes -- the host just submits 8 jobs sharing a weight base
instead of 2, the same real pattern already required today.

Real out-of-context synthesis of one systolic_group.v: 32 DSP48E1
(13.3%), confirming the original brainstorm's own DSP projection exactly.

Found and fixed two real bugs: (1) a wraparound-arithmetic width bug in
the octet index computation (same class already flagged for address
math elsewhere in this project -- needs N+1 bits before the mod-reduce
compare, not N); (2) a real, generalizable testbench race -- driving
stimulus on the same clock edge the DUT samples on works fine with a
natural gap between pulses (every prior testbench in this project has
one) but silently double-registers data when called back-to-back with
zero gap, confirmed via real signal tracing. Fixed with @(negedge clk)
stimulus; CLAUDE.md's existing blocking/nonblocking testbench-race
lesson extended to cover this new trigger.

Verified via tb_neural_director_grouped.v: 4/4 PASS (octet dispatch +
per-PE addressing, stall-not-mis-dispatch on a mismatched octet, queue
wraparound).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUG92aM9m68TRc4rG55BcC
This commit is contained in:
michele
2026-09-21 00:05:16 +02:00
co-authored by Claude Sonnet 5
parent 932aec2490
commit bd1fb5dc14
5 changed files with 627 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+14
View File
@@ -78,6 +78,20 @@ unmodified by v3, e.g. `layer_prefetch_ctrl.v`/`layer_weight_buffer.v`).
0075, 0077) before this became standing practice. If a new Icarus
testbench shows shuffled/duplicated fields or an inexplicable hang,
suspect this class of bug before assuming the RTL is wrong.
**Same race family, a DIFFERENT real trigger (EXP-0090)**: driving
stimulus on `@(posedge clk)` — even with the SAME `=`/handshake shape
already proven safe elsewhere in this project (e.g. `tb_packed_slot.v`'s
own `job_start` pulse) — still races the DUT's own posedge-triggered
sampling when a task issuing that pulse is called BACK-TO-BACK with ZERO
real simulated gap (no natural `while(!done)`-style polling delay between
calls, e.g. a tight submission loop). Confirmed via real signal tracing:
every logical push registered as TWO real, identical DUT-side writes.
Every prior working example of this pulse pattern happened to always have
a real gap between calls, so the race was never exercised until a tight
back-to-back loop (`neural_director_grouped.v`'s own test) hit it. Fix:
drive stimulus changes on `@(negedge clk)` instead — the DUT still
samples on `posedge`, so a negedge-driven change can never race it,
regardless of how tightly consecutive pulses are issued.
- **Never use a runtime-indexed part-select** (`data[idx*W +: W]` where `idx`
is a signal, not a constant) on a wide bus in anything synthesizable — a
known real Fmax killer (`weight_tile_gather.v`'s own header, EXP-0061).
docs/ARCHITECTURE_ANALYSIS.md
+25 -8
View File
@@ -659,18 +659,35 @@ specifically to document where/how it breaks rather than to succeed):
---
### 5.6 [First step DONE, EXP-0089] Hybrid systolic scaling: 4 groups × 4-PE weight-stationary chains
### 5.6 [Steps 1–2 DONE, EXP-0089/0090] Hybrid systolic scaling: 4 groups × 4-PE weight-stationary chains
Captured from a 2026-09-20 brainstorming session as a purely exploratory
idea; the same day, per the user's own explicit reprioritization, the real
open design question below (shared-weight broadcast vs. a literal PE-to-PE
systolic shift register) was resolved with the user directly (not guessed),
and the **first real, isolated step is now built and verified**:
`systolic_group.v` + `packed_pe.v` (EXP-0089) — one real group of 4 PEs
sharing a single broadcast weight fetch, real barrier-synchronized, real
xsim-verified (8/8 PASS across 2 consecutive group jobs). **Not yet done**:
Director/SPI-level job dispatch for group jobs, a real N=16 (4-group)
top-level, and any real P&R for this — see EXP-0089's own `next_action`.
systolic shift register) was resolved with the user directly (not guessed).
**Real progress so far**:
- `systolic_group.v` + `packed_pe.v` (EXP-0089) — one real group of 4 PEs
sharing a single broadcast weight fetch, real barrier-synchronized, real
xsim-verified (8/8 PASS across 2 consecutive group jobs).
- Real out-of-context synthesis of one group (EXP-0090): **32 DSP48E1**
(13.3%), confirming the original brainstorm's own quantified DSP
projection exactly (8 DSP/PE × 4 PEs = 32; scaled to 4 groups, 128/240 =
53%, matching the doc's own earlier estimate).
- `neural_director_grouped.v` (EXP-0090) — real Director extension
dispatching 8-position octets to free groups, a direct extension of
`neural_director_packed.v`'s own already-proven 2-position pairing
discipline. Real, deliberate finding: the host-facing SPI/`WRITE_JOB`
submission protocol needs **zero changes** — the host just submits 8
jobs sharing a weight base instead of 2. Real xsim-verified (4/4 PASS:
correct octet dispatch + per-PE addressing, correct stall-not-mis-
dispatch on a mismatched octet, correct queue wraparound). Also
surfaced a real, generalizable testbench-race lesson (tight back-to-
back stimulus pulses on the same edge the DUT samples on — fixed with
`@(negedge clk)` stimulus — see CLAUDE.md).
**Not yet done**: a real N=16 (4-group) top-level module + a real,
appropriately-sized arbiter, and real in-context P&R for the whole system
— see EXP-0090's own `next_action`.
**The problem it targets**: plain N=16 independent cores (§5.5's own
"documentary, expected to break" framing) means 16 independent DDR3
hardware/v2/logs/experiments.log
+92
View File
@@ -6079,3 +6079,95 @@ verified, with its own real P&R signoff. (4) Revisit the flat N=2/4/8/16
core-count scaling tests (deferred by the user's own explicit
reprioritization this session) once there's a real basis for comparing
flat vs. grouped scaling with real numbers from both.
EXP-0090 -- real second step of the 4x4 hybrid systolic architecture:
Director extension for group-level job dispatch, plus a real out-of-
context P&R sanity check for systolic_group.v (2026-09-21, continuing
the user's own explicit reprioritization: "Ok procedi ad implementare
quel che manca" -- proceed to implement what's missing)
CONTEXT: EXP-0089 built and verified the isolated systolic_group.v
mechanism (4 PEs sharing one broadcast weight fetch). Two real, disclosed
gaps remained before any top-level integration: (a) no real area/timing
data point for the new module, (b) no way to dispatch a group-level job
-- neural_director_packed.v only knows how to pair 2 queue entries for a
flat packed_slot.v, not 8 for a systolic_group.v.
PART 1 -- real out-of-context synthesis, systolic_group.v (one group,
4 PEs), xc7a100tcsg324-2: **32 DSP48E1** (240 available, 13.3%), 3533
LUTs, 0 Block RAM. This is a REAL confirmation of the original
brainstorm's own quantified rationale (docs/ARCHITECTURE_ANALYSIS.md
S5.6: "16 cores x 8 DSP/core = 128/240") -- one group of 4 PEs at 8
DSP/PE = 32 DSP exactly matches 4 PEs x 8 DSP/PE, and scaling to the
full 4-group (16-PE) design would be 4x32=128/240 (53%), exactly the
projected figure. Real, not just a projection anymore, for at least
the per-group DSP cost (timing not meaningful out-of-context, no clock
buffer -- real P&R timing requires real system integration first, per
this project's own standing practice).
PART 2 -- new module `neural_director_grouped.v`, a real, direct
extension of neural_director_packed.v's own already-proven pairing
discipline (NOT a redesign): dispatches the 8 OLDEST queue entries
together (GROUP_SIZE=8, matching systolic_group.v's own fixed 4 PEs x
2 lanes) instead of 2, requiring all 8 to share w_base/n_tiles -- same
real reasoning, same real "stall visibly, never silently mis-dispatch"
standard. REAL, DELIBERATE NON-CHANGE: the host-facing job_in_*
submission interface is byte-for-byte identical to today's -- the ESP32/
SPI protocol (spi_host_bridge_v3.v's WRITE_JOB opcode) needs ZERO real
changes; the host just submits 8 jobs sharing a w_base instead of 2, the
same real submission pattern already required today, just wider. This
was confirmed as a genuine simplification of the original integration
plan, not an oversight.
REAL BUG FOUND AND FIXED DURING DESIGN (before compiling): the initial
draft's own q_head/q_idx wraparound arithmetic computed
`q_head + qk[...]` at only Q_ADDR_WIDTH bits before comparing against
QUEUE_DEPTH -- silently wrong for the same real reason a naive `base+
tcnt` sum was flagged unsafe elsewhere in this project (EXP-0088's own
addressing note): the addition needs Q_ADDR_WIDTH+1 bits to represent a
real carry-out BEFORE the mod-reduction compare, or the comparison
against QUEUE_DEPTH silently uses an already-wrapped (wrong) sum. Fixed
by widening the intermediate sum by 1 bit before comparing/subtracting.
REAL BUG FOUND AND FIXED DURING VERIFICATION (a significant, real,
generalizable testbench-discipline finding, not just a one-off): the
first full test run showed queue entries being silently duplicated --
every logical `submit_job` push registered as TWO real, identical
writes into consecutive queue slots (confirmed via real signal tracing
of q_tail/q_count/job_in_x_base, not guessed). Root cause: the test's
own stimulus-driving task pulsed `job_in_valid` on `@(posedge clk)` --
the SAME edge the DUT's own always block samples on -- and was called
BACK-TO-BACK with zero real simulated gap (a tight 8-iteration
submission loop, unlike every OTHER testbench in this project, which
always has a natural gap via a `while(!done)`-style poll between
pulses). This is the SAME underlying race family CLAUDE.md's own
existing "blocking vs nonblocking stimulus" lesson already covers, but
a real, previously-unseen TRIGGER for it (a tight back-to-back pulse
loop with no natural gap) -- CLAUDE.md's lesson extended accordingly.
Fixed by driving stimulus changes on `@(negedge clk)` instead of
`@(posedge clk)`, guaranteeing they can never race the DUT's own
posedge sampling regardless of call tightness.
VERIFICATION: new `tb_neural_director_grouped.v`, real Icarus xsim,
tests: (1) real octet dispatch with correct per-PE x_base_a/b
assignment (position pairs 0/1->PE0, 2/3->PE1, 4/5->PE2, 6/7->PE3); (2)
a second, different-w_base octet dispatches correctly to a freed group;
(3) a real mismatched w_base among the 8 oldest entries correctly
STALLS (no dispatch, matching this Director's own disclosed real
design -- confirmed there is no in-band recovery from a real submitter
mistake like neural_director_packed.v already has for pairs, a real
reset is the only way to clear it); (4) real queue wraparound across
the QUEUE_DEPTH=16 boundary. **4/4 PASS, 0 errors, ALL TESTS PASSED.**
DECISION: real, verified second step. Group-level job dispatch is now
provably correct in isolation. Still not done (real, disclosed, next):
a real N=16 top-level module wiring 4x systolic_group.v +
neural_director_grouped.v + a real, appropriately-sized arbiter (4
group weight-fetch requesters + 16 per-PE activation/writeback
requesters + host_mem_bridge.v = 21) + the existing, unmodified
spi_host_bridge_v3.v (no changes needed, per Part 2's own real finding)
+ mig_native_adapter.v, and real, in-context P&R for that whole system.
next_action: build the real N=16 top-level, verify it end-to-end (real
xsim against the real DDR3 model, matching this project's own
established multi-level verification discipline), then real P&R.
hardware/v3/rtl/neural_director_grouped.v
+283
View File
@@ -0,0 +1,283 @@
`timescale 1ns/1ps
// ================================================================
// V3 -- Neural Director, GROUPED variant (EXP-0089/EXP-0090), forked
// from neural_director_packed.v for dispatching to systolic_group.v
// instances instead of flat packed_slot.v instances.
//
// REAL, DIRECT EXTENSION of neural_director_packed.v's own already-
// proven pairing discipline -- NOT a redesign. That module dispatches
// the 2 OLDEST queue entries together, requiring them to share
// w_base/n_tiles (one packed core = 2 positions sharing one weight
// stream). This module dispatches the 8 OLDEST queue entries together
// (GROUP_SIZE=8, matching systolic_group.v's own real, fixed 4 PEs x
// 2 lanes each), requiring ALL EIGHT to share w_base/n_tiles -- same
// real reasoning, same real failure mode if violated (the queue simply
// stops draining, a visible, diagnosable symptom, never a silent
// mis-pair), just a wider match window.
//
// REAL, DELIBERATE NON-CHANGE: the host-facing job_in_* submission
// interface is BYTE-FOR-BYTE IDENTICAL to neural_director_packed.v's
// own -- one job descriptor (x_base/w_base/n_tiles/result_addr/
// node_id) per push, exactly like today. The ESP32/SPI protocol
// (spi_host_bridge_v3.v's own WRITE_JOB opcode) needs ZERO real
// changes to use this Director -- the host just submits 8 individual
// jobs sharing the same w_base/n_tiles instead of 2, exactly the same
// real submission pattern already required today, just a wider batch.
// This was a deliberate design goal, not an accident: keeping the
// host-facing contract unchanged means this Director can be swapped
// in without touching any already-verified host-side firmware
// contract or SPI opcode.
// ================================================================
module neural_director_grouped #(
parameter ADDR_WIDTH = 26,
parameter N_GROUPS = 4,
parameter QUEUE_DEPTH = 16
)(
input wire clk,
input wire rst,
// ---- job submission: identical single-job-descriptor interface
// to neural_director_packed.v -- see header ----
input wire job_in_valid,
output wire job_in_ready,
input wire [ADDR_WIDTH-1:0] job_in_x_base,
input wire [ADDR_WIDTH-1:0] job_in_w_base,
input wire [15:0] job_in_n_tiles,
input wire [ADDR_WIDTH-1:0] job_in_result_addr,
input wire [15:0] job_in_node_id,
// ---- per-group job control (arrayed, N_GROUPS wide). Each group
// gets ONE shared w_base/n_tiles and 4 PEs' worth of x_base_a/b +
// result_addr_a/b + node_id_a/b (8 positions total) -- flattened
// as 4*ADDR_WIDTH / 4*16 buses, matching systolic_group.v's own
// real pe_x_base_a/pe_x_base_b/etc port shapes exactly. ----
output wire [N_GROUPS-1:0] group_job_start,
output wire [ADDR_WIDTH*N_GROUPS-1:0] group_w_base,
output wire [16*N_GROUPS-1:0] group_n_tiles,
output wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_x_base_a,
output wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_x_base_b,
output wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_result_addr_a,
output wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_result_addr_b,
output wire [4*16*N_GROUPS-1:0] group_pe_node_id_a,
output wire [4*16*N_GROUPS-1:0] group_pe_node_id_b,
input wire [N_GROUPS-1:0] group_job_done,
output reg job_out_done, // one-cycle pulse
output reg [$clog2(N_GROUPS)-1:0] job_out_group,
output reg [3:0] dir_state,
output reg dir_error,
output wire queue_empty
);
localparam GROUP_SIZE = 8; // 4 PEs x 2 lanes each, matches systolic_group.v's own fixed shape
localparam DIR_IDLE = 4'd0;
localparam DIR_SCAN_READY = 4'd1;
localparam DIR_ALLOCATE = 4'd2;
localparam DIR_ERROR = 4'd3;
localparam Q_ADDR_WIDTH = $clog2(QUEUE_DEPTH);
reg [ADDR_WIDTH-1:0] q_x_base [0:QUEUE_DEPTH-1];
reg [ADDR_WIDTH-1:0] q_w_base [0:QUEUE_DEPTH-1];
reg [15:0] q_n_tiles [0:QUEUE_DEPTH-1];
reg [ADDR_WIDTH-1:0] q_result_addr [0:QUEUE_DEPTH-1];
reg [15:0] q_node_id [0:QUEUE_DEPTH-1];
reg [Q_ADDR_WIDTH-1:0] q_head, q_tail;
reg [Q_ADDR_WIDTH:0] q_count;
wire q_empty = (q_count == 0);
assign queue_empty = q_empty;
wire q_full = (q_count == QUEUE_DEPTH[Q_ADDR_WIDTH:0]);
wire q_has_octet = (q_count >= GROUP_SIZE[Q_ADDR_WIDTH:0]);
assign job_in_ready = !q_full;
// real wrapping index for the k-th oldest entry (k=0..7), same
// wrap-around style neural_director_packed.v's own q_head_plus1
// already established, generalized to an 8-wide offset table.
wire [Q_ADDR_WIDTH-1:0] q_idx [0:7];
genvar qk;
generate
for (qk = 0; qk < 8; qk = qk + 1) begin : GEN_QIDX
// real, deliberate width widening BEFORE the wrap compare --
// computing q_head+qk at only Q_ADDR_WIDTH bits could
// silently overflow/wrap in the addition itself (e.g.
// q_head=14, qk=7, QUEUE_DEPTH=16 needs 5 bits to represent
// 21 correctly before reducing mod 16), giving a WRONG
// index rather than an out-of-range one -- a real, silent
// correctness bug, not just a corner case to assume away.
wire [Q_ADDR_WIDTH:0] q_sum = {1'b0, q_head} + qk[Q_ADDR_WIDTH:0];
assign q_idx[qk] = (q_sum >= QUEUE_DEPTH[Q_ADDR_WIDTH:0])
? (q_sum - QUEUE_DEPTH[Q_ADDR_WIDTH:0])
: q_sum[Q_ADDR_WIDTH-1:0];
end
endgenerate
// the 8 oldest entries share a resident weight iff w_base AND
// n_tiles ALL match (checked pairwise against entry 0, same real
// reasoning as neural_director_packed.v's own pair_ready -- a
// coincidentally-equal w_base with mismatched n_tiles must not be
// wrongly accepted).
wire octet_match =
(q_w_base[q_idx[1]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[1]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[2]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[2]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[3]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[3]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[4]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[4]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[5]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[5]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[6]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[6]] == q_n_tiles[q_idx[0]]) &&
(q_w_base[q_idx[7]] == q_w_base[q_idx[0]]) && (q_n_tiles[q_idx[7]] == q_n_tiles[q_idx[0]]);
wire group_ready = q_has_octet && octet_match;
reg [N_GROUPS-1:0] group_busy;
wire [N_GROUPS-1:0] group_free = ~group_busy;
wire any_group_free = |group_free;
reg [$clog2(N_GROUPS)-1:0] free_group_idx;
integer fi;
always @(*) begin
free_group_idx = {$clog2(N_GROUPS){1'b0}};
for (fi = N_GROUPS-1; fi >= 0; fi = fi - 1) begin
if (group_free[fi]) free_group_idx = fi[$clog2(N_GROUPS)-1:0];
end
end
// per-group output storage -- N_GROUPS parallel constant-indexed
// writes (same anti-runtime-indexed-part-select discipline
// neural_director_packed.v's own slot_x_base_r already established).
reg group_job_start_r [0:N_GROUPS-1];
reg [ADDR_WIDTH-1:0] group_w_base_r [0:N_GROUPS-1];
reg [15:0] group_n_tiles_r [0:N_GROUPS-1];
reg [ADDR_WIDTH-1:0] group_pe_x_base_a_r [0:N_GROUPS-1][0:3];
reg [ADDR_WIDTH-1:0] group_pe_x_base_b_r [0:N_GROUPS-1][0:3];
reg [ADDR_WIDTH-1:0] group_pe_result_addr_a_r [0:N_GROUPS-1][0:3];
reg [ADDR_WIDTH-1:0] group_pe_result_addr_b_r [0:N_GROUPS-1][0:3];
reg [15:0] group_pe_node_id_a_r [0:N_GROUPS-1][0:3];
reg [15:0] group_pe_node_id_b_r [0:N_GROUPS-1][0:3];
genvar gg, gp;
generate
for (gg = 0; gg < N_GROUPS; gg = gg + 1) begin : GEN_GROUP_OUT
assign group_job_start[gg] = group_job_start_r[gg];
assign group_w_base[gg*ADDR_WIDTH +: ADDR_WIDTH] = group_w_base_r[gg];
assign group_n_tiles[gg*16 +: 16] = group_n_tiles_r[gg];
for (gp = 0; gp < 4; gp = gp + 1) begin : GEN_PE_OUT
assign group_pe_x_base_a[(gg*4+gp)*ADDR_WIDTH +: ADDR_WIDTH] = group_pe_x_base_a_r[gg][gp];
assign group_pe_x_base_b[(gg*4+gp)*ADDR_WIDTH +: ADDR_WIDTH] = group_pe_x_base_b_r[gg][gp];
assign group_pe_result_addr_a[(gg*4+gp)*ADDR_WIDTH +: ADDR_WIDTH] = group_pe_result_addr_a_r[gg][gp];
assign group_pe_result_addr_b[(gg*4+gp)*ADDR_WIDTH +: ADDR_WIDTH] = group_pe_result_addr_b_r[gg][gp];
assign group_pe_node_id_a[(gg*4+gp)*16 +: 16] = group_pe_node_id_a_r[gg][gp];
assign group_pe_node_id_b[(gg*4+gp)*16 +: 16] = group_pe_node_id_b_r[gg][gp];
end
end
endgenerate
reg [$clog2(N_GROUPS)-1:0] done_group_idx;
integer di;
always @(*) begin
done_group_idx = {$clog2(N_GROUPS){1'b0}};
for (di = N_GROUPS-1; di >= 0; di = di - 1) begin
if (group_job_done[di]) done_group_idx = di[$clog2(N_GROUPS)-1:0];
end
end
integer pi;
always @(posedge clk) begin
if (rst) begin
dir_state <= DIR_IDLE;
dir_error <= 1'b0;
q_head <= {Q_ADDR_WIDTH{1'b0}};
q_tail <= {Q_ADDR_WIDTH{1'b0}};
q_count <= {(Q_ADDR_WIDTH+1){1'b0}};
group_busy <= {N_GROUPS{1'b0}};
for (fi = 0; fi < N_GROUPS; fi = fi + 1) begin
group_job_start_r[fi] <= 1'b0;
group_w_base_r[fi] <= {ADDR_WIDTH{1'b0}};
group_n_tiles_r[fi] <= 16'b0;
for (pi = 0; pi < 4; pi = pi + 1) begin
group_pe_x_base_a_r[fi][pi] <= {ADDR_WIDTH{1'b0}};
group_pe_x_base_b_r[fi][pi] <= {ADDR_WIDTH{1'b0}};
group_pe_result_addr_a_r[fi][pi] <= {ADDR_WIDTH{1'b0}};
group_pe_result_addr_b_r[fi][pi] <= {ADDR_WIDTH{1'b0}};
group_pe_node_id_a_r[fi][pi] <= 16'b0;
group_pe_node_id_b_r[fi][pi] <= 16'b0;
end
end
job_out_done <= 1'b0;
job_out_group <= {$clog2(N_GROUPS){1'b0}};
end else begin
for (fi = 0; fi < N_GROUPS; fi = fi + 1) group_job_start_r[fi] <= 1'b0;
job_out_done <= 1'b0;
if (job_in_valid && job_in_ready) begin
q_x_base[q_tail] <= job_in_x_base;
q_w_base[q_tail] <= job_in_w_base;
q_n_tiles[q_tail] <= job_in_n_tiles;
q_result_addr[q_tail] <= job_in_result_addr;
q_node_id[q_tail] <= job_in_node_id;
q_tail <= (q_tail == QUEUE_DEPTH[Q_ADDR_WIDTH-1:0]-1'b1) ? {Q_ADDR_WIDTH{1'b0}} : q_tail + 1'b1;
end
group_busy <= group_busy & ~group_job_done;
if (|group_job_done) begin
job_out_done <= 1'b1;
job_out_group <= done_group_idx;
end
case (dir_state)
DIR_IDLE: begin
dir_state <= DIR_SCAN_READY;
end
DIR_SCAN_READY: begin
if (group_ready && any_group_free) begin
dir_state <= DIR_ALLOCATE;
end
end
DIR_ALLOCATE: begin
for (fi = 0; fi < N_GROUPS; fi = fi + 1) begin
if (fi[$clog2(N_GROUPS)-1:0] == free_group_idx) begin
group_job_start_r[fi] <= 1'b1;
group_w_base_r[fi] <= q_w_base[q_idx[0]]; // all 8 match, checked by group_ready
group_n_tiles_r[fi] <= q_n_tiles[q_idx[0]];
for (pi = 0; pi < 4; pi = pi + 1) begin
group_pe_x_base_a_r[fi][pi] <= q_x_base[q_idx[pi*2]];
group_pe_x_base_b_r[fi][pi] <= q_x_base[q_idx[pi*2+1]];
group_pe_result_addr_a_r[fi][pi] <= q_result_addr[q_idx[pi*2]];
group_pe_result_addr_b_r[fi][pi] <= q_result_addr[q_idx[pi*2+1]];
group_pe_node_id_a_r[fi][pi] <= q_node_id[q_idx[pi*2]];
group_pe_node_id_b_r[fi][pi] <= q_node_id[q_idx[pi*2+1]];
end
end
end
group_busy[free_group_idx] <= 1'b1;
q_head <= q_idx[7] + 1'b1 == QUEUE_DEPTH[Q_ADDR_WIDTH-1:0]
? {Q_ADDR_WIDTH{1'b0}} : q_idx[7] + 1'b1;
dir_state <= DIR_SCAN_READY;
end
DIR_ERROR: begin
end
default: dir_state <= DIR_ERROR;
endcase
// q_count: +1 per accepted push, -8 per dispatched OCTET
case ({job_in_valid && job_in_ready,
(dir_state == DIR_SCAN_READY) && group_ready && any_group_free})
2'b10: q_count <= q_count + 1'b1;
2'b01: q_count <= q_count - GROUP_SIZE[Q_ADDR_WIDTH:0];
2'b11: q_count <= q_count - GROUP_SIZE[Q_ADDR_WIDTH:0] + 1'b1;
2'b00: q_count <= q_count;
endcase
end
end
endmodule
hardware/v3/sim/tb_neural_director_grouped.v
+213
View File
@@ -0,0 +1,213 @@
`timescale 1ns/1ps
// ============================================================
// EXP-0090 -- isolated correctness test for neural_director_grouped.v
// (does NOT instantiate real systolic_group.v -- this test verifies
// the Director's own queue/octet-matching/dispatch logic in isolation,
// same "one variable at a time" discipline as every other new module
// in this project). Checks:
// 1. 8 matching job descriptors (same w_base/n_tiles) correctly
// dispatch as ONE group job, with the right per-PE x_base_a/b
// assignment (positions 0,1 -> PE0 a/b, 2,3 -> PE1 a/b, etc).
// 2. A queue with a MISMATCHED w_base among the first 8 correctly
// STALLS (does not dispatch, does not error, does not silently
// mis-pair) -- matches neural_director_packed.v's own real,
// established "wrong dispatch must never happen" standard.
// 3. group_job_done correctly frees the group for a second dispatch.
// 4. Queue wraparound (q_head/q_tail crossing the QUEUE_DEPTH
// boundary) is exercised, not just a cold-start scenario.
// ============================================================
module tb;
localparam ADDR_WIDTH = 26;
localparam N_GROUPS = 4;
localparam QUEUE_DEPTH = 16;
localparam CLK_PERIOD_NS = 10.0;
reg clk = 0;
always #(CLK_PERIOD_NS/2.0) clk = ~clk;
reg rst;
reg job_in_valid;
wire job_in_ready;
reg [ADDR_WIDTH-1:0] job_in_x_base, job_in_w_base, job_in_result_addr;
reg [15:0] job_in_n_tiles, job_in_node_id;
wire [N_GROUPS-1:0] group_job_start;
wire [ADDR_WIDTH*N_GROUPS-1:0] group_w_base;
wire [16*N_GROUPS-1:0] group_n_tiles;
wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_x_base_a, group_pe_x_base_b;
wire [4*ADDR_WIDTH*N_GROUPS-1:0] group_pe_result_addr_a, group_pe_result_addr_b;
wire [4*16*N_GROUPS-1:0] group_pe_node_id_a, group_pe_node_id_b;
reg [N_GROUPS-1:0] group_job_done;
wire job_out_done;
wire [$clog2(N_GROUPS)-1:0] job_out_group;
wire [3:0] dir_state;
wire dir_error;
wire queue_empty;
neural_director_grouped #(
.ADDR_WIDTH(ADDR_WIDTH), .N_GROUPS(N_GROUPS), .QUEUE_DEPTH(QUEUE_DEPTH)
) dut (
.clk(clk), .rst(rst),
.job_in_valid(job_in_valid), .job_in_ready(job_in_ready),
.job_in_x_base(job_in_x_base), .job_in_w_base(job_in_w_base),
.job_in_n_tiles(job_in_n_tiles), .job_in_result_addr(job_in_result_addr),
.job_in_node_id(job_in_node_id),
.group_job_start(group_job_start), .group_w_base(group_w_base), .group_n_tiles(group_n_tiles),
.group_pe_x_base_a(group_pe_x_base_a), .group_pe_x_base_b(group_pe_x_base_b),
.group_pe_result_addr_a(group_pe_result_addr_a), .group_pe_result_addr_b(group_pe_result_addr_b),
.group_pe_node_id_a(group_pe_node_id_a), .group_pe_node_id_b(group_pe_node_id_b),
.group_job_done(group_job_done),
.job_out_done(job_out_done), .job_out_group(job_out_group),
.dir_state(dir_state), .dir_error(dir_error), .queue_empty(queue_empty)
);
integer errors, tests;
// real, root-caused fix (not guessed): driving job_in_valid on
// @(posedge clk) -- the SAME edge the DUT's own always block
// samples on -- races the DUT when submit_job is called back-to-
// back with zero real simulated gap (as submit_octet's own tight
// loop does): confirmed via real signal tracing that this
// produced a genuine DOUBLE registration, every logical push
// landing in TWO consecutive real queue slots with identical data
// (not a cosmetic/display artifact -- the DUT's own q_tail/q_count
// genuinely advanced twice per call). Standard, established fix:
// drive stimulus on the OPPOSITE edge (@(negedge clk)) from what
// the DUT samples on, so a value change can never race the DUT's
// own posedge-triggered sampling -- same underlying race family as
// this project's own documented "testbench stimulus must use
// nonblocking assignment" lesson (CLAUDE.md), now also confirmed
// to require edge separation, not just assignment-type discipline,
// for tight back-to-back pulse sequences with no natural gap.
task automatic submit_job(input [ADDR_WIDTH-1:0] xb, input [ADDR_WIDTH-1:0] wb,
input [15:0] nt, input [ADDR_WIDTH-1:0] ra, input [15:0] nid);
begin
@(negedge clk);
job_in_valid = 1'b1; job_in_x_base = xb; job_in_w_base = wb;
job_in_n_tiles = nt; job_in_result_addr = ra; job_in_node_id = nid;
@(negedge clk);
job_in_valid = 1'b0;
end
endtask
// submit an octet of 8 matching (same w_base/n_tiles) jobs at
// positions base_pos..base_pos+7
task automatic submit_octet(input [ADDR_WIDTH-1:0] wb, input [15:0] nt, input integer base_pos);
integer k;
begin
for (k = 0; k < 8; k = k + 1)
submit_job(26'h10000 + base_pos + k, wb, nt, 26'h9000 + base_pos + k, base_pos + k);
end
endtask
integer wd;
task automatic wait_group_dispatch(input integer max_wd);
begin
wd = 0;
while (!(|group_job_start) && wd < max_wd) begin @(posedge clk); wd = wd + 1; end
end
endtask
integer g, p;
task automatic check_dispatch(input [ADDR_WIDTH-1:0] wb, input [15:0] nt, input integer base_pos);
begin
tests = tests + 1;
wait_group_dispatch(200);
if (!(|group_job_start)) begin
$display("FAIL base_pos=%0d: TIMEOUT waiting for group_job_start", base_pos);
errors = errors + 1;
end else begin
g = -1;
for (p = 0; p < N_GROUPS; p = p + 1) if (group_job_start[p]) g = p;
if (group_w_base[g*ADDR_WIDTH +: ADDR_WIDTH] !== wb ||
group_n_tiles[g*16 +: 16] !== nt) begin
$display("FAIL base_pos=%0d: group%0d w_base/n_tiles mismatch (got w=%0h n=%0d exp w=%0h n=%0d)",
base_pos, g, group_w_base[g*ADDR_WIDTH +: ADDR_WIDTH], group_n_tiles[g*16 +: 16], wb, nt);
errors = errors + 1;
end else begin
for (p = 0; p < 4; p = p + 1) begin
if (group_pe_x_base_a[(g*4+p)*ADDR_WIDTH +: ADDR_WIDTH] !== (26'h10000 + base_pos + p*2) ||
group_pe_x_base_b[(g*4+p)*ADDR_WIDTH +: ADDR_WIDTH] !== (26'h10000 + base_pos + p*2 + 1)) begin
$display("FAIL base_pos=%0d group%0d PE%0d: x_base_a/b mismatch (got a=%0h b=%0h)",
base_pos, g, p,
group_pe_x_base_a[(g*4+p)*ADDR_WIDTH +: ADDR_WIDTH],
group_pe_x_base_b[(g*4+p)*ADDR_WIDTH +: ADDR_WIDTH]);
errors = errors + 1;
end
end
$display("PASS base_pos=%0d: dispatched to group%0d, w_base=%0h n_tiles=%0d, PE x_base assignment correct",
base_pos, g, wb, nt);
end
// simulate the group finishing its job after a few cycles
repeat (5) @(posedge clk);
group_job_done[g] = 1'b1;
@(posedge clk);
group_job_done[g] = 1'b0;
end
end
endtask
initial begin
errors = 0; tests = 0;
rst = 1;
job_in_valid = 0; job_in_x_base = 0; job_in_w_base = 0; job_in_n_tiles = 0;
job_in_result_addr = 0; job_in_node_id = 0; group_job_done = 0;
repeat(5) @(posedge clk);
rst = 0;
@(posedge clk);
$display("=== test 1: single octet, correct group dispatch + PE x_base assignment ===");
submit_octet(26'h1000, 16'd16, 0);
check_dispatch(26'h1000, 16'd16, 0);
$display("=== test 2: second octet, DIFFERENT w_base, correct dispatch ===");
submit_octet(26'h2000, 16'd32, 100);
check_dispatch(26'h2000, 16'd32, 100);
$display("=== test 3: mismatched w_base among the 8 oldest -- must STALL, not mis-dispatch ===");
// 7 matching + 1 mismatched. Real, established Director
// behavior (same as neural_director_packed.v's own pairing
// rule): once a mismatched entry is within the oldest-8
// window, q_head can never advance past it (nothing before it
// can ever be dispatched without it) -- the queue permanently
// stalls, a visible, diagnosable symptom, matching this
// module's own disclosed real design. There is no in-band
// recovery from a real submitter mistake like this (same real
// limitation neural_director_packed.v already has for pairs) --
// a real reset is the only way to clear it, which is exactly
// what this test does before moving on, not a workaround.
submit_job(26'h10000+200, 26'h3000, 16'd8, 26'h9000+200, 200);
submit_job(26'h10000+201, 26'h3000, 16'd8, 26'h9000+201, 201);
submit_job(26'h10000+202, 26'h3000, 16'd8, 26'h9000+202, 202);
submit_job(26'h10000+203, 26'h3000, 16'd8, 26'h9000+203, 203);
submit_job(26'h10000+204, 26'h3000, 16'd8, 26'h9000+204, 204);
submit_job(26'h10000+205, 26'h3000, 16'd8, 26'h9000+205, 205);
submit_job(26'h10000+206, 26'h3000, 16'd8, 26'h9000+206, 206);
submit_job(26'h10000+207, 26'h4000 /* MISMATCH */, 16'd8, 26'h9000+207, 207);
tests = tests + 1;
wait_group_dispatch(300);
if (|group_job_start) begin
$display("FAIL: group dispatched despite a real w_base mismatch among the 8 oldest entries -- WRONG DISPATCH");
errors = errors + 1;
end else begin
$display("PASS: correctly stalled (no dispatch) on mismatched octet, dir_error=%0b, queue_empty=%0b", dir_error, queue_empty);
end
// real reset to clear the deliberately-stalled queue before
// continuing -- not a workaround, the only real recovery path.
rst = 1;
job_in_valid = 0; group_job_done = 0;
repeat(5) @(posedge clk);
rst = 0;
@(posedge clk);
$display("=== test 4: queue wraparound (QUEUE_DEPTH=%0d boundary) ===", QUEUE_DEPTH);
submit_octet(26'h5000, 16'd4, 400);
check_dispatch(26'h5000, 16'd4, 400);
$display("=== %0d/%0d tests, %0d errors ===", tests-errors, tests, errors);
if (errors == 0) $display("ALL TESTS PASSED (tb_neural_director_grouped)");
$finish;
end
endmodule