极客工场

Appearance

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

nextpnr 命令行参数报错（unknown option / bad argument）速查 ​

更新时间：2026-10-23。FAQ 速查页，面向 FPGA 入门 阶段的同学。症状很典型：yosys 综合过了，手一敲 nextpnr-ice40 --hx8k --package ct256 --json top.json --pcf top.pcf --asc out.asc，回车瞬间就被 unrecognised option 或一整屏 usage 用法提示打回来，布局布线一步没走。本篇只回答一件事：nextpnr 连参数都读不进去时，怎么在十分钟内定位真正写错的那一个选项。

本文要回答的问题 ​

  • unrecognised option '--um5g-85k' 是参数拼错了还是根本不该用在这个二进制上？
  • --package 的封装名怎么才算和芯片型号「配对」？
  • --json / --pcf 后面漏了文件名为什么会报 Missing argument 或把下一个选项吃掉？
  • 从老教程抄来的 --freq、--placer heap 为什么在新版上报错或语义变了？
  • --seed=0 和 --seed 0 两种写法 nextpnr 都认吗？

一、报错原文：先看 nextpnr 真实长什么样 ​

nextpnr 的参数解析发生在任何实际工作之前，报错文案很朴素——要么说不认识这个选项，要么说缺参数，然后直接打印 usage 退出：

text
unrecognised option '--hx8k'
ERROR: Missing argument for option '--json'
ERROR: Bad argument for option '--package': ct256 not valid for this device
Usage: nextpnr-ecp5 [options...]
  --um5g-25k/--um5g-45k/--um5g-85k    select device
  ...

读这几行抓住两点：

  • unrecognised 意味着这个二进制根本没见过该参数——多半是家族串台（把 ice40 的参数喂给了 ecp5 可执行文件），而不是拼错一个字母；
  • usage 整屏打出说明解析阶段就中止了，后面的 json、pcf 路径对不对都没人看，先把命令行修干净再谈别的。

排查永远从第一个被点名的参数开始，修一个重跑一次。

二、排查决策树 ​

先看报错是「不认识」还是「缺参数/参数非法」：不认识先查家族二进制对不对，缺参数先查后面是不是漏了文件名；两条线都收敛后，再核芯片与封装的配对、版本改名与等号写法。

fpga/ts-nextpnr-config-parse-fail.md D2 示意图

读这张图抓住「先分流、再核配对」：红色是报错入口，蓝色是逐层排查动作，橙色是版本层修复（对照本版本 --help 改参数），紫色是写法层收敛（统一空格写法），绿色是干净重跑。任何一层命中就只修那一层，不要同时换二进制又改参数名，否则修好了也不知道哪一刀生效。

三、病因处置速查表 ​

报错现象可能原因处置
unrecognised option '--hx8k' 出现在 nextpnr-ecp5 上家族参数串台：ice40 的器件参数喂给了 ecp5 二进制ecp5 改用 --um5g-25k/45k/85k；或换用 nextpnr-ice40 二进制
unrecognised option '--speed 6' 或器件名参数不认识把老教程里别的家族/旧版本的参数照搬了过来跑 nextpnr-xxx --help 对照本版本参数表，逐条替换
Bad argument for option '--package'封装名写错（如 ct256 误写 cb256），或封装与芯片型号不配对按该器件合法封装清单改写：--hx8k --package ct256 才是合法组合
Missing argument for option '--json' 且 usage 打屏--json / --pcf 后面漏了文件名，或文件名以 - 开头被当成新选项补齐文件名；路径以短横开头时加 ./ 前缀
报错指向一个你以为是 Yosys 的参数（如 -p、synth_ice40）把综合脚本的参数混进了 nextpnr 命令行nextpnr 只收 json/pcf/asc 类参数，综合动作回 Makefile 的 yosys 步骤
老命令里的 --freq 50 行为异常或报参数错版本升级后参数语义变化（如从全局频率变成按时钟名绑定），或被改名查本版本 --help 与 changelog，按新语义重写
--placer heap 报不认识或用法变了旧版默认 placer 写法在新版被调整去掉显式 placer 参数用默认；或按新版 --help 的可选值改写
--seed=0 报 unrecognised 而 --seed 0 能过（或反之）该版本的参数解析器对等号写法支持不一致统一用空格写法；以本版本 --help 给出的语法为准

四、逐条排查展开 ​

第一步：先确认你敲的是哪个二进制。 nextpnr 按 FPGA 家族分成 nextpnr-ice40、nextpnr-ecp5、nextpnr-machxo2、nextpnr-nexus、nextpnr-gowin 等多个可执行文件，器件参数是家族专属的：--hx8k、--lp8k、--up5k 只存在于 ice40；ecp5 用的是 --um5g-25k/45k/85k 或 --12k/25k/45k/85k 这类写法；gowin 又是 --device GW1N-... 的体系。报 unrecognised option 时，九成是 Makefile 里二进制名写成了 ecp5、命令行却还抄着 ice40 教程的参数。先跑一句确认身份：

bash
nextpnr-ice40 --version
nextpnr-ice40 --help | head -40

--help 打印的参数表就是本机这个版本的唯一权威清单，一切以它为准，不以外面任何教程为准。

第二步：芯片与封装必须配对。 --package 不是随便一个封装名都收——同一个 --hx8k，合法封装是 ct256、cb132、cm121 这一组；写成 --hx8k --package tq144（那是 lp1k/lp8k 的封装）就直接 Bad argument。封装名的字母还要逐字符对：ct256 写成 cb256 同样非法。拿不准时用器件数据库查，或者干脆跑一句让它自己告诉你：

bash
nextpnr-ice40 --hx8k --package bogus 2>&1 | head -5
# 报错信息里通常会列出该器件支持的封装清单

第三步：缺参数值会「吃掉」下一个选项。 --json 后面应该紧跟文件名，如果命令行写成 ... --json --pcf top.pcf ...，解析器会把 --pcf 当成 json 的参数值、或者报 Missing argument，之后整个解析全乱。检查口诀：凡是要带值的参数（--json、--pcf、--asc、--package、--freq、--seed、--top），后面必须紧跟一个不以 - 开头的单词；文件名本身以短横开头时（罕见但存在），写成 ./-weird.json 绕开。

第四步：别把 Yosys 的活塞给 nextpnr。 入门教程常见一个错误：把 yosys -p "synth_ice40 -top top -json top.json" 整段抄进 nextpnr 命令行，于是 nextpnr 对着 -p、synth_ice40 报一串 unrecognised。分工是铁律：yosys 负责从 Verilog 综合出 json 网表，nextpnr 只消费 json/pcf 产出 asc/bitstream。命令行里出现任何综合语义的关键字（synth、read_verilog、-p 脚本），说明边界搞错了，回 Makefile 把它们拆成两行。

第五步：版本改名与语义变化。 从两年前的博客抄命令是这条线的重灾区。典型例子：--freq 在不同版本里语义有变化——有的版本是「给唯一时钟设全局频率」，新版本要求配合约束或 json 里的时钟名绑定；旧版显式写 --placer heap 的用法在新版可能被调整或移除。判别方法很机械：报错参数在本版本 --help 里搜不到，就是改名/移除了；搜得到但行为不对，就是语义变了，去看对应版本的 changelog 或 README。版本整体对不上时，参考 nextpnr 版本不匹配速查 的口径处理。

第六步：等号写法与空格写法。 多数版本的 nextpnr 对 --seed=0 和 --seed 0 都接受，但个别参数或个别版本只认其中一种；团队混用两种写法还会让 Makefile 难以 grep。规约很简单：全项目统一空格写法，遇到 unrecognised 且参数名肉眼没错时，先把等号拆掉再试一次。

第七步：参数顺序。 nextpnr 对参数顺序基本不敏感，但有两个例外习惯要养成：器件与封装参数（--hx8k --package ct256）写在最前面，输入输出（--json --pcf --asc）跟在后面——这样报错时一眼能看出器件上下文；另外 shell 里用了通配符或变量展开的命令，先 echo 一遍最终拼出的命令行再执行，很多「参数报错」其实是变量没展开导致的空参数。

五、防复发 ​

  • 以本机 --help 为唯一权威：新环境装完 nextpnr 先把 --help 输出存一份进项目文档，团队对参数以它为准，不以博客为准。
  • Makefile 里家族变量集中定义：NEXTPNR := nextpnr-ice40、DEVICE := --hx8k --package ct256 写在文件头部，换板子只改两行，杜绝二进制与参数分两处改漏一处。
  • 芯片+封装组合写进 README：合法配对是项目的固定知识，写在显眼位置，新人不用去翻器件数据库。
  • CI 先跑干跑：CI 加一步 nextpnr-ice40 --hx8k --package ct256 --json /dev/null 级别的最小命令，参数错在提交时拦下，不进完整布局布线。
  • 升级版本先 diff --help：nextpnr 升级后，新旧两版 --help 输出 diff 一遍，被移除/改名的参数一次性替换掉，别等报错再逐个撞。
  • 命令行进版本库：把验证过的完整命令行（含全部参数）存成脚本或 Makefile 目标进 git，杜绝「上次能跑的那条命令」只活在某人的 shell 历史里。

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

本篇是 FPGA 排错速查簇的一员，处理「命令行本身写错了，nextpnr 在参数解析阶段就退出」这一类问题。命令行能过、但约束文件内容写错的（PCF/LPF 语法、引脚名对不上网表），见 nextpnr 约束文件解析报错速查；参数都合法、跑起来报资源放不下的，见 nextpnr 资源放不下速查。三篇共用同一条方法论：只认第一条报错、修一条重跑一条、以本机工具的 --help 为唯一权威。

一句话总结 ​

nextpnr 命令行参数报错先按报错文案分流：unrecognised option 九成是家族串台——ice40 的 --hx8k 喂给 ecp5 二进制必炸，各家族器件参数互不通用；Missing/Bad argument 先查 --json/--pcf 后漏文件名，再核 --package 封装与芯片型号是否合法配对（--hx8k --package ct256 这种组合）；老教程抄来的 --freq、--placer heap 要对版本改名保持警惕，Yosys 的综合参数永远不该出现在 nextpnr 命令行里；一切参数以本版本 --help 打印的清单为准，统一空格写法、修一条重跑一条。