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

编写所有模块的 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