极客工场

Appearance

共 2,759 字预计阅读约 9 分钟

nextpnr 顶层端口未约束 PCF 报错：IO unconstrained in PCF 的硬错误与降级开关 ​

更新时间：2026-11-11。长尾排查篇，属于 EDA 报错排查系列，汇总入口见 开源 EDA 报错排查导航。Yosys 综合顺利产出 JSON，nextpnr-ice40 却在加载 PCF 一步直接报 ERROR: IO 'led' is unconstrained in PCF 退出，这是 iCE40 开源流程里最常见的后端报错之一。本文用一个三端口最小工程把默认硬错误、降级开关和补齐约束三条路径全部跑透。

首屏答案：PCF 文件只约束了 clk 和 rst，漏掉顶层输出 led 的 set_io 条目，nextpnr 无法决定把这个端口放到 hx1k tq144 的哪个物理引脚上，于是抛出两条 ERROR 并以退出码 255 中止。报错文案里自带的 --pcf-allow-unconstrained 只是把硬错误降级为警告、让工具自动分配引脚，位置不可控，只适合临时应急；正道是在 PCF 中补上 set_io led 23，复跑后布局布线正常结束，icepack 打出 32220 字节的比特流。

PCF 未约束顶层端口的六步处置路径：从综合产物到比特流

这张流程卡对应本文的叙事顺序：先看清报错卡在哪一步，再区分应急开关与正式修复，最后用比特流产物收口。跳过 PCF 核对直接加开关，是这类问题最常见的返工路径。

本文要回答的问题 ​

  • PCF 漏掉一个顶层端口的 set_io 时，nextpnr-ice40 0.6 的完整报错原文是什么，退出码是多少？
  • 未约束端口为什么是硬错误而不是警告，它和 hx1k tq144 封装引脚是什么关系？
  • --pcf-allow-unconstrained 到底改了什么，自动布局的引脚能不能直接上板？
  • 补齐约束后怎样用 nextpnr 与 icepack 的输出确认修复闭环？

一、完整报错原文 ​

最小工程只有一个带复位的翻转寄存器，顶层三个端口：时钟 clk、复位 rst、输出 led。

verilog
module top(input clk, input rst, output reg led);
always @(posedge clk)
  if (rst) led <= 1'b0;
  else led <= ~led;
endmodule

综合脚本走标准的 iCE40 JSON 流程，synth_ice40 -json 直接产出 nextpnr 可读的网表：

bash
read_verilog top.v
synth_ice40 -top top -json top.json

出问题的 bad.pcf 只有两行，led 被漏掉了：

bash
set_io clk 49
set_io rst 50

执行 nextpnr-ice40 --hx1k --package tq144 --json top.json --pcf bad.pcf --asc bad.asc，工具先成功绑定了两个有约束的端口，随即在 led 上中止。下面是日志原样摘录，未作任何润色：

exp-log
$ nextpnr-ice40 --hx1k --package tq144 --json top.json --pcf bad.pcf --asc bad.asc
Info: constrained 'clk' to bel 'X6/Y0/io1'
Info: constrained 'rst' to bel 'X7/Y0/io0'
ERROR: IO 'led' is unconstrained in PCF (override this error with --pcf-allow-unconstrained)
ERROR: Loading PCF failed.
0 warnings, 2 errors
exit code: 255

读这段输出抓住三点。第一，两条 Info: constrained 证明 PCF 本身能被解析，问题不是文件格式或引脚号非法，而是约束不全；第二，报错明确点名端口 led，并在括号内直接给出降级开关的名字，这是 nextpnr 的固定文案；第三，Loading PCF failed 说明整个 PCF 加载阶段被判失败，进程以 255 退出，不会产生 .asc 布线结果，后续 icepack 自然无从打包。

二、工具与版本 ​

本次实验全部在 Docker 镜像 geek-eda:0.4-flow 内完成，宿主机只负责启动容器，不参与布局布线。工具版本与日志头部完全一致：

  • nextpnr-ice40 0.6-3build5（Debian 打包版本号）
  • Yosys 0.33，负责 synth_ice40 综合
  • Project IceStorm 工具集的 icepack，负责 ASCII 布线结果到二进制比特流的打包

版本要先固定，是因为 PCF 诊断措辞和开关行为随 nextpnr 版本演进过。本文的报错原文、警告文案与退出码只对 0.6 这个构建负责；换到其他大版本时，应保留当次完整输出再对照，不能凭本文文案反推。

三、根本原因：PCF 是顶层端口到物理引脚的契约 ​

3.1 set_io 连接的是网表端口与封装引脚 ​

PCF（Physical Constraints File）在这个流程里只做一件事：把综合后网表里的顶层端口名，绑定到目标封装的具体引脚号上。--hx1k --package tq144 选定的器件是 iCE40 HX1K 的 TQ144 封装，set_io clk 49 的含义就是「端口 clk 必须落在 144 脚封装的第 49 脚」。下图画出三个端口各自的落点，其中 led 这一条链是断的。

eda/ts-nextpnr-unconstrained-top-port.md D2 示意图

图中红色节点是断掉的约束链：正常端口经 set_io 落到确定引脚，而 led 在 PCF 里查不到条目，工具无法把它分配给任何物理 IO BEL。综合阶段为什么没拦住？因为 Yosys 只面对逻辑网表，不知道封装和引脚的存在；端口到引脚的映射是 nextpnr 加载 PCF 时才履行的契约，这也是 Yosys synth_ice40 全流程 中综合与布局布线两个阶段的分工边界。

3.2 为什么默认是硬错误 ​

未约束端口不只是「少写一行配置」。如果工具默默挑一个引脚，烧录后 led 可能落在没有接线、被其他功能占用或电气属性不符的引脚上，板级现象会是「比特流能烧、灯不亮」，排查成本远高于编译期报错。因此 nextpnr 的默认策略是拒绝替用户猜测，直接中止 PCF 加载，把问题钉在构建期解决。理解了这一点，就能明白报错文案为什么把降级开关显式写进括号里——它知道有人确实需要自动分配，但要求你主动声明、自担后果。

3.3 降级开关改的是报错等级，不是约束本身 ​

加上 --pcf-allow-unconstrained 后，同一条事实被降级为警告，进程退出码变为 0：

bash
nextpnr-ice40 --hx1k --package tq144 --json top.json \
  --pcf bad.pcf --pcf-allow-unconstrained --asc override.asc

对应输出是 Warning: IO 'led' is unconstrained in PCF and will be automatically placed。注意措辞从 unconstrained in PCF 变成了 will be automatically placed：开关没有凭空生成约束，只是允许布局器自行挑一个空闲引脚。这个引脚在每次布局、每个工具版本间都可能变化，与 PCB 上的实际走线没有任何对应关系，因此它只适用于暂时没有板级引脚要求的原型验证，不能作为交付配置。三种处理路径的差异可以压成下表。

处理方式端口 led 的引脚退出码产物适用场景
默认（坏 PCF）无落点255无 .asc报错即止，提示补约束
加降级开关工具自动分配，不可控0可打包但引脚随机无板级约束的临时原型
补齐 set_io固定引脚 23032220 字节比特流正式修复，可上板

四、排查清单：先数端口，再对 PCF，最后看分支 ​

eda/ts-nextpnr-unconstrained-top-port.md D2 示意图

图中蓝色是信息收集动作，灰色是判定节点，红色是默认失败分支，橙色是应急分支，绿色是正式修复分支。对照这张图，落地排查按四步走：

  • 先数网表端口：打开顶层模块列出全部输入输出，本例是 clk、rst、led 三个；多位宽总线在 PCF 中要逐位约束，漏一位同样触发该报错。
  • 再对 PCF 条目：每个端口名必须能在 PCF 里找到同名 set_io，注意端口名大小写与拼写，综合后的网表名才是匹配依据。
  • 核对引脚号合法性：引脚号必须存在于目标封装（本例 tq144）且具备对应 IO 能力，引脚号非法会是另一类报错，不要与本条混淆。
  • 按分支选动作：正式工程补约束复跑；只有临时原型才允许用降级开关，并且要在交付前用完整 PCF 重新生成比特流。

如果设计里还有双向端口，端口能否被综合成 iCE40 的 SB_IO 原语属于综合阶段的问题，排查方法见 Yosys ice40 SB_IO 推断失败排查，与本文的 PCF 落点问题分属两个阶段。

五、修复代码与复跑确认 ​

修复只动 PCF，给 led 补上引脚 23 的约束，RTL 与综合脚本一行不改：

bash
set_io clk 49
set_io rst 50
set_io led 23

一次 bash run.sh 顺序跑出坏 PCF 报错、降级开关警告和修复后通过三段记录，前两段的终端实录如下：

坏 PCF 硬错误退出与降级开关警告的对照输出

第三步用 fixed.pcf 重跑并接 icepack 打包，日志原样摘录如下：

exp-log
--- 3. fixed PCF: place-and-route finishes, bitstream packs ---
$ nextpnr-ice40 ... --pcf fixed.pcf && icepack

Info: Program finished normally.
nextpnr exit code: 0
icepack ok: 32220 bytes

修复闭环有三处证据要一起读。其一，nextpnr 输出 Program finished normally 且退出码为 0，说明三个端口全部完成引脚绑定、布局布线走完全程；其二，fixed.asc 正常产出，icepack 才能接上班，生成 32220 字节的 fixed.bin，与 hx1k 器件的比特流体积量级吻合；其三，整个修复没有触碰 RTL，证明问题自始至终在约束文件而非逻辑设计。综合产物 JSON 的字段核对方法可参考 Yosys JSON 网表回读检查。

实验环境 ​

  • 机器/系统：macOS 宿主机启动 Docker，容器内为 Debian bookworm 系工具链
  • 工具版本：镜像 geek-eda:0.4-flow，nextpnr-ice40 0.6-3build5、Yosys 0.33、Project IceStorm icepack
  • 日期：2026-11-11
  • 完整命令：在实验目录执行 bash run.sh；脚本先跑 yosys -s synth.ys 综合出 top.json（310164 字节），再依次执行坏 PCF、带 --pcf-allow-unconstrained、fixed.pcf 三次 nextpnr-ice40，最后对修复结果执行 icepack，并打印每步退出码。

代码获取 ​

完整源码、综合脚本、bad.pcf 与 fixed.pcf 两份约束文件及复现脚本位于公开仓：https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-nextpnr-unconstrained-top-port。本地取得 geek-eda:0.4-flow 镜像后，在仓库上级目录执行以下命令即可原样复现三段运行：

bash
docker run --rm -v "$PWD":/work -w /work/ts-nextpnr-unconstrained-top-port geek-eda:0.4-flow bash run.sh

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

本篇属于 开源 EDA 报错排查导航 的 iCE40 后端分支，回答「PCF 漏约束为什么硬失败、开关能不能替代约束」。正常流程的完整四步走见 Yosys synth_ice40 流程：RTL 到 iCE40 比特流四步走通；综合阶段的双向端口原语问题见 Yosys ice40 SB_IO 推断失败排查；综合产物 JSON 的回读核对见 Yosys JSON 网表回读：write_json 与 read_json 往返检查。四篇合起来覆盖 iCE40 开源链路「综合、网表交换、IO 推断、引脚约束」四个故障面。

总结 ​

nextpnr 顶层端口未约束 PCF 报错，本质是端口到物理引脚的契约缺项：bad.pcf 只约束 clk 与 rst，输出 led 没有 set_io 条目，nextpnr-ice40 0.6 拒绝替用户猜测引脚，抛出 IO 'led' is unconstrained in PCF 与 Loading PCF failed 两条 ERROR 并以 255 退出。--pcf-allow-unconstrained 只把硬错误降级为自动放置警告，引脚随机且不可控，仅限临时原型；正式修复是补上 set_io led 23，复跑后布局布线正常结束，icepack 打出 32220 字节比特流，且全程无需改动 RTL。