update system design report

doc/reports/system/modules/02_dma_subsystem.md

@@ -0,0 +1,83 @@
+# 通用 DMA 子系统技术说明
+
+## 1. 功能与组成
+
+DMA 子系统位于 `rtl/ip/cdma/`，对软件提供四个逻辑通道，对系统提供一个 32 位 AXI4
+主端，并对矩阵乘法器提供 32 位本地 endpoint。当前顶层实例参数为 `PORTS=4`、
+`DATA_WIDTH=32`、`FIFO_DEPTH=64`。源码中的“8 通道”实例名和注释是历史名称，实际
+综合配置应以参数值四通道为准。
+
+子系统由三部分组成。`snix_axil_cdma_mux` 实现通道寄存器、轮询仲裁、传输模式选择和
+AXI 主端复用；`snix_axi_mm2mm` 实现普通内存到内存的 burst 搬运；本地 endpoint 状态机
+实现内存与矩阵双 Bank 之间的数据传递。同步 FIFO 和 AXIS FIFO 用于隔离 AXI 读、写
+通道的反压。
+
+## 2. 软件接口
+
+每个通道占用 `0x40` 字节，通道 `n` 的偏移基址为 `n*0x40`。
+
+| 偏移 | 名称 | 说明 |
+|---|---|---|
+| `0x00` | SRC_ADDR | 源物理地址 |
+| `0x04` | DST_ADDR | 目的物理地址 |
+| `0x08` | LENGTH | 传输字节数 |
+| `0x0c` | TAG | 软件标记，硬件不解释 |
+| `0x10` | CTRL | bit 0 启动，bits 5:3 为 AxSIZE，bits 13:6 为 AxLEN |
+| `0x14` | STATUS | bit 0 busy，bit 1 done；done 采用 W1C |
+| `0x18` | MODE | 0 为 mem2mem，1 为 mem2ep，2 为 ep2mem |
+| `0x1c` | EP_CFG | bits 3:0 Bank，bits 15:8 word offset，bits 19:16 endpoint ID |
+
+通道处于 busy 时，源地址、目的地址、长度、模式和 endpoint 配置不再接受修改。新启动
+请求会清除旧 done，硬件完成与软件 W1C 同周期发生时以硬件置位优先，避免丢失完成事件。
+所有地址均为物理地址，长度以字节计。
+
+## 3. 通道仲裁
+
+`snix_axil_cdma_mux` 为四个通道维护独立的请求位和完成位，但共享一个实际搬运引擎。
+仲裁器从 `rr_ptr` 开始循环检查待处理通道，选中后锁存 `cur_ch`，在 START 状态发出单拍
+`engine_start`，在 RUN 状态等待对应引擎完成。完成后设置该通道 done，并将轮询指针
+移动到下一通道。该结构保证长期存在的请求不会固定占用最低编号优先级。
+
+共享引擎意味着四个通道可以独立排队，但不能同时占用 AXI 主端。多通道的主要收益是
+减少软件串行配置依赖并提供公平排队，而不是形成四路并行 AXI 数据流。
+
+## 4. 内存到内存路径
+
+`snix_axi_mm2mm` 的控制状态依次为 IDLE、PREP1、PREP2、AR、READ、AW、WRITE 和
+WAIT_BRESP。引擎先计算本次 burst 的实际长度，发出 INCR 读请求，将 R 通道数据写入
+FIFO，再发出对应写请求并从 FIFO 驱动 W 通道。最后一个写响应返回后，若仍有剩余字节，
+引擎更新源地址和目的地址并处理下一 burst。
+
+读数据只在 READ 状态接收，写数据只在 WRITE 状态发送。该门控防止非活动状态下的
+AXI beat 被误计数。末尾不足一个数据宽度时由 `WSTRB` 屏蔽无效字节。当前 SoC 数据宽度
+为 32 bit，常用配置为 AxSIZE=2，即每 beat 4 字节。
+
+## 5. 本地 endpoint 路径
+
+mem2ep 模式从 AXI 地址读取数据，并逐字送往 `ep_wr_valid/ready`；ep2mem 模式通过
+`ep_rd_valid/ready` 读取本地结果，再发出 AXI 写事务。endpoint 接口附带 endpoint ID、
+Bank 号和字地址，因此无需把矩阵双 Bank 映射回 Crossbar，也避免每个 32 位字再次经过
+从端地址译码。
+
+矩阵批处理序列器还可通过 `ext_rd_req_*` 和 `ext_wr_req_*` 直接提交一次外部请求。这组
+请求优先占用 AXI 主端，并在通用通道引擎空闲时接收。读请求完成后产生单拍
+`ext_rd_req_done`，写请求在 B 响应返回后产生 `ext_wr_req_done`。该接口用于流水调度，
+减少序列器重复写入通道 CSR 的延迟。
+
+## 6. 复位与反压
+
+当前集成的 DMA 通道寄存器、仲裁器、mem2mem 引擎、endpoint 引擎和 AXI 主端均工作在
+`sys_clk`，内部不存在活动的异步时钟边界。仓库保留的 `snix_async_fifo` 未被当前
+`soc_top` 层次实例化；实际数据 FIFO 为同一 SYS 域内的同步 FIFO。
+
+所有控制状态、通道请求和完成位在 `rst_n=0` 时清零。AXI 与 endpoint 均遵循
+valid/ready 规则：发送端在握手前保持数据和控制字段，接收端可通过 ready 插入反压。
+目前 endpoint 只按 32 位数据宽度实现，字节数不是 4 的整数倍时不应使用该路径。
+
+## 7. 验证方法与限制
+
+DMA 验证至少应覆盖不同 burst 长度、末尾非满 beat、四通道公平性、R/W 反压、
+mem2mem、mem2ep、ep2mem 和 W1C 竞态。当前板级 FFT DMA 和 ML-KEM DMA 测试证明了
+普通外设窗口搬运路径，矩阵评测证明了外部请求与本地 endpoint 路径。当前实现未设置
+总线超时和错误恢复状态，若 AXI 从端永久不响应，通道会保持 busy；因此系统集成时必须
+保证目标地址有效，或在后续版本增加 watchdog 和错误码。