# ML-KEM AXI 前端与跨时钟域技术说明

## 1. 共享从端结构

`fft_mlkem_axi_slave` 将 Crossbar Slave 6 分成 FFT 和 ML-KEM 两个内部目标。写地址或读
地址的 bits 15:12 小于等于 3 时选择 ML-KEM；FFT 使用 0x8000--0xc000 窗口。ML-KEM
以外且未被 FFT 定义的地址仍会路由到 FFT 前端，但返回零或忽略写入，因此软件只应使用
文档化区间。

AXI 写地址和写数据通道彼此独立。共享前端在 AW 握手时锁存 `write_sel`，直到对应 B
响应完成才释放；读路径在 AR 握手时锁存 `read_sel`，直到带 RLAST 的最后一个 R beat
完成才释放。响应选择不使用实时地址，避免 burst 期间地址变化导致响应串到另一个内部
从端。

FFT 控制器直接工作在 `sys_clk`。ML-KEM 的完整 AXI 五通道通过 `Axi_CDC` 跨入
`mlkem_clk`，之后由 `mlkem_axi_slave` 和 `mlkem_top` 在同一计算时钟域处理。ML-KEM
中断从计算域返回系统域时经过两级同步寄存器。

XDC 将 SYS 与 ML-KEM 声明为异步时钟组，因此跨域有效性由 `Axi_CDC` 的双时钟 FIFO
保证，而不是由 PLL 同源关系或普通时序路径保证。具体约束和复位关系见
[时钟域、复位与跨时钟域设计说明](00_clock_domains.md)。

## 2. ML-KEM 寄存器接口

ML-KEM 物理基址为 `0x1f40_0000`，CPU 未缓存映射为 `0xbf40_0000`。

| 偏移 | 名称 | 说明 |
|---|---|---|
| `0x000` | CTRL | bit 0 启动，bit 1 软复位 |
| `0x004` | STATUS | bit 0 busy，bit 1 done，bit 2 preload busy；done 为 W1C |
| `0x008` | CONFIG | bits 2:0 为 K，bits 5:4 为操作码 |
| `0x010--0x02c` | D | 32 字节 KeyGen 随机种子 |
| `0x030--0x04c` | Z | 32 字节隐式拒绝种子 |
| `0x050--0x06c` | MSG | 32 字节 Encaps 消息 |
| `0x070--0x08c` | SS | 32 字节共享密钥，只读 |
| `0x100/104/108` | PRE_SEL/ADR/DAT | 逐字节预装载接口 |
| `0x10c/110/114` | RDB_SEL/ADR/DAT | 逐字节读回接口 |
| `0x1000` | EK window | 公钥批量输入或输出窗口 |
| `0x2000` | DK window | 私钥批量输入或输出窗口 |
| `0x3000` | CT window | 密文批量输入或输出窗口 |

CONFIG 的操作码 0、1、2 分别表示 KeyGen、Encaps、Decaps。软件必须在启动前完成参数与
输入装载，并在 busy 期间保持配置不变。done 保持到软件 W1C，便于轮询程序不丢失短脉冲。

## 3. 字节端口与批量窗口

传统 PRE 接口通过 PRE_SEL 选择 ek、dk 或 c，通过 PRE_ADR 设置字节地址，向 PRE_DAT
写入低 8 位并自动递增地址。读回接口以同样方式选择 ek、完整 dk 或 ct。该路径便于调试，
但每个字节至少需要一次 AXI 寄存器事务，传输大密钥时开销较高。

三个批量窗口把 AXI 32 位 beat 分解为最多四个有效字节。写状态机依据 WSTRB 跳过无效
lane，将字节地址、选择和数据送入核心 BRAM 写口，并等待内部确认后继续下一个 lane。
读状态机按字节地址读取内部 BRAM，补偿同步读延迟后组装 32 位 RDATA。窗口支持 INCR
burst，使通用 DMA 能以少量控制事务搬运完整公钥、私钥和密文。

批量窗口不改变密码核心的算法执行时间，但显著减少 CPU 逐字节访问开销。性能报告应把
CPU 寄存器路径和 DMA 窗口路径分别列出，不能把两者差值解释为核心计算加速。

## 4. 事件控制与复位

CTRL start、软复位和 done clear 在 `mlkem_axi_slave` 中均转换为 toggle 事件，再通过
边沿检测产生单拍控制。软复位事件经计数器展宽，形成核心局部复位。预装载写入使用
request/ack toggle，使 AXI 写 beat 只有在目标字节被核心侧接收后才完成。

外层 `Axi_CDC` 已承担 SYS--ML-KEM 的 AXI 通道跨域；前端内部的 toggle 机制主要用于
把寄存器写动作转换为不会重复触发的单拍事件，并串行化字节预装载。系统复位有效期间，
所有 AXI valid、start 和预装载事件必须保持无效。

## 5. 协议验证重点

共享前端需要覆盖 AW 与 W 不同拍到达、B/R 反压、ML-KEM 与 FFT 交替访问、长 burst
末拍、WSTRB 空洞以及读写并发。ML-KEM 窗口还需验证 800--3168 字节的非统一长度、最后
一个不满字、BRAM 读延迟和软复位中止。当前板级 CPU 与 DMA 双路径证明了常用顺序访问，
但不等价于覆盖所有并发和异常协议组合。