verilator lint:--lint-only 静态检查实操、告警分级与 waiver 豁免
本篇是 eda-lab 开源 EDA 工具实操系列里「仿真段」的一篇,主打 verilator lint 这条最便宜的 RTL 质量防线:不用写 testbench、不用跑仿真,一条 verilator --lint-only 就能把位宽不匹配、组合环、锁存器推断这类低级但致命的问题在几秒内全抖出来。商用流程里对应的概念(lint 基线、waiver 管理)在 RTL Lint 基线与 waiver 流程 和 Lint waiver 管理流程 里讲的是方法论,本篇用开源工具把整条链路亲手跑一遍,告警原文全部来自真实运行。
本文要回答的问题
verilator --lint-only到底能查出哪几类问题?告警原文长什么样、怎么读?- 默认告警集和
-Wall差多少?多出来的告警值不值得开? - Warning 和 Error 在 Verilator 里是什么关系?为什么满屏 Warning 最后却报
%Error? - 确认无害的告警怎么豁免?源码
lint_off注释和.vlt配置文件两种方式各适合什么场景? - 怎么把 verilator lint 接进 CI 当提交门禁?
环境
实验统一跑在 Docker 容器 geek-eda:0.1(ubuntu:24.04 基底)里,工具版本实测:
$ verilator --version
Verilator 5.020 2024-01-01 rev (Debian 5.020-1)复现命令(挂载实验目录,容器内跑 Makefile):
docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp \
-v ~/Project/geek-doc.cn/experiments:/work \
-w /work/eda-lab-verilator-lint geek-eda:0.1 make run代码获取:本实验完整 RTL(
lint_demo.v)、waiver 示例(lint_off/waivers.vlt)、Makefile 与真实输出日志见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-verilator-lint/。克隆后make run即可复现。
一、实验设计:一份故意埋了六类问题的 RTL
为了在一屏之内看到尽量多种告警,lint_demo.v 故意埋了六类最典型的 RTL 问题,每一类都对应真实项目里踩过的坑:
| 问题类别 | 告警规则名 | 埋雷代码 | 真实项目里的后果 |
|---|---|---|---|
| 常量截断 | WIDTHTRUNC | nibble <= 32'd7;(32 位赋 4 位) | 高位悄悄丢掉,数据错了还不报错 |
| 运算扩位 | WIDTHEXPAND | dout = a8 + din;(8+8 位赋 16 位) | 隐式零扩展掩盖进位丢失 |
| 组合环 | UNOPTFLAT | loop_x 依赖 loop_y、loop_y 又依赖 loop_x | 仿真震荡不收敛,综合直接报错 |
| 锁存器推断 | LATCH | if (din[2]) q_latch = din[3]; 无 else | 组合逻辑里混进电平敏感存储,时序噩梦 |
| 未用/未驱动信号 | UNUSEDSIGNAL | 声明了 never_used、never_driven 没人接 | 设计没连完的残肢,常是漏连端口的前兆 |
| case 分支不全 | CASEINCOMPLETE | 4 选 1 漏了 2'b11 且无 default | 综合出锁存器,仿真与综合行为不一致 |
这里有一个实验设计上的细节值得说:组合环如果不被使用,根本触发不了 UNOPTFLAT。第一版实验里 loop_x/loop_y 没有扇出,Verilator 在优化阶段直接把整个环当死代码删了,告警零输出——这本身就是一条有用的认知:lint 是在优化后的网表上做的,死代码里的问题可能永远看不到。所以正式版把环通过 loop_out 端口引了出来。
另外,顶层端口的「未使用」不会被报——unused_port 全程静默。原因也合理:端口是模块对外的接口契约,用不用是上层的事,lint 只管模块内部的信号。
二、真实运行:-Wall 下的告警原文逐条解读
跑 verilator --lint-only -Wall lint_demo.v,完整输出 11 条告警(out/lint.log),按类别摘录关键行:
%Warning-WIDTHTRUNC: lint_demo.v:30:20: Operator ASSIGNDLY expects 4 bits on the
Assign RHS, but Assign RHS's CONST '32'h7' generates 32 bits.
30 | nibble <= 32'd7;
| ^~
%Warning-WIDTHEXPAND: lint_demo.v:35:19: Operator ADD expects 16 bits on the LHS,
but LHS's VARREF 'a8' generates 8 bits.
35 | dout = a8 + din;
| ^
%Warning-UNUSEDSIGNAL: lint_demo.v:54:16: Signal is not driven, nor used: 'never_used'
54 | wire [3:0] never_used;
| ^~~~~~~~~~
%Warning-CASEINCOMPLETE: lint_demo.v:60:9: Case values incompletely covered (example pattern 0x3)
60 | case (sel)
| ^~~~
%Warning-LATCH: lint_demo.v:47:5: Latch inferred for signal 'lint_demo.q_latch'
(not all control paths of combinational always assign a value)
: ... Suggest use of always_latch for intentional latches
47 | always @(*) begin
| ^~~~~~
%Warning-UNOPTFLAT: lint_demo.v:39:10: Signal unoptimizable: Circular combinational
logic: 'lint_demo.loop_x'
lint_demo.v:39:10: Example path: lint_demo.loop_x
lint_demo.v:40:10: Example path: lint_demo.loop_y
lint_demo.v:39:10: Example path: lint_demo.loop_x
%Error: Exiting due to 11 warning(s)读告警有固定的套路,每条都按四段拆解:
- 规则名(
%Warning-WIDTHTRUNC):waiver 和-Wno-XXX都按这个名字操作,是最重要的字段。 - 位置(
lint_demo.v:30:20):文件:行:列,编辑器里直接跳。 - 诊断正文:说明「期望多少位、实际给了多少位」。WIDTHTRUNC 那句
expects 4 bits ... generates 32 bits就是截断的铁证。 - 源码快照 +
^~指针:箭头精确指到出问题的表达式,不用自己数列号。
UNOPTFLAT 是其中最特别的一条:它不光报名字,还把环的传播路径(loop_x → loop_y → loop_x)一段段打印出来,照着路径就能把环拆开。LATCH 那条还给了一句建议——故意的锁存器请用 always_latch 显式声明,这样 lint 就不再报、读代码的人也知道你是故意的。
整个检查到出报告的流程可以这样概括:
看图里最上面那条旁路:优化发生在规则检查之前。这就是为什么第一版实验的组合环没报出来——它先被当死代码删了。所以「lint 没报」不等于「没问题」,只等于「活代码里没查到问题」。
三、告警分级:默认告警集 vs -Wall 实测
Verilator 的告警不是一锅端,每条规则有自己的默认开关。同一份 RTL 跑两遍,实测差异如下:
| 运行方式 | 告警总数 | 各类别条数 | 日志 |
|---|---|---|---|
--lint-only(默认) | 6 | WIDTHTRUNC×1、WIDTHEXPAND×2、UNOPTFLAT×1、LATCH×1、CASEINCOMPLETE×1 | out/default.log |
--lint-only -Wall | 11 | 上面 6 条 + UNUSEDSIGNAL×5 | out/lint.log |
结论很清楚:-Wall 多出来的 5 条全是 UNUSEDSIGNAL。换句话说,影响功能正确性的硬伤类规则(位宽、组合环、锁存器、case 覆盖)默认就是开的;-Wall 主要补的是「清洁度」类规则——未用信号、文件名与模块名不一致、文件末尾没换行这类。
值不值得开?看 UNUSEDSIGNAL 报出来的内容就知道值:5 条里有 2 条是 nibble 和 mux_out 这种「算了半天没人消费」的信号——这在真实项目里往往意味着输出端口漏连了,是比风格问题严重得多的设计缺陷前兆。-Wall 的代价是多处理一些噪音,收益是抓住漏连,工程上强烈建议常开。
再说 Warning 与 Error 的关系,这块最容易让新手困惑:日志最后一行是 %Error: Exiting due to 11 warning(s),退出码 1。明明没有一条 %Error-XXX 规则命中,为什么报 Error?这是 Verilator 的设计哲学——lint 模式下 Warning 即失败。它认为告警不处理干净就不该放行,所以只要告警数大于零就以 Error 收场。这个行为恰恰是接 CI 门禁最想要的:make 里一条 verilator --lint-only -Wall rtl/*.v,非零退出直接卡住流水线,不需要再写脚本解析告警文本。如果想让某类告警只提示不阻塞,就得显式 -Wno-XXX 或 waiver 掉——这正是下一节的内容。
四、waiver 实操:lint_off 注释与 .vlt 配置文件
告警不可能全修:有些是第三方 IP 改不了,有些是经过评审确认无害的「有意为之」。这时要豁免(waiver),Verilator 给两条路。
方式一:源码内 lint_off/lint_on 注释。在 lint_demo_waived.v 里,对评审确认无害的两处直接贴注释:
/* verilator lint_off WIDTHTRUNC */
nibble <= 32'd7; // 已评审:截断是有意为之
/* verilator lint_on WIDTHTRUNC */
/* verilator lint_off UNOPTFLAT */
wire loop_x;
wire loop_y;
assign loop_x = loop_y & din[0];
assign loop_y = loop_x | din[1];
/* verilator lint_on UNOPTFLAT */同时把 WIDTHEXPAND 那处真的修掉(dout = {8'd0, a8 + din}; 显式补高位),演示「能修就修、不能修才豁免」的纪律。实测对比:
| 运行 | 告警数 | 变化 |
|---|---|---|
lint_demo.v(原版) | 11 | 基线 |
lint_demo_waived.v(注释 waiver + 修一处) | 7 | WIDTHTRUNC、WIDTHEXPAND×2、UNOPTFLAT 消失 |
方式二:.vlt 配置文件。不想改 RTL(比如代码是第三方交付的)时,写一个 lint_off/waivers.vlt:
`verilator_config
lint_off -rule CASEINCOMPLETE -file "*lint_demo.v"
lint_off -rule UNUSED -file "*lint_demo.v"
lint_off -rule UNDRIVEN -file "*lint_demo.v"然后把它当输入文件一起传给命令行:verilator --lint-only -Wall lint_off/waivers.vlt lint_demo.v。实测告警从 11 条降到 4 条——CASEINCOMPLETE 和全部 5 条 UNUSEDSIGNAL 消失,剩下的 WIDTH、LATCH、UNOPTFLAT 原样保留(out/vlt.log)。
两种方式怎么选,一张表说清:
| 维度 | lint_off 注释 | .vlt 配置文件 |
|---|---|---|
| 粒度 | 精确到代码行区间 | 按规则 × 文件通配 |
| 可移植性 | 跟着代码走,换工具链注释是死文本 | 独立文件,但要记得随代码分发 |
| 适用场景 | 自己维护的 RTL、零星豁免 | 第三方 IP 不能改源码、批量豁免 |
| 评审可见性 | 评审 diff 时直接可见 | 需要单独评审 .vlt 文件 |
| 风险 | 注释范围写太大容易误豁免 | 通配符写宽了一豁免一大片 |
商用签核流程里对 waiver 有严格的基线管理(新增告警必须评审、waiver 条目要有 owner 和理由),方法论见 Lint waiver 管理流程;开源工具这边虽然没有流程系统兜底,但把 .vlt 文件纳入 git 评审、强制写注释说明理由,能达到同样的纪律效果。
五、常见报错排查
1. 明明有组合环却没报 UNOPTFLAT。 本实验第一版就踩了这个坑:环没有扇出,被优化阶段当死代码删了。处置:确认被怀疑的逻辑最终能到达某个输出端口或寄存器;也可以加 --no-dead-cells 类选项保留死代码再查,但更好的办法是先想清楚这段代码为什么没连出去。
2. 想关掉某条告警,-Wno-XXX 名字写错不生效也不报错。 规则名必须以告警原文里的为准(如 WIDTHTRUNC 不是 WIDTH-TRUNC),5.020 把老的 WIDTH 拆成了 WIDTHTRUNC/WIDTHEXPAND 两条,抄旧博客的命令行会漏。处置:直接从告警第一行抄规则名,或查 https://verilator.org/warn/<规则名>(告警文本里自带链接)。
3. waiver 写了但告警还在。 两种常见原因:.vlt 文件没传到命令行(它是要当输入文件给的,不是自动搜索的);-file 通配没匹配上(注意是 glob 模式,路径前缀要算进去)。处置:先跑一遍不带 -file 限定的 lint_off -rule XXX 全局豁免验证规则名对不对,再逐步收紧。
4. CI 里 lint 过了但本地报错(或反过来)。 版本差异:告警规则集随版本演进,本实验的 11 条是基于 5.020 的实测,换版本条数和分类都可能变。处置:像本实验一样用固定镜像(geek-eda:0.1)锁版本,日志落盘可追溯。
这一篇在知识体系里的位置
本篇是 eda-lab「仿真段」的质量入口:lint 过了,才轮到跑仿真(iverilog / Verilator --binary)和写 testbench(cocotb)。对应的知识文在 RTL Lint 基线与 waiver 流程、Lint waiver 管理流程、SpyGlass RTL Lint(商用工具对照),以及 Verilator lint 与仿真;waiver 签核视角还可看 Lint waiver signoff。
总结
verilator lint 是 RTL 质量最便宜的第一道防线:一条 verilator --lint-only -Wall 几秒钟抓出位宽、组合环、锁存器、漏连六类硬伤,有告警即非零退出天然适配 CI 门禁;确认无害的告警用 lint_off 注释(贴代码、评审可见)或 .vlt 配置文件(不改第三方源码、集中管理)豁免,但记住 lint 查的是优化后的活代码——死代码里的问题它看不到,「没报」从不等于「没错」。