极客工场

Appearance

共 2,413 字预计阅读约 8 分钟

nextpnr 版本不匹配速查：chipdb 版本不符、unknown cell type 与找不到数据库怎么办 ​

更新时间：2026-10-23。FAQ 速查页，属于 FPGA 工具报错排错系列。nextpnr（开源 FPGA 布局布线工具）的版本兼容问题有一个和商业工具不一样的根因：它是「nextpnr 二进制 + chipdb 数据库 + yosys 综合器 + 内嵌 Python」四个组件拼起来的组合体，任何两件的版本错位都会咬人——chipdb 是用某个版本的 nextpnr 源码编出来的，换二进制不换库就报版本不符；yosys 太旧输出的 .json 缺字段，太新用了 nextpnr 不认识的 cell 类型；多套工具链（系统包、OSS CAD Suite、自编译）共存时 PATH 指错更是家常便饭。闭源阵营的同类问题对照 Quartus 版本不兼容速查 与 Yosys 版本不兼容速查。

本文要回答的问题 ​

  • 「chipdb version mismatch」是 chipdb 错了还是 nextpnr 二进制错了？
  • yosys 综合出来的 .json 被 nextpnr 报 unknown cell type，升谁降谁？
  • 报「cannot open database file」是真缺文件还是版本对不上？
  • 机器上装了系统包、OSS CAD Suite、自编译三套，怎么确认现在跑的是哪套？
  • nextpnr 内嵌 Python 脚本报 API 错，和 Python 版本有什么关系？
  • 怎么从组织上避免「半套升级」再次踩坑？

一、报错原文与典型现象 ​

版本错位在四个位置暴露：启动加载 chipdb 时、读 yosys 网表时、内嵌 Python 执行时、调 icestorm/trellis 数据文件时。以下为典型文案，路径与器件名已占位：

1. chipdb 版本不符（启动加载器件数据库时报）：

text
ERROR: chipdb version mismatch: database was generated with
nextpnr version 0.7, but this binary expects 0.6.

chipdb（内嵌或外置的器件数据库）由特定版本源码生成，二进制与库必须成对。OSS CAD Suite 只更新了一半组件、或自编 nextpnr 指到了旧库目录，是最常见的触发方式。

2. yosys 网表不兼容（nextpnr-ice40 --json <design>.json 读网表时报）：

text
ERROR: unknown cell type '$_DFFSR_' at cell '<path>/cell_42'

yosys 太新，输出了该版本 nextpnr 不认识的 cell；反向也有——yosys 太旧输出的 .json 缺 nextpnr 新版要求的字段，报「missing attribute」一类错。两边都归「yosys-nextpnr 版本对不齐」。

3. 找不到数据库文件（启动时报）：

text
ERROR: cannot open database file '<prefix>/share/nextpnr/ice40/chipdb-384.bin'

两种情况：文件真不存在（装得不全），或装的是另一套器件族的数据库（比如用 ice40 目标却指向 trellis 的 ECP5 库目录）。前者补装，后者是前缀/环境变量指错。

4. Python 绑定版本错（用 nextpnr 的 Python API 写自定义布局脚本时报）：

text
AttributeError: module 'nextpnr' has no attribute 'Context'

nextpnr 内嵌 Python 绑定随版本演进，教程脚本按老 API 写、二进制是新版本（或反之），属性名/函数签名对不上。系统里有多个 Python 时，nextpnr 内嵌的解释器版本也可能与脚本预期不符。

二、现象 → 病因 → 处置速查表 ​

报错现象最常见病因处置
chipdb version mismatchchipdb 用 A 版本生成、二进制是 B 版本（半套升级）整套对齐：nextpnr 与 chipdb 来自同一次构建/同一个发行包
unknown cell typeyosys 太新，cell 类型 nextpnr 不认识对齐 yosys 与 nextpnr 版本；或 yosys 综合后加 synth_ice40 等目标流程重出网表
missing attribute / json 解析错yosys 太旧，.json 缺新字段升级 yosys 到与 nextpnr 同期版本
cannot open database file文件缺失或前缀指错到别的器件族核对 --chipdb 参数与安装前缀；补装对应器件族数据库
Python AttributeError脚本按老 API 写，或系统多 Python 串错解释器按当前 nextpnr 版本的 Python API 文档改脚本；确认内嵌 Python 版本
甲机好乙机报错多套工具链共存，PATH 指到不同套which -a nextpnr-ice40 yosys 全列出来，统一到单一套装
ice40 目标报 trellis 库错器件族混指：ice40 命令指向 ECP5 库按器件族核对命令（nextpnr-ice40 / nextpnr-ecp5）与库目录一一对应
OSS CAD Suite 更新后报错只更新了部分组件（如只换了 yosys）整包替换或整包回退，不要混着用新旧两半
自编译后系统包报错自编 nextpnr 与系统包 chipdb 混用自编用自编库（安装到独立前缀），系统包用系统库，PATH 二选一

三、排查决策树 ​

分诊只做两件事：先把四类版本串抄齐，再对号走对应通道。下图颜色含义：红=报错入口，蓝=排查动作，橙=修复动作，绿=流程恢复，紫=防复发。

fpga/ts-nextpnr-version-mismatch.md D2 示意图

读这张图抓住一条主线：红色入口之后，蓝色第一步永远是抄齐四类版本串——nextpnr-ice40 --version、yosys -V、which -a nextpnr-ice40 yosys 看路径前缀是否同源，用 Python 脚本的再加一条确认 nextpnr 内嵌 Python 版本。四个通道互不相通：chipdb 版本不符靠升降 yosys 治不好，PATH 串台靠重装单套也变不出来；橙色处置做完必须回到绿色节点用一次完整流程（yosys 综合 → nextpnr 布局布线 → icepack/ecppack 打包）确认闭环，最后落到紫色节点把版本纪律固化。

四、逐条排查展开 ​

chipdb 类：二进制与库必须成对，整套对齐重装最稳。 chipdb 是 nextpnr 构建期从器件数据生成的，版本串写死在文件头里，换二进制不换库就报 mismatch。用 OSS CAD Suite 的最省事——整包删除换新版或整包回退旧版，包内 nextpnr、chipdb、yosys 天然对齐；自编译的记住「make install 装的是一对」，不要只拷贝新二进制去配旧库目录。报「cannot open database file」时先用 ls <prefix>/share/nextpnr/<family>/ 看库文件在不在、是哪个器件族的（ice40 的 chipdb-384.bin 与 ECP5 的库不能互相顶替）。

网表类：yosys 与 nextpnr 保持同期版本。 报 unknown cell type 先查 yosys 版本——yosys -V 与 nextpnr 版本对拍，两者最好来自同一个发行包或同一段时间的源码。临时绕法是综合时显式走目标器件流程（synth_ice40、synth_ecp5），让 yosys 只输出 nextpnr 认识的 cell 集合；根治是升降 yosys 到匹配版本。反向「missing attribute」是 yosys 太旧，同理升级。

Python 类：脚本跟着 API 版本走，解释器别串。 nextpnr 的 Python 绑定（nextpnr 模块）随版本加删 API，网上教程脚本按老版本写的居多。报错后查当前版本对应的 Python API 文档改脚本；系统里有多个 Python 时，确认 nextpnr 内嵌的是哪一个（构建期定死），自定义脚本要在兼容的解释器下跑。

PATH 类：多套装共存必须单源化。 which -a nextpnr-ice40 列出所有命中路径，常见串台是系统 apt 包排在 OSS CAD Suite 前面、或 .bashrc 里旧前缀没清干净。处置：环境只留一套的路径，其余从 PATH 摘掉；要并存就写绝对路径调用，别靠 PATH 顺序赌。换终端才报错的多半是 shell 配置文件里加载逻辑不一致，把 export 集中到一处。

五、预防与纪律 ​

  • 整套对齐，不半套升级：OSS CAD Suite 整包替换；自编译的 nextpnr 与 chipdb 同一次 make install。
  • 版本串全抄：nextpnr、yosys、chipdb 版本串加 Python 版本四件套，README 与 CI 日志开头各打一份。
  • PATH 单源化：环境只留一套工具链路径；多套并存用绝对路径调用，不靠顺序。
  • 器件族一一对应：ice40 用 nextpnr-ice40 + ice40 库，ECP5 用 nextpnr-ecp5 + trellis 库，不混指。
  • CI 镜像钉版：构建容器固定整套工具版本，升级走窗口并回归，不在日常构建里随手拉新。
  • Python 脚本随版本走：脚本头注明兼容的 nextpnr 版本，换版本先过一遍 API 差异。

这一篇在知识体系里的位置 ​

本篇是 FPGA 工具报错排错簇中「版本兼容」节点的 nextpnr FAQ 页：综合侧的版本问题（yosys 与 nextpnr 对不齐的另一半）见 Yosys 版本不兼容速查；闭源阵营的单向兼容与 IP 升级逻辑对照 Quartus 版本不兼容速查。版本对齐之后仍跑不出结果的容量类问题，转 nextpnr 资源放不下速查。

一句话总结 ​

nextpnr 版本不匹配先抄齐四件套版本串（nextpnr --version、yosys -V、which -a 路径对拍、内嵌 Python），再按报错原文分四类：chipdb version mismatch 是二进制与库不配对，整套对齐重装不半套升级；unknown cell type 是 yosys 与 nextpnr 版本错位，升降 yosys 或显式走 synth 目标流程；cannot open database file 是库缺失或器件族混指，核对前缀与器件族一一对应；Python AttributeError 是脚本 API 与绑定版本不符，按当前版本文档改脚本。根治靠单源套装、PATH 单源化、版本串四件套锁定与 CI 镜像钉版。