update system design report

doc/reports/system/modules/00_clock_domains.md

@@ -0,0 +1,104 @@
+# 时钟域、复位与跨时钟域设计说明
+
+## 1. 时钟拓扑
+
+板级输入 `clk` 的周期为 20 ns，即 50 MHz。硬件路径由 `clk_pll` 产生 CPU、系统总线和
+ML-KEM 三个时钟。当前实现报告记录的周期和频率如下。
+
+| 时钟 | 周期 | 频率 | 主要负载 |
+|---|---:|---:|---|
+| `cpu_clk` | 30 ns | 33.333 MHz | OpenLA500 CPU、CPU 侧缓存和 AXI 主接口 |
+| `sys_clk` | 20 ns | 50 MHz | Crossbar、SRAM、UART、DMA、FFT、matmul 和系统寄存器 |
+| `mlkem_clk` | 13 ns | 76.923 MHz | ML-KEM AXI 从端、算法总控、Keccak、NTT 和多项式算子 |
+
+三个时钟均由同一个 PLL 产生，但 `soc.xdc` 使用 `set_clock_groups -asynchronous` 将三者
+划入独立异步组。工程含义是任何跨域逻辑都不能依赖固定相位关系，静态时序分析也不会把
+普通组合路径当作同步时序路径检查。跨域正确性必须由双时钟 FIFO、同步器、握手协议和
+专门的 CDC 验证保证。
+
+## 2. 模块归属
+
+CPU 核及其 AXI 主端属于 CPU 域。CPU 发出的 AW、W、AR 通道在进入 Crossbar 前跨到
+SYS 域，B 和 R 响应反向跨回 CPU 域。Crossbar 的两个主端、八个从端、外部 SRAM、
+DMA、FFT、矩阵序列器和矩阵乘法器全部属于 SYS 域，这些模块之间是同步连接。
+
+FFT/ML-KEM 共享从端的地址选择和 FFT 分支属于 SYS 域。ML-KEM 分支的完整 AXI 接口
+跨到 ML-KEM 域后，`mlkem_axi_slave`、`mlkem_top` 及其所有叶子算子均在
+`mlkem_clk` 下工作。密码核心内部没有第二个计算时钟。
+
+## 3. CPU--SYS AXI 跨域
+
+`u_Axi_CDC` 为 AXI 的 AW、W、B、AR 和 R 五个通道分别设置双时钟 FIFO。AW、W 和 AR
+在 CPU 域写入 FIFO、在 SYS 域读出；B 和 R 在 SYS 域写入、在 CPU 域读出。FIFO 将
+valid/ready 反压限制在各自时钟域，并连同地址、ID、burst 属性、数据、WSTRB、响应和
+RLAST/WLAST 一起跨域。
+
+该结构不对多位 AXI payload 逐位使用两级同步器，而是在写时钟域稳定写入存储，使用同步
+后的读写指针传递所有权，再在读时钟域读取。这是多位总线跨域的必要条件。AW 和 W 仍为
+独立通道，下游从端必须按 AXI 规则处理两者不同拍到达，不能假设跨域 FIFO 会自动配对。
+
+CPU--SYS 路径的延迟包含 FIFO 入队、指针同步和出队，不应通过 CPU 与 SYS 周期的简单
+比例估算。端到端软件周期已经包含该延迟。
+
+## 4. SYS--ML-KEM AXI 跨域
+
+`fft_mlkem_axi_slave` 在 SYS 域锁存目标选择。FFT 请求保持在 SYS 域；ML-KEM 请求进入
+第二个 `Axi_CDC`，再由 ML-KEM 域的 `mlkem_axi_slave` 处理。该跨域同样覆盖 AXI 五个
+通道，而不是只同步 start/done。因此配置寄存器、批量密钥窗口和读回数据都遵循统一的
+AXI CDC 语义。
+
+ML-KEM 完成中断在 `mlkem_clk` 域产生，先通过两级 `mlkem_intr_sync` 同步到 SYS 域。
+由于完成状态保持到软件 W1C，接收端观察的是电平而不是单周期脉冲，避免因频率差异丢失
+事件。软件读取 STATUS 获得最终完成语义，中断只负责通知。
+
+## 5. 中断到 CPU 的边界
+
+当前 `soc_top` 将 `confreg_int`、DMA done、matmul done 和 ML-KEM done 组合后直接连接
+到 CPU 的 `intrpt` 输入。其中 DMA 和 matmul 状态产生于 SYS 域；ML-KEM 状态虽已同步到
+SYS 域，仍需跨入 CPU 域。它们均为保持到清除的电平信号，因此相较单拍脉冲更不易漏采，
+但当前顶层没有为项目新增的三路中断显式实例化 CPU 域两级同步器。
+
+严谨的前端实现应在 `cpu_clk` 域对每路异步电平增加两级 `ASYNC_REG` 同步，或把中断状态
+放入已有的 CPU--SYS 握手寄存器。同步前的电平必须保持不少于两个 CPU 周期，清除语义也
+应以 CPU 可观察到状态后再执行。该项属于时钟域实现风险，不能仅以板级轮询程序通过替代
+结构验证。
+
+## 6. 复位生成与释放顺序
+
+`rst_sync` 包含两个串联寄存器。输入复位有效时通过异步低电平立即把两级清零；输入复位
+撤销后，逻辑 1 在本时钟域连续两个上升沿移入，形成异步断言、同步撤销的低有效复位。
+
+硬件路径中，外部 reset 先复位 PLL。PLL `locked` 进入 SYS 域复位同步器，产生
+`sys_resetn`；随后 `sys_resetn` 分别作为 CPU 和 ML-KEM 复位同步器输入，产生
+`cpu_resetn` 和 `mlkem_resetn`。因此 SYS 域先释放，CPU 和 ML-KEM 域至少再等待各自两个
+有效时钟边沿。CDC 两侧在各自复位释放前不得发送 valid，也不得保留上一轮 FIFO 所有权。
+
+行为仿真 `SIMULATION=1` 不实例化 PLL。testbench 的 50 MHz 时钟直接作为 `sys_clk`，
+内部 30 ns 周期时钟作为 `cpu_clk`，`mlkem_clk` 暂等于 `sys_clk`。此模式可验证复位顺序
+和零事务，但不能验证真实 13 ns ML-KEM 时钟的相位、PLL 锁定过程或异步 FIFO 的全部
+频率组合。
+
+当前 20 us XSIM VCD 中，外部 reset 在 2.000 us 撤销，`sys_resetn`、`mlkem_resetn` 和
+`cpu_resetn` 分别约在 2.030、2.070 和 2.085 us 释放。第一个 CPU ARVALID 约在
+2.205 us 出现，复位释放前 UART、AXI、DMA 请求和加速器 start 均没有高电平。
+
+## 7. 跨域信号设计规则
+
+单比特静态状态可以采用两级同步器，但源端必须保持足够长时间。单周期脉冲需要 toggle、
+脉冲展宽或 request/ack 握手，不能直接送入另一个时钟域。多位配置和数据必须通过异步
+FIFO、握手后稳定保持的影子寄存器或双口存储传递，禁止逐位同步后重新组合。
+
+复位也是跨域信号。每个时钟域必须使用本地同步释放的 resetn，不能用另一个域同步器的
+输出直接复位本域大量寄存器。所有 CDC 结构的两侧复位关系必须保证复位期间不会把残留
+valid 解释为新事务。
+
+## 8. 时序与验证方法
+
+单域时序分别在 `cpu_clk`、`sys_clk` 和 `mlkem_clk` 路径组内检查 setup 和 hold。由于
+时钟组被声明为异步，跨域路径不应以普通 WNS 作为正确性依据。验证应包括 CDC 结构审查、
+同步寄存器属性检查、异步 FIFO 满空边界、随机相位/频率仿真、复位任意时刻进入，以及
+valid/ready 双向反压。
+
+板级功能测试证明常用任务能够跨域完成，但不能观察亚稳态。报告中的时钟域结论应分别
+引用时钟报告、单域时序报告、复位波形和 CDC 结构说明，避免用单一板级 PASS 替代这些
+不同层次的证据。