update system design report

doc/reports/system/modules/07_mlkem_axi_frontend.md

@@ -0,0 +1,74 @@
+# ML-KEM AXI 前端与跨时钟域技术说明
+
+## 1. 共享从端结构
+
+`fft_mlkem_axi_slave` 将 Crossbar Slave 6 分成 FFT 和 ML-KEM 两个内部目标。写地址或读
+地址的 bits 15:12 小于等于 3 时选择 ML-KEM；FFT 使用 0x8000--0xc000 窗口。ML-KEM
+以外且未被 FFT 定义的地址仍会路由到 FFT 前端，但返回零或忽略写入，因此软件只应使用
+文档化区间。
+
+AXI 写地址和写数据通道彼此独立。共享前端在 AW 握手时锁存 `write_sel`，直到对应 B
+响应完成才释放；读路径在 AR 握手时锁存 `read_sel`，直到带 RLAST 的最后一个 R beat
+完成才释放。响应选择不使用实时地址，避免 burst 期间地址变化导致响应串到另一个内部
+从端。
+
+FFT 控制器直接工作在 `sys_clk`。ML-KEM 的完整 AXI 五通道通过 `Axi_CDC` 跨入
+`mlkem_clk`，之后由 `mlkem_axi_slave` 和 `mlkem_top` 在同一计算时钟域处理。ML-KEM
+中断从计算域返回系统域时经过两级同步寄存器。
+
+XDC 将 SYS 与 ML-KEM 声明为异步时钟组，因此跨域有效性由 `Axi_CDC` 的双时钟 FIFO
+保证，而不是由 PLL 同源关系或普通时序路径保证。具体约束和复位关系见
+[时钟域、复位与跨时钟域设计说明](00_clock_domains.md)。
+
+## 2. ML-KEM 寄存器接口
+
+ML-KEM 物理基址为 `0x1f40_0000`，CPU 未缓存映射为 `0xbf40_0000`。
+
+| 偏移 | 名称 | 说明 |
+|---|---|---|
+| `0x000` | CTRL | bit 0 启动，bit 1 软复位 |
+| `0x004` | STATUS | bit 0 busy，bit 1 done，bit 2 preload busy；done 为 W1C |
+| `0x008` | CONFIG | bits 2:0 为 K，bits 5:4 为操作码 |
+| `0x010--0x02c` | D | 32 字节 KeyGen 随机种子 |
+| `0x030--0x04c` | Z | 32 字节隐式拒绝种子 |
+| `0x050--0x06c` | MSG | 32 字节 Encaps 消息 |
+| `0x070--0x08c` | SS | 32 字节共享密钥，只读 |
+| `0x100/104/108` | PRE_SEL/ADR/DAT | 逐字节预装载接口 |
+| `0x10c/110/114` | RDB_SEL/ADR/DAT | 逐字节读回接口 |
+| `0x1000` | EK window | 公钥批量输入或输出窗口 |
+| `0x2000` | DK window | 私钥批量输入或输出窗口 |
+| `0x3000` | CT window | 密文批量输入或输出窗口 |
+
+CONFIG 的操作码 0、1、2 分别表示 KeyGen、Encaps、Decaps。软件必须在启动前完成参数与
+输入装载，并在 busy 期间保持配置不变。done 保持到软件 W1C，便于轮询程序不丢失短脉冲。
+
+## 3. 字节端口与批量窗口
+
+传统 PRE 接口通过 PRE_SEL 选择 ek、dk 或 c，通过 PRE_ADR 设置字节地址，向 PRE_DAT
+写入低 8 位并自动递增地址。读回接口以同样方式选择 ek、完整 dk 或 ct。该路径便于调试，
+但每个字节至少需要一次 AXI 寄存器事务，传输大密钥时开销较高。
+
+三个批量窗口把 AXI 32 位 beat 分解为最多四个有效字节。写状态机依据 WSTRB 跳过无效
+lane，将字节地址、选择和数据送入核心 BRAM 写口，并等待内部确认后继续下一个 lane。
+读状态机按字节地址读取内部 BRAM，补偿同步读延迟后组装 32 位 RDATA。窗口支持 INCR
+burst，使通用 DMA 能以少量控制事务搬运完整公钥、私钥和密文。
+
+批量窗口不改变密码核心的算法执行时间，但显著减少 CPU 逐字节访问开销。性能报告应把
+CPU 寄存器路径和 DMA 窗口路径分别列出，不能把两者差值解释为核心计算加速。
+
+## 4. 事件控制与复位
+
+CTRL start、软复位和 done clear 在 `mlkem_axi_slave` 中均转换为 toggle 事件，再通过
+边沿检测产生单拍控制。软复位事件经计数器展宽，形成核心局部复位。预装载写入使用
+request/ack toggle，使 AXI 写 beat 只有在目标字节被核心侧接收后才完成。
+
+外层 `Axi_CDC` 已承担 SYS--ML-KEM 的 AXI 通道跨域；前端内部的 toggle 机制主要用于
+把寄存器写动作转换为不会重复触发的单拍事件，并串行化字节预装载。系统复位有效期间，
+所有 AXI valid、start 和预装载事件必须保持无效。
+
+## 5. 协议验证重点
+
+共享前端需要覆盖 AW 与 W 不同拍到达、B/R 反压、ML-KEM 与 FFT 交替访问、长 burst
+末拍、WSTRB 空洞以及读写并发。ML-KEM 窗口还需验证 800--3168 字节的非统一长度、最后
+一个不满字、BRAM 读延迟和软复位中止。当前板级 CPU 与 DMA 双路径证明了常用顺序访问，
+但不等价于覆盖所有并发和异常协议组合。