Kintex-7 双通道 DDR3 板卡 Bring-up 全记录:openTPU FPGA 从时钟到 PCIe 的点亮过程

原创2026-11-02 14:53:521,871 阅读

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 里看清楚:

openTPU Kintex-7 加速器 floorplan:双通道 DDR3 AXI 端口、MXU、TMEM 与 VPU 的数据流与时钟路径

🕒 第一步:读懂时钟树(时钟规划是 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(掉电不丢)

这条链路上有几个真实的坑,脚本已经替我们处理好了:

  1. JTAG 链里有一颗 Inspur CPLD(IDCODE 0x10931093)挡在 FPGA 前面,openFPGALoader 必须显式声明 --misc-device 并用 --index-chain 0 选中 FPGA;
  2. Xilinx Platform Cable USB II 每次插入都要重刷 FX2 固件,脚本通过 XUSB_FIRMWARE 自动处理;
  3. FT232H 线(Digilent HS2 型)可直接替代:CABLE=digilent_hs2 make program——项目最初的"第一次点亮"就是用这条线完成的;
  4. 所有加载自动重试 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 带宽与温度):

Kintex-7 板卡 Bring-up 完成后运行 LFM2.5 大模型聊天,otpu-smi 显示 PCIe Gen1 x8 链路与双通道 DDR3 实时状态

💾 附录:写入 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):

  1. 先备份原厂 flash 镜像(flash_jtag.sh backup)——写之前这是唯一副本;
  2. 写入后 FPGA 从 flash 配置,冷上电即枚举,无需 JTAG、无需重扫;
  3. 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 板卡上复现这条点亮路径。

登录后查看全文
openTPU