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