Kintex-7 双通道 DDR3 板卡 Bring-up 全记录:openTPU FPGA 从时钟到 PCIe 的点亮过程
Kintex-7 双通道 DDR3 板卡 Bring-up 全记录:openTPU FPGA 从时钟到 PCIe 的点亮过程
openTPU 是一个开源 AI 加速器:RTL、指令集(ISA)、模拟器、编译器与 Profiler 都在同一个仓库中。本文完整记录 openTPU 在 Kintex-7(xc7k480t)+ 双通道 DDR3 的 YPCB-00338 PCIe 板卡上的 Bring-up 全过程:时钟规划、bitstream 构建、JTAG 下载、PCIe 枚举、DDR3 校准与内存体检,直到板卡上跑通 Qwen3 / LFM2.5 / Qwen3.5 推理。所有命令与数据均来自实测记录,新手可以照着一步步执行。
🎯 板卡与系统架构一览
这张板卡的核心配置(目标定义见 targets/ypcb-00338.toml):
- FPGA:Xilinx Kintex-7
xc7k480t-ffg1156-2 - 内存:2 × 2 GiB DDR3-1066(x64 双通道),经 LiteDRAM 控制器接入
- 主机接口:PCIe Gen2 x8(Xilinx XDMA),AXI4 128 位 @ 250 MHz
- 片上配置:1 个 openTPU slice(D=128,4 列 MXU 脉动阵列、8 条 VPU lane、64K 字 TMEM)
主机与卡之间的数据通路如下:
host PC ── PCIe Gen2 x8 ── XDMA ──┬── AXI-Lite (BAR0) ── 控制寄存器
└── AXI4 128b @250MHz ──┐
otp_u_board (core_clk) ── 512b ch0 ── otpu_mem_ch ── LiteDRAM ── DDR3 CH0 (2 GiB)
slice + native_dram ── ch1 ────────── otpu_mem_ch ── LiteDRAM ── DDR3 CH1 (2 GiB)
加速器内部的数据流全景(MXU、TMEM、VPU 与双通道 AXI 端口)可以在这张 floorplan 里看清楚:
🕒 第一步:读懂时钟树(时钟规划是 Bring-up 的地基)
Bring-up 的第一件事不是下载 bitstream,而是把时钟算清楚。这张卡的所有时钟都源自板载 50 MHz 振荡器经 MMCM 分频:
| 时钟 | 频率 | 来源 | 驱动对象 |
|---|---|---|---|
sys_clk_50 |
50 MHz | AA28 振荡器 | MMCM(VCO 800 MHz) |
core_clk |
133.33 MHz(生产默认) | MMCM /6 | 加速器、控制寄存器、互连核心侧 |
clk_mig / ui_clk |
133.33 MHz | MMCM /3、MIG | LiteDRAM 控制器 AXI 侧 |
| DDR3 CK | 533 MHz | MIG PLL | DDR3 存储器 |
axi_aclk |
250 MHz(Gen2)/ 125 MHz(Gen1) | XDMA | PCIe AXI 侧 |
为什么是 133.33 MHz?这里有一条Roofline 逻辑(详见 docs/board.md 第 5 节):
- 每个 DDR3 通道(x64)在 DDR3-1066 下峰值约 8.5 GB/s,双通道合计 17.1 GB/s;
- 加速器峰值每
core_clk周期消费 128 字节,即吞吐 = 128 B × 核心频率; - 要让片上端口不成为瓶颈(17.07 GB/s ÷ 128 B ≈ 133.3 MHz),核心时钟必须 ≥ 133 MHz;
- 核心时钟高于 133 MHz 在 DDR3-1066 下毫无收益——内存带宽才是天花板。
这正是 Decode(逐 token 流式读权重)性能的决定因素,后面所有性能数据都能用这张表解释。
🏗️ 第二步:一键构建 bitstream
构建入口是 boards/ypcb-00338/Makefile,核心就两条命令:
cd boards/ypcb-00338
make lint # 离线检查:Tcl 语法、XDC 端口 vs 顶层、Verilator lint
make bit # Vivado 批处理构建 -> build/vivado/otpu.bit / otpu.mcs / reports/
几个新手必须知道的要点:
- License:Vivado 免费版不含 xc7k480t,需要付费 license 或 AMD 的 30 天评估版(node-locked 到网卡 MAC);
- 开发期建议
make bit FAST=1:100 MHz、默认综合策略,速度约一半,功能验证先行; - 构建耗时 1.5–3 小时,完成后先看
build/vivado/reports/SUMMARY.txt的 WNS/WHS 与每时钟达成频率,再看timing_summary.rpt、util_hier.rpt、cdc.rpt; - 实测默认构建(MCOLS=2、100 MHz):全部时序约束满足,WNS +0.082 ns;LUT 占用 62.9%、BRAM 66.5%、DSP 13.9%。
构建脚本 run_vivado.sh 支持用环境变量微调所有关键旋钮,例如 CORE_MHZ=100(关不收敛时的兜底)、MCOLS=4、PCIE_GEN=1(退到 Gen1 x8)、TARGET=ypcb-00338:m8(8 列 MXU 变体)等,全部默认值来自目标配置文件。
🔌 第三步:JTAG 下载 bitstream
bitstream 构建好后,用 JTAG 加载上卡。program.sh 封装了三种方式:
make program BIT=path/to/otpu.bit # openFPGALoader(macOS/Linux 通用)
make program-vivado BIT=path/to/otpu.bit # Vivado hw_manager
make flash MCS=path/to/otpu.mcs # 写入 BPI flash(掉电不丢)
这条链路上有几个真实的坑,脚本已经替我们处理好了:
- JTAG 链里有一颗 Inspur CPLD(IDCODE 0x10931093)挡在 FPGA 前面,openFPGALoader 必须显式声明
--misc-device并用--index-chain 0选中 FPGA; - Xilinx Platform Cable USB II 每次插入都要重刷 FX2 固件,脚本通过
XUSB_FIRMWARE自动处理; - FT232H 线(Digilent HS2 型)可直接替代:
CABLE=digilent_hs2 make program——项目最初的"第一次点亮"就是用这条线完成的; - 所有加载自动重试 5 次;若每次都是 "Unable to read constant",直接重插 USB 线。
⚠️ JTAG 加载的内容掉电即失,只有写进 flash 的才会保留。
📡 第四步:PCIe 点亮(最容易被忽略的一步)
这是新手最常卡住的地方:PCIe 设备必须在通电后约 100 ms 内就绪,而 JTAG 加载发生得晚得多——所以下载完之后,主机必须手动重扫总线:
sudo otpu-setup --rescan # 移除并重扫卡、绑定驱动、读 ID 寄存器
otpu-setup --check # 检查驱动、udev 规则、卡、链路、设备节点是否全部就位
otpu-setup(主机侧脚本在 opentpu/host/setup_pcie.sh)一次性完成:编译安装 Xilinx XDMA 内核驱动(含 DKMS 自动跟随内核升级)、安装 udev 规则(driver_override=xdma + 设备节点权限)、加载驱动并绑定设备。
期望结果:
- 链路速率 = 卡自身的
LnkCap:Gen2 bitstream 为 5 GT/s x8(约 3.0 GB/s),Gen1 为 2.5 GT/s x8; lspci -nn显示Processing accelerators [1200]: Xilinx Corporation Device [10ee:7028];- 设备节点
/dev/xdma0_user(BAR0 控制寄存器)、/dev/xdma0_h2c_0/_c2h_0(DMA 读写 DDR3)。
如果设备没出现:--rescan 会重训上游端口链路;仍然不行就暖重启主机(FPGA 配置在暖重启中保留,只要插槽不断电)。若链路训练成更窄的宽度,先怀疑 lane 顺序——本卡 GTX 引脚跨两个 bank(116 → 115),XDC 中显式 LOC 了每条 lane。
🧪 第五步:双通道 DDR3 校准与内存体检
PCIe 通了,内存还没通。DDR3 的 bring-up 分三层验证(流程详见 docs/board.md 第 5 节):
1. 校准——otpu-diag 的 "DDR3 calibration channel 0/1" 行(对应 STATUS 寄存器 bit 5/6):控制器在 5 秒内完成逐 lane 校准即通过,否则后续全部跳过。
2. 内存测试——otpu-diag --mem full --soak 10:对整 4 GiB 跑 march C- 测试 + 重复内核压力,冷态和热态(跑 10 分钟以上 otpu-chat 之后)各来一次,因为时序余量随芯片升温会收窄。
3. ECC 纠错计数——单比特错误会被静默纠正,"边缘链路"可能所有测试都通过。所以要在压力前后读 ECC correctable-error 计数器,必须保持为 0。
DDR3 速率选择上有一条重要实测结论(HR bank @ 1.5 V 的规格边界):
| DDR3 速率 | 是否在规格内 | 板卡实测结果 |
|---|---|---|
| DDR3-800 | ✅ | 基线,全部通过 |
| DDR3-1066 | ✅ | 生产选择:校准通过,decode 周期数 -20% |
| DDR3-1300 | ❌(超规格) | 校准与 diag 均通过,但未做完整资格认证 |
| DDR3-1333 | ❌(需打 PHY 补丁) | 失败:H2C 超时后卡掉出 PCIe 总线 |
💡 教训:超规格速率即使"测过去"也不可靠——1333 的失败直接让卡脱离了 PCIe 总线。生产构建老老实实用 DDR3-1066(LiteDRAM 控制器就是按这个速率生成的)。
内存通道地址映射与主机侧的映射逻辑在 opentpu/host/board.py:加速器把两个物理通道交织成一个 4 GiB 逻辑 DRAM(64 字节 beat 粒度),主机工具一律使用逻辑地址,无需关心通道细节。
✅ 第六步:selftest → diag → 聊天(验证闭环)
板卡点亮的最终判据是三步走(命令清单与原理见 docs/host.md):
otpu-selftest # 分级自检,任一阶段失败即停并给提示
otpu-diag --json diag.json # 全量诊断:不中断,输出"能/不能"矩阵
otpu-chat --backend board # 在卡上跑 Qwen3-0.6B 聊天
otpu-smi # 另一个终端看卡的状态
otpu-selftest 按 link → 寄存器 → 内存 → DMA 带宽 → 指令集 → 模型 逐级推进;otpu-diag 则执行所有前置条件满足的检查(124+ 项,含 93 种指令变体),输出可存档的 JSON 状态记录。
"第一次点亮"(2026-09-26,实测)成绩单:PCIe Gen1 x8、双通道 DDR3 均校准成功,selftest 全阶段通过,greedy 解码与 ISA 模拟器逐 token 一致:
| 模型 | 每 token 百万周期 | 100 MHz 下 tok/s |
|---|---|---|
| Qwen3-0.6B | 20.66 | 4.8 |
| LFM2.5-230M | 7.71 | 13.0 |
| Qwen3.5-0.8B | 25.91 | 3.9 |
经过 AXI 读突发、DDR3-1066、地址映射(ROW_BANK_COLUMN)等几轮优化后,生产镜像(133.33 MHz + DDR3-1066)达到:
| 模型(4-bit + int8 head) | decode tok/s | decode 时 DRAM 带宽 | prefill tok/s |
|---|---|---|---|
| LFM2.5-230M | 85.8 | 14.1 GB/s(82% 峰值) | 335 |
| Qwen3-0.6B | 31.3 | 13.9 GB/s(82%) | 103 |
| Qwen3.5-0.8B | 24.5 | 14.1 GB/s(83%) | 67 |
注意 DRAM 效率稳定在 82–85%——decode 是 DRAM-bound,这个数字就是硬件的极限体现。
板卡上聊天 + 状态监控的真实画面(左侧 otpu-chat 在生成回答,右侧 otpu-smi 显示 PCIe 链路、DRAM 带宽与温度):
💾 附录:写入 Flash,让开机即启动
JTAG 加载掉电即失。卡上挂的是 BPI x16、64 MB 并行 NOR flash(约束见 constraints/vendor_ypcb003381p1.xdc):
make flash MCS=../../build/vivado/otpu.mcs # 经 FPGA 内的 BPI 桥写 flash
流程要点(完整方案与"golden image + 回退"设计见 docs/flash.md):
- 先备份原厂 flash 镜像(
flash_jtag.sh backup)——写之前这是唯一副本; - 写入后 FPGA 从 flash 配置,冷上电即枚举,无需 JTAG、无需重扫;
- 13.1 MiB 的压缩镜像在默认 CONFIGRATE 下约 2.3 s 配置完毕,早于 BIOS 枚举,时间上安全。
📋 Bring-up 检查清单(一页速查)
| 阶段 | 命令 / 动作 | 判据 |
|---|---|---|
| 构建 | make lint && make bit |
SUMMARY.txt:全部时序满足,WNS > 0 |
| 下载 | make program BIT=... |
openFPGALoader 成功(5 次重试兜底) |
| PCIe | sudo otpu-setup --rescan |
--check 输出 "all in place",LnkSta = 5 GT/s x8 |
| 内存 | otpu-diag(校准行) |
双通道 5 s 内校准完成 |
| 体检 | otpu-diag --mem full --soak 10 |
冷态 + 热态全通过,ECC CE = 0 |
| 功能 | otpu-selftest |
ALL PASS |
| 业务 | otpu-chat --backend board |
逐 token 与 ISA 模拟器一致 |
| 固化 | make flash MCS=... |
冷上电自动枚举 |
📚 相关文件导览
| 资料 | 说明 |
|---|---|
| docs/board.md | 板卡构建与 Bring-up 主文档(本文的事实来源) |
| docs/host.md | 主机侧驱动、工具与寄存器/设备节点 |
| docs/flash.md | BPI flash 写入方案与 golden image 设计 |
| docs/litedram.md | LiteDRAM 控制器与 DDR3 带宽模型 |
| boards/ypcb-00338/Makefile | lint / bit / program / flash 入口 |
| boards/ypcb-00338/program.sh | JTAG 下载与 flash 写入脚本 |
| boards/ypcb-00338/run_vivado.sh | Vivado 批处理构建(原生 / Docker) |
| targets/ypcb-00338.toml | 目标配置:架构参数、时钟、变体定义 |
| rtl/boards/ypcb-00338/otpu_fpga_top_ld.sv | LiteDRAM 版顶层 |
| opentpu/host/board.py | 主机侧地址映射与板卡抽象 |
Bring-up 的本质是把"时钟算对 → 构建收敛 → 链路训通 → 内存可信 → 数值一致"这条链逐级点亮:每一步都有明确的判据命令和失败兜底,这也是 openTPU 把整条流程(含所有踩坑记录)写进仓库文档的原因。照上面的清单走,你也能在自己的 Kintex-7 板卡上复现这条点亮路径。

