nextpnr-ice40 命令行参数与器件族选择:UP5K 与 HX8K 双流程实测
更新时间:2026-11-22。Yosys synth_ice40 流程 已经介绍了 RTL 到比特流的完整链路,本篇把焦点收窄到布局布线命令本身:器件族和封装怎样共同确定芯片,PCF 在哪个时刻生效,
--asc、--report、--log分别留下什么。两条对照流程共用同一份 JSON,只更换目标器件及其约束,便于把差异归因到后端参数而不是 RTL。
本文要回答的问题
--up5k、--hx8k、--lp8k选择的是晶粒、封装还是电路速度等级?- 为什么
--package必须与 PCF 一起核对,换封装后哪些内容不能复用? --json、--pcf、--asc、--report、--log各负责哪一份输入或输出?--freq、--seed与--timing-allow-fail改变了什么,又不能证明什么?- 同一网表在 UP5K 与 HX8K 上各用多少资源,失败运行会不会留下 ASC?
这张图也是排错顺序。先确认目标和输入,再看布局布线,最后检查产物;在器件或封装选错时调整布局算法,解决不了引脚契约问题。
一、实验设计:只让 nextpnr-ice40 命令行参数中的物理目标变化
实验电路是一个带初值的 24 位自由运行计数器,最高位驱动一颗 LED。12 MHz 时钟下,counter[23] 每约 0.70 秒翻转一次,完整闪烁周期约 1.40 秒。逻辑虽简单,却包含 24 级寄存器、加法进位链、时钟全局网络与两个物理 IO,足够观察打包、资源统计和关键路径。
module top (
input wire clk,
output wire led
);
reg [23:0] counter = 24'd0;
always @(posedge clk) begin
counter <= counter + 24'd1;
end
assign led = counter[23];
endmodule综合只执行一次:read_verilog top.v 后运行 synth_ice40 -top top -json top.json。这个 354153 字节的 JSON 被两条后端命令原样读取,SHA-256 为 a47eed3f467aa15f75b6a3aae76d5a320fd386c98d3b2752a13c89e17e273e14。因此后文不会出现「UP5K 综合得更省」这种混淆变量:逻辑输入完全相同,差别从 nextpnr 的物理数据库开始。
| 对照项 | UP5K 流程 | HX8K 流程 |
|---|---|---|
| 器件与封装参数 | --up5k --package sg48 | --hx8k --package ct256 |
| 对应实验板 | iCEBreaker | Lattice iCE40-HX8K Breakout Board |
| 时钟约束 | set_io clk 35 | set_io clk J3 |
| LED 约束 | set_io led 37 | set_io led B5 |
| 时序目标与随机种子 | --freq 12 --seed 1 | --freq 12 --seed 1 |
| 输出 | up5k.asc 与 JSON report | hx8k.asc 与 JSON report |
UP5K 的绿色 LED 为低电平点亮,HX8K 板卡 LED0 为高电平点亮。这不影响布局布线输入,却会影响上板观察:同一个 led=1 在两块板上的亮灭状态相反。本文只验证实现流程和产物,没有进行烧录与板级电气测量。
二、器件族与封装:nextpnr-ice40 命令行参数先回答在哪颗芯片上实现
--up5k 和 --hx8k 选择器件架构数据库及容量。它们不是输出文件前缀,也不是简单的「速度模式」:UP5K 在本次日志中提供 5280 个 LC、30 个块 RAM、8 个 DSP 和 1 个 PLL;HX8K 提供 7680 个 LC、32 个块 RAM和 2 个 PLL,资源类别也更少。只有器件族与目标芯片一致,占用率分母、硬资源检查和布线延迟模型才有意义。
--package 再选定晶粒对外的封装。PCF 中的 35 与 J3 都不是跨封装通用的物理地址,只有在当前封装引脚表里才可解析。下面的关系图把三层概念分开:JSON 只有逻辑端口,器件族决定阵列,封装加 PCF 才决定端口落到哪里。
图中紫色是物理目标,橙色是约束输入,绿色才是实现结果。换板时不能只把 --up5k 改成 --hx8k 而保留旧 PCF;反过来,同一 UP5K 晶粒换成另一种封装,也要重新核对封装名和每个引脚。器件族选项互斥,应在命令中明确写一个,不依赖默认值。
--lp8k 同属 iCE40 器件族选择开关,面向低功耗 LP 系列的 8K 容量器件;它不能与 --hx8k 同时出现,也不继承 HX8K 的封装和 PCF。本文没有运行 LP8K 流程,因此不提供它的实测资源、时序或封装结论。实际选用时,应依据具体料号的数据手册和当前 nextpnr 器件数据库确定合法 --package,再用对应板卡引脚表重做 PCF,而不是把 HX8K-CT256 的约束直接换名复用。
三、JSON、PCF 与输出文件:五个常用参数各管一段
一条完整命令可以按「目标、输入、约束、输出、运行控制」分组阅读,不必死记参数顺序:
nextpnr-ice40 --up5k --package sg48 \
--json top.json --pcf up5k-sg48.pcf \
--asc build/up5k.asc --report build/up5k-report.json \
--freq 12 --seed 1| 参数 | 实际职责 | 使用时的边界 |
|---|---|---|
--json <文件> | 读取 Yosys 生成的结构化网表 | 不含引脚坐标和最终布线延迟,不能替代 PCF |
--pcf <文件> | 用 set_io 端口 引脚 固定顶层 IO | 端口按名称逐位匹配,引脚必须属于所选封装 |
--asc <文件> | 写出 ASCII 配置数据,交给 icepack | 成功产物,不是可读的资源报告 |
--report <文件> | 写 JSON 格式的利用率、Fmax 和关键路径 | 适合脚本提取,字段仍应与文本日志交叉核对 |
--log <文件> | 把工具消息独立写入日志,即使使用 quiet 模式也可保留 | 与 shell 的 tee 都能留日志,但它是工具自带参数 |
--freq <MHz> | 给自动识别时钟设置目标频率 | 不改变晶振,也不是板级时序签核 |
--seed <整数> | 固定布局随机种子,便于复现 | 不能消除版本、器件数据库或输入变化带来的差异 |
--write <文件> | 写出布局布线后的 JSON 网表 | 与输入 --json 方向相反,不是 ASC |
--sdf <文件> | 输出延迟反标文件,供后仿真使用 | 需要匹配的后仿真流程,不等于直接生成测试台 |
--placed-svg / --routed-svg | 分别输出布局或布线可视化 | 用于观察物理结果,不替代 timing report |
调试时还有 --pack-only、--no-place、--no-route,可把流程停在指定阶段,用来区分打包、布局和布线问题;它们不适合作为正常交付命令。--timing-allow-fail 允许时序未达标仍继续执行,只改变失败处理,不会改善关键路径。相反,--Werror 会把警告升级为错误,适合要求严格日志卫生的自动构建。
进阶参数也不应变成每条命令的固定装饰。当前版本默认布局器是 heap、布线器是 router1,显式写出它们可以记录算法选择,却不等于开启了额外优化。下表列出容易与基础参数混用的一组开关:
| 参数 | 何时值得用 | 不要怎样理解 |
|---|---|---|
--top <模块名> | JSON 内有多个候选顶层时明确选择 | 它不会修改 PCF,也不会重新综合 RTL |
--randomize-seed | 主动探索不同布局起点 | 与固定复现的目标相反,结果比较要记录当次种子 |
--placer heap / --placer sa | 对照布局算法或复现旧流程 | 不能仅凭单次运行时间宣布一种算法普遍更优 |
--router router1 / --router router2 | 对照布线结果与拥塞行为 | 换布线器不能修复非法器件或错误约束 |
--detailed-timing-report | JSON report 还需要逐网段详细时序 | 文件会更详细,但不会提高电路 Fmax |
--opt-timing | 明确评估当前版本的实验性布局后时序优化 | 帮助文本标明 experimental,不应无条件用于交付 |
--threads <数量> | 当前构建机和可并行 pass 已确认时使用 | 不是所有阶段都会按线程数线性加速 |
PCF 默认要求顶层 IO 全部受约束。若缺少条目,工具会报错;--pcf-allow-unconstrained 可让工具自动放置未约束 IO,但位置不受 PCB 约束控制。该分支的完整复现见 nextpnr 顶层端口未约束 PCF 报错,本篇不再把降级开关当作正常参数组合。
多位总线要逐位写约束,例如 set_io led[0] B5、set_io led[1] B4,方括号是端口位选的一部分。名称应与综合后顶层端口一致,而不是凭 RTL 里的内部信号名猜测;写 set_io counter 10 不会自动约束整个 24 位计数器,因为 counter 不是顶层 IO。维护 PCF 时可以把板卡原理图页码、接口方向和有效电平写进注释,但工具真正执行的仍是 set_io 映射。若同一块板更换连接器或跳线位置,也应把 PCF 当作需要评审的硬件接口文件,而不是构建脚本里的附属文本。
四、双器件族实跑:资源相同不代表物理结果相同
UP5K 成功命令的资源段如下。开头两条 constrained 证明 PCF 已把两个端口绑定到具体 BEL,后面的分母才对应 UP5K,而不是综合报告里的通用单元数。
24 个 LC 同时容纳 LUT4 与 DFF,进位链合法化再使用 1 个 LC,总计 27 个。这里日志百分比显示 0% 是整数取整,并不表示没有使用资源;精确判断应读 27/5280。HX8K 的打包数量相同,但可用 IO 与 PLL 数量不同:
| 结果项 | UP5K-SG48 | HX8K-CT256 |
|---|---|---|
ICESTORM_LC | 27 / 5280 | 27 / 7680 |
SB_IO | 2 / 96 | 2 / 256 |
SB_GB | 1 / 8 | 1 / 8 |
ICESTORM_RAM | 0 / 30 | 0 / 32 |
ICESTORM_PLL | 0 / 1 | 0 / 2 |
| 布线后时钟 Fmax | 79.76 MHz | 194.33 MHz |
| 对 12 MHz 目标 | PASS | PASS |
| ASC 字节数 | 709322 | 953456 |
表里的 SB_IO 分母来自器件架构资源统计,不等于 SG48 或 CT256 实际引出、也不等于实验板连接器提供给用户的 IO 数量。板级能用哪些脚仍要同时看封装和原理图,不能拿 96 或 256 直接规划外部接口。
两次布局前 Fmax 分别为 83.85 和 190.33 MHz,布线后才收敛到表中的 79.76 和 194.33 MHz,所以报告应取最后的 Program finished normally 之前结果,不能摘到第一条 Fmax 就收工。HX8K 本次数值更高,反映其延迟模型和这次物理实现,不能外推成所有设计都快约 2.44 倍。JSON report 的 fmax.*.achieved 保存了更高精度数值,utilization 保存 used/available 对,critical_paths 则逐段记录逻辑与布线延迟,适合自动检查而不必解析对齐文本。
两条关键路径也解释了为什么不能只抄一个 Fmax。UP5K 的寄存器到寄存器路径总计约 12.5 ns,其中文本日志归为 9.0 ns 逻辑与 3.5 ns 布线;HX8K 对应为约 5.1 ns、3.9 ns 逻辑与 1.2 ns 布线。关键路径沿 24 位加法的进位链前进,报告中的 loc 还给出每一步物理坐标。排查时若 Fmax 不达预期,应先确认是哪条时钟域、哪一段路径,再决定调整 RTL、约束或布局,而不是先换随机种子反复碰运气。
产物核验还检查了文件非空和失败分支无 ASC。两份 ASC 的 SHA-256 分别为 bd12b4182999ca9d0459af072fed8b10148746cdd3734cb1ddd73c131703ccfd 与 450cf7d4cdc913059a26ae66e4e11ef5f33d8dc6773684f1a535375b57a03793;它们内容不同是预期结果。ASC 体积差异也不能当逻辑面积差异,二者逻辑用量明明同为 27 LC,文件布局由器件配置结构决定。
五、失败与适用边界:非法引脚在实现开始前就应被拦住
失败对照仍使用 UP5K-SG48 和同一 JSON,只把 LED 从合法的 37 改为 SG48 不存在的 99。结果不是「自动生成一个较差布局」,而是在加载 PCF 时中止:
$ nextpnr-ice40 --up5k --package sg48 --json top.json --pcf up5k-sg48-bad-pin.pcf --asc build/bad-pin.asc --report build/bad-pin-report.json --freq 12 --seed 1
Info: constrained 'clk' to bel 'X12/Y31/io1'
ERROR: package does not have a pin named '99' (on line 3)
ERROR: Loading PCF failed.
0 warnings, 2 errors
bad-pin exit code: 255这段输出定位很直接:clk 已成功绑定,错误发生在 PCF 第 3 行,无需调整 RTL 或重新综合。脚本随后确认进程退出码为 255、bad-pin.asc 不存在。实践中应同时检查退出码与产物新鲜度,避免目录里上一轮遗留的 ASC 被误当成本轮成功结果。
选择参数时可以按任务收敛:做正式板卡构建,明确器件族、封装、完整 PCF 和目标频率;做算法对照,再固定 JSON、种子和工具版本;做分阶段诊断,才临时使用 --pack-only 或 --no-route。--freq 12 的 PASS 只说明当前模型下满足 12 MHz 预算,既不验证输入时钟真实频率,也不覆盖 IO 电平、供电、复位和外部走线。--seed 1 只服务可复现性,不代表这是最优于其他种子的结果。
六、把参数沉淀成可检查的构建输入
手工命令适合理解参数,项目里更适合让每块板拥有独立的目标描述。一个稳妥的组织方式是把器件族、封装、PCF 和频率放在同一组变量中,避免只改其中一项;输出目录再按板卡名分开,防止 UP5K 的 ASC 覆盖 HX8K 的结果。本文脚本把两次调用包进同一个函数,但 PCF 文件分别命名,正是为了让这组对应关系一眼可见。
交付前至少保留四类核对。第一,constrained 行覆盖全部顶层端口,数量和 PCF 条目一致;第二,Device utilisation 的 used 不超过 available,分母确实属于目标器件;第三,最后的 Fmax 满足显式 --freq,失败时没有被 --timing-allow-fail 隐藏;第四,ASC 与 report 是本轮新生成的非空文件。需要自动读取时,优先解析 report 的 fmax 和 utilization,同时保留文本日志用于定位具体 pass,二者不是互相替代的关系。
复现比较还要控制输入版本。同样的 --seed 1 只有在 JSON、工具版本、器件数据库、PCF、频率和算法参数都一致时才有明确意义;改变其中任何一项,都应把它当作一次新实现。若目的是评估不同器件,就像本文一样共用 JSON;若目的是评估 RTL 优化,则应固定器件和 PCF,只改变综合输入。把实验变量先说清,比收集更多无法对齐的 Fmax 数字更有价值。
最后,ASC 仍需交给 icepack 才能生成烧录用的二进制文件,本文停在后端产物是为了隔离 nextpnr 参数。实际烧录前还要确认板卡供电、Flash 连接和下载器目标,不能用「布局布线成功」替代这些板级检查。
实验环境
- 机器/系统:macOS 宿主机,Docker 镜像
geek-eda:0.4-flow,容器工具链为 linux/amd64。 - 工具版本:Yosys 0.33(git sha1 2584903a060)、nextpnr-ice40 0.6-3build5。
- 日期:2026-11-22。
- 完整命令:在实验目录执行
docker run --rm -v "$PWD":/work -w /work geek-eda:0.4-flow bash ./run.sh。脚本先执行yosys -s synth.ys,再分别运行第四节两条 nextpnr 命令,最后运行第五节的非法引脚对照,并核验 ASC、report、文件大小和 SHA-256。全部终端输出保存在run1.log,每次 nextpnr 另有独立日志。
代码获取
完整 RTL、综合脚本、两族 PCF、非法引脚对照、运行脚本、README 与 JSON 结果摘录位于公开仓:geek-doc.cn/experiments/flow-nextpnr-ice40-cli-options。取得相同镜像后,在该目录执行 make 即可复现;本机已装工具链时执行 make DOCKER_RUN="",make clean 删除可重建文件。
这一篇在知识体系里的位置
- 上游综合与 icepack 打包的完整链路见 Yosys synth_ice40 流程;本篇只展开其中的 nextpnr 后端。
- 固定器件、PCF 与频率,只改变布局种子的五轮对照见 nextpnr-iCE40 布局种子扫描。
- 如果目标换成 ECP5、关注点是综合 JSON 中的 Trellis 原语与回读验收,见 Yosys synth_ecp5 综合到 JSON 流程。
- PCF 漏端口、自动放置降级开关与补齐约束的三路对照见 nextpnr 顶层端口未约束 PCF 报错。
- 更多综合、实现与报错文章从 EDA 知识目录 进入。
总结
nextpnr-ice40 命令行参数要按物理目标、逻辑输入、引脚约束和结果产物四组理解:--up5k/--hx8k/--lp8k 选器件族,--package 选封装,--json 提供网表,--pcf 绑定端口,--asc 输出配置,--report 和 --log 分别服务程序与人工检查。同一计数器 JSON 在 UP5K-SG48 和 HX8K-CT256 上都占用 27 个 LC、2 个 IO 和 1 条全局网络,布线后 Fmax 为 79.76 与 194.33 MHz,均通过 12 MHz 目标;非法 SG48 引脚 99 则以 255 退出且不生成 ASC。LP8K 本文未实测,实际迁移必须重新核对封装和 PCF,不能只替换器件开关。