update system design report

doc/reports/system/modules/01_soc_integration.md

@@ -0,0 +1,77 @@
+# SoC 集成与时钟复位技术说明
+
+## 1. 模块定位
+
+`rtl/soc_top.v` 是项目的系统集成顶层。该文件不重新实现 CPU、UART 或 SRAM 控制器，
+而是将 OpenLA500 处理器、存储器、外设、DMA 和三个计算加速器组织为统一的 AXI 系统。
+项目相关的集成工作包括扩展 Crossbar 从端口、增加 DMA 主端口、划分加速器地址窗口、
+建立 CPU--SYS 和 SYS--ML-KEM 时钟边界，以及将完成状态接入中断系统。
+
+系统采用 CPU 控制、DMA 搬运、加速器计算的职责划分。CPU 通过寄存器完成参数配置和
+任务启动；DMA 作为第二个 AXI 主机访问存储器与外设；FFT、ML-KEM 和矩阵乘法器作为
+被控计算单元。矩阵批处理序列器位于 DMA 控制窗口内，可脱离 CPU 的逐组调度执行长任务。
+
+## 2. 地址空间与互连
+
+系统 Crossbar 具有两个主端和八个从端。主端 0 接收经 `Axi_CDC` 转换后的 CPU AXI
+事务，主端 1 接收 DMA 发起的 AXI 事务。与本项目直接相关的从端如下。
+
+| 物理地址 | 模块 | 作用 |
+|---|---|---|
+| `0x1f30_0000` | DMA 控制窗口 | 通道寄存器位于 `0x000--0x1ff`，矩阵序列器位于 `0x200--0x21f` |
+| `0x1f40_0000` | FFT/ML-KEM 共享窗口 | ML-KEM 使用低 `0x0000--0x3fff`，FFT 使用 `0x8000--0xcfff` |
+| `0x1f50_0000` | 矩阵乘法器 | 控制状态、CRC32、双 Bank 输入和结果窗口 |
+
+CPU 软件使用高位映射访问未缓存地址，例如物理地址 `0x1f40_0000` 对应
+`0xbf40_0000`。DMA 始终使用物理地址，软件在提交描述符前需要去除 CPU 虚拟地址的
+高位映射。该约定避免 DMA 错把虚拟地址送入 Crossbar。
+
+DMA 控制从端原始接口为 AXI4，经 `axi_axil_adapter` 转换为 AXI-Lite。地址偏移
+`0x200` 的访问在顶层被路由到 `cdma_matmul_bridge`，其余访问进入通用 DMA 通道寄存器。
+写地址的目标选择在 AW 握手后保持到 B 响应返回，读地址选择保持到 R 响应返回，从而
+避免响应阶段再次依赖变化中的地址信号。
+
+## 3. 时钟结构
+
+硬件实现使用 50 MHz 外部时钟驱动 PLL，产生三个逻辑时钟域。当前实现报告中的目标
+频率为 CPU 33.333 MHz、系统总线 50 MHz 和 ML-KEM 76.923 MHz。CPU 核及其 AXI 侧
+逻辑工作在 `cpu_clk`；Crossbar、DMA、FFT、矩阵乘法器和外设工作在 `sys_clk`；
+ML-KEM 核心工作在 `mlkem_clk`。
+
+CPU AXI 五个通道通过 `Axi_CDC` 跨入系统时钟域。ML-KEM 的配置、批量数据窗口和完成
+响应通过第二个完整 AXI CDC 跨越 SYS--ML-KEM 边界；`mlkem_axi_slave` 内部的
+toggle/ack 负责把寄存器动作转换为单次事件。FFT 与矩阵乘法器均位于系统时钟域，不需要
+额外的计算域 CDC。
+
+完整的时钟归属、异步时钟组约束、AXI 双时钟 FIFO 和中断边界见
+[时钟域、复位与跨时钟域设计说明](00_clock_domains.md)。本文件只说明顶层集成关系。
+
+行为仿真中 `SIMULATION=1`，PLL 被可控仿真时钟替代：`sys_clk` 使用 50 MHz testbench
+时钟，`cpu_clk` 使用约 33.333 MHz 时钟，`mlkem_clk` 暂与 `sys_clk` 相同。该模式用于
+功能验证，不用于推导硬件 PLL 的锁定时间或跨域相位关系。
+
+## 4. 复位结构
+
+硬件路径中，PLL 的 `locked` 信号首先送入系统域 `rst_sync`。`sys_resetn` 释放后，CPU
+域和 ML-KEM 域的复位同步器再分别产生 `cpu_resetn` 和 `mlkem_resetn`。各同步器采用
+异步断言、同步撤销原则，使复位可立即进入有效状态，而退出复位只能发生在本时钟域的
+有效边沿。
+
+复位约束不仅要求状态机回到初始状态，还要求复位释放前不产生外部可见事务。当前短时
+XSIM 证据记录了 UART 写使能、CPU AXI AW/W/AR valid、DMA 读写请求、矩阵启动和
+ML-KEM 启动。VCD 中 `sys_resetn`、`mlkem_resetn` 和 `cpu_resetn` 分别约在 2.030 us、
+2.070 us 和 2.085 us 释放；第一个 CPU 读请求出现在约 2.205 us，晚于 CPU 复位释放。
+
+## 5. 中断与完成状态
+
+DMA 的通道完成标志归并为 `cdma_dma_finish`，矩阵序列器另有 `cdma_matmul_seq_irq`。
+矩阵乘法器输出电平型 `matmul_intr`，ML-KEM 前端输出 `mlkem_intr`，FFT 完成状态接入
+原有 `confreg` 中断路径。性能测试程序主要采用轮询，以减少短任务的中断现场开销；
+中断信号仍保留给功能软件和后续异步调度使用。
+
+## 6. 验证重点
+
+顶层验证应覆盖地址译码互斥性、CPU 与 DMA 并发访问、AW/W 分离到达、复位前零事务、
+各域复位释放顺序以及完成状态的置位和清除。板级功能通过 FFT、ML-KEM 和矩阵乘法
+程序分别验证；时钟频率、时序裕量和资源使用以实现后报告为准。行为仿真不能替代 PLL
+实现检查，单个应用通过也不能证明所有地址空洞和并发组合均已覆盖。