# 通用 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 和错误码。