# TileNPU

**Repository Path**: magicor/TileNPU

## Basic Information

- **Project Name**: TileNPU
- **Description**: a npu base on tile
- **Primary Language**: Scala
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TileNPU

基于 Chisel 的 tile 级 NPU 工程骨架。目标 ISA 参考 PTO（Parallel Tile Operation），微架构参考同级的 `../verilog` 与 `../openTPU`。

> 命名说明：参考实现中的 VM（Vector Memory）/AM（Accumulator Memory）在代码中分别命名为 `TileMem` / `AccumMem`。

## 当前状态

- 工具链：sbt 1.11.7 + Chisel 7.16.0 + Scala 2.13.18
- 顶层 `TileNPU` 例化 controller / loader / imem / idma / odma / mac / vector / `TileMem` / `AccumMem`
- MAC：默认 **16×16×16**（spatial × output × reduce）= **4096 int8 MAC/cycle**；A/B 广播、16→1 规约、256×32b 本地累加；尺寸可由 `TileConfig` 配置（2 的幂）；K 循环双缓冲流水（稳态 1 cycle/K-group）
- TMATMUL Phase 1：16 槽 TileDesc + `SET_TILE_DESC`；运行时 M/N/K、valid region、A/B RowMajor/ColMajor、C 16×16 block、`TMATMUL_ACC` / `TMATMUL_BIAS`（int8→int32）
- TileMem：32 bank × 1024 × 128b（16 channel × 8b，共 512KB）；AccumMem：2 bank × 128 × 8192b（1KB/word，共 256KB）
- 每 bank 单端口；`BankedMem` 做 per-bank 读优先 + 写老化（4 cycle 强制授权）；TileMem 使用 5-bit XOR bank hash
- Controller：从 IMEM 取指、译码、**issue-ahead** 发射；命令入队后 PC 即前进，不再等单元 `done`
- 每个单元（iDMA / oDMA / MAC / Vector）有独立命令队列（深度 4），同队列内按序、跨队列并行
- 显式同步：Ascend 式 per-pair `SET_FLAG/WAIT_FLAG`（`WAIT` 只阻塞目的队列）+ 全局 `BAR`；`HALT` 是隐式 barrier
- 事件 flag 表：8 个 one-shot flag，`WAIT` 放行时清 flag；同时只有一个 waiter 被放行
- IMEM：2 × 1024 × 256b ping-pong bank；Loader 写 inactive bank，Controller 读 active bank
- Loader：Host 触发后把程序从外部存储搬到 inactive IMEM bank；`load` 可在程序运行期间后台执行；无 ICache/DCache
- Host 控制寄存器：`progAddr` / `progLen` / `load` / `run`；状态：`pc` / `halted` / `loadDone` / `loadReady` / `busy` / `err`；调试：`dbgProgSel` / `dbgBankValid`
- 程序切换：HALT 排空后若另一 bank 已加载完成，自动 retire 旧 bank、切换并执行；`halted` 仅在没有下一段程序时置位
- iDMA / oDMA：2D `TLOAD` / `TSTORE`（rows + ext stride + tile stride），64B beat、4 lane、尾 beat 掩码；单 outstanding
- Vector：FP16 tile 级逐元素/标量运算，32R/32W × 128b（8 FP16/word；lane 数可配置）；支持 `TADD/TSUB/TMUL`、`TADDS/TMULS`、`TRELU`、`TCVT`（FP16↔FP32/I32）、`TEXPANDS`，vector 本地 16 槽描述符；通过 AccumMem lane 1 提供 `ACC2TILE`/`TILE2ACC` bridge
- TileMem：**16R/8W** 逻辑端口（MAC 48R、Vector 32R/32W、iDMA 1R/4W、oDMA 4R、debug 1R/1W 的 lane 经旋转优先级 mux 共享端口）；AccumMem：**2R/2W**（MAC / Vector / debug 共享）
- TileMem/AccumMem 有 debug 读写口（debug read 有独立 `re`，运行时可关闭）
- `sbt compile` 通过；`make verilog` 生成 `output/TileNPU.sv`；`make lint` 通过
- `make sim` 通过：描述符 TMATMUL 覆盖 1×1×1 / 4×4×4 / tails / valid padding / 16×16×16 / 四种 layout / ACC / BIAS / ACC+BIAS / 非法 dtype / DMA+Bias 端到端 / oDMA TSTORE / 25 组固定种子随机 M/N/K；FP16 vector 覆盖逐元素/标量/relu/cvt/别名/非法用例；AccumMem bridge 覆盖 ACC2TILE/TILE2ACC 与 `TMATMUL → AccumMem → ACC2TILE → TileMem` 端到端；ping-pong 后台加载 + HALT 自动切换、停机后加载自动启动

## 构建

```bash
# 编译 Scala/Chisel
make compile

# 生成 SystemVerilog 到 output/
make verilog

# Verilator lint
make lint

# 功能仿真：TMATMUL / vector / AccumMem bridge / IMEM 测试
# （默认 -O0 + output-split；JOBS=n 并行度，OPT=-O2 换优化级别，SPLIT=… 调拆分粒度）
make sim

# 只跑名字包含子串的用例（避免大模型全量回归）
./output/obj_dir/tb_TileNPU --only ping-pong

# 清理
make clean
```

默认产物：`output/TileNPU.sv`（TileMem/AccumMem 的 bank、仲裁和 debug 口都会保留在网表中）。

## 目录

```text
build.sbt
project/build.properties
src/main/scala/tilenpu/
  config/TileConfig.scala       # 组合 Mac/Memory/Vector/Controller 子配置
  config/MacConfig.scala        # MAC 形状 + TileMem/AccumMem word 宽度
  config/MemoryConfig.scala     # IMEM/TileMem/AccumMem bank 与端口
  config/VectorConfig.scala     # vector lane/描述符槽
  config/ControllerConfig.scala # instrW/队列/flag/DMA lane
  pkg/Isa.scala
  pkg/Bundles.scala
  pkg/UnitStub.scala
  controller/Controller.scala   # 取指/issue-ahead/barrier/halt FSM
  controller/ControllerDecoder.scala # 指令解包 + target 分类
  controller/IssueTracker.scala # per-unit outstanding 计数
  controller/CommandQueue.scala  # per-unit 队列 + SET/WAIT 标记
  controller/SyncFlags.scala     # per-pair 事件 flag 表
  controller/Loader.scala
  controller/Iterator.scala
  dma/Idma.scala
  dma/Odma.scala
  dma/Dma2D.scala          # TLOAD/TSTORE 共用的 2D 字段/地址解码
  dma/DmaSequencer.scala   # iDMA/oDMA 共用的 row/beat/group 计数与边界
  mac/MacArray.scala       # TMATMUL FSM + 双缓冲 K-group 读
  mac/MacDecoder.scala     # TMATMUL 描述符合法性（纯组合）
  mac/MacPEArray.scala     # S×O PE 阵列 + 显式 clear/init/update 模式
  mac/MacKGroupDatapath.scala # layout/transpose/K-mask 操作数格式化
  mac/MacPE.scala          # 单个 16-way MAC PE
  mac/TileAddr.scala       # 2D layout 地址/范围检查
  vector/VectorUnit.scala  # vector FSM 编排
  vector/VecGeometry.scala # lane/word/phase 常量
  vector/VecDecoder.scala  # VOP 解码 + 描述符合法性
  vector/VecElementwiseDatapath.scala # 逐元素/标量/cvt 计算
  vector/VecAccPackers.scala # ACC2TILE / TILE2ACC 打包
  vector/Fp16Ops.scala     # native FP16 add/sub/mul/relu/cvt
  vector/VecAddr.scala     # vector tile 地址/合法性
  mem/SramBank.scala
  mem/BankedMem.scala      # bank 阵列 + 读返回流水
  mem/BankedMemConfig.scala # 端口/bank/hash/老化参数
  mem/BankHash.scala       # 逻辑地址 → bank index
  mem/TileMem.scala
  mem/AccumMem.scala
  mem/Imem.scala
  top/TileNPU.scala        # 单元实例化 + 端口图
  top/ExtMemArbiter.scala  # loader/iDMA/oDMA 外部存储仲裁
  top/ImemBankCtrl.scala   # ping-pong IMEM bank 记账
  Elaborate.scala
tb/harness.h               # Sim/DUT、外部存储模型、Tester 接口
tb/harness.cpp
tb/tests.h                 # 测试组入口
tb/tb_tmatmul.cpp
tb/tb_vector.cpp
tb/tb_acc_bridge.cpp
tb/tb_imem.cpp
tb/main.cpp                # 参数解析 + 测试组调度
Makefile
output/            # gitignored
```

## 文档

- [当前设计说明](docs/current-design.md)
- [微架构分析](docs/microarchitecture.md)
- [TMATMUL Phase 1](docs/tmatmul.md)
- [FP16 Vector Phase 1](docs/vector.md)
- [TileNPU ISA](docs/tilenpu-isa.md)
- [PTO ISA 参考手册](docs/pto-isa-reference.md)
- [参考设计调研](docs/reference-design.md)
- [工程设计](design.md)

## 程序执行流程

```text
host: progAddr/progLen ─► LOAD
       Loader: 外部存储 → inactive IMEM bank（运行中也可后台加载）
       loadDone=1
host: RUN
       Controller: PC → active IMEM bank → Decode → enqueue UnitCmd → PC++
       HALT 排空后若有 staged 程序：自动切换 bank，PC=0 继续
                    │
                    ├─► iDMA queue   ─► iDMA   ┐
                    ├─► oDMA queue   ─► oDMA   │ 并行执行
                    ├─► MAC queue    ─► MAC    │
                    └─► Vector queue ─► Vector ┘
       SET_FLAG(src,dst,id)  → 进 src 队列，src 排空后置 flag
       WAIT_FLAG(src,dst,id) → 进 dst 队列，只阻塞 dst
       BAR  → 等所有队列排空
       HALT → 隐式 barrier；有下一段程序则切换，否则 halted=1
```

## 下一步

1. TMATMUL Phase 2：FP8 E4M3/E5M2 → f32。
2. TMATMUL Phase 3：MXFP8/MXFP4 + E8M0 SA/SB scale。
3. Phase 4：TQUANT（block max → E8M0 → FP8/FP4 pack）。
4. Vector Phase 2：归约/广播、compare/select、FP32/BF16 运算；epilogue 融合 scale/bias/ReLU/quant。
5. A/B 操作数复用、MAC 多 output block 流水和内部流水寄存器（K 循环流水已实现）。
6. 补 `REPEAT/JMP` 和标量寄存器堆（如需要）。
7. 视需要加 footprint scoreboard，或用事件 flag 支持更复杂的同步模式。
8. DMA 后置项：多 outstanding、gather、压缩、非对齐行起点。