# 时钟域、复位与跨时钟域设计说明

## 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 替代这些
不同层次的证据。