# 软件运行时与测试程序技术说明

## 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 输出顺序时，必须同步更新驱动、测试判定和指标
解析脚本。