nextpnr 引用无法解析：网表缺 cell 与黑盒模块速查
更新时间：2026-10-25。FAQ 速查页，属于 FPGA 开源工具链排错系列。nextpnr 拿到 yosys 给的 JSON 网表开始布线，开头就报某个 cell 类型不认识、或某个模块根本没有定义——这类「引用无法解析」十有八九不是 nextpnr 的问题，而是综合阶段交出来的网表本身就不完整：层级没展开、黑盒没填实现、库映射漏了一类单元。排查的正确方向是回到 yosys，而不是在 nextpnr 参数里找开关。相邻问题见 nextpnr 模块找不到、nextpnr 未定义符号 与 yosys 引用无法解析。
本文要回答的问题
- nextpnr 报 cell 找不到，为什么是 yosys 阶段的锅？
hierarchy -top忘了写会怎样，报错长什么样？- 黑盒模块（只有端口没有实现）怎么让流程跑通？
- 工艺库映射缺失时，该补库还是改 RTL？
一、报错原文与现象
ERROR: Cell type 'my_fifo' is not recognised
ERROR: Module 'pll_50m' referenced but not defined
Warning: replacing unknown cell 'SB_PLL40_CORE' with blackbox
ERROR: Failed to import cell 'u_ram' of type 'dp_ram_4k'第一条和第二条是最典型的形态：网表里引用了 my_fifo、pll_50m 这样的模块名，但它们的定义从没被综合进来——nextpnr 只认目标器件的原语单元，任何用户层级模块都必须在这之前被展开成原语。第四条 dp_ram_4k 这类自定义存储模块同理。第三条 Warning 看着温和，实际是把不认识的单元当黑盒放行，布出来的结果必然不对。
二、可能原因总览
| 报错/现象 | 可能原因 | 处置 |
|---|---|---|
| Cell type not recognised | 层级未展开，用户模块进了网表 | yosys 补 hierarchy -top 与 synth |
| referenced but not defined | 模块文件没读进 yosys | 核对 read_verilog 文件列表 |
| replacing unknown cell with blackbox | 单元类型工具链不认识 | 查库映射或换成目标器件原语 |
| Failed to import cell | 网表 cell 与器件库不匹配 | 确认 synth 目标族与实际器件一致 |
| 顶层名对不上 | -top 指定的名字不是真顶层 | 用 yosys 列出的模块名单核对 |
| 参数化模块未实例化 | generate/参数组合没展开 | 检查参数传递与实例名 |
| 库单元缺时序信息 | 自定义库单元无 timing 视图 | 换用官方原语或补库描述 |
三、逐条排查展开
先立一个心智模型：nextpnr 只认原语。 iCE40 流程里 nextpnr 认识的单元是 SB_LUT4、SB_DFF、SB_IO 这类器件原语；ECP5 流程是 TRELLIS_SLICE 那一族。凡是你在 RTL 里写的模块名（my_fifo）、例化的软核名，出现在最终网表里就是「引用无法解析」。所以看到这类报错，第一反应是问「yosys 为什么没把它展开成原语」，而不是翻 nextpnr 的文档。
层级展开的正确顺序。 yosys 脚本的标准骨架：
read_verilog top.v fifo.v pll.v
hierarchy -check -top top
synth_ice40 -top top
write_json build/top.jsonhierarchy -check -top top 做两件事：确认 top 存在且为唯一顶层，把所有子模块的引用与定义对上号——-check 会让缺定义的模块在这一步就报错，而不是留到 nextpnr 才炸。漏写这行或漏写 -top，多顶层工程可能选错顶层，子模块缺定义也只能到后面才暴露。报错信息里出现用户模块名，九成是这一步没做对或文件没读全。
模块文件没读全是最常见的低级原因。 工程加了新文件忘了加进 yosys 的 read 列表，或 Makefile 里 VERILOG_SRCS 变量漏了一项——hierarchy -check 会直接告诉你哪个模块缺定义，按名字补文件即可。建议 read 列表用通配或显式变量集中管理，不要散在多处。
黑盒模块：知道自己在干什么再用。 有时候你故意不给实现：比如调用厂商硬核、或某个 IP 只有网表没有源码。做法是在 RTL 里给黑盒模块加属性声明：
(* blackbox *)
module hard_ip (...);这样 yosys 知道「这是故意的空洞」，不在层级检查时报错。但要想清楚：nextpnr 最终还是要认识这个单元的物理实现，纯黑盒到了布线阶段依然要能提供对应原语或网表，否则只是把时间炸弹往后挪。「工具自动把未知单元转黑盒」那种 Warning 必须当错误处理，不能放任。
库映射缺失：目标族对不上。 synth_ice40 综合出的网表喂给 nextpnr-ecp5，或自定义库单元没有对应器件的物理视图，都会报 cell 不认识。处置：确认综合目标族（synth_ice40 / synth_ecp5）与 nextpnr 调用的器件系列一致；存储、PLL 这类资源优先直接例化官方原语，比依赖综合器推断更可控。与 nextpnr 版本不匹配 里讲的工具链版本对齐是同类纪律。
参数化模块与 generate。 参数传递写错、generate 块条件恒假，会导致某个实例根本没被创建，引用它的上层自然报未定义。这类问题在 yosys 阶段用 hierarchy -check 加 stat 命令核对模块实例数量最容易抓。
用 stat 做网表完整性体检。 综合结束前跑一条 stat，输出里会列出每个模块的单元类型与数量统计。两个用法：一看有没有用户模块名出现在单元统计里——出现了就说明层级没展开干净；二看原语构成是否合理——比如一个 FIFO 设计里一个 SB_RAM40_4K 都没有，说明存储被推断成了触发器堆，面积和时序都不会好看。把 stat 输出归档进每次构建的日志，出问题时前后对比，能省掉大量盲猜。
名字对不上的旁支问题。 报错里的名字带层级路径（如 u_ram.dp_ram_4k），说明层级只展开了一半；名字带随机后缀则是综合改名。这类「名字与定义对不上」的排查手法和 nextpnr 信号被优化看不到 互通：都是回 JSON 网表查实际名单。
四、排查决策流程
这张图的关键分叉在「报错名字是用户模块还是原语」：用户模块名走左支——层级没展开或文件没读全，回 yosys 补 hierarchy -check -top 与 read 列表；原语/库单元名走右支——目标族或库映射问题，对器件系列、换官方原语。两支都汇入绿色节点：重综合到 yosys 零未定义再交给 nextpnr。
五、预防与纪律
- read 列表集中管理：源文件清单用一个 Makefile 变量维护，新增文件只改一处。
- hierarchy -check 永不省略：让缺定义在综合阶段就炸，不把未定义引用留给 nextpnr。
- 黑盒必须有明确去处：
(* blackbox *)只用于「后续确实能拿到实现」的单元，工具自动转黑盒的 Warning 一律当错误。 - 原语优先于推断：PLL、块存储等关键资源直接例化官方原语，减少库映射变数。
- yosys 零未定义才进布线：把「综合输出无 unresolved 引用」写进 CI 检查项。
这一篇在知识体系里的位置
本篇是 FPGA 开源工具链排错簇中「网表完整性」节点的 FAQ 页：与 nextpnr 模块找不到（文件/路径侧）、nextpnr 未定义符号（符号侧）、yosys 引用无法解析（综合阶段视角）、nextpnr 信号被优化看不到（名字对不上的旁支）互补；工具链版本对齐纪律见 nextpnr 版本不匹配，系列总览见 FPGA 知识版图。
一句话总结
nextpnr 报引用无法解析，本质是综合交出的网表不完整：报错名是用户模块，就回 yosys 补 hierarchy -check -top 和 read 文件列表，让缺定义在综合阶段就暴露；报错名是原语或库单元，就核对综合目标族与器件系列一致、关键资源改例化官方原语；故意的黑盒加 (* blackbox *) 并确保后续有实现，工具自动转黑盒的 Warning 当错误处理；最终纪律是「yosys 零未定义引用才交给 nextpnr」，并写进 CI 检查。