update system design report

doc/reports/system/modules/05_fft_accelerator.md

@@ -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 反压。