mlpv_gemv_dualclk_bridge.sv.md
Source reports/results/GEMM_REVISION_20261117/rtl_snapshot/mlpv_gemv_dualclk_bridge.sv.md · source md5 dfd1a9747be76d45d724385e04aad0f9 · EAGLE4 FPGA archive, 2026-11-18
# Snapshot: verilog/clean7c/rtl/array/mlpv/gemv_dualclk_bridge.sv
Copied 2026-11-17T17:32:37Z from the clean7c tree (verilog repo commit 5998a7f1, md5 249b3823908d0b85cea0d0e3bf2f14b8). Read-only copy for review; the live file is in the RTL repo.
```systemverilog
// =====================================================================================================================
// gemv_dualclk_bridge (clean7c rtl/array/mlpv, WP3)
// =====================================================================================================================
// Imported from the shipped packaged copy ref/mlpv_1361/packaged_ip/src/gemv_array_dualclk.sv md5 0395872de0c670fbcd74422d5ca6b51c (MLPV 0xE4B71361 (M1361, PDI e24deb3f)).
// Code = the shipped code; only this header, the items under 'clean7c edits' and the role include differ.
// Regenerate / verify: tools/wp3_import.py [--check]. Architecture + diagrams: docs/ARRAY.md.
//
// Purpose : runs the MLPV u_array on its own clock clk_fast = 2 x clk (same source, integer ratio, phase aligned) and owns
// EVERY crossing: phase reference (tick_s toggles on clk, tick_f copies it on clk_fast, first_half = tick_s ^ tick_f
// marks the first fast cycle after each slow edge); slow->fast: start, boot weight/scale writes and the activation
// cache fill, all slow-registered and qualified by first_half (seen at exactly one fast edge); fast->slow: done via
// a fast toggle the slow side compares, capturing result_q/acc_out into slow hold registers in the same edge.
// Once per stage invocation (act_reload) it FILLS the array's per-die activation cache (LCACHE) from the slow seams
// through the same chunk_idx_out / a_chunk interface the drafter already has; EARLY_START launches the first tile
// mid-fill at the derived bound S = ceil((np+3)/2) + ES_MARGIN. FAST_TP 1: fast-domain tile issue for the TILE_PIPE
// array (the array's `ready` -> pending slot -> slow `ready`). FAST_RST_SYNC 1: every clk_fast flop of the bridge
// and the array (f_rst_n) resets from a 2-flop clk_fast copy of rst_n (g_frst.frst_q).
// Users : MLPV drafter g_array_scaled.g_dc.u_dc_bridge (1). Module gemv_array_dualclk of the same shipped file (bridge +
// array composite) is elaborated by no shipped image and is not imported.
// Latency : fill = ceil(nc/2) + 2 slow cycles per stage; result_q_per_lane changes only on the slow `done` cycle and holds.
// Reset : rst_n (slow flops) and rst_nf = frst_q[1] (fast flops); tick_s / tick_f / frst_q have initial values, no reset.
// Invariant: no async FIFO, no ASYNC_REG, no multicycle: every crossing has a one-fast-period static requirement
// (both clocks from one MMCM).
// Instances in the image: 1 (resolved parameters: rtl/array/SHIPPED_PARAMS.tsv, rows 'mlpv gemv_dualclk_bridge').
// Ports (generated from the port list; widths as declared, resolved values are in SHIPPED_PARAMS.tsv):
// input clk 1
// input clk_fast 1
// input rst_n 1
// output f_rst_n 1
// input act_reload 1
// input fold_i 1
// input start 1
// input a_chunk signed [K_PAR*A_WIDTH-1:0]
// input a_chunk_b signed [K_PAR*A_WIDTH-1:0]
// input stage_sel [3:0]
// input we 1
// input wr_addr [16:0]
// input wr_data [31:0]
// input sc_we 1
// input sc_wr_addr [16:0]
// input sc_wr_data [SCALE_WIDTH-1:0]
// input tile_idx [15:0]
// input f_ready 1
// output f_tile_idx [15:0]
// output ready 1
// output f_start 1
// output f_we 1
// output f_wr_addr [16:0]
// output f_wr_data [31:0]
// output f_sc_we 1
// output f_sc_wr_addr [16:0]
// output f_sc_wr_data [SCALE_WIDTH-1:0]
// output f_lc_we 1
// output f_lc_waddr [CW-1:0]
// output f_lc_wdata_e signed [K_PAR*A_WIDTH-1:0]
// output f_lc_wdata_o signed [K_PAR*A_WIDTH-1:0]
// input f_done 1
// input f_res signed [RES_WIDTH*LANES-1:0]
// input f_acc signed [32*LANES-1:0]
// output chunk_idx_out [CW-1:0]
// output chunk_idx_b_out [CW-1:0]
// output chunk_idx_valid 1
// output acc_out_per_lane signed [32*LANES-1:0]
// output result_q_per_lane signed [RES_WIDTH*LANES-1:0]
// output done 1
// output fill_busy 1
// output start_while_busy 1
// clean7c edits:
// - dead branch `g_frst_raw` (FAST_RST_SYNC 0) removed -> stub (shipped :176-178)
// - default LANES 128 -> 256 (every gemv_dualclk_bridge instance of the image resolves 256)
// - default FAST_TP 1'b0 -> 1'b1 (every gemv_dualclk_bridge instance of the image resolves 1'b1)
// - default FAST_RST_SYNC 1'b0 -> 1'b1 (every gemv_dualclk_bridge instance of the image resolves 1'b1)
// =====================================================================================================================
`timescale 1ns/1ps
`default_nettype none
`include "e4c_array_mlpv.svh" // role guard + config/e4c_config.svh + config/e4c_stage_geometry.svh (was stage_geometry.svh)
module gemv_dualclk_bridge #(
parameter int FOLD_PAIRS = 0, // EMBFOLD_C7: first pair a folded G4 lane reads (FOLD_BASE/2 = 96); 0 = no fold
parameter int K = 8192,
parameter int K_PAR = 16,
parameter int LANES = 256,
parameter int A_WIDTH = 16,
parameter int RES_WIDTH = 48,
parameter int SCALE_WIDTH = 16,
parameter int LC_WR_PIPE = 2,
parameter bit EARLY_START = 1'b1,
parameter int ES_MARGIN = 1,
parameter bit RED_FILL_PHASE = 1'b0,
parameter bit RED_BOOT_PHASE = 1'b0,
parameter bit RED_DONE_RAW = 1'b0,
parameter bit RED_START_RAW = 1'b0,
// I12_FASTCLK_TILEPIPE_20260924: fast-domain tile issue (see the FAST_TP
// block below). 0 = the ARRAY_DUALCLK_20260923 bridge, unchanged.
parameter bit FAST_TP = 1'b1,
// RED (FAST_TP only): the array's tile_idx changes one fast cycle LATE
// (valid T-1 instead of T-2) -> the new column's first address uses the
// old col_offset_acc. Must FAIL the A/B gate. Default 0.
parameter bit RED_TP_TI_LATE = 1'b0,
// FAST_RST_SYNC (2026-10-19, OOC hold RCA: MLPV_V12_L256DC.md / HYBRID_L512_MLPV.md): 1 = every clk_fast flop of the bridge AND
// the array (via f_rst_n) resets from a 2-flop clk_fast copy of rst_n, so the only slow->fast reset path is ONE fanout-1 flop the
// router can hold-fix. At L512 opt_design put the raw 25K-fanout slow rst_n on a BUFG_FABRIC (no hold detours on global routing)
// -> slow->fast WHS -0.538 (P40) / -0.142 (P48). Assert/release move 2 fast cycles later on the fast side only (boot and compute
// start long after). 0 = the raw rst_n (byte-identical; f_rst_n = rst_n).
parameter bit FAST_RST_SYNC = 1'b1,
parameter int N_CHUNKS = K / K_PAR,
parameter int CW = (N_CHUNKS <= 1) ? 1 : $clog2(N_CHUNKS + 2)
) (
input wire clk,
input wire clk_fast,
input wire rst_n,
output wire f_rst_n, // FAST_RST_SYNC: reset for the clk_fast array (= rst_n at 0)
input wire act_reload,
input wire fold_i, // EMBFOLD_C7: this start's stage is a folded G4 (walk starts at pair FOLD_PAIRS)
input wire start,
input wire signed [K_PAR*A_WIDTH-1:0] a_chunk,
input wire signed [K_PAR*A_WIDTH-1:0] a_chunk_b,
input wire [3:0] stage_sel,
input wire we,
input wire [16:0] wr_addr,
input wire [31:0] wr_data,
input wire sc_we,
input wire [16:0] sc_wr_addr,
input wire [SCALE_WIDTH-1:0] sc_wr_data,
// I12 FAST_TP only (ignored / constant at FAST_TP=0)
input wire [15:0] tile_idx, // slow: the drafter's array_tile_idx
input wire f_ready, // fast: the array's TILE_PIPE `ready`
output wire [15:0] f_tile_idx, // fast: tile_idx to the array
output wire ready, // slow: "send the next tile's start"
// to the fast array
output wire f_start,
output wire f_we,
output wire [16:0] f_wr_addr,
output wire [31:0] f_wr_data,
output wire f_sc_we,
output wire [16:0] f_sc_wr_addr,
output wire [SCALE_WIDTH-1:0] f_sc_wr_data,
output wire f_lc_we,
output wire [CW-1:0] f_lc_waddr,
output wire signed [K_PAR*A_WIDTH-1:0] f_lc_wdata_e,
output wire signed [K_PAR*A_WIDTH-1:0] f_lc_wdata_o,
// from the fast array
input wire f_done,
input wire signed [RES_WIDTH*LANES-1:0] f_res,
input wire signed [32*LANES-1:0] f_acc,
// slow-side contract
output wire [CW-1:0] chunk_idx_out,
output wire [CW-1:0] chunk_idx_b_out,
output wire chunk_idx_valid,
output wire signed [32*LANES-1:0] acc_out_per_lane,
output wire signed [RES_WIDTH*LANES-1:0] result_q_per_lane,
output wire done,
output wire fill_busy,
output wire start_while_busy
);
generate
if (EARLY_START && LC_WR_PIPE != 2) begin : g_x_es ERROR_DUALCLK_EARLY_START_BOUND_DERIVED_FOR_LC_WR_PIPE_2 u_v (); end
endgenerate
localparam int W = K_PAR * A_WIDTH;
// ---------------- phase reference ----------------
reg tick_s = 1'b0;
always_ff @(posedge clk) tick_s <= ~tick_s;
reg tick_f = 1'b0;
wire rst_nf; // reset seen by every clk_fast flop of this bridge (and exported as f_rst_n)
generate if (FAST_RST_SYNC) begin : g_frst
(* keep = "true", shreg_extract = "no" *) reg [1:0] frst_q = 2'b00;
always_ff @(posedge clk_fast) frst_q <= {frst_q[0], rst_n};
assign rst_nf = frst_q[1];
end else begin : g_frst_raw
// clean7c WP3: branch `g_frst_raw` (FAST_RST_SYNC 0) is elaborated by NO instance of MLPV 0xE4B71361 (M1361, PDI e24deb3f) and was removed
// (shipped text: ref/mlpv_1361/packaged_ip/src/gemv_array_dualclk.sv:176-178). Selecting it is an elaboration
// error, never silently different hardware; restoring it is a lever (PLAN.md §6), not a cleanup.
C7_REMOVED_BRANCH__gemv_dualclk_bridge__g_frst_raw u_c7_removed ();
end endgenerate
assign f_rst_n = rst_nf;
always_ff @(posedge clk_fast) tick_f <= tick_s;
wire first_half = tick_s ^ tick_f;
// ---------------- slow side: fill / issue / done ----------------
function automatic [3:0] act_grp(input [3:0] s);
act_grp = (s == 4'd3) ? 4'd2 : s; // G7u reads the same premlp seam as G7g
endfunction
function automatic [CW-1:0] np_of(input [3:0] s);
logic [16:0] c;
c = sg_w_chunks_per_col(s);
if (c == 17'd0 || c > 17'(N_CHUNKS)) c = 17'(N_CHUNKS);
np_of = CW'((c + 17'd1) >> 1);
endfunction
reg busy, filling, started;
reg [3:0] cache_grp;
reg cache_ok, reload_pend;
reg [CW:0] fcnt, np_q, s_thr, f_end;
reg wr_v;
reg [CW-1:0] wr_p;
reg fw_we_s;
reg [CW-1:0] fw_a_s;
reg [W-1:0] fw_de_s, fw_do_s;
reg start_s;
reg sw_busy_err;
reg dt_s;
reg done_q;
reg signed [RES_WIDTH*LANES-1:0] res_q;
reg signed [32*LANES-1:0] acc_q;
reg done_tog_f;
// I12 FAST_TP state (slow side)
reg pend_tog_s; // flips on every accepted start (1-deep pending slot)
reg [15:0] pend_tile_s; // tile_idx captured with that start
reg perm_s; // 0 while a fill has not reached its EARLY_START bound
reg cons_seen_s; // slow copy of cons_tog_f
reg ready_s; // 1-slow-cycle "pending slot consumed" pulse
reg cons_tog_f; // fast: = pend_tog_s after the launch that consumed it
wire pend_busy_s = FAST_TP && (pend_tog_s != cons_tog_f);
wire [CW-1:0] np_now = np_of(stage_sel);
wire need_ld = reload_pend || act_reload || !cache_ok || (act_grp(stage_sel) != cache_grp);
// EARLY_START threshold (see header): ceil((np+3)/2) + ES_MARGIN, floored at 0.
function automatic [CW:0] thr_of(input [CW-1:0] np);
int t;
t = (int'(np) + 4) / 2 + ES_MARGIN;
if (t < 0) t = 0;
thr_of = (CW+1)'(t);
endfunction
wire done_seen = RED_DONE_RAW ? f_done : (done_tog_f != dt_s);
// 4C1 TIMING (2026-10-17, s3LAattf4 routed dcp md5 82955c05, re-timed with the lrst bound: WNS -1.069,
// 13,635 endpoints = done_tog_f (clk_fast) -> done_seen -> CE of every res_q/acc_q bit, a one-fast-period
// cross-clock requirement on a ~10K fanout that the router's hold padding broke).
// done_seen is now registered in the slow domain (ONE cross-clock endpoint) and the done/result capture
// happens one slow edge later from that slow register (slow->slow CE). Still exact: f_res/f_acc only
// change at the NEXT column's f_done (TILE_PIPE 2-bank / or the next slow-issued start at FAST_TP=0),
// which is >= one whole column of fast cycles after this done, far beyond the +2 fast cycles added here.
// done, result_q_per_lane and busy move together, so the slow consumer's contract is unchanged; cost =
// +1 slow cycle of latency per array done.
reg done_seen_s;
always_ff @(posedge clk) begin
if (!rst_n) begin
busy <= 1'b0; filling <= 1'b0; started <= 1'b0;
cache_grp <= 4'hF; cache_ok <= 1'b0; reload_pend <= 1'b0;
fcnt <= '0; np_q <= '0; s_thr <= '0; f_end <= '0;
wr_v <= 1'b0; wr_p <= '0;
fw_we_s <= 1'b0; fw_a_s <= '0; fw_de_s <= '0; fw_do_s <= '0;
start_s <= 1'b0; sw_busy_err <= 1'b0;
dt_s <= 1'b0; done_seen_s <= 1'b0; done_q <= 1'b0; res_q <= '0; acc_q <= '0;
pend_tog_s <= 1'b0; pend_tile_s <= '0; perm_s <= 1'b1; cons_seen_s <= 1'b0; ready_s <= 1'b0;
end else begin
start_s <= 1'b0;
fw_we_s <= 1'b0;
done_q <= 1'b0;
if (act_reload) reload_pend <= 1'b1;
// ---- fill: registered seam return (RD_LAT=1) -> fw_*_s ----
wr_v <= filling && (fcnt < {1'b0, np_q[CW-1:0]});
wr_p <= fcnt[CW-1:0];
if (wr_v) begin
fw_we_s <= 1'b1;
fw_a_s <= RED_FILL_PHASE ? (wr_p + CW'(1)) : wr_p;
fw_de_s <= a_chunk;
fw_do_s <= a_chunk_b;
end
if (filling) begin
fcnt <= fcnt + 1'b1;
if (!started && fcnt == s_thr) begin
started <= 1'b1;
if (FAST_TP) perm_s <= 1'b1; // the fast issuer may now launch
else start_s <= 1'b1;
end
if (fcnt == f_end) filling <= 1'b0;
end
// ---- I12 FAST_TP: pending slot consumed -> tell the drafter ----
cons_seen_s <= cons_tog_f;
ready_s <= FAST_TP && (cons_tog_f != cons_seen_s);
// ---- issue ----
if (FAST_TP) begin
// Every start (first tile of a stage or an overlapped one) goes
// into the 1-deep pending slot; the fast side launches it.
if (start) begin
if (pend_busy_s) sw_busy_err <= 1'b1;
else begin
pend_tog_s <= ~pend_tog_s;
pend_tile_s <= tile_idx;
if (need_ld) begin
filling <= 1'b1;
started <= 1'b0;
perm_s <= 1'b0;
fcnt <= '0;
np_q <= {1'b0, np_now};
// CONSOLIDATED AC (I12 FAST_TP x EMBFOLD): the fast-issue fill path takes the same folded EARLY_START
// bound as the serial path (fold_i=0 -> the original expression, byte-identical behaviour).
s_thr <= EARLY_START ? thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0))) : ({1'b0, np_now} + (CW+1)'(2));
f_end <= (EARLY_START && thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0))) > ({1'b0, np_now} + (CW+1)'(2)))
? thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0))) : ({1'b0, np_now} + (CW+1)'(2));
cache_grp <= act_grp(stage_sel);
cache_ok <= 1'b1;
reload_pend <= 1'b0;
end
end
end
end else
if (start) begin
if (busy) sw_busy_err <= 1'b1;
else begin
busy <= 1'b1;
if (need_ld) begin
filling <= 1'b1;
started <= 1'b0;
fcnt <= '0;
np_q <= {1'b0, np_now};
// start threshold: EARLY -> derived bound; else after the last write left (np+2)
// EMBFOLD_C7: a folded G4 lane reads pair FOLD_PAIRS+p at the edge a pair-0 walk reads p,
// so the EARLY_START bound is taken at np+FOLD_PAIRS (fold_i=0 -> the original expression).
s_thr <= EARLY_START ? thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0)))
: ({1'b0, np_now} + (CW+1)'(2));
f_end <= (EARLY_START && thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0))) > ({1'b0, np_now} + (CW+1)'(2)))
? thr_of(np_now + ((FOLD_PAIRS > 0 && fold_i) ? CW'(FOLD_PAIRS) : CW'(0))) : ({1'b0, np_now} + (CW+1)'(2));
cache_grp <= act_grp(stage_sel);
cache_ok <= 1'b1;
reload_pend <= 1'b0;
end else begin
start_s <= 1'b1; started <= 1'b1;
end
end
end
// ---- fast -> slow done + result capture (same slow edge) ----
dt_s <= done_tog_f;
done_seen_s <= done_seen;
if (done_seen_s) begin
done_q <= 1'b1;
res_q <= f_res;
acc_q <= f_acc;
busy <= 1'b0;
end
end
end
assign chunk_idx_out = {fcnt[CW-2:0], 1'b0};
assign chunk_idx_b_out = {fcnt[CW-2:0], 1'b1};
assign chunk_idx_valid = filling && (fcnt < {1'b0, np_q[CW-1:0]});
assign fill_busy = filling;
assign start_while_busy = sw_busy_err;
// ---------------- fast side ----------------
// I12 FAST_TP: the tile ISSUER lives here, on clk_fast.
// pending : pend_tog_s != cons_tog_f (a slow-registered slot; sampled
// directly -- slow registers are stable for both fast cycles
// of a slow period; toggle compare, so no pulse can be seen
// twice and no first_half qualification is needed).
// launch : pending && perm_s && (f_ready || nothing in flight).
// f_ready is the array's own TILE_PIPE `ready` (high in fast
// cycle T-3 of the in-flight column, TP_RDY_OFF=4). The chain
// below is the drafter's single-clock chain rebuilt in fast
// cycles: tile_idx changes at the end of T-3 (valid T-2, same as
// the caller advancing tile_idx), start_1 (T-2) = start_r,
// start_2 (T-1) = array_start_fsm_q -> forward seam -> the lane
// sees start on its terminal pair (T). The ROUND-15 guard cycle
// is therefore preserved exactly as derived in the array header.
// idle : infl_f == 0 -> launch immediately (first tile of a stage, or
// the drafter was late for the ready window). The lane is idle
// by then (done fires after the last CSA output; the launch
// is >= 3 fast cycles after the array-level done).
// infl_f : columns launched and not yet `done` (<= 2).
reg tp_st1_f, tp_st2_f;
reg [15:0] tp_ti_f, tp_ti_late_f;
reg [1:0] infl_f;
wire tp_pv_f = FAST_TP && (pend_tog_s != cons_tog_f) && perm_s;
wire tp_launch = tp_pv_f && (f_ready || (infl_f == 2'd0));
always_ff @(posedge clk_fast) begin
if (!rst_nf) begin
tp_st1_f <= 1'b0; tp_st2_f <= 1'b0; tp_ti_f <= '0; tp_ti_late_f <= '0; cons_tog_f <= 1'b0; infl_f <= '0;
end else begin
tp_st1_f <= tp_launch;
tp_st2_f <= tp_st1_f;
if (tp_launch) begin tp_ti_f <= pend_tile_s; cons_tog_f <= pend_tog_s; end
tp_ti_late_f <= tp_ti_f;
infl_f <= infl_f + (tp_launch ? 2'd1 : 2'd0) - (f_done ? 2'd1 : 2'd0);
end
end
assign f_tile_idx = FAST_TP ? (RED_TP_TI_LATE ? tp_ti_late_f : tp_ti_f) : tile_idx;
assign ready = FAST_TP ? ready_s : 1'b0;
assign f_start = FAST_TP ? tp_st2_f : (RED_START_RAW ? start_s : (start_s & first_half));
reg [16:0] bd_wa_f, bd_sa_f;
reg [31:0] bd_wd_f;
reg [SCALE_WIDTH-1:0] bd_sd_f;
always_ff @(posedge clk_fast) begin
bd_wa_f <= wr_addr; bd_wd_f <= wr_data; bd_sa_f <= sc_wr_addr; bd_sd_f <= sc_wr_data;
end
assign f_wr_addr = RED_BOOT_PHASE ? bd_wa_f : wr_addr;
assign f_wr_data = RED_BOOT_PHASE ? bd_wd_f : wr_data;
assign f_sc_wr_addr = RED_BOOT_PHASE ? bd_sa_f : sc_wr_addr;
assign f_sc_wr_data = RED_BOOT_PHASE ? bd_sd_f : sc_wr_data;
assign f_we = we & first_half;
assign f_sc_we = sc_we & first_half;
assign f_lc_we = fw_we_s & first_half;
assign f_lc_waddr = fw_a_s;
assign f_lc_wdata_e = fw_de_s;
assign f_lc_wdata_o = fw_do_s;
always_ff @(posedge clk_fast) begin
if (!rst_nf) done_tog_f <= 1'b0;
else if (f_done) done_tog_f <= ~done_tog_f;
end
assign acc_out_per_lane = acc_q;
assign result_q_per_lane = res_q;
assign done = done_q;
endmodule
`default_nettype wire
```