update system design report

doc/reports/system/modules/08_mlkem_hash_sampling.md

@@ -0,0 +1,62 @@
+# ML-KEM Keccak、SHA3 与采样模块技术说明
+
+## 1. Keccak-f[1600] 置换核
+
+`keccak_core` 保存 1600 位状态，并调用组合 `keccak_round` 每周期执行一轮
+Keccak-f[1600]。轮函数包含 theta、rho、pi、chi 和 iota 五个步骤，轮常数由 5 位轮计数
+选择。默认执行 24 轮，输入在 `valid_i && ready_o` 时装载，最后一轮结果通过
+`valid_o/ready_i` 交付；接收端反压时保持最终状态。
+
+该结构只实例化一份 1600 位轮函数，单次置换约需 24 个计算周期，面积主要来自宽 XOR、
+移位布线和 chi 非线性逻辑。它不是 24 轮完全展开的单周期实现，也不是每周期接收一个
+新状态的深流水实现。
+
+本文件中的 Keccak、SHA3/SHAKE、SampleNTT 和 CBD 均位于 `mlkem_clk` 域。共享接口是
+同一时钟域内的 valid/ready 复用，不是 CDC。SYS--ML-KEM 跨域终止于外层 AXI 前端。
+
+## 2. SHA3/SHAKE 协议层
+
+`sha3_top_shared` 在置换核外实现吸收、填充、多块状态累积和输出提取。单块模式支持
+KeyGen 使用的 G、SHA3-256 H、SHAKE-256 J，以及对完整 64 字节消息执行的 SHA3-512 G。
+模块依据模式选择 576 位或 1088 位 rate，并加入 SHA3 或 SHAKE 域分隔后执行 pad10*1。
+
+多块模式面向长度随安全等级变化的公钥哈希。调用方预先构造 1088 位 rate block，并用
+`mb_last_i` 标记最终块。模块将新块异或到累计 sponge 状态，调用共享 Keccak，最后从
+低 256 位提取摘要。多块状态在一次消息结束前保持，不会在块间重新初始化。
+
+ML-KEM 顶层以状态机选择当前 Keccak 消费者。SHA3、SampleNTT 和 CBD 在算法调度上互斥，
+因此可以共享一个置换核；若未来引入跨状态并行，必须增加显式仲裁和每个消费者独立的
+sponge 上下文，不能继续依赖状态互斥假设。
+
+## 3. SampleNTT 拒绝采样
+
+`sample_ntt_sync_shared` 实现 FIPS 203 SampleNTT。模块吸收 32 字节 rho 以及行列索引
+`j,i`，形成 34 字节 SHAKE-128 输入。挤出字节流按每 3 字节拆成两个 12 位候选值，只有
+候选值小于 q=3329 时才输出。模块持续采样直到产生 256 个有效系数。
+
+输出使用 `coeff_valid_o/coeff_ready_i` 握手，反压时保持当前系数和索引。拒绝采样的运行
+周期依赖候选值分布，因此系统 FSM 依据有效系数计数结束，而不是使用固定延迟。对固定
+rho 和索引，输出必须与软件 SampleNTT 逐系数一致。
+
+## 4. 中心二项分布采样
+
+`sample_cbd_sync_shared` 使用 SHAKE-256 PRF 生成伪随机字节，再实现 CBD_eta。eta=2 时，
+每个系数消耗 4 bit，计算两组 2 bit 的汉明重量差；eta=3 时，每个系数消耗 6 bit，计算
+两组 3 bit 的汉明重量差。ML-KEM-512 的 eta1 为 3，其余等级的 eta1 为 2，eta2 始终为 2。
+
+CBD 输出转换到模 q 表示后，以 valid/ready 逐系数写入系数 Bank。当前优化版本对 CBD
+输出到 Bank 写入路径增加寄存，以缩短组合路径；地址和有效信号必须与该流水级同步延迟。
+
+## 5. 共享接口约束
+
+三个消费者向共享 Keccak 提供状态、valid 和 ready。选择信号由 ML-KEM 主状态直接推导，
+未选中的消费者不能认为广播输出属于自己。消费者内部必须只在活动上下文采样
+`kc_valid_o`。复位需要同时清除 Keccak busy、各 sponge 状态、候选字节缓存和输出计数，
+否则下一次请求可能继承前一消息状态。
+
+## 6. 验证方法
+
+Keccak 应使用标准空消息和多块测试向量逐 bit 比较。SHA3/SHAKE 层应覆盖 rate 边界前后
+的消息长度、域分隔和多块最后一块填充。SampleNTT 应比较全部 256 个系数并统计拒绝
+候选数；CBD 应覆盖 eta=2/3、输出反压和连续请求。顶层 KAT 通过能够发现大部分功能错误，
+但叶子级握手、边界填充和共享仲裁仍需要独立测试平台验证。