fallensigh/ciciec2026
Archived
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update system design report

Browse Source
This commit is contained in:
FallenSigh
2026-07-15 11:09:57 +08:00
parent c4d36515cc
commit fe20f28a72
46 changed files with 35507 additions and 1285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
doc/reports/system/modules/00_clock_domains.md Normal file
View File

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

77
doc/reports/system/modules/01_soc_integration.md Normal file
View File

@@ -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
实现检查，单个应用通过也不能证明所有地址空洞和并发组合均已覆盖。

83
doc/reports/system/modules/02_dma_subsystem.md Normal file
View File

@@ -0,0 +1,83 @@
# 通用 DMA 子系统技术说明
## 1. 功能与组成
DMA 子系统位于 `rtl/ip/cdma/`，对软件提供四个逻辑通道，对系统提供一个 32 位 AXI4
主端，并对矩阵乘法器提供 32 位本地 endpoint。当前顶层实例参数为 `PORTS=4`、
`DATA_WIDTH=32`、`FIFO_DEPTH=64`。源码中的“8 通道”实例名和注释是历史名称，实际
综合配置应以参数值四通道为准。
子系统由三部分组成。`snix_axil_cdma_mux` 实现通道寄存器、轮询仲裁、传输模式选择和
AXI 主端复用；`snix_axi_mm2mm` 实现普通内存到内存的 burst 搬运；本地 endpoint 状态机
实现内存与矩阵双 Bank 之间的数据传递。同步 FIFO 和 AXIS FIFO 用于隔离 AXI 读、写
通道的反压。
## 2. 软件接口
每个通道占用 `0x40` 字节，通道 `n` 的偏移基址为 `n*0x40`。
| 偏移 | 名称 | 说明 |
|---|---|---|
| `0x00` | SRC_ADDR | 源物理地址 |
| `0x04` | DST_ADDR | 目的物理地址 |
| `0x08` | LENGTH | 传输字节数 |
| `0x0c` | TAG | 软件标记，硬件不解释 |
| `0x10` | CTRL | bit 0 启动，bits 5:3 为 AxSIZE，bits 13:6 为 AxLEN |
| `0x14` | STATUS | bit 0 busy，bit 1 done；done 采用 W1C |
| `0x18` | MODE | 0 为 mem2mem，1 为 mem2ep，2 为 ep2mem |
| `0x1c` | EP_CFG | bits 3:0 Bank，bits 15:8 word offset，bits 19:16 endpoint ID |
通道处于 busy 时，源地址、目的地址、长度、模式和 endpoint 配置不再接受修改。新启动
请求会清除旧 done，硬件完成与软件 W1C 同周期发生时以硬件置位优先，避免丢失完成事件。
所有地址均为物理地址，长度以字节计。
## 3. 通道仲裁
`snix_axil_cdma_mux` 为四个通道维护独立的请求位和完成位，但共享一个实际搬运引擎。
仲裁器从 `rr_ptr` 开始循环检查待处理通道，选中后锁存 `cur_ch`，在 START 状态发出单拍
`engine_start`，在 RUN 状态等待对应引擎完成。完成后设置该通道 done，并将轮询指针
移动到下一通道。该结构保证长期存在的请求不会固定占用最低编号优先级。
共享引擎意味着四个通道可以独立排队，但不能同时占用 AXI 主端。多通道的主要收益是
减少软件串行配置依赖并提供公平排队，而不是形成四路并行 AXI 数据流。
## 4. 内存到内存路径
`snix_axi_mm2mm` 的控制状态依次为 IDLE、PREP1、PREP2、AR、READ、AW、WRITE 和
WAIT_BRESP。引擎先计算本次 burst 的实际长度，发出 INCR 读请求，将 R 通道数据写入
FIFO，再发出对应写请求并从 FIFO 驱动 W 通道。最后一个写响应返回后，若仍有剩余字节，
引擎更新源地址和目的地址并处理下一 burst。
读数据只在 READ 状态接收，写数据只在 WRITE 状态发送。该门控防止非活动状态下的
AXI beat 被误计数。末尾不足一个数据宽度时由 `WSTRB` 屏蔽无效字节。当前 SoC 数据宽度
为 32 bit，常用配置为 AxSIZE=2，即每 beat 4 字节。
## 5. 本地 endpoint 路径
mem2ep 模式从 AXI 地址读取数据，并逐字送往 `ep_wr_valid/ready`；ep2mem 模式通过
`ep_rd_valid/ready` 读取本地结果，再发出 AXI 写事务。endpoint 接口附带 endpoint ID、
Bank 号和字地址，因此无需把矩阵双 Bank 映射回 Crossbar，也避免每个 32 位字再次经过
从端地址译码。
矩阵批处理序列器还可通过 `ext_rd_req_*` 和 `ext_wr_req_*` 直接提交一次外部请求。这组
请求优先占用 AXI 主端，并在通用通道引擎空闲时接收。读请求完成后产生单拍
`ext_rd_req_done`，写请求在 B 响应返回后产生 `ext_wr_req_done`。该接口用于流水调度，
减少序列器重复写入通道 CSR 的延迟。
## 6. 复位与反压
当前集成的 DMA 通道寄存器、仲裁器、mem2mem 引擎、endpoint 引擎和 AXI 主端均工作在
`sys_clk`，内部不存在活动的异步时钟边界。仓库保留的 `snix_async_fifo` 未被当前
`soc_top` 层次实例化；实际数据 FIFO 为同一 SYS 域内的同步 FIFO。
所有控制状态、通道请求和完成位在 `rst_n=0` 时清零。AXI 与 endpoint 均遵循
valid/ready 规则：发送端在握手前保持数据和控制字段，接收端可通过 ready 插入反压。
目前 endpoint 只按 32 位数据宽度实现，字节数不是 4 的整数倍时不应使用该路径。
## 7. 验证方法与限制
DMA 验证至少应覆盖不同 burst 长度、末尾非满 beat、四通道公平性、R/W 反压、
mem2mem、mem2ep、ep2mem 和 W1C 竞态。当前板级 FFT DMA 和 ML-KEM DMA 测试证明了
普通外设窗口搬运路径，矩阵评测证明了外部请求与本地 endpoint 路径。当前实现未设置
总线超时和错误恢复状态，若 AXI 从端永久不响应，通道会保持 busy；因此系统集成时必须
保证目标地址有效，或在后续版本增加 watchdog 和错误码。

70
doc/reports/system/modules/03_matmul_batch_sequencer.md Normal file
View File

@@ -0,0 +1,70 @@
# 矩阵批处理序列器技术说明
## 1. 模块职责
`cdma_matmul_bridge` 将一次软件启动扩展为多组矩阵的完整硬件调度。模块位于 DMA 控制
窗口偏移 `0x200`，通过通用 DMA 的外部请求接口搬运输入和可选结果，通过本地控制信号
启动矩阵乘法器。该结构消除了 CPU 对 5000 组任务逐组配置、轮询和切换 Bank 的开销。
序列器、通用 DMA 外部请求接口和矩阵本地控制接口全部工作在 `sys_clk`，因此 Bank 状态、
request/done 和 start 信号之间为同步路径。CPU 对序列器寄存器的访问在到达本模块前已由
CPU--SYS `Axi_CDC` 完成跨域。
每组输入由两个 4x4、32 位无符号矩阵组成，共 32 个字，即 128 字节。每组结果包含
16 个 66 位元素，以每元素三个 32 位字存储，共 192 字节。序列器使用可配置 stride，
因此数据可以连续排列，也可嵌入更大的记录结构。
## 2. 寄存器接口
| 绝对偏移 | 名称 | 说明 |
|---|---|---|
| `0x200` | CTRL | bit 0 启动，bit 1 跳过结果写回 |
| `0x204` | STATUS | bit 0 busy，bit 1 done；done 为 W1C |
| `0x208` | SRC_BASE | 第一组 A/B 的物理地址 |
| `0x20c` | DST_BASE | 第一组 C 的物理地址 |
| `0x210` | GROUPS | 任务组数 |
| `0x214` | MAT_BASE | 软件兼容字段，当前直接 endpoint 路径不使用 |
| `0x218` | SRC_STRIDE | 相邻输入组地址间隔，默认 128 字节 |
| `0x21c` | DST_STRIDE | 相邻结果组地址间隔，默认 192 字节 |
配置寄存器只在序列器空闲时接受写入。启动时模块锁存是否跳过写回，清除旧完成状态，
清零矩阵 CRC，并初始化组计数、地址计数和两个 Bank 的占用状态。`GROUPS=0` 不产生计算。
## 3. 双 Bank 调度模型
序列器为两个 Bank 分别维护 load active、A/B valid、compute active、store pending 和
store active 五类状态。一个 Bank 只有在上述状态均为零时才能接收下一组输入。输入组
按组号奇偶映射到 Bank 0/1，并在 `bank_group_idx` 中记录所属组号。
调度过程包含三个可重叠阶段。装载阶段提交 128 字节 mem2ep 请求；计算阶段在 A/B
有效后发出 `mat_start_valid` 和 Bank 号；存储阶段在计算完成后提交 192 字节 ep2mem
请求。只要另一 Bank 可用，下一组装载可以与当前组计算或结果写回交叠。
当两个 Bank 均具备计算条件时，序列器选择组号较小者，保持提交顺序。计算 Bank 被放入
两项深度的 `compute_q`，用于把矩阵乘法器的电平 done 事件对应回具体 Bank。done 通过
边沿检测转化为单次完成事件，防止电平保持期间重复退休同一任务。
## 4. 完成与快速路径
正常模式下，一组任务在结果写回的 B 响应完成后退休。快速模式设置
`skip_result_writeback`，计算完成即退休，不再把 192 字节结果写入 ExtRAM。矩阵乘法器
在计算结果产生时直接更新整批 CRC32，因此跳过写回不会跳过正确性判定。该模式适用于
官方评测只检查最终 CRC、无需读取全部结果矩阵的场景。
当 `groups_retired` 达到配置组数，且没有活动的装载、计算和存储任务时，序列器清除
busy、置位 done 并拉高 `seq_done_irq`。软件通过 STATUS 的 W1C 位确认并清除完成状态。
## 5. 关键不变量
同一 Bank 不得同时被装载和计算，也不得在结果尚未消费时覆盖。组号只在输入请求被接受
后递增，退休计数只响应写回完成或快速模式下的计算完成。输入和结果地址分别按 stride
递增，不从 Bank 号反推地址。CRC 只在整批启动时清零，不在 Bank 切换时清零。
这些不变量是验证的核心。若仅检查最终 done，无法发现 Bank 覆盖、组号乱序或重复退休。
测试平台应同时观察每个 Bank 的状态向量、DMA 请求握手、矩阵 start/done 和退休计数。
## 6. 当前验证范围
区域赛证据包含三次 5000 组官方板级运行，三次均收到完成标志并通过 CRC。该结果验证了
长序列快速模式的主要数据流，但不等价于覆盖所有边界。模块级回归仍应包含组数 1、2、3，
两种写回模式，不同 stride，DMA 读写反压，以及 done W1C 后立即启动下一批等场景。

82
doc/reports/system/modules/04_matmul_accelerator.md Normal file
View File

@@ -0,0 +1,82 @@
# 4x4 矩阵乘法加速器技术说明
## 1. 计算规格
`matmul_axi_slave` 计算两个 4x4 无符号整数矩阵的乘积。输入元素宽度为 32 bit，输出
元素满足
`C[i][j] = sum(A[i][k] * B[k][j]), k=0..3`。
单个乘积为 64 bit，四项相加的最坏情况需要 66 bit，因此结果存储宽度固定为 66 bit。
每个输出元素通过三个 32 位字传输：低 32 位、高 32 位以及最高 2 位。该布局使 AXI 和
DMA 数据宽度保持 32 bit，同时不截断数学结果。
## 2. 接口组成
模块同时提供完整 AXI4 从接口、本地 DMA endpoint 和矩阵序列器直连控制接口。AXI
接口支持 INCR burst，可由 CPU 或普通 DMA 访问控制寄存器及双 Bank 数据窗口。本地
endpoint 直接接收 A/B 字或输出 C 字，不经过 Crossbar 的矩阵从端。序列器通过
`mat_start_valid`、`mat_start_bank`、`mat_done_clear` 和 `mat_crc_clear` 完成批处理控制。
矩阵 AXI 从端、endpoint、乘法流水线和 CRC 均使用 `sys_clk/sys_resetn`。DMA 和序列器也
位于 SYS 域，三者之间没有 CDC。CPU 发起的矩阵访问在 Crossbar 之前已经跨入 SYS 域。
`matmul_intr` 产生于 SYS 域，接入 CPU 前的时钟边界见独立时钟域说明。
两个 endpoint ready 在当前实现中恒为 1，表示矩阵本地缓冲不施加反压。上游仍必须只在
目标 Bank 空闲时写入，Bank 所有权由批处理序列器保证，而不是由加速器内部检查。
## 3. 寄存器与双 Bank 布局
| 偏移 | 内容 | 说明 |
|---|---|---|
| `0x000` | CTRL | bit 0 请求 Bank 0，bit 1 请求 Bank 1 |
| `0x004` | STATUS | busy、done、error；done/error 支持 W1C |
| `0x010` | CRC32 | 返回 `crc_reg XOR 0xffff_ffff`；写入用于清零 CRC |
| `0x100` | Bank 0 A | 16 个 32 位元素 |
| `0x140` | Bank 0 B | 16 个 32 位元素 |
| `0x180` | Bank 0 C | 16 个 66 位元素，共 48 个 32 位字 |
| `0x300` | Bank 1 A | 16 个 32 位元素 |
| `0x340` | Bank 1 B | 16 个 32 位元素 |
| `0x380` | Bank 1 C | 16 个 66 位元素，共 48 个 32 位字 |
A 和 B 均按行优先方式存储。endpoint 写地址 0--15 对应 A，16--31 对应 B；endpoint
读地址 0--47 对应 C 的三字布局。双 Bank 允许一组数据计算时准备另一组，但计算核心
本身一次只处理一个 Bank。
## 4. 乘法数据通路
核心包含四个 `pipelined_mult_32x32` 实例，并使用 `use_dsp="no"` 属性约束综合器将乘法
映射到 LUT 逻辑。每个乘法器包含输入寄存、乘积寄存和输出寄存三个流水级，吞吐率为
每周期一个乘积。
计算核心每周期选择一个输出元素 `(i,j)`，同时向四个乘法器发出
`A[i][0..3]` 与 `B[0..3][j]`。流水线对齐后，四个 64 位乘积采用成对加法生成一个
66 位结果。16 个输出元素连续发射，索引和 Bank 标识经过四级有效流水线与乘积对齐。
因此稳态吞吐为每周期一个 C 元素，而不是逐项乘加的四周期结构。
当 Bank 0 完成且 Bank 1 已有待处理请求时，状态机可直接调用 `start_calc_bank` 切换
Bank，不必先返回空闲态。最后一个有效结果写回时产生 `calc_done_pulse`，置位 done 并
驱动电平型中断。
## 5. CRC32 数据通路
CRC 使用 IEEE 802.3 反射多项式 `0xedb8_8320`，初值为 `0xffff_ffff`，软件读取时执行
末尾异或。每个 66 位 C 元素按低 32 位、高 32 位、最高 2 位补零三个字依次进入
`crc32_word_next`。CRC 在计算结果有效时更新，与 CPU 或 DMA 是否读取 C 无关。
这一选择使快速评测可以关闭结果写回，只保留硬件计算与 CRC。CRC 顺序严格跟随输出
元素发射顺序；整批任务开始时由序列器清零，Bank 切换和单组完成不会清零。
## 6. AXI 协议处理
写通道分别处理 AW、W 和 B 阶段，锁存 ID、burst 类型和起始地址；INCR burst 每次有效
W 握手后地址增加 4。读通道锁存 AR 参数并连续产生 R beat，最后一拍置位 RLAST。
无效写地址置位 error，响应码当前始终为 OKAY。输出 C 的组合读选择在当前地址上解析
元素号和三字片段。
## 7. 验证要求
功能验证需要逐元素与 128 bit 或更宽的软件参考模型比较，覆盖全零、全 `0xffff_ffff`、
单位矩阵和随机矩阵。协议验证需覆盖 AW/W 分离、R/B 反压、单 beat 与 burst、两个 Bank
连续请求和非法地址。CRC 应独立比较完整 192 字节输出序列。当前官方板测只读取最终
CRC，证明了长批处理的端到端一致性，但不能替代逐元素和 AXI 边界测试。

73
doc/reports/system/modules/05_fft_accelerator.md Normal file
View File

@@ -0,0 +1,73 @@
# 1024 点 FFT 加速器技术说明
## 1. 模块组成与数值格式
FFT 加速器由 `fft_controller`、五级 `SdfUnit` 流水、蝶形、延迟反馈存储、旋转因子 ROM
和复数乘法器构成。当前配置处理 1024 点复数序列，实部和虚部均为 16 位有符号定点数。
AXI 窗口按 32 位字编址，每个字的低 16 位承载一个输入或输出分量，读取时对 16 位结果
进行符号扩展。
FFT 的 AXI 控制器、输入输出 BRAM、SDF 数据通路和完成状态全部工作在
`sys_clk/sys_resetn`。DMA 访问 FFT 窗口时不跨域；CPU 请求在到达共享从端前已经通过
CPU--SYS AXI CDC。FFT 不使用 `mlkem_clk`，即使两者共享同一外部地址从端。
顶层 `FFT` 使用 Radix-2^2 单路径延迟反馈架构。五个 `SdfUnit` 的参数 M 依次为 1024、
256、64、16 和 4，每级完成两层 radix-2 蝶形并处理相应旋转因子。输入要求按自然顺序
连续提供，核心输出为位反转顺序；AXI 控制器在读输出 BRAM 时反转地址位，使软件观察到
自然顺序结果。
## 2. 地址窗口
FFT 位于共享物理基址 `0x1f40_0000` 的高半区。
| 偏移 | 内容 | 容量 |
|---|---|---|
| `0x8000` | 输入实部 | 1024 个 32 位字，低 16 位有效 |
| `0x9000` | 输入虚部 | 1024 个 32 位字，低 16 位有效 |
| `0xa000` | 输出实部 | 1024 个符号扩展的 32 位字 |
| `0xb000` | 输出虚部 | 1024 个符号扩展的 32 位字 |
| `0xc000` | CSR | bits 3:0 状态，bits 7:4 控制 |
CSR 控制 bit 4 为 start，状态 bit 0 为 busy，bit 1 为 done。写 start 同时清除旧 done；
计算完成后 done 保持，`fft_finish` 直接反映该状态。输入和输出窗口均支持 AXI INCR
burst，因此既可由 CPU 逐字访问，也可由 DMA 批量搬运。
## 3. 控制状态机
控制器包含 IDLE、LOAD、WAIT_OUT 和 DONE 四个状态。IDLE 检测 start；LOAD 在 1024 个
周期内顺序读取输入实部和虚部 BRAM，并根据 BRAM 读延迟产生对齐的 `di_en`；WAIT_OUT
接收 FFT 流水线输出并写入输出 BRAM；收到第 1024 个有效输出后进入 DONE，再返回 IDLE。
busy 在 LOAD 和 WAIT_OUT 期间有效。输入 BRAM 与输出 BRAM均采用独立读写端口，CPU 或
DMA 的窗口访问与计算侧顺序访问通过双端口结构隔离。软件不得在 busy 期间覆盖输入，
也不应在 done 前读取尚未完成的输出。
## 4. SDF 数据通路
每个 `SdfUnit` 含两级蝶形和两组延迟反馈缓存。计数器决定当前样本进入反馈存储还是参与
加减运算。第二级蝶形输出根据当前阶段选择 `1`、`-j` 或 ROM 旋转因子，并通过复数乘法
进入下一级。单路径结构每周期只传递一个复数样本，减少并行蝶形和存储端口数量。
`Butterfly` 对和、差各执行一次算术右移，相邻级使用不同的半舍入偏置以减小累计偏差。
五个 SDF 单元合计执行十次除 2，因此总缩放因子为 `1/1024`。软件参考结果同样除以
1024 后再与硬件比较。
复数乘法器计算四个有符号乘积并按 `WIDTH-1` 位右移恢复定点尺度。模块带有
`use_dsp="no"` 属性，所有乘法映射到 LUT/CARRY 资源。该约束满足竞赛资源要求，但会
增加 LUT 占用和组合路径压力。
## 5. 软件访问模式
CPU 路径逐字写入两个输入窗口、启动 FFT、轮询 done，再逐字读回两个输出窗口。DMA
路径使用两个 DMA 通道分别搬入实部和虚部，计算完成后再分别搬回输出。CPU 路径测量
包含大量寄存器访问，DMA 路径测量包含四次批量搬运和一次计算，二者均属于端到端时间，
不能直接解释为纯 FFT 核延迟。
## 6. 验证与数值误差
板级程序使用相同的 1024 点多音输入和浮点 radix-2 DIT 软件参考。全部 1024 个点逐点
比较，当前三次 CPU 路径和三次 DMA 路径的最大绝对误差均为实部 1、虚部 2，低于阈值
8。CPU 路径端到端时间为 1,724,940 ns，DMA 路径为 296,730 ns；三次运行结果一致。
这些结果证明当前测试向量上的定点误差和数据搬运正确性。进一步验证应增加冲激、单频、
满幅随机、接近溢出和复数输入，并检查连续 start、busy 期间非法写入以及 AXI 反压。

78
doc/reports/system/modules/06_mlkem_core.md Normal file
View File

@@ -0,0 +1,78 @@
# ML-KEM 总控与算法数据通路技术说明
## 1. 功能范围
`mlkem_top` 实现 FIPS 203 ML-KEM 的 KeyGen、Encaps 和 Decaps 主数据通路。安全等级由
运行时参数 `k_i` 选择：2、3、4 分别对应 ML-KEM-512、768、1024。模数固定为 3329，
多项式次数固定为 256，共享密钥长度为 32 字节。模块在 `start_i` 有效时锁存安全等级和
操作码，运行期间不再读取外部配置。
三个等级共享同一比特流。片上存储按最大等级静态分配，循环边界、槽位基址、密钥长度和
压缩参数由锁存的 K 动态计算。对应公钥长度为 800、1184、1568 字节，私钥长度为 1632、
2400、3168 字节，密文长度为 768、1088、1568 字节。
## 2. 顶层接口
配置端口包括 3 位安全等级、2 位操作码和单拍 start。KeyGen 输入 256 位随机种子 d 和 z；
Encaps 输入消息 m，并在启动前通过字节端口装载公钥；Decaps 在启动前通过字节端口装载
私钥和密文。`busy_o` 在非 IDLE 状态有效，`done_o` 在 ST_DONE 产生完成脉冲，`ss_o`
输出 256 位共享密钥。
公钥、私钥和密文不使用超宽并行端口，而是通过 8 位写接口和调试读回接口访问内部 BRAM。
系统集成层在该字节接口外提供 AXI 寄存器路径和 32 位批量窗口。
`mlkem_top` 及 Keccak、采样、NTT、多项式运算和局部 BRAM 全部工作在
`mlkem_clk/mlkem_resetn`。模块内部算子之间没有 CDC。来自 SYS 域的寄存器和批量窗口
事务在进入 `mlkem_axi_slave` 前已通过完整 AXI CDC；完成中断先同步回 SYS 域。
## 3. 集中式控制状态机
模块使用 5 位集中式状态机调度算子和存储端口。KeyGen 路径依次执行 G 哈希、SampleNTT
生成矩阵、CBD 生成 s/e、前向 NTT、矩阵向量点乘、密钥编码和公钥哈希。各阶段通过
系数 BRAM 和字节 BRAM 传递数据，不在阶段之间复制完整多项式总线。
Encaps 路径首先计算公钥哈希与 `G(m || H(ek))`，随后重新生成转置矩阵，解码公钥 t，
采样 y/e1/e2，对 y 执行 NTT，计算 u 和 v，最后按等级参数 `du/dv` 压缩并编码密文。
共享密钥为 G 输出的 K 部分。
Decaps 路径解码并解压密文，解码私钥 s，对 u 执行 NTT，恢复消息 m'，再计算
`G(m' || H(ek))` 和 `J(z || c)`。D6 重加密不复制第二套加密硬件，而是把 m' 和 r'
送回 Encaps 状态序列生成参考密文 c'。最后状态逐字节比较 c' 与输入 c，并选择正常密钥
或隐式拒绝备用密钥。
比较循环不因首个不匹配字节提前退出，控制路径按完整密文长度运行。该行为是 RTL 的设计
属性；当前 regional 板级日志没有专门注入篡改密文，因此现有系统报告不把负向隐式拒绝
测试列为已验证结果。
## 4. 算子复用
Keccak-f[1600] 是面积最大的算子。SHA3/SHAKE 协议层、SampleNTT 和 CBD 在互斥状态中
共享一个 `keccak_core`，输入由状态选择器复用，输出广播给当前活动消费者。NTT、逆 NTT、
多项式基乘以及压缩/解压同样按状态复用，而不是为 KeyGen、Encaps 和 Decaps 分别复制。
该架构降低面积，但限制了状态间并行度。SampleNTT、CBD、NTT 和多项式乘法不能跨主状态
重叠，整体延迟由各阶段串行累加。技术报告应将其描述为面积与吞吐之间的明确权衡。
## 5. 存储组织
系数数据使用三个主要存储库。`bank_a` 为 12 bit x 4096，存放 A 矩阵及部分临时多项式；
`bank_se` 为 12 bit x 2048，存放 s/e、y、u 等向量；`bank_t` 为 12 bit x 1024，存放 t、
点乘累加、v 和 w。槽位以 256 个系数为单位，基址由 K、K^2 和当前算法阶段计算。
字节数据使用独立的 `ek_bram`、`dkp_bram`、`ct_bram` 和 `c_in_bram`。输入密文与重加密
产生的参考密文分开存储，使最终比较可以同周期读取两者。Decaps 私钥装载地址还会把
`dk_pke`、嵌入的公钥、H(ek) 和 z 分派到不同存储或寄存器。
## 6. 数值与资源约束
多项式系数采用 12 位模 q 表示。模乘通过流水化 Barrett 约简实现，相关乘法强制不使用
DSP。NTT 使用四路 Banked BRAM 和双蝶形流水，点乘使用独立偶/奇 Bank。当前实现中
ML-KEM 计算域目标频率为 76.923 MHz，最终时序结论以布局布线报告为准。
## 7. 验证边界
叶子算子应分别与软件或 Python 参考模型比较；顶层应按 FIPS 203 KAT 对公钥、私钥、
密文和共享密钥逐字节比较；系统级还需验证 CPU 寄存器路径和 DMA 窗口路径。当前板级
证据由 ML-KEM-512、768、1024 三个独立编译程序组成，每个程序对软件、CPU 和 DMA
路径各执行 100 次，现有日志的 FAILS 均为 0。该重复次数证明固定向量上的稳定性，不能
表述为 900 个不同随机 KAT。

74
doc/reports/system/modules/07_mlkem_axi_frontend.md Normal file
View File

@@ -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 双路径证明了常用顺序访问，
但不等价于覆盖所有并发和异常协议组合。

62
doc/reports/system/modules/08_mlkem_hash_sampling.md Normal file
View File

@@ -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 通过能够发现大部分功能错误，
但叶子级握手、边界填充和共享仲裁仍需要独立测试平台验证。

72
doc/reports/system/modules/09_mlkem_polynomial_arithmetic.md Normal file
View File

@@ -0,0 +1,72 @@
# ML-KEM 多项式运算模块技术说明
## 1. 运算域与数据表示
多项式运算位于环 `Z_q[x]/(x^256+1)`，其中 q=3329。系数在硬件中使用 12 位无符号模 q
表示。该组模块包括前向/逆向 NTT、Barrett 模乘、NTT 域 basecase 乘法、多项式加减以及
Compress/Decompress。算子使用 valid/ready 或 start/done 接口，由 `mlkem_top` 分时复用。
本文件中的 NTT、模乘、basecase、多项式加减、压缩模块及其局部 BRAM 均工作在
`mlkem_clk/mlkem_resetn`。算子与 `mlkem_top` 之间是单时钟域同步接口，不包含独立 CDC。
地址、valid 和数据的延迟对齐属于流水线时序问题，而不是跨时钟域问题。
## 2. NTT 核
`ntt_core` 实现 256 点前向和逆向 NTT。系数存储由 `coeff_bram_4way` 划分为四个 Bank，
每个 Bank 具有同步读和写端口。地址生成器把同周期的两个蝶形对映射到互不冲突的 Bank，
从而同时处理四个系数。
数据通路包含两个 `butterfly_unit_pipe`。第 t 周期发出 BRAM 地址，下一周期取得系数，
随后进入流水化蝶形和 Barrett 模乘；写地址通过同长度延迟链与结果对齐。每层发射结束后
等待流水排空，再更新层号和旋转因子索引。逆 NTT 在七层变换后复用模乘流水线执行末尾
缩放。
`zeta_rom` 保存 128 个 12 位旋转因子。前向和逆向变换使用不同的索引方向及蝶形公式。
验证不能只比较 NTT 后的频域值，还应执行 INTT(NTT(a)) 并检查恢复系数，覆盖 Bank 地址
冲突和最后一层流水排空。
## 3. Barrett 模约简与蝶形
`barrett_mul_pipe` 先计算 12x12 位乘积，再用常数 5039 估计除以 q 的商，计算
`r = p - q_est*q`，最后通过条件减 q 把结果限制到 `[0,q)`。各乘法级之间加入寄存器，
并以 `use_dsp="no"` 约束映射到 LUT。蝶形单元在模乘前后执行模加或模减，并将 valid
沿流水线传递。
商估计只在限定输入范围内成立，因此上游必须保证输入系数已经规范化。叶子测试应覆盖
0、q-1、乘积最大值和所有修正分支，不能仅使用随机中间值。
## 4. NTT 域多项式乘法
`poly_mul_sync` 对 256 个频域系数按相邻偶/奇系数组成 128 个 basecase。每个 basecase
结合对应 zeta 计算两个输出系数。输入多项式写入独立 Bank，控制器按 LOAD、RUN 和
OUTPUT 阶段管理装载、流水计算和结果输出。
`basecase_mul_pipe` 并行计算多个模乘项，再完成模加。当前版本将系数存储改为偶/奇
Banked BRAM，减少离散寄存器和 LUTRAM。受同步 BRAM 读延迟和发射控制影响，RUN 阶段
每两周期发射一个 basecase。输出采用 valid/ready，接收端反压时不得覆盖尚未消费的系数。
`poly_arith_sync` 提供系数级模加和模减，用于点乘累加、噪声相加以及解封装中的差值。
运算结果在每一步规范化到模 q 范围，避免后续模乘输入超界。
## 5. 压缩与解压缩
`comp_decomp_sync` 实现 FIPS 203 的 Compress_d 和 Decompress_d。压缩近似计算
`round(2^d*x/q) mod 2^d`，解压计算 `round(q*y/2^d)`。当前流水线使用常数乘法和移位
近似除法，避免综合组合除法器；模式、d 和 valid 随数据经过各级寄存。
输出端具有保持寄存器。当下游未 ready 时，结果和 valid 保持；输入 ready 由流水线及
输出可用性共同决定，因此文档和测试不应假设任意反压下始终每周期接收一个系数。需要
分别覆盖 d=1、4、5、10、11 等算法实际参数，并与精确整数公式逐值比较。
## 6. 存储和调度约束
NTT 核和多项式乘法器各自包含局部 BRAM，ML-KEM 顶层还包含全局系数 Bank。进入算子前
需要将目标多项式装入局部存储，完成后再流式写回全局 Bank。这种结构简化端口仲裁，但
增加装载和回写周期。主 FSM 保证同一全局 Bank 端口在一个状态内只有一个所有者。
## 7. 验证边界
叶子级验证应覆盖 NTT、INTT、basecase、完整多项式乘法、模加减和压缩解压，并对所有
256 个系数比较。顶层 KAT 能验证算子组合后的算法结果，但当多个误差互相抵消时不能定位
根因。实现后还需检查 BRAM 推断、DSP=0 和 valid/地址延迟对齐；这些属于结构验证，不能
仅由软件结果正确推出。

74
doc/reports/system/modules/10_software_runtime.md Normal file
View File

@@ -0,0 +1,74 @@
# 软件运行时与测试程序技术说明
## 1. 软件职责
软件位于 `sdk/software/examples/`，负责构造输入、配置物理地址和寄存器、启动硬件、等待
完成、读取结果并与参考值比较。算法的高开销数据通路由硬件完成；软件保留参考实现和
诊断输出，用于区分计算错误、数据搬运错误和接口错误。
CPU 访问外设时使用 `0xbfxx_xxxx` 未缓存映射，DMA 描述符使用 `0x1xxx_xxxx` 物理地址。
软件缓冲区通过未缓存别名读写，避免数据缓存中的旧副本与 DMA 结果不一致。该地址转换是
驱动正确性的一部分，而不是性能优化细节。
软件指令在 `cpu_clk` 域执行，外设寄存器和 DMA 数据面主要位于 `sys_clk` 域，ML-KEM
核心位于 `mlkem_clk` 域。软件不直接处理相位关系，而是通过 AXI valid/ready、状态保持
和 W1C 完成语义与异步硬件交互。CPU 周期计数包含跨域 FIFO 和外设响应延迟。
## 2. DMA 驱动
`dma.c/dma.h` 将通道寄存器映射为 C 结构体。驱动先检查 busy，再写源地址、目的地址、
字节数和 tag，配置 32 位 beat 与 burst 长度后置位 start。`dma_wait_polling` 轮询 done，
完成后通过 W1C 清除状态。
FFT 驱动使用 AxLEN=15，即 16 beat burst；矩阵快速路径使用 AxLEN=63，即 64 beat 配置。
实际末 burst 长度由硬件按剩余字节裁剪。当前驱动遇到通道 busy 时直接返回，没有错误码；
轮询也没有软件超时。因此调用方必须保证通道所有权，正式运行时应增加返回值和超时处理。
## 3. 矩阵乘法评测程序
`asm/user-sample.c` 面向官方 5000 组评测。程序配置矩阵批处理序列器的源地址、目的地址、
组数和 stride，发送 `MATMUL_START`，启动硬件并轮询序列器 done。完成后读取矩阵加速器
CRC32，并以紧凑 UART 写入输出 CRC 和 `MATMUL_DONE`。
快速启动配置使用 `start_matmul_fast.S` 缩短通用 C 运行时初始化。UART 输出避免 `printf`
格式化开销，并按 FIFO 可用状态分段写入。设置 `MATMUL_WRITEBACK_RESULTS=0` 时，序列器
跳过 5000 组结果写回，但矩阵核心仍对全部 66 位结果更新 CRC。
官方计时从接收到 START 到接收到 DONE，因此软件启动顺序、串口发送和完成尾部均会进入
端到端时间。当前 regional 证据包含三次运行，中位数为 6.944404 ms，CRC 均匹配。该数据
不包含 `test_1` 中的后续优化。
## 4. FFT 测试程序
`fft/main.c` 通过 CPU 逐字写入 1024 个实部和虚部，启动 FFT，读回全部输出，再执行浮点
radix-2 DIT 软件参考。`fft_dma/main.c` 使用两个 DMA 通道搬入输入，计算完成后搬回输出。
两者都对 1024 个 bin 计算最大实部和虚部绝对误差，并以阈值 8 判定。
软件参考结果除以 1024，与硬件每级缩放后的输出尺度一致。当前 CPU 和 DMA 路径各有三份
板级日志，结果完全一致。硬件时间为端到端测量，CPU 路径包含 4096 次窗口读写，DMA
路径包含四次搬运，因此两者反映接口方案而非单独的 FFT 流水线周期。
## 5. ML-KEM 测试程序
`mlkem_test/main.c` 为每个安全等级分别构建和运行。当前源码通过 `LEVELS` 数组选择本次
编译的 K，区域赛证据中的 512、768、1024 来自三个独立程序，不是一个程序内并行执行。
每个程序使用固定 KAT count 0 输入，分别运行软件参考、CPU 寄存器路径和 DMA 窗口路径。
CPU 路径通过 PRE/RDB 接口逐字节装载和读取密钥、密文；DMA 路径通过 EK、DK、CT
窗口批量搬运。两条硬件路径均执行 KeyGen、Encaps 和 Decaps，并检查封装/解封共享密钥
一致性以及固定黄金值。每条路径重复 100 次，记录失败次数和平均 CPU 周期。
现有测试的重复输入用于稳定性和性能统计，不代表不同随机 KAT。程序未篡改密文触发负向
隐式拒绝，因此报告只能说明正常输入路径通过，不能把 RTL 中存在的拒绝逻辑表述为已完成
板级负向测试。
## 6. 构建与证据输出
报告工作流只编译 `asm`、`fft`、`fft_dma`、`mlkem_test` 和 `mlkem_hello`。FFT 与
ML-KEM 的通用 SoC 软件仿真耗时较长，当前功能数据采用板级 UART 日志。日志使用固定
机器可读字段，例如 `FFT_RESULT`、`MLKEM*_FAILS`、平均周期和完成标志，指标脚本从这些
字段聚合报告数据。
软件测试的通过条件包括算法结果、DMA 完成和输出标记，不能只依据程序返回。后续改动
寄存器布局、缓存属性、时钟频率或 UART 输出顺序时，必须同步更新驱动、测试判定和指标
解析脚本。

48
doc/reports/system/modules/README.md Normal file
View File

@@ -0,0 +1,48 @@
# 自研模块技术说明索引
本目录记录区域赛仓库中由项目组设计、修改或完成系统级集成的模块。技术说明以当前
`main` 分支 RTL 和软件源码为依据，服务于系统设计报告的后续重写。文档中的“已实现”
表示源码中存在相应数据通路或控制逻辑；“已验证”仅指当前 `evidence/` 中能够直接支持
的结论，两者不混用。
OpenLA500 处理器、UART、DVI、基础 SRAM 控制器以及赛事提供的 SoC 框架不作为自研 IP
列入。项目组对这些模块的地址连接、时钟连接和中断集成记录在 SoC 集成说明中，但不把
其内部实现归入项目贡献。
| 文档 | 主要 RTL 或软件 | 技术边界 |
|---|---|---|
| [时钟域、复位与 CDC](00_clock_domains.md) | `clk_pll`、`rst_sync`、`Axi_CDC`、`soc.xdc` | 三时钟域归属、复位链、跨域协议和约束模型 |
| [SoC 集成与时钟复位](01_soc_integration.md) | `rtl/soc_top.v`、`rst_sync.v` | 地址空间、主从互连、时钟域、复位和中断集成 |
| [通用 DMA 子系统](02_dma_subsystem.md) | `rtl/ip/cdma/snix_*.sv` | 四通道 DMA、AXI 搬运、本地 endpoint 和仲裁 |
| [矩阵批处理序列器](03_matmul_batch_sequencer.md) | `cdma_matmul_bridge.sv` | 5000 组任务调度、双 Bank 流水和可选结果写回 |
| [矩阵乘法加速器](04_matmul_accelerator.md) | `matmul_axi_slave.v` | 4x4 无符号矩阵乘法、AXI/endpoint、CRC32 |
| [FFT 加速器](05_fft_accelerator.md) | `rtl/ip/fft/*.v` | 1024 点定点 FFT、SDF 数据通路和 AXI 存储窗口 |
| [ML-KEM 总控与算法数据通路](06_mlkem_core.md) | `mlkem_top.v` | 三等级、三操作、集中式 FSM 和片上存储组织 |
| [ML-KEM AXI 前端与 CDC](07_mlkem_axi_frontend.md) | `fft_mlkem_axi_slave.v`、`mlkem_axi_slave.v` | 共享地址窗口、批量数据窗口和跨时钟域握手 |
| [Keccak 与采样模块](08_mlkem_hash_sampling.md) | `sha3/`、`sample_ntt/`、`sample_cbd/` | SHA3/SHAKE、拒绝采样和 CBD 采样 |
| [多项式运算模块](09_mlkem_polynomial_arithmetic.md) | `ntt/`、`poly_mul/`、`comp_decomp/` | NTT、基乘、模约简、压缩与解压缩 |
| [软件运行时与测试程序](10_software_runtime.md) | `sdk/software/examples/{asm,fft,fft_dma,mlkem_test}` | 寄存器驱动、DMA 调度、参考模型和结果判定 |
文档中的地址均为物理地址，除非明确写为 CPU 未缓存虚拟地址。AXI 信号名沿用 RTL，
寄存器偏移以字节为单位。频率和资源数据属于当前 regional 仓库，不包含 `test_1` 中的
后续矩阵乘法优化。
## RTL 模块覆盖说明
当前 SoC 有效层次中的计算和搬运模块均已纳入上述文档。DMA 说明覆盖
`snix_axil_cdma_mux`、`snix_axi_mm2mm`、`snix_axis_fifo` 和 `snix_sync_fifo`；矩阵说明
覆盖 `matmul_axi_slave`、`pipelined_mult_32x32` 和 `cdma_matmul_bridge`；FFT 说明覆盖
`fft_controller`、`FFT`、`SdfUnit`、`Butterfly`、`Multiply`、`DelayBuffer` 和 `Twiddle`。
ML-KEM 说明覆盖当前集成层次中的 `fft_mlkem_axi_slave`、`mlkem_axi_slave`、
`mlkem_top`、`keccak_core`、`keccak_round`、`sha3_top_shared`、
`sample_ntt_sync_shared`、`sample_cbd_sync_shared`、`ntt_core`、`coeff_bram_4way`、
`butterfly_unit_pipe`、`barrett_mul_pipe`、`poly_mul_sync`、`basecase_mul_pipe`、
`poly_arith_sync`、`comp_decomp_sync`、`zeta_rom`、`poly_mul_zeta_rom`、`pipeline_reg`、
`skid_buffer`、`sd_bram` 和 `s_bram`。
仓库还保留 `snix_axi_cdma`、`snix_axi_cdma_csr`、`snix_async_fifo`、
`snix_register_slice`，以及非共享版 `sha3_top`、`sample_ntt_sync`、`sample_cbd_sync`、
旧版 `ntt_sync`、`butterfly_unit`、`barrett_mul` 和 `basecase_mul`。这些文件用于早期方案、
叶子测试或兼容参考，当前 `soc_top`/`mlkem_top` 未实例化，因而不作为独立系统模块另写
性能结论。若后续重新接入，应先更新本索引及对应技术说明。