chore(task): archive 06-25-vivado-verilog-tb

.trellis/tasks/archive/2026-06/06-25-vivado-verilog-tb/prd.md

@@ -0,0 +1,167 @@
+# 编写所有模块的 Vivado Verilog Testbench
+
+## Goal
+
+为 ML-KEM 硬件项目的所有 RTL 模块编写 Verilog testbench（.v 文件），可在 Vivado xsim 中仿真。遵循已有 sha3/TB/ 的 xsim testbench 约定和风格。
+
+## What I already know
+
+### 项目结构
+- 项目根目录：`/home/fallensigh/Dev/mlkem`
+- 所有 RTL 源码在 `sync_rtl/` 下按功能分目录
+- 已有 testbench 在各自的 `TB/` 子目录下
+
+### 已有 testbench 情况
+| 模块目录 | 已有 Verilator (.cpp) TB | 已有 XSIM (.v) TB | 需要新增 .v TB |
+|----------|------------------------|-------------------|---------------|
+| sha3/ | ✅ tb_sha3.cpp | ✅ tb_sha3_xsim.v, tb_sha3_xsim_simple.v, tb_keccak_core_xsim.v | ❌ 已完成 |
+| sha3_chain/ | ✅ tb_sha3_chain.cpp | ❌ | ✅ |
+| ntt/ | ✅ tb_ntt.cpp | ❌ | ✅ |
+| poly_mul/ | ✅ tb_poly_mul.cpp | ❌ | ✅ |
+| poly_arith/ | ✅ tb_poly_arith.cpp | ❌ | ✅ |
+| sample_cbd/ | ✅ tb_sample_cbd.cpp | ❌ | ✅ |
+| sample_ntt/ | ✅ tb_sample_ntt.cpp | ❌ | ✅ |
+| rng/ | ✅ tb_rng.cpp | ❌ | ✅ |
+| comp_decomp/ | ✅ tb_comp_decomp.cpp | ❌ | ✅ |
+| storage/ | ✅ tb_storage.cpp | ❌ | ✅ |
+| mod_add/ | ✅ tb_mod_add.cpp | ❌ | ✅ |
+| common/ | ❌ | ❌ | ✅ (pipeline_reg, skid_buffer) |
+
+### RTL 模块清单（按目录）
+
+**sha3/** (已有 TB)：
+- `sha3_top.v` - SHA3 顶层（G/H/J 模式）
+- `keccak_core.v` - Keccak 24 轮核心
+- `keccak_round.v` - 单轮 Keccak（组合逻辑）
+
+**sha3_chain/**：
+- `sha3_chain_top.v` - SHA3 链式调用顶层
+
+**ntt/**：
+- `ntt_sync.v` - NTT 同步顶层（wrapper）
+- `ntt_core.v` - NTT 核心（Barrett 约简 + butterfly）
+- `butterfly_unit.v` - 蝶形运算单元
+- `barrett_mul.v` - Barrett 模乘
+- `zeta_rom.v` - Zeta 预计算 ROM
+
+**poly_mul/**：
+- `poly_mul_sync.v` - 多项式乘法顶层
+- `poly_mul_zeta_rom.v` - PolyMul zeta ROM
+- `basecase_mul.v` - 基础乘法
+
+**poly_arith/**：
+- `poly_arith_sync.v` - 多项式加减（PolyAdd/PolySub）
+
+**sample_cbd/**：
+- `sample_cbd_sync.v` - CBD 采样（SHAKE-256 PRF）
+
+**sample_ntt/**：
+- `sample_ntt_sync.v` - NTT 域采样
+
+**rng/**：
+- `rng_sync.v` - Galois LFSR PRNG（256-bit）
+
+**comp_decomp/**：
+- `comp_decomp_sync.v` - 压缩/解压缩
+
+**storage/**：
+- `s_bram.v` - 单口 BRAM
+- `sd_bram.v` - 简单双口 BRAM
+
+**mod_add/**：
+- `mod_add_sync.v` - 模加法
+
+**common/**：
+- `pipeline_reg.v` - 流水线寄存器
+- `skid_buffer.v` - Skid Buffer
+
+### 现有 XSIM TB 约定（参考 sha3/TB/）
+- 命名：`tb_<module>_xsim.v`
+- 时钟：100MHz，10ns 周期（`always #5 clk = ~clk`）
+- 复位：`rst_n` 低有效 3 周期
+- 自检模式：hardcode 期望值，用 `$error` 报告 mismatch
+- 文件向量模式：`$readmemh` 从 hex 文件读测试向量
+- 输出：`$display` 日志 + `$fwrite` 结果文件
+- 超时看门狗：防止死锁
+- 编译脚本：`xsim_run.tcl` (xvlog → xelab → xsim)
+
+### 接口约定（从各模块 port 列表得出）
+- 所有模块使用 synchronous valid/ready 握手
+- `clk, rst_n` 标准端口
+- 数据宽度：12-bit 系数（ntt/poly），256-bit（rng），512-bit（sha3）
+- 部分模块有 `done_o` 信号（如 ntt_sync）
+
+## Assumptions
+
+1. 测试自检模式为主，可对比 Python 参考实现的期望输出
+2. 简单模块（common/）用 hardcoded 向量测试
+3. 复杂模块可能需要 hex 文件向量
+4. 子模块（butterfly_unit, barrett_mul, zeta_rom, basecase_mul 等）通过父模块间接测试
+
+## Decisions Made
+
+* **测试范围**：只测顶层 sync 模块，子模块通过父模块间接覆盖
+* **common/** 模块（pipeline_reg, skid_buffer）不在本次范围内
+* **测试模式**：文件向量模式（`$readmemh` 读 hex 文件），参考 `tb_sha3_xsim.v` 风格
+* **向量生成**：每个模块配套 Python `gen_vectors.py` 生成输入向量 `.hex` 文件
+* **编译脚本**：每个模块目录一个独立的 `xsim_run.tcl`
+
+## 需要编写 TB 的模块清单（10 个）
+
+| # | 模块 | 文件 | 接口要点 |
+|---|------|------|---------|
+| 1 | `sha3_chain_top` | `sync_rtl/sha3_chain/sha3_chain_top.v` | d_in[255:0], start_i → rho_out[255:0], sigma_out[255:0] |
+| 2 | `ntt_core` | `sync_rtl/ntt/ntt_core.v` | coeff_in[11:0]×256, mode → coeff_out[11:0]×256, done_o |
+| 3 | `poly_mul_sync` | `sync_rtl/poly_mul/poly_mul_sync.v` | coeff_a/b ×256 → coeff_out ×256 |
+| 4 | `poly_arith_sync` | `sync_rtl/poly_arith/poly_arith_sync.v` | coeff_a/b[11:0], mode → coeff_out[11:0] (流式) |
+| 5 | `sample_cbd_sync` | `sync_rtl/sample_cbd/sample_cbd_sync.v` | seed_i[255:0], nonce_i[7:0], eta_i → coeff_o[11:0]×256 |
+| 6 | `sample_ntt_sync` | `sync_rtl/sample_ntt/sample_ntt_sync.v` | rho_i[255:0], k/i/j_idx → coeff_o[11:0]×256 |
+| 7 | `rng_sync` | `sync_rtl/rng/rng_sync.v` | valid_i → data_o[255:0] (LFSR) |
+| 8 | `comp_decomp_sync` | `sync_rtl/comp_decomp/comp_decomp_sync.v` | coeff_in[11:0], d[4:0], mode → coeff_out[11:0] |
+| 9 | `s_bram` / `sd_bram` | `sync_rtl/storage/s_bram.v`, `sd_bram.v` | 参数化 BRAM 读写 |
+| 10 | `mod_add_sync` | `sync_rtl/mod_add/mod_add_sync.v` | a[11:0], b[11:0] → sum[11:0] |
+
+## Requirements (final)
+
+* 10 个顶层 sync 模块各产出 4 个文件：
+  - `TB/tb_<module>_xsim.v` — Verilog testbench（文件向量模式，`$readmemh` + `$fwrite`）
+  - `TB/vectors/<module>_input.hex` — 测试输入向量
+  - `TB/gen_vectors.py` — Python 脚本生成输入向量
+  - `TB/xsim_run.tcl` — Vivado 编译+仿真脚本
+* 遵循 sha3/TB/ 的编码风格和目录结构：
+  - 时钟 100MHz (`always #5 clk = ~clk`)
+  - 复位 `rst_n` 低有效 3 周期
+  - valid/ready 握手协议
+  - 超时看门狗
+  - pass/fail 统计 + `$display` 报告
+* 支持 `xvlog -sv` + `xelab` + `xsim -R` 流程
+
+## Acceptance Criteria
+
+* [ ] 10 个模块各有完整的 TB 目录：tb .v + gen_vectors.py + xsim_run.tcl
+* [ ] 每个 testbench 可通过 `xvlog -sv` 编译无 error
+* [ ] 每个 testbench 可通过 `xelab` + `xsim -R` 跑通仿真
+* [ ] 输出清晰的 pass/fail 报告
+* [ ] 包含超时看门狗防止死锁
+* [ ] Python `gen_vectors.py` 可独立运行生成 hex 向量文件
+
+## Definition of Done
+
+* 所有 10 个模块的 4 类文件已创建
+* 每个 TB 遵循 `sha3/TB/` 的代码风格
+* 向量文件格式与 `$readmemh` 兼容
+
+## Out of Scope
+
+* Verilator C++ testbench（已有）
+* 覆盖率收集
+* UVM 框架
+* 子模块独立 TB（butterfly_unit, barrett_mul, basecase_mul, ROM 等）
+* common/ 模块 TB（pipeline_reg, skid_buffer）
+
+## Technical Notes
+
+- 参考已有 TB：`sync_rtl/sha3/TB/tb_sha3_xsim.v`（文件向量模式）、`sync_rtl/sha3/TB/tb_sha3_xsim_simple.v`（简单自检模式）
+- 编译脚本参考：`sync_rtl/sha3/TB/xsim_run.tcl`
+- RTL spec：`.trellis/spec/rtl/verilator-conventions.md`（Verilator 相关，部分适用）
+- 时钟定义：`sync_rtl/common/defines.vh` 中的 `CLK_PERIOD 10.0`