docs: add competition summary and reorganize reports

- add 比赛总结
- rename AXI bus/module docs to 总线模块说明
- add README overview

doc/总线模块说明.md

@@ -0,0 +1,570 @@
+# AXI 总线模块说明
+
+本文档基于 `full` 分支的 `rtl/soc_top.v`、各 AXI 外设源码和软件头文件整理，用于说明当前 SoC 中 AXI 总线上的模块作用、端口含义和寄存器地址。
+
+## 1. 总体连接关系
+
+顶层 AXI 互连为 `AxiCrossbar_2x8`。它有 2 个 AXI master 输入和 8 个 AXI slave 输出。
+
+### 1.1 AXI master 输入
+
+| Crossbar 端口 | 顶层连接 | 作用 |
+| --- | --- | --- |
+| `axiIn_0_*` | `core_top` 经 `Axi_CDC` 后的 `cpu_sync_*` | CPU 访问内存、外设和加速器 |
+| `axiIn_1_*` | `snix_axil_cdma_mux` 的 `dma_m_*` / `mm2mm_*` | DMA/CDMA 作为 AXI master 发起内存和外设数据搬运 |
+
+### 1.2 AXI slave 输出和地址窗口
+
+| Crossbar 端口 | 物理地址窗口 | 常用非缓存虚拟地址窗口 | 顶层连接 | 作用 |
+| --- | --- | --- | --- | --- |
+| `axiOut_0_*` | `0x1c000000` - `0x1c7fffff` | 软件通常直接使用物理地址 | `axi_wrap_ram_sp_external` | BaseRAM/ExtRAM 存储子系统 |
+| `axiOut_1_*` | `0x00000000` - `0x007fffff` | 无 | reserved tie-off | 保留窗口，当前返回空响应 |
+| `axiOut_2_*` | `0x1f000000` - `0x1f0fffff` | `0xbf000000` - `0xbf0fffff` | `axi_uart_controller` | UART0 |
+| `axiOut_3_*` | `0x1f100000` - `0x1f1fffff` | `0xbf100000` - `0xbf1fffff` | `axi_dvi` | 视频输出 |
+| `axiOut_4_*` | `0x1f200000` - `0x1f2fffff` | `0xbf200000` - `0xbf2fffff` | `confreg` | LED、数码管、按键、开关、定时器、中断 |
+| `axiOut_5_*` | `0x1f300000` - `0x1f3fffff` | `0xbf300000` - `0xbf3fffff` | `axi_axil_adapter` -> DMA/CDMA | DMA 配置窗口 |
+| `axiOut_6_*` | `0x1f400000` - `0x1f4fffff` | `0xbf400000` - `0xbf4fffff` | `fft_mlkem_axi_slave` | FFT、ML-KEM 共享窗口 |
+| `axiOut_7_*` | `0x1f500000` - `0x1f5fffff` | `0xbf500000` - `0xbf5fffff` | `matmul_axi_slave` | 矩阵乘法加速器 |
+
+说明：软件中的 `0xbfxxxxxx` 地址是 Loongson/LoongArch 非缓存映射地址；硬件 crossbar 实际译码使用 `0x1fxxxxxx` 等物理地址。
+
+## 2. AXI 信号字典
+
+多个模块使用完全相同的 AXI4 或 AXI-Lite 端口。后续各模块只列出端口前缀，例如 `ram_*`、`uart_*`、`s_axi_*`、`dma_m_*`。这些前缀下的每个信号含义按本节解释。
+
+### 2.1 AXI4 slave 接口信号
+
+适用于 `axi_wrap_ram_sp_external`、`axi_uart_controller`、`axi_dvi`、`confreg`、`fft_mlkem_axi_slave`、`mlkem_axi_slave`、`matmul_axi_slave` 等模块。
+
+| 信号 | 方向，以 slave 模块为准 | 含义 |
+| --- | --- | --- |
+| `clk` / `aclk` | input | AXI 总线时钟。当前大多数 slave 使用 `sys_clk`。 |
+| `resetn` / `aresetn` / `rst_n` | input | 低有效复位，已在顶层同步。 |
+| `s_axi_awid` / `axi_awid` | input | 写地址事务 ID，用于响应通道返回对应 ID。 |
+| `s_axi_awaddr` / `axi_awaddr` | input | 写地址。模块通常使用低位做内部寄存器偏移。 |
+| `s_axi_awlen` / `axi_awlen` | input | 突发长度，表示 beats-1。 |
+| `s_axi_awsize` / `axi_awsize` | input | 每个 beat 的字节数编码，`2` 表示 4 字节。 |
+| `s_axi_awburst` / `axi_awburst` | input | 突发类型，常用 `INCR`。 |
+| `s_axi_awlock` / `axi_awlock` | input | AXI lock 属性，本设计基本不使用。 |
+| `s_axi_awcache` / `axi_awcache` | input | cache 属性，本设计通常透传或忽略。 |
+| `s_axi_awprot` / `axi_awprot` | input | protection 属性，本设计通常透传或忽略。 |
+| `s_axi_awvalid` / `axi_awvalid` | input | 写地址有效。 |
+| `s_axi_awready` / `axi_awready` | output | slave 可接收写地址。 |
+| `s_axi_wid` | input | 写数据 ID。部分 AXI4 实现保留，很多模块不使用。 |
+| `s_axi_wdata` / `axi_wdata` | input | 写数据。 |
+| `s_axi_wstrb` / `axi_wstrb` | input | 写字节使能，bit0 对应低 8 位。 |
+| `s_axi_wlast` / `axi_wlast` | input | 写突发最后一拍。 |
+| `s_axi_wvalid` / `axi_wvalid` | input | 写数据有效。 |
+| `s_axi_wready` / `axi_wready` | output | slave 可接收写数据。 |
+| `s_axi_bid` / `axi_bid` | output | 写响应 ID。 |
+| `s_axi_bresp` / `axi_bresp` | output | 写响应状态，当前外设一般返回 `OKAY=2'b00`。 |
+| `s_axi_bvalid` / `axi_bvalid` | output | 写响应有效。 |
+| `s_axi_bready` / `axi_bready` | input | master 可接收写响应。 |
+| `s_axi_arid` / `axi_arid` | input | 读地址事务 ID。 |
+| `s_axi_araddr` / `axi_araddr` | input | 读地址。 |
+| `s_axi_arlen` / `axi_arlen` | input | 读突发长度，表示 beats-1。 |
+| `s_axi_arsize` / `axi_arsize` | input | 每个读 beat 的字节数编码。 |
+| `s_axi_arburst` / `axi_arburst` | input | 读突发类型，常用 `INCR`。 |
+| `s_axi_arlock` / `axi_arlock` | input | AXI lock 属性，本设计基本不使用。 |
+| `s_axi_arcache` / `axi_arcache` | input | cache 属性，本设计通常透传或忽略。 |
+| `s_axi_arprot` / `axi_arprot` | input | protection 属性，本设计通常透传或忽略。 |
+| `s_axi_arvalid` / `axi_arvalid` | input | 读地址有效。 |
+| `s_axi_arready` / `axi_arready` | output | slave 可接收读地址。 |
+| `s_axi_rid` / `axi_rid` | output | 读响应 ID。 |
+| `s_axi_rdata` / `axi_rdata` | output | 读数据。 |
+| `s_axi_rresp` / `axi_rresp` | output | 读响应状态，当前外设一般返回 `OKAY=2'b00`。 |
+| `s_axi_rlast` / `axi_rlast` | output | 读突发最后一拍。 |
+| `s_axi_rvalid` / `axi_rvalid` | output | 读数据有效。 |
+| `s_axi_rready` / `axi_rready` | input | master 可接收读数据。 |
+
+### 2.2 AXI4 master 接口信号
+
+适用于 `snix_axil_cdma_mux` 的 `mm2mm_*` / 顶层 `dma_m_*`。信号名称与 AXI4 slave 一致，但方向相反：`awaddr/araddr/wdata/wstrb/valid/ready` 等由 DMA master 发起，crossbar/slave 返回 ready、response 和 read data。
+
+| 信号组 | 方向，以 DMA 为准 | 含义 |
+| --- | --- | --- |
+| `mm2mm_aw*` | output/input | DMA 写地址通道，用于向目标地址发起写事务。 |
+| `mm2mm_w*` | output/input | DMA 写数据通道。 |
+| `mm2mm_b*` | input/output | DMA 写响应通道。 |
+| `mm2mm_ar*` | output/input | DMA 读地址通道，用于从源地址发起读事务。 |
+| `mm2mm_r*` | input/output | DMA 读数据通道。 |
+| `mm2mm_awqos/arqos` | output | AXI QoS，顶层未使用。 |
+| `mm2mm_awuser/wuser/aruser` | output | AXI user sideband，顶层未使用。 |
+| `mm2mm_buser/ruser` | input | AXI user sideband，顶层绑常量。 |
+
+### 2.3 AXI-Lite slave 接口信号
+
+适用于 `snix_axil_cdma_mux` 和 `cdma_matmul_bridge` 的配置接口。
+
+| 信号 | 方向，以 AXI-Lite slave 为准 | 含义 |
+| --- | --- | --- |
+| `s_axil_awaddr` | input | AXI-Lite 写地址。 |
+| `s_axil_awvalid` | input | 写地址有效。 |
+| `s_axil_awready` | output | slave 可接收写地址。 |
+| `s_axil_wdata` | input | 写数据。 |
+| `s_axil_wstrb` | input | 写字节使能。 |
+| `s_axil_wvalid` | input | 写数据有效。 |
+| `s_axil_wready` | output | slave 可接收写数据。 |
+| `s_axil_bresp` | output | 写响应状态。 |
+| `s_axil_bvalid` | output | 写响应有效。 |
+| `s_axil_bready` | input | master 可接收写响应。 |
+| `s_axil_araddr` | input | AXI-Lite 读地址。 |
+| `s_axil_arvalid` | input | 读地址有效。 |
+| `s_axil_arready` | output | slave 可接收读地址。 |
+| `s_axil_rdata` | output | 读数据。 |
+| `s_axil_rresp` | output | 读响应状态。 |
+| `s_axil_rvalid` | output | 读数据有效。 |
+| `s_axil_rready` | input | master 可接收读数据。 |
+
+## 3. 各 AXI 模块作用与端口
+
+### 3.1 `AxiCrossbar_2x8`
+
+作用：系统 AXI 主互连。它将 CPU 和 DMA 两个 master 的读写请求按地址译码转发到 8 个 slave，并负责读写响应返回。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | crossbar 工作时钟，顶层连接 `sys_clk`。 |
+| `resetn` | input | 低有效复位，顶层连接 `sys_resetn`。 |
+| `axiIn_0_*` | input/output | CPU 侧 AXI master 接口，信号含义见 AXI4 字典。 |
+| `axiIn_1_*` | input/output | DMA/CDMA 侧 AXI master 接口，信号含义见 AXI4 字典。 |
+| `axiOut_0_*` | output/input | RAM AXI slave 接口。 |
+| `axiOut_1_*` | output/input | 保留 AXI slave 接口，顶层 tie-off。 |
+| `axiOut_2_*` | output/input | UART AXI slave 接口。 |
+| `axiOut_3_*` | output/input | DVI AXI slave 接口。 |
+| `axiOut_4_*` | output/input | confreg AXI slave 接口。 |
+| `axiOut_5_*` | output/input | DMA 配置 AXI slave 接口。 |
+| `axiOut_6_*` | output/input | FFT/ML-KEM AXI slave 接口。 |
+| `axiOut_7_*` | output/input | matmul AXI slave 接口。 |
+
+### 3.2 `core_top` 与 `Axi_CDC`
+
+作用：`core_top` 是 CPU；`Axi_CDC` 将 CPU 时钟域的 AXI 请求同步到 `sys_clk` 域，再送入 crossbar master 0。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `core_top.aclk` | input | CPU 时钟 `cpu_clk`。 |
+| `core_top.aresetn` | input | CPU 低有效复位 `cpu_resetn`。 |
+| `core_top.intrpt[7:0]` | input | CPU 中断输入。当前 `{4'd0, mlkem_intr, matmul_intr, dma_finish, confreg_int}`。 |
+| `core_top.ar*/r*/aw*/w*/b*` | input/output | CPU AXI master 接口。 |
+| `core_top.debug0_*` | output | CPU 写回级调试信号。 |
+| `Axi_CDC.axiInClk/axiInRstn` | input | CPU 侧时钟/复位。 |
+| `Axi_CDC.axiOutClk/axiOutRstn` | input | crossbar 侧时钟/复位。 |
+| `Axi_CDC.axiIn_*` | input/output | CPU 侧 AXI 信号。 |
+| `Axi_CDC.axiOut_*` | output/input | `sys_clk` 域 AXI 信号，连接 crossbar master 0。 |
+
+### 3.3 `axi_wrap_ram_sp_external`
+
+作用：SRAM 子系统的 AXI slave 包装器。它把 AXI 读写转换为异步 SRAM 控制信号，并根据内部地址 bit22 选择 BaseRAM 或 ExtRAM。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `aclk` | input | AXI/SRAM 控制器时钟，连接 `sys_clk`。 |
+| `aresetn` | input | 低有效复位。 |
+| `axi_ar*/axi_r*/axi_aw*/axi_w*/axi_b*` | input/output | RAM 的 AXI4 slave 接口，连接 crossbar `axiOut_0_*`。 |
+| `base_ram_data[31:0]` | inout | BaseRAM 双向数据总线。写周期由控制器驱动，读周期为高阻输入。 |
+| `base_ram_addr[19:0]` | output | BaseRAM 字地址，来自 `soc_sram_addr[21:2]`。 |
+| `base_ram_be_n[3:0]` | output | BaseRAM 字节使能，低有效。 |
+| `base_ram_ce_n` | output | BaseRAM 片选，低有效。 |
+| `base_ram_oe_n` | output | BaseRAM 读使能，低有效。 |
+| `base_ram_we_n` | output | BaseRAM 写使能，低有效。 |
+| `ext_ram_data[31:0]` | inout | ExtRAM 双向数据总线。 |
+| `ext_ram_addr[19:0]` | output | ExtRAM 字地址，来自 `soc_sram_addr[21:2]`。 |
+| `ext_ram_be_n[3:0]` | output | ExtRAM 字节使能，低有效。 |
+| `ext_ram_ce_n` | output | ExtRAM 片选，低有效。 |
+| `ext_ram_oe_n` | output | ExtRAM 读使能，低有效。 |
+| `ext_ram_we_n` | output | ExtRAM 写使能，低有效。 |
+
+地址说明：`0x1c000000` - `0x1c3fffff` 选择 BaseRAM，`0x1c400000` - `0x1c7fffff` 选择 ExtRAM。
+
+### 3.4 reserved window
+
+作用：`axiOut_1_*` 是保留窗口，顶层没有接实际模块。读数据返回 0，写请求直接 ready/空响应。该窗口不建议软件使用。
+
+### 3.5 `axi_uart_controller`
+
+作用：AXI 到 APB/UART 控制器。CPU 通过 AXI 访问 16550 风格 UART 寄存器，实现串口收发和中断。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | UART AXI/APB 时钟，连接 `sys_clk`。 |
+| `rst_n` | input | 低有效复位。 |
+| `axi_s_*` | input/output | UART 的 AXI4 slave 接口，连接 crossbar `axiOut_2_*`。 |
+| `apb_rw_dma` | input | DMA APB 访问方向，顶层绑 0，当前未使用。 |
+| `apb_psel_dma` | input | DMA APB 片选，顶层绑 0。 |
+| `apb_enab_dma` | input | DMA APB enable，顶层绑 0。 |
+| `apb_addr_dma[19:0]` | input | DMA APB 地址，顶层绑 0。 |
+| `apb_valid_dma` | input | DMA APB 请求有效，顶层绑 0。 |
+| `apb_wdata_dma[31:0]` | input | DMA APB 写数据，顶层绑 0。 |
+| `apb_rdata_dma[31:0]` | output | DMA APB 读数据，顶层未使用。 |
+| `apb_ready_dma` | output | DMA APB ready，顶层未使用。 |
+| `dma_grant` | output | APB mux 对 DMA 的授权，顶层未使用。 |
+| `dma_req_o` | output | UART 控制器内部 DMA 请求，顶层未使用。 |
+| `dma_ack_i` | input | DMA ack，顶层绑 0。 |
+| `uart0_txd_i` | input | UART TX 管脚回读输入。 |
+| `uart0_txd_o` | output | UART TX 输出值。 |
+| `uart0_txd_oe` | output | UART TX 输出使能；顶层用它控制三态。 |
+| `uart0_rxd_i` | input | UART RX 输入值。 |
+| `uart0_rxd_o` | output | UART RX 输出值，三态模式下使用。 |
+| `uart0_rxd_oe` | output | UART RX 输出使能。 |
+| `uart0_rts_o` | output | UART RTS 调制解调控制输出。 |
+| `uart0_dtr_o` | output | UART DTR 调制解调控制输出。 |
+| `uart0_cts_i` | input | UART CTS 输入。 |
+| `uart0_dsr_i` | input | UART DSR 输入。 |
+| `uart0_dcd_i` | input | UART DCD 输入。 |
+| `uart0_ri_i` | input | UART RI 输入。 |
+| `uart0_int` | output | UART0 中断，送入 confreg 中断控制。 |
+
+### 3.6 `axi_dvi`
+
+作用：AXI 可配置的视频输出控制器。软件写入矩形/方形参数，模块产生 VGA/DVI 时序和 RGB 输出。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `aclk` | input | DVI 控制器和像素时钟来源。 |
+| `aresetn` | input | 低有效复位。 |
+| `s_aw*/s_w*/s_b*/s_ar*/s_r*` | input/output | DVI 的 AXI4 slave 接口，连接 crossbar `axiOut_3_*`。 |
+| `video_clk` | output | 视频像素时钟输出。 |
+| `hsync` | output | 行同步信号。 |
+| `vsync` | output | 场同步信号。 |
+| `data_enable` | output | 有效显示区域指示。 |
+| `video_red[2:0]` | output | 红色像素分量。 |
+| `video_green[2:0]` | output | 绿色像素分量。 |
+| `video_blue[1:0]` | output | 蓝色像素分量。 |
+
+### 3.7 `confreg`
+
+作用：基础外设和中断控制寄存器模块。它负责 LED、数码管、拨码开关、触摸按键、系统定时器、中断状态聚合和仿真标志。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `aclk` | input | AXI 外设时钟，连接 `sys_clk`。 |
+| `aresetn` | input | 低有效 AXI 复位。 |
+| `cpu_clk` | input | CPU 时钟，当前传入但主要逻辑在 `aclk` 域。 |
+| `cpu_resetn` | input | CPU 低有效复位。 |
+| `s_aw*/s_w*/s_b*/s_ar*/s_r*` | input/output | confreg 的 AXI4 slave 接口，连接 crossbar `axiOut_4_*`。 |
+| `led[15:0]` | output | 16 位 LED 输出。 |
+| `dpy0[7:0]` | output | 低位数码管输出。 |
+| `dpy1[7:0]` | output | 高位数码管输出。 |
+| `switch[31:0]` | input | 32 位拨码开关输入。 |
+| `touch_btn[3:0]` | input | 4 位触摸按键输入。 |
+| `uart0_int` | input | UART 中断输入，映射到 confreg 中断源 bit5。 |
+| `fft_finish` | input | FFT 完成输入，映射到 confreg 中断源 bit6。 |
+| `confreg_int` | output | confreg 聚合后的中断输出，送入 CPU `intrpt[0]`。 |
+
+### 3.8 `axi_axil_adapter`
+
+作用：把 crossbar `axiOut_5_*` 的 AXI4 slave 访问转换为 AXI-Lite 访问，供 DMA/CDMA 配置寄存器使用。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | adapter 时钟，连接 `sys_clk`。 |
+| `rst` | input | 高有效复位，顶层连接 `~sys_resetn`。 |
+| `s_axi_*` | input/output | AXI4 slave 侧，连接 crossbar `axiOut_5_*`。 |
+| `m_axil_*` | output/input | AXI-Lite master 侧，连接 DMA 配置分流逻辑。 |
+
+### 3.9 `snix_axil_cdma_mux`
+
+作用：多通道 CDMA 控制器。它有 AXI-Lite 配置接口、AXI4 `mm2mm` master 数据搬运接口，以及本地 endpoint 接口。当前顶层参数 `PORTS=4`，即 4 个软件可见 DMA 通道。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | CDMA 时钟，连接 `sys_clk`。 |
+| `rst_n` | input | 低有效复位。 |
+| `s_axil_*` | input/output | AXI-Lite 配置 slave 接口，来自 `axi_axil_adapter` 且未命中 bridge 子窗口时进入本模块。 |
+| `mm2mm_aw* / mm2mm_w* / mm2mm_b* / mm2mm_ar* / mm2mm_r*` | output/input | AXI4 master 数据搬运接口，连接 crossbar `axiIn_1_*`。 |
+| `ep_wr_valid` | output | 向本地 endpoint 写数据请求有效。当前连接 matmul。 |
+| `ep_wr_id[3:0]` | output | endpoint 编号。当前 matmul 使用 id 0。 |
+| `ep_wr_bank[3:0]` | output | endpoint bank 选择。当前 matmul 使用 bank0/bank1。 |
+| `ep_wr_word_addr[7:0]` | output | endpoint 内部 word 地址。 |
+| `ep_wr_data[31:0]` | output | 写入 endpoint 的 32 位数据。 |
+| `ep_wr_ready` | input | endpoint 可接收写数据。 |
+| `ep_rd_valid` | output | 从 endpoint 读数据请求有效。 |
+| `ep_rd_id[3:0]` | output | endpoint 编号。 |
+| `ep_rd_bank[3:0]` | output | endpoint bank 选择。 |
+| `ep_rd_word_addr[7:0]` | output | endpoint 内部 word 地址。 |
+| `ep_rd_data[31:0]` | input | endpoint 返回的 32 位数据。 |
+| `ep_rd_ready` | input | endpoint 读数据有效/可被采样。 |
+| `ext_rd_req_valid` | input | 外部序列器请求“内存到 endpoint”搬运。当前来自 `cdma_matmul_bridge`。 |
+| `ext_rd_req_ready` | output | CDMA 可接收外部读请求。 |
+| `ext_rd_req_src[31:0]` | input | 外部读请求的内存源地址。 |
+| `ext_rd_req_bytes[31:0]` | input | 外部读请求字节数。 |
+| `ext_rd_req_ep_id[3:0]` | input | 外部读请求目标 endpoint id。 |
+| `ext_rd_req_ep_bank[3:0]` | input | 外部读请求目标 endpoint bank。 |
+| `ext_rd_req_ep_word_off[7:0]` | input | 外部读请求目标 endpoint word 偏移。 |
+| `ext_rd_req_done` | output | 外部读请求完成脉冲/标志。 |
+| `ext_wr_req_valid` | input | 外部序列器请求“endpoint 到内存”搬运。 |
+| `ext_wr_req_ready` | output | CDMA 可接收外部写请求。 |
+| `ext_wr_req_dst[31:0]` | input | 外部写请求的内存目的地址。 |
+| `ext_wr_req_bytes[31:0]` | input | 外部写请求字节数。 |
+| `ext_wr_req_ep_id[3:0]` | input | 外部写请求源 endpoint id。 |
+| `ext_wr_req_ep_bank[3:0]` | input | 外部写请求源 endpoint bank。 |
+| `ext_wr_req_ep_word_off[7:0]` | input | 外部写请求源 endpoint word 偏移。 |
+| `ext_wr_req_done` | output | 外部写请求完成脉冲/标志。 |
+| `dma_finish` | output | DMA 完成中断/状态输出，送入顶层 `dma_finish` 合并逻辑。 |
+
+### 3.10 `cdma_matmul_bridge`
+
+作用：matmul 专用 CDMA 序列控制器。CPU 配置输入基地址、输出基地址、组数和 stride 后，它自动向 `snix_axil_cdma_mux` 发起 endpoint 读写请求，并直接控制 matmul 启动、清状态、清 CRC。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | bridge 时钟，连接 `sys_clk`。 |
+| `rst_n` | input | 低有效复位。 |
+| `s_axil_*` | input/output | AXI-Lite 配置 slave 接口。当 DMA 配置地址 `[11:8] == 4'h2` 时访问本模块。 |
+| `cdma_rd_req_valid` | output | 请求 CDMA 从内存读取数据到 matmul endpoint。 |
+| `cdma_rd_req_ready` | input | CDMA 可接收读请求。 |
+| `cdma_rd_req_src[31:0]` | output | 读请求内存源地址。 |
+| `cdma_rd_req_bytes[31:0]` | output | 读请求字节数，matmul 输入固定为 128B。 |
+| `cdma_rd_req_ep_id[3:0]` | output | 读请求目标 endpoint id。 |
+| `cdma_rd_req_ep_bank[3:0]` | output | 读请求目标 matmul bank。 |
+| `cdma_rd_req_ep_word_off[7:0]` | output | 读请求目标 endpoint word 偏移。 |
+| `cdma_rd_req_done` | input | CDMA 读请求完成。 |
+| `cdma_wr_req_valid` | output | 请求 CDMA 从 matmul endpoint 写回内存。 |
+| `cdma_wr_req_ready` | input | CDMA 可接收写请求。 |
+| `cdma_wr_req_dst[31:0]` | output | 写请求内存目的地址。 |
+| `cdma_wr_req_bytes[31:0]` | output | 写请求字节数，matmul 输出固定为 192B。 |
+| `cdma_wr_req_ep_id[3:0]` | output | 写请求源 endpoint id。 |
+| `cdma_wr_req_ep_bank[3:0]` | output | 写请求源 matmul bank。 |
+| `cdma_wr_req_ep_word_off[7:0]` | output | 写请求源 endpoint word 偏移。 |
+| `cdma_wr_req_done` | input | CDMA 写请求完成。 |
+| `mat_start_valid` | output | 启动 matmul 计算的有效脉冲。 |
+| `mat_start_bank` | output | 启动哪个 matmul bank。 |
+| `mat_done_clear` | output | 清除 matmul done/error 状态。 |
+| `mat_crc_clear` | output | 清除 matmul CRC 累积值。 |
+| `mat_done` | input | matmul 计算完成状态。 |
+| `seq_done_irq` | output | 整个 matmul 序列完成中断，顶层与 `cdma_dma_finish` OR 成 `dma_finish`。 |
+
+### 3.11 `fft_mlkem_axi_slave`
+
+作用：共享 AXI slave 地址窗口，按地址低 16 位的 `[15:12]` 将请求分发到 ML-KEM 或 FFT。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | AXI 时钟，连接 `sys_clk`。 |
+| `resetn` | input | 低有效复位。 |
+| `s_axi_*` | input/output | 共享加速器 AXI4 slave 接口，连接 crossbar `axiOut_6_*`。 |
+| `fft_finish` | output | FFT 完成状态，送入 confreg。 |
+| `mlkem_intr` | output | ML-KEM 完成中断，直接送入 CPU `intrpt[3]`。 |
+
+内部地址分发：
+
+| 偏移范围 | 子模块 |
+| --- | --- |
+| `0x0000` - `0x3fff` | `mlkem_axi_slave` |
+| `0x8000` - `0xcfff` | `fft_controller` / FFT |
+
+### 3.12 `mlkem_axi_slave`
+
+作用：ML-KEM 加速器 AXI4 slave 包装器，提供 KeyGen、Encaps、Decaps 的配置、输入预加载、输出读回和中断。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | AXI 总线时钟。内部再产生 `mlkem_clk = clk/2`。 |
+| `resetn` | input | 低有效复位。 |
+| `s_axi_*` | input/output | ML-KEM AXI4 slave 接口，由 `fft_mlkem_axi_slave` 分发而来。 |
+| `intr` | output | ML-KEM done 锁存后的高电平中断。 |
+
+### 3.13 `fft_controller`
+
+作用：1024 点 16-bit FFT 加速器。通过 AXI 写入输入实部/虚部 BRAM，写 CSR 启动计算，完成后从输出实部/虚部窗口读取结果。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `aclk` | input | FFT/AXI 时钟。 |
+| `aresetn` | input | 低有效复位。 |
+| `s_aw*/s_w*/s_b*/s_ar*/s_r*` | input/output | FFT AXI4 slave 接口，由 `fft_mlkem_axi_slave` 分发而来。 |
+| `fft_finish` | output | FFT done 状态，来自 CSR status bit1。 |
+
+### 3.14 `matmul_axi_slave`
+
+作用：矩阵乘法加速器 AXI slave。它既支持 CPU 通过 AXI 访问控制寄存器和 bank 数据，也支持 CDMA 通过本地 endpoint 写入输入、读出结果。模块内部带 CRC32 累积逻辑。
+
+端口说明：
+
+| 端口 | 方向 | 解释 |
+| --- | --- | --- |
+| `clk` | input | matmul/AXI 时钟，连接 `sys_clk`。 |
+| `resetn` | input | 低有效复位。 |
+| `s_axi_*` | input/output | matmul AXI4 slave 接口，连接 crossbar `axiOut_7_*`。 |
+| `ep_wr_valid` | input | CDMA 本地 endpoint 写请求有效。 |
+| `ep_wr_id[3:0]` | input | endpoint id。当前仅使用 id 0。 |
+| `ep_wr_bank[3:0]` | input | 写入 bank 选择，bit0 选择 bank0/bank1。 |
+| `ep_wr_word_addr[7:0]` | input | 写入 bank 内 word 地址，0-15 为 A，16-31 为 B。 |
+| `ep_wr_data[31:0]` | input | 写入 A/B 矩阵的 32 位数据。 |
+| `ep_wr_ready` | output | matmul endpoint 可接收写数据。当前恒为 1。 |
+| `ep_rd_valid` | input | CDMA 本地 endpoint 读请求有效。 |
+| `ep_rd_id[3:0]` | input | endpoint id。 |
+| `ep_rd_bank[3:0]` | input | 读取 bank 选择。 |
+| `ep_rd_word_addr[7:0]` | input | 读取结果 C 的 word 地址。每个 66-bit 结果拆成 3 个 32-bit word。 |
+| `ep_rd_data[31:0]` | output | endpoint 返回的 32 位结果数据。 |
+| `ep_rd_ready` | output | endpoint 读数据可用。当前恒为 1。 |
+| `mat_start_valid` | input | 来自 bridge 的启动脉冲。 |
+| `mat_start_bank` | input | 启动计算的 bank。 |
+| `mat_done_clear` | input | 清除 done/error。 |
+| `mat_crc_clear` | input | 清除 CRC32 累积值。 |
+| `mat_done` | output | 计算完成状态。 |
+| `intr` | output | matmul 完成中断，送入 CPU `intrpt[2]`。 |
+
+## 4. 寄存器地址表
+
+以下地址以软件常用非缓存虚拟地址列出；括号中给出对应物理地址基址。
+
+### 4.1 UART0 (`0xbf000000`, physical `0x1f000000`)
+
+16550 风格 8-bit 寄存器，软件常用字节访问。
+
+| 地址 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf000000` | `0x0` | `RBR/THR` 或 `DLL` | R/W | DLAB=0 时读接收缓冲/写发送保持；DLAB=1 时为 divisor low byte。 |
+| `0xbf000001` | `0x1` | `IER` 或 `DLM` | R/W | DLAB=0 时为中断使能；DLAB=1 时为 divisor high byte。 |
+| `0xbf000002` | `0x2` | `IIR/FCR` | R/W | 读为中断识别，写为 FIFO 控制；DLAB=1 时部分实现作为 divisor 扩展。 |
+| `0xbf000003` | `0x3` | `LCR` | R/W | 线控制寄存器，bit7 为 DLAB。 |
+| `0xbf000004` | `0x4` | `MCR` | R/W | modem 控制。 |
+| `0xbf000005` | `0x5` | `LSR` | R | 线状态，软件轮询 bit5/bit6 判断发送 FIFO/发送器空。 |
+| `0xbf000006` | `0x6` | `MSR` | R | modem 状态。 |
+| `0xbf000007` | `0x7` | `SCR` | R/W | scratch/mode 寄存器。 |
+
+### 4.2 DVI (`0xbf100000`, physical `0x1f100000`)
+
+| 地址 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf100000` | `0x0` | `DVI_RECT_DIR` | R/W | 矩形位置参数，`[31:16]` 为 x，`[15:0]` 为 y。 |
+| `0xbf100004` | `0x4` | `DVI_RECT_L_W` | R/W | 矩形尺寸参数，`[31:16]` 为长度/半宽相关参数，`[15:0]` 为宽度/高度相关参数。 |
+| `0xbf100008` | `0x8` | `DVI_SQU_DIR` | R/W | 方形位置参数。 |
+| `0xbf10000c` | `0xc` | `DVI_SQU_R` | R/W | 方形半径/尺寸参数。 |
+
+### 4.3 confreg (`0xbf200000`, physical `0x1f200000`)
+
+| 地址 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf20f000` | `0xf000` | `CONFREG_INT_EN` | R/W | 中断使能。 |
+| `0xbf20f004` | `0xf004` | `CONFREG_INT_EDGE` | R/W | 中断边沿/电平模式配置。 |
+| `0xbf20f008` | `0xf008` | `CONFREG_INT_POL` | R/W | 中断极性配置。 |
+| `0xbf20f00c` | `0xf00c` | `CONFREG_INT_CLR` | W/R | 写 1 清除对应中断状态。 |
+| `0xbf20f010` | `0xf010` | `CONFREG_INT_SET` | W/R | 写 1 软件置位对应中断状态。 |
+| `0xbf20f014` | `0xf014` | `CONFREG_INT_STATE` | R | 当前中断状态。bit0-3 touch_btn，bit4 timer，bit5 UART，bit6 FFT。 |
+| `0xbf20f100` | `0xf100` | `TIMER_VALUE` | R | 系统计数器当前值。 |
+| `0xbf20f104` | `0xf104` | `TIMER_CMP` | R/W | 定时器比较值。 |
+| `0xbf20f108` | `0xf108` | `TIMER_EN` | R/W | bit0 使能定时器。 |
+| `0xbf20f200` | `0xf200` | `DIGITAL_CTRL` | R/W | 数码管控制寄存器。 |
+| `0xbf20f204` | `0xf204` | `DIGITAL_DATA` | R/W | 数码管显示数据。 |
+| `0xbf20f300` | `0xf300` | `LED_DATA` | R/W | LED 输出寄存器，低 16 位连接 `leds[15:0]`。 |
+| `0xbf20f400` | `0xf400` | `SWITCH_DATA` | R | 32 位拨码开关输入。 |
+| `0xbf20f500` | `0xf500` | `SIMU_FLAG` | R | 仿真标志，值为 `{32{SIMULATION}}`。 |
+
+### 4.4 DMA/CDMA (`0xbf300000`, physical `0x1f300000`)
+
+当前 `snix_axil_cdma_mux` 在顶层例化为 `PORTS=4`，通道 `ch=0..3`，每个通道 stride 为 `0x40`。通道寄存器地址为 `0xbf300000 + ch * 0x40 + offset`。
+
+| 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- |
+| `0x00` | `SRC_ADDR` | R/W | 源地址。mem2mem/mem2ep 时为内存源地址。 |
+| `0x04` | `DST_ADDR` | R/W | 目的地址。mem2mem/ep2mem 时为内存目的地址。 |
+| `0x08` | `LENGTH` | R/W | 传输字节数。 |
+| `0x0c` | `TAG` | R/W | 软件 tag，硬件不参与数据路径。 |
+| `0x10` | `CTRL` | R/W | bit0 写 1 启动；`[5:3]` 为 AXI AxSIZE；`[13:6]` 为 AXI AxLEN。 |
+| `0x14` | `STATUS` | R/W | bit0 busy，只读；bit1 done，写 1 清除。 |
+| `0x18` | `MODE` | R/W | `0=mem2mem`，`1=mem2ep`，`2=ep2mem`。 |
+| `0x1c` | `EP_CFG` | R/W | `[3:0]` bank，`[15:8]` word offset，`[19:16]` endpoint id。 |
+
+通道基址：
+
+| 通道 | 基址 |
+| --- | --- |
+| channel 0 | `0xbf300000` |
+| channel 1 | `0xbf300040` |
+| channel 2 | `0xbf300080` |
+| channel 3 | `0xbf3000c0` |
+
+matmul 序列控制子窗口由 `cdma_matmul_bridge` 实现，地址为 `0xbf300200 + offset`：
+
+| 地址 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf300200` | `0x200` | `SEQ_CTRL` | R/W | bit0 start；bit1 skip_result_writeback。 |
+| `0xbf300204` | `0x204` | `SEQ_STATUS` | R/W | bit0 busy；bit1 done，写 1 清除。 |
+| `0xbf300208` | `0x208` | `SEQ_SRC_BASE` | R/W | 输入矩阵组的物理源基址。 |
+| `0xbf30020c` | `0x20c` | `SEQ_DST_BASE` | R/W | 输出矩阵组的物理目的基址。 |
+| `0xbf300210` | `0x210` | `SEQ_GROUPS` | R/W | 自动处理的矩阵组数。 |
+| `0xbf300214` | `0x214` | `SEQ_MAT_BASE` | R/W | 保留兼容字段，软件通常写 `0x1f500000`。 |
+| `0xbf300218` | `0x218` | `SEQ_SRC_STRIDE` | R/W | 相邻输入组间隔，默认 128B。 |
+| `0xbf30021c` | `0x21c` | `SEQ_DST_STRIDE` | R/W | 相邻输出组间隔，默认 192B。 |
+
+### 4.5 FFT/ML-KEM 共享窗口 (`0xbf400000`, physical `0x1f400000`)
+
+#### 4.5.1 ML-KEM 子窗口
+
+| 地址/范围 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf400000` | `0x000` | `MLKEM_CTRL` | W | bit0 start，启动 CONFIG 指定的操作。 |
+| `0xbf400004` | `0x004` | `MLKEM_STATUS` | R/W | bit0 busy，bit1 done，bit2 preload_busy；写 bit1=1 清 done。 |
+| `0xbf400008` | `0x008` | `MLKEM_CONFIG` | R/W | `[2:0] k`，`[5:4] op`，op: 0 KeyGen，1 Encaps，2 Decaps。 |
+| `0xbf400010` - `0xbf40002c` | `0x010` - `0x02c` | `D[0..7]` | R/W | KeyGen seed d，8 个 32-bit word。 |
+| `0xbf400030` - `0xbf40004c` | `0x030` - `0x04c` | `Z[0..7]` | R/W | implicit-reject seed z。 |
+| `0xbf400050` - `0xbf40006c` | `0x050` - `0x06c` | `MSG[0..7]` | R/W | Encaps message m。 |
+| `0xbf400070` - `0xbf40008c` | `0x070` - `0x08c` | `SS[0..7]` | R | shared secret 输出。 |
+| `0xbf400100` | `0x100` | `PRELOAD_SEL` | R/W | 0=ek_in，1=dk_in，2=c_in。 |
+| `0xbf400104` | `0x104` | `PRELOAD_ADDR` | R/W | 预加载字节地址，写 `PRELOAD_DATA` 后自动递增。 |
+| `0xbf400108` | `0x108` | `PRELOAD_DATA` | W | 写低 8 位，流入所选输入端口。 |
+| `0xbf40010c` | `0x10c` | `RDBK_SEL` | R/W | 0=ek，1=dk_pke，2=full-dk，3=ciphertext。 |
+| `0xbf400110` | `0x110` | `RDBK_ADDR` | R/W | 读回字节索引。 |
+| `0xbf400114` | `0x114` | `RDBK_DATA` | R | 读回低 8 位数据。 |
+| `0xbf401000` - `0xbf401fff` | `0x1000` - `0x1fff` | `EK` | W/R | 写为 preload ek_in，读为 generated ek。 |
+| `0xbf402000` - `0xbf402fff` | `0x2000` - `0x2fff` | `DK` | W/R | 写为 preload dk_in，读为 generated full dk。 |
+| `0xbf403000` - `0xbf403fff` | `0x3000` - `0x3fff` | `CT` | W/R | 写为 preload c_in，读为 generated ciphertext。 |
+
+#### 4.5.2 FFT 子窗口
+
+| 地址/范围 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf408000` - `0xbf408ffc` | `0x8000` - `0x8ffc` | `FFT_IN_RE[0..1023]` | W | 输入实部 BRAM，每项低 16 位有效。 |
+| `0xbf409000` - `0xbf409ffc` | `0x9000` - `0x9ffc` | `FFT_IN_IM[0..1023]` | W | 输入虚部 BRAM，每项低 16 位有效。 |
+| `0xbf40a000` - `0xbf40affc` | `0xa000` - `0xaffc` | `FFT_OUT_RE[0..1023]` | R | 输出实部，符号扩展到 32 位，读出时使用 bit-reverse 地址。 |
+| `0xbf40b000` - `0xbf40bffc` | `0xb000` - `0xbffc` | `FFT_OUT_IM[0..1023]` | R | 输出虚部，符号扩展到 32 位，读出时使用 bit-reverse 地址。 |
+| `0xbf40c000` | `0xc000` | `FFT_CSR` | R/W | `[7:4]` 为 ctrl，写 bit4 启动/清 done；`[3:0]` 为 status，bit0 busy，bit1 done。 |
+
+### 4.6 Matmul (`0xbf500000`, physical `0x1f500000`)
+
+| 地址/范围 | 偏移 | 名称 | 访问 | 说明 |
+| --- | --- | --- | --- | --- |
+| `0xbf500000` | `0x000` | `MAT_CTRL` | R/W | bit0 启动 bank0，bit1 启动 bank1。 |
+| `0xbf500004` | `0x004` | `MAT_STATUS` | R/W | bit0 busy，bit1 done，bit2 error；写 bit1 清 done，写 bit2 清 error。 |
+| `0xbf500010` | `0x010` | `MAT_CRC` | R/W | 读返回 `crc_reg ^ 0xffffffff`；写该地址或 bridge 的 `mat_crc_clear` 清 CRC。 |
+| `0xbf500100` - `0xbf50013c` | `0x100` - `0x13c` | `B0_A[0..15]` | R/W | bank0 输入矩阵 A，16 个 32-bit word。 |
+| `0xbf500140` - `0xbf50017c` | `0x140` - `0x17c` | `B0_B[0..15]` | R/W | bank0 输入矩阵 B。 |
+| `0xbf500180` - `0xbf50023c` | `0x180` - `0x23c` | `B0_C` | R | bank0 输出矩阵 C，16 个 66-bit 结果，每个结果拆成 3 个 32-bit word，共 192B。 |
+| `0xbf500300` - `0xbf50033c` | `0x300` - `0x33c` | `B1_A[0..15]` | R/W | bank1 输入矩阵 A。 |
+| `0xbf500340` - `0xbf50037c` | `0x340` - `0x37c` | `B1_B[0..15]` | R/W | bank1 输入矩阵 B。 |
+| `0xbf500380` - `0xbf50043c` | `0x380` - `0x43c` | `B1_C` | R | bank1 输出矩阵 C，格式同 bank0。 |
+
+## 5. 关键数据路径说明
+
+1. CPU 访问任意外设或内存：`core_top -> Axi_CDC -> AxiCrossbar_2x8 -> 对应 AXI slave`。
+2. DMA 访问 SRAM：`snix_axil_cdma_mux mm2mm master -> AxiCrossbar_2x8 -> axi_wrap_ram_sp_external -> BaseRAM/ExtRAM`。DMA 和 SRAM 没有直接物理连线。
+3. DMA 访问 matmul 本地 endpoint：`snix_axil_cdma_mux -> ep_wr/ep_rd -> matmul_axi_slave`。这条是本地 endpoint 通路，不经过 AXI crossbar。
+4. matmul 批处理序列：CPU 写 `0xbf300200` 等寄存器配置 `cdma_matmul_bridge`，bridge 自动发起 CDMA 读/写请求并控制 matmul 启停。
+5. FFT/ML-KEM 共用 `0xbf400000` 窗口，由 `fft_mlkem_axi_slave` 依据偏移分发。