9.0 KiB
9.0 KiB
ML-KEM AXI Slave 寄存器参考手册
概述
mlkem_axi_slave 是 ML-KEM 硬件加速器的 AXI4 Slave 总线接口。它封装 mlkem_top 核心，提供完整的寄存器映射用于软件控制 KeyGen / Encaps / Decaps 操作。
关键特性
- 总线: AXI4 (支持 INCR burst read/write)
- 基址:
0xbf400000（LoongArch 虚地址） - 时钟域: sys_clk (50 MHz) → mlkem_clk (25 MHz)，跨域通过 toggle 握手同步
- 支持参数: k=2 (ML-KEM-512), k=3 (ML-KEM-768), k=4 (ML-KEM-1024)
- 中断:
intr信号，当 done 标志锁存时电平有效高
寄存器映射
所有寄存器为 32-bit 对齐。偏移量相对于基址 0xbf400000。
| 偏移 | 名称 | 访问 | 复位值 | 描述 |
|---|---|---|---|---|
0x000 |
CTRL | W | 0x00000000 |
控制寄存器：写 bit0=1 启动操作 |
0x004 |
STATUS | R/W1C | 0x00000000 |
状态寄存器 |
0x008 |
CONFIG | RW | 0x00000004 |
配置寄存器：k 值和操作码 |
0x010–0x02C |
D[0..7] | RW | 0x00000000 |
KeyGen 种子 d（256-bit，8字） |
0x030–0x04C |
Z[0..7] | RW | 0x00000000 |
KeyGen 隐式拒绝种子 z（256-bit，8字） |
0x050–0x06C |
MSG[0..7] | RW | 0x00000000 |
Encaps 消息 m（256-bit，8字） |
0x070–0x08C |
SS[0..7] | R | — | 共享密钥输出（256-bit，8字，只读） |
0x100 |
PRELOAD_SEL | RW | 0x00000000 |
预载端口选择 |
0x104 |
PRELOAD_ADDR | RW | 0x00000000 |
预载字节地址（写入后自动递增） |
0x108 |
PRELOAD_DATA | W | — | 预载数据字节（写低 8-bit，自动 wait-state） |
0x10C |
READBACK_SEL | RW | 0x00000000 |
回读端口选择 |
0x110 |
READBACK_ADDR | RW | 0x00000000 |
回读字节索引（无自动递增） |
0x114 |
READBACK_DATA | R | — | 回读数据字节（低 8-bit 有效） |
寄存器详情
CTRL (0x000) — 控制寄存器，只写
| Bits | 名称 | 描述 |
|---|---|---|
0 |
start | 写 1 启动当前 CONFIG 中配置的操作。写 0 无效。 |
- 写 start 后，STATUS.busy 立即置位，done 清零。
- 操作完成前不可再次启动。
- CTRL 本身不可读（读返回 0）。
STATUS (0x004) — 状态寄存器，读/写1清零
| Bits | 名称 | 访问 | 描述 |
|---|---|---|---|
0 |
busy | R | 核心正在执行操作（KeyGen/Encaps/Decaps） |
1 |
done | R/W1C | 操作已完成。写 1 清除（写 0 无效）。启动新操作时自动清除 |
2 |
preload_busy | R | 预载数据传输正在进行中（跨域字节握手未完成） |
31:3 |
— | — | 保留，读为 0 |
注意:
done是锁存标志：操作完成后保持为 1，直到软件写 1 清零或启动新操作。busy和done不互斥：在 done 置位的同一周期 busy 清零，两者可能同时为 1（短暂窗口）。preload_busy为 1 时，写入 PRELOAD_DATA 会被 wait-state 直到传输完成。
CONFIG (0x008) — 配置寄存器，读写
| Bits | 名称 | 复位值 | 描述 |
|---|---|---|---|
2:0 |
k | 3'b100 (4) |
ML-KEM 参数：2=ML-KEM-512, 3=ML-KEM-768, 4=ML-KEM-1024 |
4 |
— | 0 |
保留 |
5:4 |
op | 2'b00 |
操作码：0=KeyGen, 1=Encaps, 2=Decaps |
31:6 |
— | 0 |
保留 |
约束:
- 修改 CONFIG 应在启动操作之前完成。启动后修改可能导致未定义行为。
- k 必须为 2、3 或 4。
D[0..7] (0x010–0x02C) — KeyGen 种子 d，读写
256-bit 种子 d，用于 KeyGen 操作。存储为 8 个 32-bit 字，小端序：
| 字偏移 | 地址 | 包含字节 |
|---|---|---|
| D[0] | 0x010 |
d[3:0]（字节 3 在 bit[31:24]，字节 0 在 bit[7:0]） |
| D[1] | 0x014 |
d[7:4] |
| ... | ... | ... |
| D[7] | 0x02C |
d[31:28] |
核心看到的 256-bit 总线为 {D[7], D[6], ..., D[0]}，其中 d_i[7:0] = D[0][7:0]。
支持 AXI wstrb 按字节写入。
Z[0..7] (0x030–0x04C) — 隐式拒绝种子 z，读写
256-bit 种子 z，用于 KeyGen。布局与 D 相同。
MSG[0..7] (0x050–0x06C) — Encaps 消息 m，读写
256-bit 消息 m，用于 Encaps。布局与 D 相同。
SS[0..7] (0x070–0x08C) — 共享密钥，只读
256-bit 共享密钥输出。KeyGen 和 Encaps 操作完成后在此处提供结果。
| 字偏移 | 地址 | 内容 |
|---|---|---|
| SS[0] | 0x070 |
ss[31:0] |
| SS[1] | 0x074 |
ss[63:32] |
| ... | ... | ... |
| SS[7] | 0x08C |
ss[255:224] |
PRELOAD_SEL (0x100) — 预载端口选择，读写
| Bits | 名称 | 描述 |
|---|---|---|
1:0 |
sel | 预载目标端口：0=ek, 1=dk, 2=c（密文） |
31:2 |
— | 保留 |
设置后，随后写入 PRELOAD_DATA 的字节将流向所选端口。
PRELOAD_ADDR (0x104) — 预载字节地址，读写
| Bits | 名称 | 描述 |
|---|---|---|
11:0 |
addr | 预载端口内的字节偏移地址。每次 PRELOAD_DATA 写入成功后自动递增 |
31:12 |
— | 保留 |
写入 PRELOAD_DATA 前必须先设置好 PRELOAD_SEL 和 PRELOAD_ADDR（通常 addr=0）。
PRELOAD_DATA (0x108) — 预载数据字节，只写
| Bits | 名称 | 描述 |
|---|---|---|
7:0 |
byte | 写入所选预载端口的字节数据 |
31:8 |
— | 忽略 |
此寄存器自动 wait-state：写入后 AXI 总线暂停，直到跨域握手完成（字节被 mlkem 核心采样）。然后 PRELOAD_ADDR 自动递增 1。
重要: 每个字节需要一次 AXI 写事务。对于大数据量（ek=800B, dk=1632B），建议使用 INCR burst 写，burst 长度设为字节数。
READBACK_SEL (0x10C) — 回读端口选择，读写
| Bits | 名称 | 描述 |
|---|---|---|
1:0 |
sel | 回读源：0=ek, 1=dk_pke, 2=完整 dk, 3=密文 |
31:2 |
— | 保留 |
READBACK_ADDR (0x110) — 回读字节索引，读写
| Bits | 名称 | 描述 |
|---|---|---|
11:0 |
addr | 待读取字节在回读端口中的索引。无自动递增 |
31:12 |
— | 保留 |
每个字节的读取流程：写 READBACK_ADDR → 读 READBACK_DATA。
READBACK_DATA (0x114) — 回读数据字节，只读
| Bits | 名称 | 描述 |
|---|---|---|
7:0 |
byte | 所选回读端口中 READBACK_ADDR 索引处的字节 |
31:24 |
— | 读为 0 |
操作流程
1. KeyGen: (d, z) → ek, dk
1. 写 CONFIG: op=0 (KeyGen), k=2/3/4
2. 写 D[0..7] ← 种子 d (256-bit)
3. 写 Z[0..7] ← 种子 z (256-bit)
4. 写 CTRL: bit0=1 → 启动
5. 轮询 STATUS.done == 1（或等待 intr）
6. 通过 READBACK 读取 ek 和 dk:
a. RDB_SEL=0, 逐个字节读 ADDR=0..799 → ek (800 B for k=2)
b. RDB_SEL=2, 逐个字节读 ADDR=0..1631 → dk (1632 B for k=2)
7. 读 SS[0..7] → 共享密钥（可选）
8. 写 STATUS: bit1=1 → 清除 done
2. Encaps: (ek, m) → (ss, ct)
1. 写 CONFIG: op=1 (Encaps), k=2/3/4
2. 通过 PRELOAD 预载 ek:
a. PRE_SEL=0, PRE_ADR=0
b. 逐个字节写 PRE_DAT (800 B for k=2)
3. 写 MSG[0..7] ← 消息 m (256-bit)
4. 写 CTRL: bit0=1 → 启动
5. 轮询 STATUS.done == 1
6. 读 SS[0..7] → 共享密钥
7. 通过 READBACK 读取 ct:
a. RDB_SEL=3, 逐个字节读 ADDR=0..767 → ct (768 B for k=2)
3. Decaps: (dk, ct) → ss
1. 写 CONFIG: op=2 (Decaps), k=2/3/4
2. 通过 PRELOAD 预载 dk 和 ct:
a. PRE_SEL=1, PRE_ADR=0, 逐个字节写 PRE_DAT (1632 B for k=2)
b. PRE_SEL=2, PRE_ADR=0, 逐个字节写 PRE_DAT (768 B for k=2)
3. 写 CTRL: bit0=1 → 启动
4. 轮询 STATUS.done == 1
5. 读 SS[0..7] → 共享密钥
数据尺寸参考
| 参数 | k=2 (ML-KEM-512) | k=3 (ML-KEM-768) | k=4 (ML-KEM-1024) |
|---|---|---|---|
| ek 字节数 | 800 | 1184 | 1568 |
| dk_pke 字节数 | 768 | 1152 | 1536 |
| dk 总字节数 | 1632 | 2400 | 3168 |
| ct 字节数 | 768 | 1088 | 1568 |
中断
intr信号在STATUS.done == 1时保持高电平。- 清除中断：写
STATUS的 bit1=1（W1C）或启动新操作。 intr是电平触发（非脉冲），连接到 LoongArch 的 HWI 输入。
注意事项
- 时钟域: 核心运行在 sys_clk/2 (25 MHz)。PRELOAD_DATA 写入自动 wait-state，软件无需处理跨域延迟。
- 启动时序: 确保在写 CTRL.start 之前，config/seeds/preload 数据已全部写入且稳定。
- PRELOAD_ADDR 自动递增: 连续写 PRELOAD_DATA 时地址自动递增，无需手动更新 PRELOAD_ADDR（除非切换端口）。
- READBACK_ADDR 无自动递增: 每次读 READBACK_DATA 前必须手动写 READBACK_ADDR。
- done 标志: 是锁存的，启动新操作时自动清除。连续执行多个操作时，每次启动前先确认 busy==0，然后清 done。
- STATUS 读取时机: done 标志在操作完成的 mlkem_clk 周期后，需经 2 级同步器（~40ns）才能在 sys_clk 域看到。