# ML-KEM 顶层集成模块

## Goal

实现 `mlkem_top` 顶层模块，将现有 10 个子模块集成为完整的 ML-KEM 系统，支持 KeyGen、Encaps、Decaps 三个操作。对外使用 valid/ready 流式接口。

## Decisions Made

* **操作范围**：KeyGen + Encaps + Decaps 全部实现
* **接口风格**：valid/ready 流式接口（类似 AXI-Stream）
* **k 值支持**：全支持 k=2,3,4，通过 `parameter K=4` 参数化，通过 `i_k[2:0]` 输入选择
* **Keccak 策略**：共享 1 个 `keccak_core` 实例，各消费者通过仲裁器复用。需重构 `sha3_chain_top`/`sample_cbd_sync`/`sample_ntt_sync` 接受外部 Keccak 接口

## What I already know

### 现有模块接口汇总

| 模块 | 协议 | 关键信号 | 数据宽度 | 延迟 |
|------|------|---------|:---:|------|
| `rng_sync` | v/r | `valid_i`→`data_o[255]` | 256 | 1 cycle/word |
| `sha3_chain_top` | start/done | `start_i`→`done_o`→`rho_out/sigma_out[255]` | 256→512 | ~24 cycles |
| `sha3_top` | v/r | `mode[1:0]`, `data_i[512]`→`hash_o[512]` | 512→512 | ~24 cycles |
| `sample_cbd_sync` | v/r+last | `seed_i[255],nonce_i[8],eta_i[2]`→`coeff_o[12]×256` | — | ~300 cycles |
| `sample_ntt_sync` | v/r+last | `rho_i[255],k_i,i_idx,j_idx`→`coeff_o[12]×256` | — | ~4000 cycles |
| `ntt_core` | v/r+done | `coeff_in[12]×256,mode`→`coeff_out[12]×256` | 12→12 | ~200 cycles |
| `poly_arith_sync` | v/r | `coeff_a/b[12],mode`→`coeff_out[12]` | 12→12 | 1 cycle/coeff |
| `poly_mul_sync` | v/r | `coeff_a/b[12]×256`→`coeff_out[12]×256` | 12→12 | ~300 cycles |
| `mod_add_sync` | v/r | `a,b[12]`→`sum[12]` | 12→12 | 1 cycle |
| `comp_decomp_sync` | v/r | `coeff_in[12],d[5],mode`→`coeff_out[12]` | 12→12 | 1 cycle/coeff |
| `s_bram` | raw | `rd_en,wr_en,addr,data` | 48 | 1 cycle |
| `sd_bram` | raw | `wr_en,addr,data` | 48 | 1 cycle |

### ML-KEM 算法数据流

**KeyGen**:
1. `d = RNG(256)` → `sha3_chain(d)` → ρ, σ
2. for i in 0..k-1: `sample_ntt(ρ, k, i, 0)` → `ntt_core(NTT)` → Â[i]
3. for i in 0..k-1: `sample_cbd(σ, N=i)` → `ntt_core(NTT)` → ŝ[i]  (秘密)
4. ŝ̂ = ŝ  (already in NTT domain)
5. for i in 0..k-1: `poly_add(ê[i], ŝ̂[i])` → 再 `poly_mul(ê[i], Â[i])`
6. `t̂ = ê + ŝ̂`, then `comp_decomp(t̂)` → public key pk
7. `comp_decomp(ŝ̂)` → secret key sk

**Encaps**:
1. `m = RNG(256)`
2. `m = SHA3-256(m)` → hash
3. `(K̄, r) = G(m || H(pk))` → SHA3-512
4. for i: `sample_ntt(ρ, k, i, 0)` → `ntt_core(NTT)` → Â[i]
5. for i: `sample_cbd(r, N=i)` → `ntt_core(NTT)` → ŷ[i]
6. `u = NTT^{-1}(Â^T · ŷ) + sample_cbd(r, N=k+i)`
7. `v = NTT^{-1}(t̂^T · ŷ) + sample_cbd(r, N=2k) + decompress(m)`
8. `c1 = compress(u)`, `c2 = compress(v)`
9. `K = KDF(K̄ || SHA3-256(c))`

**Decaps**:
1. `u = decompress(c1)`, `v = decompress(c2)`
2. `u` → `ntt_core(NTT)` → û
3. `v - NTT^{-1}(ŝ̂^T · û)` → `comp_decomp(decompress)` → m'
4. `(K̄', r') = G(m' || H(pk))`
5. Re-encrypt with r' to get c'
6. If c == c', K = KDF(K̄' || SHA3-256(c)), else K = KDF(z || SHA3-256(c))

### 关键架构问题

1. **多项式存储**：中间多项式（Â[0..k-1], ŝ[0..k-1], ŷ[0..k-1] 等）需要 BRAM 存储
2. **Keccak 共享**：sha3_chain_top 和 sample_ntt/sample_cbd 内部都有 sha3_top 实例，需决定共享还是各自独立
3. **RNG 重用**：KeyGen/Encaps 中多次调用 RNG，需确定是串行复用还是并行

## Open Questions

（全部已解决）

## Requirements (final)

* 三合一顶层模块 `mlkem_top`，通过 mode[1:0] 选择操作
* 对外 valid/ready 接口
* 多项式中间结果存入 BRAM
* 单时钟域 100MHz
* RNG 复用（串行调用）

## Acceptance Criteria (evolving)

* [ ] KeyGen 产生正确的 (pk, sk) 输出
* [ ] Encaps 产生正确的 (c, K) 输出
* [ ] Decaps 产生正确的 K 输出
* [ ] 验证 Encaps(Decaps()) consistency
* [ ] Vivado XSIM 可编译仿真

## Out of Scope

* AXI4-Full 总线桥接
* DMA 控制器
* 性能优化（多模块并行）

## Technical Notes

- 参考 FIPS 203 Section 7 (Algorithm 15-17)
- 现有模块接口见上方表格
- BRAM 参数：建议 W=12, D=256 (或 W=48 打包 4 系数)
