# 自研模块技术说明索引

本目录记录区域赛仓库中由项目组设计、修改或完成系统级集成的模块。技术说明以当前
`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` 未实例化，因而不作为独立系统模块另写
性能结论。若后续重新接入，应先更新本索引及对应技术说明。