ARRAY_clean7c.md
Source reports/results/GEMM_REVISION_20261117/rtl_snapshot/ARRAY_clean7c.md · source md5 d87e476cf58031d1a7f6aa62db1b5378 · EAGLE4 FPGA archive, 2026-11-18
# clean7c GEMV array (WP3): the 2-bit weight-stationary GEMV engine of both card roles
**Docs:** [ARCHITECTURE](ARCHITECTURE.md) · [GETTING_STARTED](GETTING_STARTED.md) · [HAZARDS](HAZARDS.md) · **ARRAY** (this page) · [ATT](ATT.md) · [MLPV](MLPV.md) · [LINK](LINK.md) · [CSR_MAP](CSR_MAP.md) · [STRAPS](STRAPS.md)
Program 1: ONE Llama-3.2-3B drafter on 7 V80s: ATT `0xE4B713BE` x4 (TP4 attention) + MLPV M1361 (`0xE4B71361`, PDI e24deb3f) x2.
Scope: the drafter's `u_array` and everything under it (lanes, lane clusters, weight / scale / zero banks, the ATT int8
quantizer, the MLPV packed-DSP dot units), plus the MLPV `gemv_dualclk_bridge` that runs it on the fast clock. The array's
feeders and sinks (seams, FSM, G9 exchange, R7 / G11 / G12 consumers) belong to WP4 / WP5.
Marks: [R] read from the RTL (`rtl/array/`, file:line), [M] measured (shipped synthesis census `data/wp0/*_shipped_synth.tsv`,
or a WP3 world, `reports/results/CLEAN_RTL_REPO_20261114/WP3_REPORT.md`). Nothing here is a projection.
> **KNOWN HAZARD [H1](HAZARDS.md#h1), SHIPPED AND KEPT ON PURPOSE (section 7): datapath registers that share a reset with control.** The issue
> registers of every lane (`qw_d` / `qwb_d` / `sc_d` / `ec_d`), the broadcast replicas, the RET_SER return registers, the MLPV
> return register `res_ret` and the G9 accumulators downstream of the array are pure data, but they sit in an
> `if (!rst_n) ... <= '0` block. Those are exactly the cells whose `IS_R_INVERTED` place_design flipped on other images
> (M1364: 12 `qw_d` bits of lane 84; T4: 36 G9 accumulator bits). clean7c is bit- and cycle-identical to what ships, so it keeps
> every reset; removing them is lever L-RST-DP (PLAN.md §6), a hardware change with its own gate.
## 1. Files (one module per file; each role keeps its own copy: the two shipped arrays are different lineages)
The ATT and MLPV arrays share a file name but not a body (1,109 differing lines in the shipped copies): ATT is the LUT-GEMM
lineage (`LUTG`, `A8Q`, `RET_SER`, `PRE_BASE`), MLPV the DOT_E3 lineage (`LANE_MO`, `LCACHE`, `RST_PIPE`, fast clock).
EQ-HIER compares every resolved parameter and port, so one merged file would add ports / parameters to the other role and fail
by construction; merging them is a lever, not a cleanup. Module names are unchanged (XDC / pblock / gate scripts match them).
| clean file | module | shipped source (ref/<role>/packaged_ip/src, md5) | code change (tools/code_diff.py, comment-stripped) |
|---|---|---|---|
| `att/gemv_stage_array_scaled_slr.sv` | the ATT array | 592d02ca | 29 never-elaborated branches -> stubs (-741 / +43 lines); 14 literal defaults = shipped |
| `att/lutgemm_lane_w2.sv` | W2 x A8 LUT-GEMM lane | 6edf4036 | g_csa20 / g_banks2 / g_fold_dsp -> stubs; 4 defaults |
| `att/lutg_a8q.sv` | per-token int8 quantizer | 7b6a3ced | none (role include only) |
| `att/lutg_a8q_tie63.svh` | tie ROM (include) | 589da239 | byte-identical copy |
| `att/csa_tree16_w.sv` | width-generic Wallace tree | 102c8ae3 | none |
| `att/weight_bank_multistage.sv` | lane weight bank (PRE_BASE form) | 8c7a12cd | g_local_base -> stub; 4 defaults |
| `att/scale_bram.sv` | lane scale / zero bank (PRE_BASE form) | 27f81ab4 | g_local_base -> stub; 3 defaults |
| `mlpv/gemv_stage_array_scaled_slr.sv` | the MLPV array | 723449ee | 16 branches -> stubs (-447 / +30); 14 defaults |
| `mlpv/gemv_lane_scaled_stream_dual_ext_opt.sv` | DOT_EXT dual-port lane | 7ca4843b | g_wlat0 -> stub; `ifdef RED_NOMASK / RED_GW arms gone; 8 defaults |
| `mlpv/e3b_packed_dot.sv`, `e3b_dsp58_mac.sv`, `e3b_dsp58_add.sv` | packed-DSP58 pair dot + its 2 DSP wrappers | e3b_packed_dot.sv 4b48ee7b (3 modules) | split; `ifdef E3_BEHAV arm gone; file-level `define E3B_RED_DEFAULT folded (1'b0); add: OPM default = shipped |
| `mlpv/gptq2_dequant16.sv` | combinational 2-bit dequant | 2af58b12 | none |
| `mlpv/gemv_dualclk_bridge.sv` | the 2:1 clock bridge | gemv_array_dualclk.sv 0395872d | split (module gemv_array_dualclk elaborates nowhere: not imported); g_frst_raw -> stub; 3 defaults |
| `mlpv/weight_bank_multistage.sv`, `scale_bram.sv` | lane banks (local-base form) | bb6565c3 / 0193548a | defaults only |
| `att/e4c_array_att.svh`, `mlpv/e4c_array_mlpv.svh` | role include | new | refuse the other role, state the role, include config + geometry |
| `../common/weight_bank_uram.sv` | URAM primitive (WP2 shared leaf) | 70c8acfa | WP2 |
- Every edit is generated by `tools/wp3_import.py` from the md5-pinned shipped file (`--check` re-derives and must be identical);
the old -> new map is `rtl/array/IMPORTS.tsv`, the resolved shipped parameters of every module `rtl/array/SHIPPED_PARAMS.tsv`.
- A removed branch is replaced INSIDE its own generate label by `C7_REMOVED_BRANCH__<module>__<label> u_c7_removed ();`: the
label and every taken branch stay byte-identical (the elaborated hierarchy cannot change), and selecting the branch is an
elaboration error in xelab and in synth_design (undefined module), never silently different hardware. The legality
interlocks (`g_*_x*`, the unresolved-module idiom) are kept.
- Compile inputs: `filelists/array_att.f`, `filelists/array_mlpv.f`.
## 2. Hierarchy: array -> group -> lane -> banks [R]
```mermaid
flowchart TB
subgraph ATT["ATT u_array (gemv_stage_array_scaled_slr, LANES 512, clk = ap_clk)"]
BA["g_bcast_pipe.g_grp_pipe[0..2]<br/>start / stage / tile / qz + PRE_BASE bases<br/>1 registered replica per SLR group"]
BWA["g_bootwr_pipe.g_bw_grp[0..2]<br/>boot weight+scale write bus, 2 deep"]
Q["g_a8q.u_a8q (lutg_a8q)<br/>dry walk -> M, R, T"]
LEAD["g_a8q.u_lead (lutgemm_lane_w2, no datapath)<br/>chunk-index lookahead"]
subgraph GA["g_grp[g], g = 0..2 (171 / 171 / 170 lanes)"]
CL["g_lutcl.g_cl[ck] (8 lanes per cluster)<br/>int8 act reg + g=2 pair tables + S / 3S"]
subgraph LA["g_lane[li].g_dual"]
WB["u_bank: weight_bank_multistage<br/>-> u_uram weight_bank_uram (URAM)"]
SB["u_scale: scale_bram (BRAM, SCALE_W 16)"]
ZB["g_lutg.g_zb.u_zero: scale_bram (BRAM18, SCALE_W 2)"]
LN["g_lutg.u_lane: lutgemm_lane_w2<br/>2 x csa_tree16_w"]
RS["g_lutg.g_rescale: x T >>> 14"]
end
end
RET["g_ret_ser.g_rs_grp[g]<br/>8 lanes x 48 b per beat, 22 beats / column<br/>rs_x (source) -> rs_l (landing) -> rs_out"]
end
BA --> CL --> LN
WB --> LN
SB --> LN
ZB --> LN
Q --> CL
LEAD --> Q
LN --> RS --> RET
BWA --> WB
BWA --> SB
```
```mermaid
flowchart TB
subgraph DC["MLPV g_dc.u_dc_bridge (gemv_dualclk_bridge): clk -> clk_fast = 2 x clk"]
FILL["fill FSM: chunk_idx_out -> slow seam -> lc_we / lc_waddr / lc_wdata"]
ISS["FAST_TP issuer: pending slot -> f_start / f_tile_idx; slow `ready`"]
BACK["done toggle -> slow capture of result_q_per_lane"]
end
subgraph MLPV["MLPV u_array (gemv_stage_array_scaled_slr, LANES 256, clk = ap_clk_fast)"]
RP["g_rst_pipe.g_rp[0..2]: rstg_n = rst_n delayed 2 (keep, max_fanout 512)"]
LC["g_lcache.g_lc_grp[g]: per-die activation cache<br/>mem_e / mem_o BRAM, 256 pairs"]
BM["g_bcast_pipe: 1 registered replica per group"]
subgraph GM["g_grp[g] (86 / 86 / 84 lanes)"]
subgraph LM["g_lane[li].g_dual_mo"]
WBM["u_bank: weight_bank_multistage -> u_uram (URAM)"]
SBM["u_scale: scale_bram (BRAM)"]
LNM["g_e3.u_lane: gemv_lane_scaled_stream_dual_ext_opt"]
E3["g_e3.g_pair (even li): u_e3_e / u_e3_o e3b_packed_dot<br/>(lanes li, li+1; 17 DSP58 each; 2 x gptq2_dequant16)"]
end
end
RR["g_ret_pipe.g_ret[rl].g_noaccret: res_ret (1 register)"]
end
FILL --> LC --> BM --> LNM
ISS --> LNM
WBM --> LNM
SBM --> LNM
LNM <-->|x_qw / x_a / x_v out, x_s back after 6| E3
LNM --> RR --> BACK
```
## 3. Residency (shipped synthesis census of the array subtree, per role) [M]
| what | ATT (512 lanes) | MLPV (256 lanes) |
|---|---|---|
| 2-bit qweight, 16 codes per 32-b word | URAM288E5 x 512 = 1 per lane (`u_bank`, DEPTH 8,192; 4,128 words used: G4 2,304 + G6 288 + G7g 768 + G7u 768) | URAM288E5 x 512 = 2 per lane (DEPTH 16,384; 10,160 used: G9 6,144 + G12 4,016) |
| GPTQ group scale (Q3.13) | RAMB36 x 512 (`u_scale`, DEPTH 2,048) | RAMB36 x 256 (`u_scale`, DEPTH 2,048) |
| GPTQ-v2 2-bit zero (per lane, per group) | RAMB18 x 512 (`g_zb.u_zero`, SCALE_W 2) | none (zero broadcast: `qz_raw`, per group) |
| activations | FF: per-cluster int8 register + pair tables (`g_lutcl`), broadcast replicas | BRAM x 24 per-die cache (`g_lcache`, 3 groups x even/odd), then FF broadcast replicas |
| DSP58 | 1,635 (512 in the lanes + 1,026 in the array scope, where the per-lane A8Q rescale multiply `g_rescale` lives + 96 in `u_a8q` + 1 in `u_lead`) | 5,120 (4,352 in the packed dot units = 256 x 17, 256 in the lanes, 256 in `u_bank` + 256 in `u_scale`: the local-base `col x chunks_per_col` multiply) |
| FDRE / FDSE | 466,350 / 514 | 149,251 / 1,540 (of which the bridge: 12,892 / 4) |
| SRL16E | 0 | 4,864 (the lanes' CSA_LAT tag / scale shift registers) |
Only the activation vector moves at compute time; every weight / scale / zero a lane reads is in its own bank, addressed by
`(stage_sel, tile_idx, chunk index)`. HBM is not touched by the array.
## 4. The per-stage time multiplex (stage_sel) and the array math [R + M]
```mermaid
flowchart LR
S["stage_sel (4 b), tile_idx (16 b)"] --> B["bank column base<br/>stage_base(s) + tile * chunks_per_col(s)<br/>(ATT: precomputed once per group, PRE_BASE)"]
B --> W["each lane reads chunk c of ITS column:<br/>URAM[base + c] port A (even), port B (odd)"]
A["activation chunk c (16 x int16)<br/>broadcast to every lane"] --> L["lane: 32 MACs / cycle<br/>(2 chunks), per-group fold, 1 scale multiply / group"]
W --> L --> R["result_q (48 b) per lane = one output element"]
```
- The banks hold the role's stages back to back (`config/e4c_stage_geometry.svh` `sg_w_stage_base_role`, role-rebased): role 1
(ATT) = stages [0, 4) G4 / G6 / G7g / G7u, role 2 (MLPV) = [4, 6) G9 / G12. A stage_sel outside the role maps to base 0.
- One pass of the array computes `LANES` output elements (one column per lane) of the stage; `tile_idx` walks the columns.
Per column the lane runs `ceil(nc / 2)` S_RUN cycles (nc = K / 16 chunks; 2 chunks per cycle on the dual-read URAM).
```
cycles(stage) = N * K / (LANES * K_PAR * RD_PORTS) K_PAR 16, RD_PORTS 2 (+ a per-column tail; TILE_PIPE overlaps it)
```
| role | stage | N x K (this card) | columns per lane | pairs per column | cycles | clock |
|---|---|---|---|---|---|---|
| ATT | G4 QKV | 3,072 x 6,144 | 6 | 192 | 1,152 | ap_clk |
| ATT | G6 o-proj | 3,072 x 768 | 6 | 24 | 144 | ap_clk |
| ATT | G7g / G7u | 2,048 x 3,072 each | 4 | 96 | 384 each | ap_clk |
| MLPV | G9 down (K half) | 6,144 x 4,096 | 24 | 128 | 3,072 | clk_fast (2 x ap_clk) |
| MLPV | G12 cheap lm-head (vocab half) | 64,128 x 256 | 251 (ceil) | 8 | 2,008 | clk_fast |
The formula and the shapes are [R] (`e4c_role_<role>.svh` GEOM rows); the same formula was measured exact to the cycle on the
shipped arrays at 8 stage points (NOW.md D790).
## 5. Handshake and latency contract [R]
- **Activation fetch (both roles):** the consumer fetches `a_chunk` / `a_chunk_b` off `chunk_idx_out` / `chunk_idx_b_out`
through a registered seam (RD_LAT 1: `a_chunk(t+1) = row[chunk_idx_out(t)]`). The forward broadcast replica adds one more
register, so the array exposes an index that LEADS the lane by one (`g_idx_lookahead`, `= chunk_idx_next_out` of lane 0), and
the lanes re-register their weight / scale / zero once (`WLAT 1`, the D1 seam fix) so act[c] meets W[c].
- **ATT A8Q:** on the first tile of a stage pass (`start && tile_idx == 0`) `u_a8q` holds the lane start, drives the index
itself over every pair (dry walk), takes M = max|x|, runs two dividers (31 cycles), then releases the start; the lead lane
`u_lead` (started one cycle before the lanes) keeps the lookahead aligned.
- **TILE_PIPE (both):** `ready` pulses `TP_RDY_OFF * TP_STEP` = 8 lane-counter steps before the terminal pair; the caller
advances `tile_idx` and registers its start on that edge and presents `start` one cycle later, so the lane accepts the next
column on its terminal pair cycle (derivation in the TILE_PIPE block of each array file; one step earlier re-bases the bank
while the old column's last address is still presented: the documented RED). MLPV: the bridge rebuilds this chain on
clk_fast (`FAST_TP`), and its slow `ready` means "the pending slot was consumed, send the next start".
- **Return:** ATT `done` = all 3 groups committed their serial return (22 beats per column); MLPV `done` = `&done_ret` one
register after the lanes, then the bridge's toggle + slow capture.
- **Report-only status:** `tp_start_dropped` (a start the lane could not accept), ATT `lutg_err` (wrong pair sequence). They
gate nothing.
## 6. MLPV clock crossing (gemv_dualclk_bridge) [R]
| path | mechanism | static requirement |
|---|---|---|
| phase | `tick_s` toggles on clk, `tick_f <= tick_s` on clk_fast, `first_half = tick_s ^ tick_f` | - |
| slow -> fast: start, boot writes, cache fill | slow-registered, held one slow cycle, qualified with `first_half` (seen at exactly one fast edge) | one fast period |
| slow -> fast: reset | `g_frst.frst_q` 2-flop clk_fast copy (FAST_RST_SYNC 1) -> `f_rst_n` (array reset) | one fanout-1 flop |
| fast -> slow: done + results | `done_tog_f` toggle, slow compare `done_seen_s`, capture `res_q` one slow edge later | one fast period |
| FAST_TP issue | pending slot `pend_tog_s` / `cons_tog_f`, launch on `f_ready` or nothing in flight | toggle compare, no pulse seen twice |
No async FIFO, no ASYNC_REG, no multicycle: both clocks come from one MMCM at an integer 2:1 ratio.
## 7. KNOWN HAZARD: datapath registers that carry an unnecessary reset [R + M]
Every reset in the array is synchronous active-low (the audit `RTL_RESET_STYLE_AND_STRAPS_AUDIT_20261114.md`); the rows below
are DATA registers that have no reason to be reset but share the reset block with control bits. place_design's in-placer
physical synthesis set `IS_R_INVERTED = 0` on such cells of two images (`LINEAGE1360_ROOT_RCA_20261114.md` §7-8): an
inverted active-low reset holds the FF in reset in operation (bit stuck 0), timing cannot see it, and only the reset-polarity
census (`srpol_census.tcl`, must-pass R-SRPOL) does. clean7c keeps every one of them (bit- and cycle-identical); lever
L-RST-DP removes them.
| register (data) | clean file:line (reset arm) | shipped file:line | observed flip |
|---|---|---|---|
| `qw_d`, `qwb_d`, `sc_d`, `ec_d` (MLPV lane issue regs, g_wlat1) | `mlpv/gemv_lane_scaled_stream_dual_ext_opt.sv:360` | `gemv_lane_scaled_stream_dual_ext_opt.sv:357` (7ca4843b) | **M1364 lane 84: 12 `qw_d` bits (mask 0x5F077000) INV0 on group 0's `rstg_n` BUFG => x_qw_e stuck, G9 / G12 columns 84 + 256k wrong** (the block also resets the control bits `civ_d` + tags) |
| `grp_sr`, `sc_sr`, `last_sr` / `vld_sr` (MLPV lane tag + scale shift regs) | `mlpv/gemv_lane_scaled_stream_dual_ext_opt.sv:479` | `:480` | - |
| `group_acc_b`, `scaled_acc_b`, `acc_out`, `result_q` (MLPV lane accumulators / outputs) | `mlpv/gemv_lane_scaled_stream_dual_ext_opt.sv:511`, `:528` | `:516`, `:533` | - |
| `qw_d`, `qwb_d`, `sc_d`, `qz_d`, `ec_d` (ATT LUT lane issue regs) | `att/lutgemm_lane_w2.sv:244` | `lutgemm_lane_w2.sv:240` (6edf4036) | - (same idiom as the MLPV lane) |
| `z_e`, `z_o`, `sc_sr`, `acc_s` / `gacc_s` / `sacc_s`, `acc_out` / `result_q` (ATT lane) | `att/lutgemm_lane_w2.sv:344`, `:393`, `:439`, `:454` | `:346`, `:395`, `:458`, `:473` | - |
| `a_chunk_p`, `a_chunk_b_p` (broadcast activation replica; ATT loads '0 under LUTG) | `att/gemv_stage_array_scaled_slr.sv:698`, `mlpv/...:556` | ATT `:809`, MLPV `:689` | - |
| boot write replicas `wr_data_p`, `sc_wr_data_p` ... | `att/...:1071` block (the `!rst_n` block; data replicas are adjacent lines), `mlpv/...:851` | ATT `:1361`, MLPV `:1145` | - |
| ATT cluster `a_r` / `ab_r` / `tb_r` / `tbb_r`, `s1` / `s2` / `s3x` | `att/gemv_stage_array_scaled_slr.sv:1188`, `:1203` | `:1494`, `:1509` | - |
| ATT A8Q rescale `prod`, `y` | `att/gemv_stage_array_scaled_slr.sv:1380` | `:1793` | - |
| ATT RET_SER `rs_x_d`, `rs_l_d`, `rs_shadow`, `rs_out` | `att/gemv_stage_array_scaled_slr.sv:1542`, `:1570`, `:1599` | `:2172`, `:2200`, `:2229` | - |
| MLPV return `res_ret` (on `rst_n`, not `rstg_n`) | `mlpv/gemv_stage_array_scaled_slr.sv:1158` | `:1652` | - |
| bank change detector `col_offset_d` (MLPV local-base banks) | `mlpv/weight_bank_multistage.sv:113` | `weight_bank_multistage.sv:131` (bb6565c3) | **M1364 lane 40: 3 bits INV0 (benign: the detector recomputes the same base)** |
| **G9 accumulator path (outside the array files):** `acc_sh`, `g9_acc_lat` | canonical rows: [MLPV.md §8](MLPV.md) | - | **T4: 24 + 12 bits INV0** |
The shipped M1361 and 0x13BE final checkpoints have 0 mixed-polarity reset nets (SRPOL tooth 1: WP0 baseline, `M1364E_ECO_20261114.md`),
so the hazard is latent in the RTL, not present in the images this tree reproduces.
## 8. Straps of the array (what is a parameter, what was folded) [R]
- Every array parameter keeps its declaration (EQ-HIER compares every resolved parameter); the literal defaults now equal the
value every shipped instance resolves (`SHIPPED_PARAMS.tsv`). The drafter still passes them from `config/e4c_config.svh` /
`e4c_role_<role>.svh` (e.g. `EAGLE4_SLR_SAFE` -> SLR_SAFE, `EAGLE4_LUTG` -> LUTG, `EAGLE4_ARRAY_FAST_CLK` -> RST_PIPE / LCACHE),
so the FIXED config lines are folded on the ARRAY side here and deleted from the config when WP4 / WP5 fold the drafter side.
- Folded here (branch removed, the value is now the only legal one): PREFETCH_COL 0, SLR_SAFE 1, FF_ACT_CACHE 0, BATCH_B 1,
SIB_PUMP 0, DUAL_PORT 1, BOOT_WR_PIPE != 0, EMBFOLD 0 (FOLD_WR_PIPE), RED_PRE / RED_LUTZ 0; ATT: RST_PIPE 0, PRE_BASE 1, LUTG 1,
LUTG_ZSRC 0, A8Q 1, DOT_E3 0, LCACHE 0, RET_SER 1 (non-sibling beats), CSA_NARROW / TP_SLIM / FOLD_FABRIC 1; MLPV: RST_PIPE != 0,
DOT_E3 1, LANE_MO 1, LC_BRAM 1, LCACHE 1, LANE_ACC_DBG 0, WLAT 1, FAST_RST_SYNC 1.
- Kept as written: the interlocks; zero-trip `for` generates over PIPE_STAGES / RET_STAGES (structural depth loops, not branches);
procedural uses of RED_* parameters; the `ifndef SYNTHESIS` checks; the SIM_WSNAP snapshot hooks.
Hazard register entry, gates (`must_pass_gate.sh --srpol` / `--srpol-optdiff`) and levers: [HAZARDS.md H1](HAZARDS.md#h1).
## 9. Gates (WP3; numbers in WP3_REPORT.md)
- EQ-HIER on the WP2 + WP3 overlay roots (`tools/wp3_overlay.py`), both roles, drafter + every module-ref top.
- EQ-CONN (`sim/equiv/eq_conn.py`, new): every instance's port -> expression binding, both roles, with a planted swap RED.
- EQ-UNIT shadow lockstep in the ARRAY WORLD (`sim/equiv/array/gen_array_world.py` + `array_unit_verdict.py`): every instance
of every module above, every output every edge, TB-PARAM read-back, instance-count expectations, port coverage >= 95 %.
- OOC-CENSUS: full drafter per role vs the same-recipe census of ref; XDC-PATH tier E and N.
- REDs planted in the clean modules (corner mutants, a 1-cycle `ready` shift, the M1364 lane-84 stuck-bit pattern) must FAIL.