update system design report

doc/reports/system/modules/03_matmul_batch_sequencer.md

@@ -0,0 +1,70 @@
+# 矩阵批处理序列器技术说明
+
+## 1. 模块职责
+
+`cdma_matmul_bridge` 将一次软件启动扩展为多组矩阵的完整硬件调度。模块位于 DMA 控制
+窗口偏移 `0x200`，通过通用 DMA 的外部请求接口搬运输入和可选结果，通过本地控制信号
+启动矩阵乘法器。该结构消除了 CPU 对 5000 组任务逐组配置、轮询和切换 Bank 的开销。
+
+序列器、通用 DMA 外部请求接口和矩阵本地控制接口全部工作在 `sys_clk`，因此 Bank 状态、
+request/done 和 start 信号之间为同步路径。CPU 对序列器寄存器的访问在到达本模块前已由
+CPU--SYS `Axi_CDC` 完成跨域。
+
+每组输入由两个 4x4、32 位无符号矩阵组成，共 32 个字，即 128 字节。每组结果包含
+16 个 66 位元素，以每元素三个 32 位字存储，共 192 字节。序列器使用可配置 stride，
+因此数据可以连续排列，也可嵌入更大的记录结构。
+
+## 2. 寄存器接口
+
+| 绝对偏移 | 名称 | 说明 |
+|---|---|---|
+| `0x200` | CTRL | bit 0 启动，bit 1 跳过结果写回 |
+| `0x204` | STATUS | bit 0 busy，bit 1 done；done 为 W1C |
+| `0x208` | SRC_BASE | 第一组 A/B 的物理地址 |
+| `0x20c` | DST_BASE | 第一组 C 的物理地址 |
+| `0x210` | GROUPS | 任务组数 |
+| `0x214` | MAT_BASE | 软件兼容字段，当前直接 endpoint 路径不使用 |
+| `0x218` | SRC_STRIDE | 相邻输入组地址间隔，默认 128 字节 |
+| `0x21c` | DST_STRIDE | 相邻结果组地址间隔，默认 192 字节 |
+
+配置寄存器只在序列器空闲时接受写入。启动时模块锁存是否跳过写回，清除旧完成状态，
+清零矩阵 CRC，并初始化组计数、地址计数和两个 Bank 的占用状态。`GROUPS=0` 不产生计算。
+
+## 3. 双 Bank 调度模型
+
+序列器为两个 Bank 分别维护 load active、A/B valid、compute active、store pending 和
+store active 五类状态。一个 Bank 只有在上述状态均为零时才能接收下一组输入。输入组
+按组号奇偶映射到 Bank 0/1，并在 `bank_group_idx` 中记录所属组号。
+
+调度过程包含三个可重叠阶段。装载阶段提交 128 字节 mem2ep 请求；计算阶段在 A/B
+有效后发出 `mat_start_valid` 和 Bank 号；存储阶段在计算完成后提交 192 字节 ep2mem
+请求。只要另一 Bank 可用，下一组装载可以与当前组计算或结果写回交叠。
+
+当两个 Bank 均具备计算条件时，序列器选择组号较小者，保持提交顺序。计算 Bank 被放入
+两项深度的 `compute_q`，用于把矩阵乘法器的电平 done 事件对应回具体 Bank。done 通过
+边沿检测转化为单次完成事件，防止电平保持期间重复退休同一任务。
+
+## 4. 完成与快速路径
+
+正常模式下，一组任务在结果写回的 B 响应完成后退休。快速模式设置
+`skip_result_writeback`，计算完成即退休，不再把 192 字节结果写入 ExtRAM。矩阵乘法器
+在计算结果产生时直接更新整批 CRC32，因此跳过写回不会跳过正确性判定。该模式适用于
+官方评测只检查最终 CRC、无需读取全部结果矩阵的场景。
+
+当 `groups_retired` 达到配置组数，且没有活动的装载、计算和存储任务时，序列器清除
+busy、置位 done 并拉高 `seq_done_irq`。软件通过 STATUS 的 W1C 位确认并清除完成状态。
+
+## 5. 关键不变量
+
+同一 Bank 不得同时被装载和计算，也不得在结果尚未消费时覆盖。组号只在输入请求被接受
+后递增，退休计数只响应写回完成或快速模式下的计算完成。输入和结果地址分别按 stride
+递增，不从 Bank 号反推地址。CRC 只在整批启动时清零，不在 Bank 切换时清零。
+
+这些不变量是验证的核心。若仅检查最终 done，无法发现 Bank 覆盖、组号乱序或重复退休。
+测试平台应同时观察每个 Bank 的状态向量、DMA 请求握手、矩阵 start/done 和退休计数。
+
+## 6. 当前验证范围
+
+区域赛证据包含三次 5000 组官方板级运行，三次均收到完成标志并通过 CRC。该结果验证了
+长序列快速模式的主要数据流，但不等价于覆盖所有边界。模块级回归仍应包含组数 1、2、3，
+两种写回模式，不同 stride，DMA 读写反压，以及 done W1C 后立即启动下一批等场景。