yosys 常见报错:未声明线网、多驱动、SystemVerilog 语法与组合环排查
用 Yosys 做开源综合,新手期最劝退的不是流程长,而是报错看着「似是而非」:有的写着 Warning 却藏着真 bug,有的 ERROR 指到的行根本不是病根,还有的明明确实是硬件错误,工具却安安静静跑完了。这篇 FAQ 速查档把 yosys 常见报错 里最高频的四类各用一个最小用例真实触发,报错原文全部来自容器实测,逐条讲清根因与处置。仿真侧的同类对照见 iverilog 常见报错,两篇一起看能建立「前端工具怎么报错」的完整直觉。
本文要回答的问题
default_nettype none下用未声明线网,yosys 到底报错还是放行?multiple conflicting drivers是告警还是错误?综合会继续吗?- 报
syntax error, unexpected TOK_ID但代码明明没错,是不是忘加-sv? - 组合逻辑环会让 yosys 挂死吗?
found logic loop出现在哪个阶段? - 这四类问题各自的「一票否决」防复发手段是什么?
环境与复现方式
- 容器:
geek-eda:0.1(ubuntu:24.04),Yosys 0.33 (git sha1 2584903a060)(yosys -V实测) - 实验代码:每类错误一个最小
err_*.v用例 + 一个全修复对照ok_fixed.v,Makefile 依次触发并把报错原文落out/*.log
代码获取:本实验完整可编译代码(
err_*.v/ok_fixed.v)、Makefile 与真实报错日志见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-yosys-common-errors/。克隆后make run即可复现。
复现命令:
docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp \
-v ~/Project/geek-doc.cn/experiments:/work \
-w /work/eda-lab-yosys-common-errors geek-eda:0.1 bash -c 'make run'先说一个贯穿全篇的关键事实:本次实测四类问题里,只有「SystemVerilog 语法不加 -sv」一类是 ERROR(exit=1)直接中断,其余三类全是 Warning、退出码 0 照常出网表。所以用 yosys 做 CI 时只看退出码是远远不够的,必须 grep 日志里的 Warning / Found and reported N problems 计数,这一点最后一节再展开。
一、未声明线网:default_nettype none 下 yosys 只给 Warning
现象:err_undeclared.v 文件头写了 `default_nettype none,随后 assign led = tick & en; 里的 tick 和 en 从没声明。跑 read_verilog,容器真实输出:
err_undeclared.v:10: Warning: Identifier `\tick' is implicitly declared.
err_undeclared.v:10: Warning: Identifier `\en' is implicitly declared.
Successfully finished Verilog frontend.
exit=0原因:按 IEEE 1364 标准,`default_nettype none 之后所有线网必须显式声明,未声明即编译错误。但 yosys 0.33 的 Verilog 前端对这条指令的处理是「降级为 Warning」——它照标准识别出了隐式声明,却只是警告一声、自动补一根 1 位线网继续往下走,exit=0。这与 iverilog 的行为不同(iverilog 在 default_nettype none 下会直接 error),换工具时行为预期要跟着换。隐患很实际:信号名拼错一个字母,综合照样通过,拼错出来的「新线网」挂着默认值进网表,功能 bug 留到后仿甚至上板才爆。
排查命令:
yosys -p "read_verilog err_undeclared.v" 2>&1 | grep -i "implicitly declared"
grep -n 'tick' err_undeclared.v # 确认是漏声明还是拼错解决:补上 wire tick; wire en; 显式声明。ok_fixed.v 对照版在同样的 default_nettype none 下全程无 Warning。
防复发:文件头永远写 `default_nettype none、文件尾恢复 `default_nettype wire(不污染后续文件);更关键的是在 CI 里把 implicitly declared 列为致命关键词,grep 到就判失败——不能指望 yosys 的退出码替你拦。
二、多驱动同一信号:check 阶段报 Warning,网表照样生成
现象:err_multidriver.v 里输出 cnt 被两个 always 块驱动(一个 clk_a 域、一个 clk_b 域)。跑 read_verilog; hierarchy; proc; check,真实输出(check 阶段):
Warning: multiple conflicting drivers for dual_drive.\cnt:
port Q[0] of cell $procdff$6 ($adff)
port Q[0] of cell $procdff$5 ($dff)
Found and reported 1 problems.
exit=0原因:proc 阶段把每个 always 块各自翻译成一个触发器单元——日志里能看到它老老实实给 cnt 造了两个寄存器:$procdff$5($dff)和 $procdff$6($adff)。于是信号 cnt 同时挂在两个触发器的 Q 端口上,这就是「多驱动」:真实硬件里两根输出短接,电平冲突、结果未定义。check 是 yosys 的「明显问题体检」步骤,专门抓这类结构性错误,但它只报告不拦截——Found and reported 1 problems 之后 exit=0,带着冲突的网表照样能写出。注意报错里的 cell 名 $procdff$6 是综合器内部命名,往回定位要靠它前面的 proc 日志(Creating register ... using process ...err_multidriver.v:10 这类行里有源码行号)。
排查命令:
yosys -p "read_verilog err_multidriver.v; hierarchy -top dual_drive; proc; check"
# 源码侧:全工程搜这个信号的所有赋值点
grep -n 'cnt' err_multidriver.v解决:一个信号只允许一个 always 块(或一条 assign)驱动。跨时钟域的需求要用同步器/握手电路显式实现,不能让两个进程抢同一个寄存器。
防复发:养成「proc 之后必跑 check」的肌肉记忆——synth 脚本内部末尾自带 check,但手工分步跑流程时容易漏;CI 里 grep Found and reported [1-9] 判失败。另外写代码时给每个寄存器心里默念「它归哪个 always 块管」,多驱动 90% 是复制粘贴 always 块忘了改信号名。
三、SystemVerilog 语法直接 read_verilog:真正的 ERROR
现象:err_sv_syntax.v 用了 logic 类型和 always_ff,直接 read_verilog 读入,真实输出:
err_sv_syntax.v:4: ERROR: syntax error, unexpected TOK_ID, expecting ',' or '=' or ')'
exit=1原因:read_verilog 默认按 Verilog-2005 解析(日志第一行就写着 Executing Verilog-2005 frontend),logic 在 Verilog-2005 里不是类型关键字,于是第 4 行 input logic clk 里的 logic 被当成端口名、后面的 clk 就成了「意外的标识符(unexpected TOK_ID)」。这是四类里唯一一个 ERROR 级、exit=1 中断流程的问题——好消息是它拦得干脆,坏消息是报错行号和措辞完全不提 SystemVerilog,新手容易以为是自己括号写错了。判别口诀:代码里出现 logic / always_ff / always_comb / typedef enum,而 yosys 报莫名其妙的 syntax error,九成是忘加 -sv。
排查命令:
yosys -p "read_verilog err_sv_syntax.v" # 复现:unexpected TOK_ID
yosys -p "read_verilog -sv err_sv_syntax.v; hierarchy -top sv_counter; stat"解决:加 -sv 开关重读。实测修复后输出 Parsing SystemVerilog input from 'err_sv_syntax.v'(注意日志措辞从 Verilog 变成 SystemVerilog),stat 正常出报表(本例 2 个 cell:$add + $logic_not),exit=0。工程里多个文件语言代别不同时,逐文件控制:read_verilog -sv a.sv; read_verilog b.v。
防复发:构建脚本里按文件扩展名分流——.sv 一律 read_verilog -sv,.v 保持默认;把这条规则写进 Makefile/Yosys script 模板,不靠人脑记。需要完整 SystemVerilog 支持(interface、package 等 yosys 原生前端吃不下的特性)时,改用 surelog/slang 前端或 Verilator 转译,那是另一条路。
四、组合逻辑环:synth 全程跑完,check 报 found logic loop
现象:err_combloop.v 里 assign a = sel ? d : b; assign b = a;——sel=0 时 a 依赖 b、b 又等于 a,构成没有寄存器打断的组合环。跑完整 synth -top comb_loop; check,真实行为是:不挂死、不报错中断,60 秒超时防护根本没派上用场,synth 全部 25 个子步骤正常走完,最后 check 报:
Warning: found logic loop in module comb_loop:
cell $abc$80$auto$blifparse.cc:386:parse_blif$82 ($_MUX_)
wire \y
Found and reported 1 problems.
exit=0原因:组合环在电路里是不稳定振荡环(输出依赖自身,无存储元件锁定状态),属于真实的硬件错误。但 yosys 的定位是「按规则翻译网表」,环本身不妨碍它生成网表——abc 映射照常执行,stat 显示网表还剩 1 个 $_MUX_ 单元,环被折叠进 mux 的反馈里。只有 check 步骤会做拓扑分析把环找出来,而且依然只是 Warning,exit=0。报错里那串 $abc$80$auto$blifparse.cc:386:parse_blif$82 是 ABC 内部展开后的 cell 名,对定位帮助有限,更有用的是它点名的 wire \y——从这根线往回追它的驱动链。
排查命令:
yosys -p "read_verilog err_combloop.v; synth -top comb_loop; check" | grep -A3 "logic loop"
# 想看在哪一步被发现:synth 内部的 check 在 3.26,脚本末尾我又跑了一次 check(第 4 步),两处都报解决:环必须用寄存器打断。ok_fixed.v 的做法是把反馈路径改成 always @(posedge clk) 寄一拍:b_q <= d; assign y = b_q;,对照版 check 输出 Found and reported 0 problems。如果环是「本意是锁存器」写出来的,要么显式实例化锁存单元,要么干脆改成触发器。
防复发:组合环的根因几乎都是「assign 互相引用」或「always @(*) 里信号读写成环」,代码评审时盯住所有 assign 的依赖方向;工程上把 check 输出里的 logic loop 设为 CI 致命关键词。仿真侧对环更敏感(事件调度死循环),综合侧反而「安静地错」,所以这个问题尤其不能靠「工具没报错」来判断没事。
五、汇总表与 CI 拦截清单
四类问题的实测行为一览(Yosys 0.33,geek-eda:0.1 容器):
| 报错特征(日志原文关键词) | 根因 | 级别/退出码 | 出现阶段 | 处置 |
|---|---|---|---|---|
implicitly declared | 未声明线网(default_nettype none 下也只警告) | Warning,exit=0 | read_verilog | 显式声明信号;CI grep 该关键词判失败 |
multiple conflicting drivers | 同一信号多个 always/assign 驱动 | Warning,exit=0 | proc 之后的 check | 一信号一驱动;跨域改同步器 |
syntax error, unexpected TOK_ID | SV 语法未加 -sv | ERROR,exit=1 | read_verilog | read_verilog -sv;按扩展名分流 |
found logic loop | 组合逻辑环 | Warning,exit=0 | synth/check | 寄存器打断环;评审盯 assign 依赖 |
配套的最小 CI 拦截片段(思路比形式重要):
yosys -p "read_verilog -sv top.sv; synth -top top; check" 2>&1 | tee yosys.log
grep -E "implicitly declared|conflicting drivers|logic loop|reported [1-9]" yosys.log \
&& { echo "yosys 检出结构性问题,判失败"; exit 1; }核心逻辑一句话:yosys 的退出码只覆盖「前端解析失败」这一类,结构性硬件错误全靠你主动 grep Warning。
这一篇在知识体系里的位置
本文是 EDA 开源工具实操池综合段(eda-lab/synth/)的排错入门,与仿真侧 iverilog 常见报错 互为镜像——对照看会发现两个工具对同类问题的级别判定差异很大(iverilog 对未声明信号直接 error,yosys 只 warning)。仿真正确性入门见 iverilog 仿真入门,更严格的静态检查习惯可以延伸到 verilator lint(Verilator 的 lint 比 yosys check 严格得多,很多问题能提前到综合前拦下)。综合段同池三篇——yosys show 网表图、yosys stat 报表解读、yosys synth 流程拆解——讲正常流程怎么走,本篇专治走不通的时候。
总结
yosys 常见报错的要害不在「看懂英文报错」,而在认清 Yosys 0.33 的级别体系:未声明线网、多驱动、组合环全是 exit=0 的 Warning(只有语法解析失败才是 ERROR),所以处置分两层——代码层各自修复(显式声明、一信号一驱动、-sv 开关、寄存器打断环),工程层把 Warning 关键词接进 CI 拦截,别让「综合跑完了」冒充「设计没问题」。