4.7 KiB
软件运行时与测试程序技术说明
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 输出顺序时，必须同步更新驱动、测试判定和指标 解析脚本。