diff --git a/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/check.jsonl b/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/check.jsonl new file mode 100644 index 0000000..3ae1cec --- /dev/null +++ b/.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"} + diff --git a/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/implement.jsonl b/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/implement.jsonl new file mode 100644 index 0000000..d2cf8d8 --- /dev/null +++ b/.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"} + diff --git a/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/prd.md b/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/prd.md new file mode 100644 index 0000000..849f353 --- /dev/null +++ b/.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 系数) diff --git a/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/task.json b/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/task.json new file mode 100644 index 0000000..64593de --- /dev/null +++ b/.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": {} +} \ No newline at end of file