# 整机架构

> 模型机的主线是在小电脑上纯软件跑（SBC）；这页讲的 FPGA 加 ESP32-C3 是研究线，只在仿真里跑通。

> **主线是 SBC 纯软件**：在 ARM 小电脑上用自写运行时跑模型，从链上取固件那一套照样用，见[在小电脑上跑大模型](sbc.md)。下面的 FPGA 加 ESP32-C3 方案是研究线：电路是我们自己设计的，目前只在仿真里跑通，还没做成实物。

## 研究线：一张图

```text
 链上 tape 容器（BSC / X Layer）
   tapeboot/<board>/channel/*.json   频道指针
   tapeboot/<board>/<seq>/…          manifest 和文件
        │  只读 eth_call：fileInfo / readRange（一个节点不行换下一个，一律验哈希）
        ▼
 ESP32-C3：引导固件 + TapeBoot 客户端
   读频道 → 验签名和哈希 → 按块取回（缓存到 microSD）
        │  SPI 邮箱：把运行时和 TBW1 写进 DDR3，再放开软核复位
        ▼
 FPGA（GW2A-18）
   rv32ima 软核 ── 总线 ── DDR3 控制器（128 MB）
                    ├─ UART
                    ├─ 定时器 / SYSCON
                    ├─ HDMI 文本控制台
                    └─ 二值乘加单元（XNOR + popcount，自己从 DDR3 读权重）
```

> 现在在仿真里跑通，还没做成实物。

## 部件

| 部件 | 是什么 | 做什么 |
|---|---|---|
| ESP32-C3 | 引导芯片，跑引导固件，内含 TapeBoot 客户端 | 连 Wi-Fi 读链；验签名和哈希；按块取回；经 SPI 邮箱写 DDR3；看心跳决定提交还是回滚 |
| microSD | 接在 C3 上 | 块缓存和 A/B 两个槽；断网时从最近一个核对通过的槽启动 |
| GW2A-18 FPGA | 目标板 Tang Primer 20K | 放下面这些电路。比特流固定在板载 flash，用 USB 烧，不走链上 |
| rv32ima 软核 | M 态、没有 MMU，和 mini-rv32ima 兼容 | 复位后从 `0x8000_0000` 开跑 |
| DDR3 | 128 MB | 前 16 MB 放运行时，后面至多 112 MB 放模型 |
| 二值乘加单元 | XNOR + popcount | 一次算完一整个矩阵乘向量，自己读 DDR3 |
| UART | 8250 子集，8N1、115200 | 串口输出 |
| HDMI 文本控制台 | 80×30 字符，每格 2 字节（字符 + 颜色） | 屏幕输出 |
| 运行时 | TBRT 裸机运行时（主），TapeOut Linux（次） | 加载模型、推理、出字 |

## 三条接口

| 接口 | 两端 | 管什么 | 详见 |
|---|---|---|---|
| IF-1 | 模型 ↔ 硬件、运行时 | TBW1 权重文件布局。整个文件原样上链、原样进 DDR3、被乘加单元直接读，中途不转换 | [TBW1 权重格式](../reference/tbw1.md) |
| IF-2 | 硬件 ↔ 系统 | 内存映射、乘加单元寄存器、C3 和 FPGA 之间的 SPI 邮箱 | 本页下面 |
| IF-3 | 协议 ↔ 系统 | TapeBoot：链上路径、manifest、签名、校验顺序、A/B 槽 | [从链上取固件](tapeboot.md)、[TapeBoot 规范](../reference/tapeboot.md) |

## 内存映射

外设地址和 mini-rv32ima 相同，所以链上那份 TapeOut Linux 镜像可以原样启动。

| 地址 | 大小 | 内容 |
|---|---|---|
| `0x8000_0000` | 16 MB | 运行时 / 操作系统 |
| `0x8100_0000` | 至多 112 MB | 模型区：TBW1 文件原样放这里 |
| `0x1000_0000` | `0x100` | UART |
| `0x1100_4000` / `0x1100_BFF8` | — | mtimecmp / mtime |
| `0x1110_0000` | 4 | SYSCON：写 `0x5555` 关机，`0x7777` 重启 |
| `0x2000_0000` | `0x100` | 二值乘加单元 |
| `0x2100_0000` | 8 KB | HDMI 文本控制台 |
| `0x2200_0000` | `0x100` | 邮箱：C3 和软核之间的状态寄存器 |

## 乘加单元寄存器

全部 32 位。写好地址和尺寸，置 `CTRL` 的 bit0 启动，等 `STATUS` 的 bit1。

| 偏移 | 名字 | 说明 |
|---|---|---|
| `0x00` | CTRL | bit0 启动，bit1 清中断 |
| `0x04` | STATUS | bit0 忙，bit1 完成，bit2 错误 |
| `0x08` | W_ADDR | 权重张量在 DDR3 的字节地址 |
| `0x0C` | X_ADDR | 输入向量，按 64 位对齐 |
| `0x10` | Y_ADDR | int32 输出 |
| `0x14` | COLS | 列数 |
| `0x18` | ROWS | 行数 |
| `0x1C` | SCALE_ADDR | 缩放表地址 |
| `0x20` | SCALE_KIND | 缩放方式，见 [TBW1](../reference/tbw1.md) |
| `0x24` | GROUP | 分组大小 |
| `0x28` | PERF_CYCLES | 只读，用了多少拍 |
| `0x2C` | ACT_BITS | 输入位数；0 和 1 都按一位输入 |
| `0x30` | W_KIND | 0 = 一位权重（复位值），1 = INT8，其余报错 |

## SPI 邮箱

C3 当主机。模式 0，高位先出，SCK 不超过 FPGA 时钟的 1/8。一次片选拉低是一条命令，多字节字段一律小端。

| 命令 | 格式 | 做什么 |
|---|---|---|
| `0x01` WRITE | `addr[4]` 后跟数据 | 写进 DDR3。只在软核复位时有效 |
| `0x02` READ | `addr[4] dummy[2]` 后连续读 | 读 DDR3。只在软核复位时有效 |
| `0x03` RESET | `v[1]` | bit0 = 1 按住软核复位，0 放开。上电默认按住 |
| `0x04` REG_WR | `reg[1] v[4]` | 目前只能写 `0x00` BOOT_INFO |
| `0x05` REG_RD | `reg[1] dummy[1]` 后读 `v[4]` | 读下表的寄存器 |

| 寄存器 | 内容 |
|---|---|
| `0x00` BOOT_INFO | 高 16 位 = manifest 的 seq 低 16 位，低 16 位 = manifest sha256 的前 2 字节。只给运行时打印自己是哪一版 |
| `0x04` HEARTBEAT | 软核每秒加 1；复位期间清零 |
| `0x08` MSG | 软核给 C3 的状态码；复位期间清零 |
| `0x0C` STATUS | bit0 软核在复位，bit1 软核已关机，bit2 复位之外访问 DDR3 被拒，bit3 乘加单元忙，bit4 DDR3 标定完成，bit5 标定失败 |
| `0x10` 版本 | ASCII `MB01`；带 DDR3 标定位的是 `MB02` |

## 开机顺序

1. FPGA 从板载 flash 起，DDR3 控制器标定。
2. C3 每 10 ms 读一次邮箱版本，读到 `MB01` 或 `MB02` 才算 FPGA 起来了。2 秒读不到就停，不取文件、不动槽。
3. 等 STATUS 的 bit4（DDR3 标定完成）。
4. TapeBoot 读频道、取 manifest、验签名、按块取回并核哈希。见[从链上取固件](tapeboot.md)。
5. 经邮箱把运行时写到 `0x8000_0000`，把 TBW1 写到 `0x8100_0000`，写 BOOT_INFO。
6. 放开软核复位，软核从 `0x8000_0000` 开跑。
7. 60 秒内 HEARTBEAT 从 0 变成非 0 就算健康，提交这一版；否则回到旧槽。

## 两种运行时

| 运行时 | 用途 | 健康判定 |
|---|---|---|
| TBRT 裸机运行时（主线） | 一启动就推理，直接驱动乘加单元和 HDMI | 60 秒内有心跳 |
| TapeOut Linux（次线） | 原样启动链上那份 Linux 6.5.12，和链上机器逐指令对拍；开机约 4,180 万条指令 | 放开复位 60 秒后软核没关机 |

manifest 里文件的 `role` 是 `runtime` 还是 `os`，决定启动哪一个。

## 没有 FPGA 的版本

同一套 TapeBoot 也能作为 Linux 程序跑在 ARM 小电脑上，取回、校验、A/B 槽都一样，心跳改走管道。见[在小电脑上跑大模型](sbc.md)。
