doc: reorganize reports into mlkem_ip/ and system/ directories

doc/reports/system/system_design_report.tex

@@ -120,7 +120,7 @@ CPU负责系统的整体调度：配置各加速器的控制寄存器、触发
 
 \subsection{总体架构}
 
-图\ref{fig:soc_arch}给出了SoC系统的顶层架构。系统以LoongArch32r CPU核心（openLA500）为主控制器，通过AXI4总线经\texttt{Axi\_CDC}时钟域交叉桥接至系统总线域（\texttt{sys\_clk}，50 MHz），再由\texttt{AxiCrossbar\_2x8}将CPU和DMA两个主设备的访问请求按地址高位译码分发至8个从设备。
+图\ref{fig:soc_arch}给出了SoC系统的顶层架构。系统以LoongArch32r CPU核心为主控制器，通过AXI4总线经时钟域交叉桥接模块至系统总线域（50 MHz），再由AXI交叉开关将CPU和DMA两个主设备的访问请求按地址高位译码分发至8个从设备。
 
 \begin{figure}[H]
 \centering
@@ -131,7 +131,7 @@ CPU负责系统的整体调度：配置各加速器的控制寄存器、触发
 
 \subsection{地址空间分配}
 
-系统地址空间采用统一编址，CPU通过非缓存虚拟地址\texttt{0xBFxxxxxx}访问各外设（对应物理地址\texttt{0x1Fxxxxxx}）。表\ref{tab:addr_map}列出各从设备的地址窗口。
+系统地址空间采用统一编址，CPU通过非缓存虚拟地址段（0xBFxxxxxx）访问各外设，对应物理地址段为0x1Fxxxxxx。表\ref{tab:addr_map}列出各从设备的地址窗口。
 
 \begin{table}[htbp]
 \centering
@@ -153,11 +153,11 @@ Slave 7 & 0x1F50\_0000--0x1F5F\_FFFF & 0xBF50\_0000 & 矩阵乘法加速器 \\
 \end{tabular}
 \end{table}
 
-Slave 6（FFT/ML-KEM共享窗口）内部根据地址位[15:12]进一步路由：偏移0x0000--0x3FFF定向至ML-KEM的AXI从机，偏移0x8000--0xCFFF定向至FFT控制器。Slave 5（DMA配置窗口）内部根据地址位[11:8]分发：0x000--0x1FF区间通往DMA通道寄存器，0x200--0x2FF区间通往\texttt{cdma\_matmul\_bridge}的序列控制寄存器。
+Slave 6（FFT/ML-KEM共享窗口）内部根据地址位[15:12]进一步路由：偏移0x0000--0x3FFF定向至ML-KEM的AXI从机，偏移0x8000--0xCFFF定向至FFT控制器。Slave 5（DMA配置窗口）内部根据地址位[11:8]分发：0x000--0x1FF区间通往DMA通道寄存器，0x200--0x2FF区间通往matmul序列控制器的配置寄存器。
 
 \subsection{中断系统}
 
-系统中断链路由confreg模块集中管理，6个中断源经优先级编码后送入CPU的\texttt{intrpt}输入。中断映射关系如表\ref{tab:interrupts}所示。
+系统中断链路由外设配置与中断控制模块集中管理，6个中断源经优先级编码后送入CPU。中断映射关系如表\ref{tab:interrupts}所示。
 
 \begin{table}[htbp]
 \centering
@@ -177,18 +177,18 @@ intrpt[3] & mlkem\_intr & ML-KEM操作完成 \\
 
 \subsection{时钟与复位架构}
 
-系统采用单一外部晶振（50 MHz）经PLL生成三个时钟域：\texttt{cpu\_clk}（约33 MHz）驱动CPU核心，\texttt{sys\_clk}（50 MHz）驱动AXI总线、DMA控制器和matmul/FFT等外设，\texttt{mlkem\_clk}（约77 MHz）通过PLL独立生成，专用于ML-KEM加速器的高吞吐计算通路。ML-KEM的AXI从机接口（\texttt{mlkem\_axi\_slave}）内部通过\texttt{Axi\_CDC}模块实现\texttt{sys\_clk}与\texttt{mlkem\_clk}之间的跨时钟域同步，将CPU的寄存器读写请求安全传递至高速计算域；ML-KEM的中断信号同样经过跨域同步后送入CPU中断系统。三个时钟域通过\texttt{set\_clock\_groups -asynchronous}约束正确隔离，各域通过\texttt{rst\_sync}模块生成同步释放的复位信号，PLL锁定信号作为复位释放的使能条件。
+系统采用单一外部晶振（50 MHz）经PLL生成三个时钟域。CPU核心运行于约33 MHz（cpu\_clk），AXI总线、DMA控制器以及matmul和FFT等外设统一运行于50 MHz（sys\_clk）。ML-KEM加速器通过PLL独立获取约77 MHz的高频时钟（mlkem\_clk），专用于其高吞吐计算通路。ML-KEM的AXI从机接口内部通过跨时钟域桥接模块实现系统总线与高速计算域之间的同步，将CPU的寄存器读写请求安全传递至高频时钟域，中断信号同样经过跨域同步后送入CPU中断系统。三个时钟域之间通过异步时钟组约束正确隔离，各域配备独立的复位同步器，以PLL锁定信号作为复位释放的使能条件。
 
 % ================================================================
 \section{核心子系统设计}
 
 \subsection{DMA与CDMA数据搬运子系统}
 
-DMA子系统是本设计中连接CPU、外部存储器和加速器的数据搬运中枢，由三个模块协同构成。
+DMA子系统是本设计中连接CPU、外部存储器和加速器的数据搬运中枢，由中央DMA控制器、matmul自动序列控制器和AXI-Lite地址分流逻辑三个模块协同构成。
 
-中央DMA控制器snix\_axil\_cdma\_mux以PORTS=4参数例化，提供4个独立的传输通道。每个通道配备独立的源地址、目的地址、传输长度和模式寄存器组，通道寄存器组基地址以0x40为步长间隔排列。DMA控制器向外暴露两组数据接口：AXI4主设备接口（mm2mm通道）连接至AXI Crossbar的Master 1端口，用于在系统存储器和外设之间发起标准AXI Burst读写传输；本地Endpoint接口（ep\_wr/ep\_rd通道）以valid/ready握手协议直接连接至matmul加速器的内部缓冲区，实现低延迟的本地数据搬运而完全绕开Crossbar的路由延迟。
+中央DMA控制器（snix\_axil\_cdma\_mux）以4通道配置例化，每通道配备独立的源地址、目的地址、传输长度和模式寄存器组，寄存器组基地址以0x40为步长间隔排列。控制器向外暴露两组数据接口：AXI4主设备接口连接至Crossbar的Master 1端口，用于在系统存储器和外设之间发起标准AXI Burst读写传输；本地Endpoint接口以valid/ready握手协议直接连接至matmul加速器的内部缓冲区，实现低延迟的本地数据搬运，该通道完全绕开Crossbar的路由延迟。
 
-matmul专用的自动序列控制器cdma\_matmul\_bridge将批量矩阵运算的数据调度从CPU的逐次寄存器操作中解放出来。CPU通过其AXI-Lite配置接口一次性设置源基地址、目的基地址、待处理的矩阵组数和各组的数据跨度后，bridge内部的硬件状态机自动循环执行以下操作序列：向CDMA发起从ExtRAM读取一组源矩阵数据至matmul输入Bank的请求，等待CDMA返回读完成信号后触发matmul计算启动脉冲，轮询matmul的done状态后向CDMA发起将结果Bank数据写回ExtRAM的请求，然后递增矩阵组索引进入下一轮循环。bridge的序列完成中断信号seq\_done\_irq与CDMA的全局传输完成信号dma\_finish经逻辑或合并后送入CPU中断系统的intrpt[1]位。
+matmul自动序列控制器（cdma\_matmul\_bridge）使批量矩阵运算的数据调度脱离了CPU的逐次寄存器操作。CPU通过其AXI-Lite配置接口一次性设置源基地址、目的基地址、待处理的矩阵组数和各组的数据跨度后，控制器内部的硬件状态机自动循环执行以下操作序列：向DMA发起从ExtRAM读取一组源矩阵数据至matmul输入Bank的请求；等待DMA返回读完成信号后触发matmul计算启动脉冲；轮询matmul的完成状态后向DMA发起将结果Bank数据写回ExtRAM的请求；递增矩阵组索引后进入下一轮循环。控制器的序列完成中断信号与DMA的全局传输完成信号经逻辑或合并后送入CPU中断系统。
 
 \begin{figure}[H]
 \centering
@@ -234,7 +234,7 @@ matmul专用的自动序列控制器cdma\_matmul\_bridge将批量矩阵运算的
 
 \subsection{矩阵乘法加速器}
 
-矩阵乘法加速器（\texttt{matmul\_axi\_slave}）根据赛事任务要求设计，完成最大4×4矩阵的乘法运算$C = A\times B$。加速器内部包含双Bank（Bank 0和Bank 1）以实现乒乓操作：一个Bank在计算时，另一个Bank可被DMA写入下一组数据。
+矩阵乘法加速器根据赛事任务要求设计，完成最大4阶矩阵乘法运算$C = A\times B$。加速器内部包含双Bank结构以实现流水化操作：一个Bank执行乘法计算时，另一个Bank可通过DMA预装载下一组输入数据。
 
 每个Bank包含独立的A矩阵缓冲区（16个32-bit字）、B矩阵缓冲区（16个32-bit字）和C结果缓冲区（16个66-bit元素拆分为48个32-bit字）。计算阵列由4个并行乘法器实例组成，每个实例负责一行结果向量的点积累加。乘法器完全采用LUT和CARRY4逻辑资源实现32乘32-bit无符号乘法，严格遵循赛事不得使用DSP资源的约束。
 
@@ -272,9 +272,7 @@ matmul专用的自动序列控制器cdma\_matmul\_bridge将批量矩阵运算的
 
 \subsection{FFT加速器}
 
-FFT加速器基于单路径延迟反馈（Single-path Delay Feedback，SDF）架构实现1024点16-bit定点FFT/IFFT。其流水线由5级SDF单元（SU1--SU5）级联构成，每级包含一个基-2蝶形单元（\texttt{Butterfly}）、一个复数乘法器（\texttt{Multiply}）和一个深度逐级减半的延迟缓冲器（\texttt{DelayBuffer}）。旋转因子由\texttt{Twiddle1024\_32B} ROM提供。
-
-FFT加速器通过\texttt{axi\_fft\_wrapper}封装为AXI从机，提供输入实部/虚部BRAM写窗口（各1024×16-bit）、输出实部/虚部BRAM读窗口和CSR控制/状态寄存器。输入输出数据采用位反转地址索引。
+FFT加速器基于单路径延迟反馈（Single-path Delay Feedback，SDF）架构实现1024点16-bit定点FFT/IFFT。其流水线由5级SDF单元级联构成，每级包含一个基-2蝶形单元、一个复数乘法器和一个深度逐级减半的延迟缓冲器。旋转因子由片上ROM提供。加速器通过AXI从机封装接口挂载于总线，提供输入实部和虚部的BRAM写窗口（各1024个16-bit字）、输出BRAM读窗口以及控制和状态寄存器。输入输出数据通过位反转地址索引实现算法要求的序映射。
 
 \begin{figure}[H]
 \centering
@@ -287,9 +285,9 @@ FFT加速器通过\texttt{axi\_fft\_wrapper}封装为AXI从机，提供输入实
 
 \subsection{ML-KEM后量子密码加速器}
 
-ML-KEM后量子密码加速器（\texttt{mlkem\_top}）是本系统中最复杂的单一加速器，完整的IP设计已在\emph{《ML-KEM后量子密钥封装硬件IP核设计与验证》}报告中详述，此处仅概述其在系统集成层面的关键特性。
+ML-KEM后量子密码加速器是本系统中最复杂的单一加速器，完整的IP设计已在\emph{《ML-KEM后量子密钥封装硬件IP核设计与验证》}报告中详述，此处仅概述其在系统集成层面的关键特性。
 
-\texttt{mlkem\_top}在单一模块内支持FIPS 203标准全部三种操作（KeyGen/Encaps/Decaps）和三种安全等级（ML-KEM-512/768/1024），通过运行时端口$k\_i$和$op\_i$实现动态选择。加速器通过\texttt{mlkem\_axi\_slave}挂载于AXI总线，提供17个内存映射寄存器用于控制、状态查询和逐字节数据装载/回读。三个直接存储器窗口（EK窗口@0x1000、DK窗口@0x2000、CT窗口@0x3000）支持DMA批量数据搬运。
+该加速器核心在单一模块内支持FIPS 203标准全部三种操作和三种安全等级，通过运行时端口实现动态选择。加速器通过AXI从机接口挂载于总线，提供内存映射寄存器用于控制、状态查询和逐字节数据装载与回读。三个直接存储器窗口（EK、DK、CT）支持DMA批量数据搬运。
 
 \begin{figure}[H]
 \centering
@@ -305,7 +303,7 @@ ML-KEM后量子密码加速器（\texttt{mlkem\_top}）是本系统中最复杂
 
 本设计采用增量集成的设计方法学。各加速器IP首先在独立仿真环境中完成模块级功能验证，确认算法正确性和接口协议合规性后，再逐步嵌入SoC顶层。集成过程涵盖五个顺序步骤。
 
-第一步是AXI从机接口适配。矩阵乘法器、FFT和ML-KEM三个加速器各自通过对应的AXI从机包装器挂载至总线——matmul\_axi\_slave提供控制寄存器和双Bank数据窗口，ML-KEM通过mlkem\_axi\_slave暴露17个内存映射寄存器和三个DMA窗口，FFT通过axi\_fft\_wrapper封装输入输出BRAM和CSR寄存器。第二步是Crossbar端口分配，根据地址空间规划在顶层soc\_top.v中完成各AXI从机与Crossbar对应端口的信号连接。FFT和ML-KEM因共享Slave 6端口，通过fft\_mlkem\_axi\_slave模块实现基于地址位[15:12]的内部二次路由。第三步涉及中断链路的连接，各加速器的完成或错误信号根据中断映射表连接至confreg中断控制器的对应输入位或CPU的直接中断输入。第四步完成时钟与复位的集成，确保各加速器的时钟信号通过PLL的对应输出端获取，复位信号通过rst\_sync模块产生与各自时钟域同步的释放时序，避免异步复位引起的亚稳态问题。第五步为软件BSP适配，在SDK中为每个加速器添加基地址宏定义、寄存器偏移量枚举和基本的读写封装函数。
+第一步是AXI从机接口适配。三个加速器各自通过对应的AXI从机包装器挂载至总线——矩阵乘法器提供控制寄存器和双Bank数据窗口，ML-KEM通过从机接口暴露内存映射寄存器和DMA窗口，FFT通过封装接口提供输入输出BRAM和状态寄存器。第二步是交叉开关端口分配，根据地址空间规划在顶层集成文件中完成各AXI从机与交叉开关对应端口的信号连接。FFT和ML-KEM因共享同一从机端口，通过内部地址译码逻辑实现基于地址位的二次路由。第三步涉及中断链路的连接，各加速器的完成或错误信号根据中断映射表连接至中断控制器的对应输入位或CPU的直接中断输入。第四步完成时钟与复位的集成，确保各加速器的时钟信号通过PLL的对应输出端获取，复位信号通过复位同步器产生与各自时钟域同步的释放时序，避免异步复位引起的亚稳态问题。第五步为软件BSP适配，在SDK中为每个加速器添加基地址宏定义、寄存器偏移量枚举和基本的读写封装函数。
 
 \subsection{DMA数据路径验证}
 
@@ -542,7 +540,7 @@ matmul FSM独热状态        &  2,151 & FDRE \\
 \end{tabular}
 \end{table}
 
-\texttt{sys\_clk}的BUFG网络以35,652个负载的扇出位居首位，这在50 MHz设计中不会构成时序问题。值得注意的是ML-KEM内部有两个高扇出网络进入前5名——\texttt{ek\_bram}的延迟寄存器链（24,670扇出）和\texttt{poly\_mul}的加载计数器（3,758扇出），前者源于字节编码器中一个组合使能信号被复制到大量并行路径，后者是多路复用地址总线的经典高扇出场景。这些高扇出网络在50 MHz下均未产生时序违例，但若频率进一步提升，可能需要插入复制寄存器或使用BUFG驱动的全局使能策略进行优化。
+全局时钟网络（sys\_clk，BUFG驱动）以35,652个负载位居首位，在当前50 MHz工作频率下不构成时序问题。ML-KEM内部有两个高扇出网络进入前5名：系数存储BRAM的延迟寄存器链（24,670扇出）源于字节编码器中一个组合使能信号被复制到大量并行路径；多项式乘法模块的加载计数器（3,758扇出）属于多路复用地址总线的经典高扇出场景。这些网络在当前工作条件下均未产生时序违例。
 
 \subsection{验证结果汇总}
 
@@ -574,7 +572,7 @@ DMA      & 序列桥批量流水 & 10组  & 100\% & 全自动循环完成 \\
 
 本设计在龙芯SoC平台上成功构建了一个集成多种硬件加速器的异构计算系统。
 
-在AXI总线集成架构方面，以AxiCrossbar\_2x8为核心互连部件，实现了CPU和DMA双主设备对8个从设备的统一地址空间访问，涵盖外部SRAM控制器、UART串口、DVI显示控制器、GPIO与定时器、DMA配置空间、FFT与ML-KEM共享加速窗口和矩阵乘法器。共享从机的内部二次路由设计——FFT与ML-KEM通过地址位[15:12]区分并共享Slave 6端口——在不增加Crossbar端口数量的前提下实现了两种加速器的无缝共存，体现了在资源受限场景下灵活地址规划的工程价值。
+在AXI总线集成架构方面，以AXI交叉开关为核心互连部件，实现了CPU和DMA双主设备对8个从设备的统一地址空间访问，涵盖外部SRAM控制器、UART串口、DVI显示控制器、GPIO与定时器、DMA配置空间、FFT与ML-KEM共享加速窗口和矩阵乘法器。共享从机的内部二次路由设计——FFT与ML-KEM通过地址高位区分并共享同一端口——在不增加交叉开关端口数量的前提下实现了两种加速器的无缝共存，体现了在资源受限场景下灵活地址规划的工程价值。
 
 在DMA数据搬运体系方面，4通道CDMA控制器与matmul自动序列控制器的协同设计显著降低了CPU在批量计算任务中的参与度。序列控制器将逐组的源数据读取、矩阵计算触发、结果写回和组索引递增等操作固化为硬件状态机的自动循环，CPU仅需在批量任务启动前一次性配置6个序列参数。三条数据路径——mem2mem直接存储搬运、本地Endpoint加速器旁路通信和序列控制器的全自动批量流水——覆盖了SoC中所有的数据传输场景。