chore(task): archive 06-26-mlkem-top-integration

.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/check.jsonl

@@ -0,0 +1,2 @@
+{"file": ".trellis/spec/rtl/xsim-tb-conventions.md", "reason": "XSIM TB quality checks: TCL format, testbench structure, pass/fail"}
+

.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/implement.jsonl

@@ -0,0 +1,3 @@
+{"file": ".trellis/spec/rtl/verilator-conventions.md", "reason": "RTL conventions: clock 10ns, valid/ready timing, pipeline_reg behavior"}
+{"file": ".trellis/spec/rtl/xsim-tb-conventions.md", "reason": "XSIM TB conventions: TCL format, part-select, timing"}
+

.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/prd.md

@@ -0,0 +1,99 @@
+# 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 系数)

.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "mlkem-top-integration",
+  "name": "mlkem-top-integration",
+  "title": "实现ML-KEM顶层集成模块(KeyGen/Encaps/Decaps)",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "FallenSigh",
+  "assignee": "FallenSigh",
+  "createdAt": "2026-06-26",
+  "completedAt": "2026-06-26",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}