# 4x4 矩阵乘法加速器技术说明

## 1. 计算规格

`matmul_axi_slave` 计算两个 4x4 无符号整数矩阵的乘积。输入元素宽度为 32 bit，输出
元素满足

`C[i][j] = sum(A[i][k] * B[k][j]), k=0..3`。

单个乘积为 64 bit，四项相加的最坏情况需要 66 bit，因此结果存储宽度固定为 66 bit。
每个输出元素通过三个 32 位字传输：低 32 位、高 32 位以及最高 2 位。该布局使 AXI 和
DMA 数据宽度保持 32 bit，同时不截断数学结果。

## 2. 接口组成

模块同时提供完整 AXI4 从接口、本地 DMA endpoint 和矩阵序列器直连控制接口。AXI
接口支持 INCR burst，可由 CPU 或普通 DMA 访问控制寄存器及双 Bank 数据窗口。本地
endpoint 直接接收 A/B 字或输出 C 字，不经过 Crossbar 的矩阵从端。序列器通过
`mat_start_valid`、`mat_start_bank`、`mat_done_clear` 和 `mat_crc_clear` 完成批处理控制。

矩阵 AXI 从端、endpoint、乘法流水线和 CRC 均使用 `sys_clk/sys_resetn`。DMA 和序列器也
位于 SYS 域，三者之间没有 CDC。CPU 发起的矩阵访问在 Crossbar 之前已经跨入 SYS 域。
`matmul_intr` 产生于 SYS 域，接入 CPU 前的时钟边界见独立时钟域说明。

两个 endpoint ready 在当前实现中恒为 1，表示矩阵本地缓冲不施加反压。上游仍必须只在
目标 Bank 空闲时写入，Bank 所有权由批处理序列器保证，而不是由加速器内部检查。

## 3. 寄存器与双 Bank 布局

| 偏移 | 内容 | 说明 |
|---|---|---|
| `0x000` | CTRL | bit 0 请求 Bank 0，bit 1 请求 Bank 1 |
| `0x004` | STATUS | busy、done、error；done/error 支持 W1C |
| `0x010` | CRC32 | 返回 `crc_reg XOR 0xffff_ffff`；写入用于清零 CRC |
| `0x100` | Bank 0 A | 16 个 32 位元素 |
| `0x140` | Bank 0 B | 16 个 32 位元素 |
| `0x180` | Bank 0 C | 16 个 66 位元素，共 48 个 32 位字 |
| `0x300` | Bank 1 A | 16 个 32 位元素 |
| `0x340` | Bank 1 B | 16 个 32 位元素 |
| `0x380` | Bank 1 C | 16 个 66 位元素，共 48 个 32 位字 |

A 和 B 均按行优先方式存储。endpoint 写地址 0--15 对应 A，16--31 对应 B；endpoint
读地址 0--47 对应 C 的三字布局。双 Bank 允许一组数据计算时准备另一组，但计算核心
本身一次只处理一个 Bank。

## 4. 乘法数据通路

核心包含四个 `pipelined_mult_32x32` 实例，并使用 `use_dsp="no"` 属性约束综合器将乘法
映射到 LUT 逻辑。每个乘法器包含输入寄存、乘积寄存和输出寄存三个流水级，吞吐率为
每周期一个乘积。

计算核心每周期选择一个输出元素 `(i,j)`，同时向四个乘法器发出
`A[i][0..3]` 与 `B[0..3][j]`。流水线对齐后，四个 64 位乘积采用成对加法生成一个
66 位结果。16 个输出元素连续发射，索引和 Bank 标识经过四级有效流水线与乘积对齐。
因此稳态吞吐为每周期一个 C 元素，而不是逐项乘加的四周期结构。

当 Bank 0 完成且 Bank 1 已有待处理请求时，状态机可直接调用 `start_calc_bank` 切换
Bank，不必先返回空闲态。最后一个有效结果写回时产生 `calc_done_pulse`，置位 done 并
驱动电平型中断。

## 5. CRC32 数据通路

CRC 使用 IEEE 802.3 反射多项式 `0xedb8_8320`，初值为 `0xffff_ffff`，软件读取时执行
末尾异或。每个 66 位 C 元素按低 32 位、高 32 位、最高 2 位补零三个字依次进入
`crc32_word_next`。CRC 在计算结果有效时更新，与 CPU 或 DMA 是否读取 C 无关。

这一选择使快速评测可以关闭结果写回，只保留硬件计算与 CRC。CRC 顺序严格跟随输出
元素发射顺序；整批任务开始时由序列器清零，Bank 切换和单组完成不会清零。

## 6. AXI 协议处理

写通道分别处理 AW、W 和 B 阶段，锁存 ID、burst 类型和起始地址；INCR burst 每次有效
W 握手后地址增加 4。读通道锁存 AR 参数并连续产生 R beat，最后一拍置位 RLAST。
无效写地址置位 error，响应码当前始终为 OKAY。输出 C 的组合读选择在当前地址上解析
元素号和三字片段。

## 7. 验证要求

功能验证需要逐元素与 128 bit 或更宽的软件参考模型比较，覆盖全零、全 `0xffff_ffff`、
单位矩阵和随机矩阵。协议验证需覆盖 AW/W 分离、R/B 反压、单 beat 与 burst、两个 Bank
连续请求和非法地址。CRC 应独立比较完整 192 字节输出序列。当前官方板测只读取最终
CRC，证明了长批处理的端到端一致性，但不能替代逐元素和 AXI 边界测试。