Verilog lint 高频告警矩阵实测：9 类造错案例逐一触发 verilator --lint-only
更新时间：2026-10-25。本文是「集成电路大类 · 芯片设计」入门层（beginner）的一篇实验文。verilator lint：--lint-only 静态检查实操、告警分级与 waiver 豁免 已经讲过 lint 的整条工作流——告警分级、
-Wall与默认告警集的差异、waiver 怎么写；那一篇回答「lint 流程怎么走」。本篇换一个角度：把新手最高频踩的九类告警各造一个最小案例，逐个触发、逐条解剖，让你在真实项目里第一次见到%Warning-WIDTH时就能认出它、知道怎么修。所有告警原文均来自真实运行日志，一行不缺。
本文要回答的问题
verilator --lint-only -Wall触发的告警原文长什么样，怎么读「文件:行:列 + 代码片段」的指向格式？- WIDTH、CASEINCOMPLETE、UNOPTFLAT、BLKSEQ、UNUSED、UNDRIVEN、LATCH、MULTIDRIVEN、IMPLICIT 九类告警各自在抓什么错误？
- 为什么满屏
%Warning最后却以%Error: Exiting收尾、退出码是 1？ - 每类告警的标准修法是什么？哪些是真 bug、哪些只是代码卫生问题？
先给本次实验的结论卡，四个数字全部可在后文原始日志里核对：
读这张卡抓两点：一是九类告警全部按预期触发，没有一类「造错了却没被发现」——说明 -Wall 的覆盖面对这些高频坑是够用的；二是每个案例的退出码都是 1，即 lint 在 CI 里天然可以当门禁用，不需要额外解析输出文本。
一、实验设计：九个最小造错文件
比较 lint 告警最忌「拿真实大工程跑出来一锅端」——几百条告警混在一起，看不清哪条对应哪种错误。本篇的做法是每类告警一个独立的最小 Verilog 文件（4-6 行），文件头注释写明要触发什么，然后循环执行：
for f in width caseincomplete unoptflat blkseq unused undriven latch multidriven implicit; do
verilator --lint-only -Wall $f.v | tee lint_$f.log
done每个案例的判定标准是「输出里至少出现一条 %Warning 或 %Error」，触发成功打 COLLECTED: <案例名>。九个案例全部 COLLECTED 后输出 RESULT: COLLECTED。
还有一个贯穿所有案例的背景噪音要先交代：九个文件每一个都额外触发了一条 %Warning-DECLFILENAME（文件名与模块名不一致，比如 width.v 里模块叫 width_case）。这是 -Wall 才开启的风格类检查，默认告警集里没有。它本身无害，但给了我们一个观察 Verilator 告警格式的绝佳样本——每条告警都是「%Warning-类型: 文件:行:列: 一句话描述 + 带行号的源码片段 + ^ 精确指向出错 token + 豁免提示」四段式。读 Lint 输出先认这个格式，后面遇到任何陌生告警都能照套。同时它也解释了为什么每个案例的告警条数比「造的那一类错」多——-Wall 是把风格检查也一起打开的，实际项目里要么遵守「文件名=模块名」的约定，要么在 waiver 文件里统一豁免这一类。
九类告警按危害程度可以分成三档，这个分档决定了你修它们的优先级：
读这张图抓住配色语义：红色档是会悄悄改变电路行为的硬伤（截断、隐式线网、组合环），橙色档是仿真与综合可能不一致的写法问题，灰色档是不影响正确性但污染代码的冗余。下面九节按这个分档展开，每节给「造错源码 → 告警原文 → 原因 → 修法」四件套。
二、功能级告警：会悄悄改行为的三种
WIDTH：位宽不匹配的静默截断
造错源码（8 位输入直接赋给 4 位输出）：
module width_case (input wire [7:0] a, output wire [3:0] y);
assign y = a; // 高 4 位被静默丢弃
endmodule真实告警原文（日志第 12-19 行）：
%Warning-WIDTH: width.v:3:14: Operator ASSIGNW expects 4 bits on the Assign RHS,
but Assign RHS's VARREF 'a' generates 8 bits.
%Warning-UNUSED: width.v:2:37: Bits of signal are not used: 'a'[7:4]原因：Verilog 允许不同位宽直接赋值，超出部分静默截断——语言层面合法，但 99% 是设计失误。注意这个文件连发了三条告警：除了 WIDTH，还有 UNUSED 指出 a[7:4] 没人用，外加一条 DECLFILENAME（文件名 width 与模块名 width_case 不一致，属风格类）。修法：显式写出截断意图 assign y = a[3:0];，既消除 WIDTH 也消除 UNUSED；如果本来就该是 8 位输出，改输出位宽。
IMPLICIT：拼写错误变成隐式线网
造错源码把端口 b 误敲成 bb：
module implicit_case (input wire a, input wire b, output wire y);
assign y = a & bb; // 'bb' 没有声明
endmoduleVerilator 这里直接给了 Error 而不是 Warning：
%Error: implicit.v:3:20: Can't find definition of variable: 'bb'
: ... Suggested alternative: 'b'原因：Verilog 默认允许「隐式线网声明」——引用一个没声明过的标识符时，编译器默默创建一根 1 位 wire。拼写错误因此不会报错，而是变成一根永远悬空的线网，仿真里表现是 x 或 z 一路传播，极难定位。Verilator 的提示相当贴心，直接给出了最接近的合法标识符 b。修法：治标是改回正确拼写；治本是源文件顶部加 `default_nettype none，强制所有线网显式声明，把这类拼写错误从「行为异常」变成「编译期报错」。
UNOPTFLAT：组合逻辑成环
造错源码让 x 和 z 互相定义：
wire x, z;
assign x = z | a;
assign z = x; // 环：x 依赖 z，z 依赖 x告警原文里 Verilator 把整条环路都画了出来（日志第 57-64 行）：
%Warning-UNOPTFLAT: unoptflat.v:3:13: Signal unoptimizable:
Feedback to clock or circular logic: 'unopt_case.z'
Example path: unopt_case.z -> ASSIGNW -> unopt_case.x -> ASSIGNW -> unopt_case.z原因：组合逻辑不允许成环——没有寄存器打断的环路，行为依赖仿真器的求值顺序，综合工具也无法收敛。Verilator 遇到环会把环路在某个点断开、按固定顺序求值，功能恰好「看起来对」的情况纯属运气。修法：找到环里本应打拍的位置插入寄存器，把组合环改成时序链路。这条告警在真实项目里往往出现在大型组合逻辑网中（比如仲裁器与流控逻辑互相引用），Example path 就是定位环路的路线图。
三、时序写法告警：仿真与综合可能打架
BLKSEQ：时序块里用阻塞赋值
always @(posedge clk) begin
q = d; // 时钟块里用了 =，应为 <=
end告警原文：%Warning-BLKSEQ: blkseq.v:4:11: Blocking assignments (=) in sequential (flop or latch) block ... Suggest delayed assignments (<=)。
原因：单个寄存器用 = 还是 <= 常常结果相同，但多个寄存器串联时，阻塞赋值按代码顺序立即生效，会产生与综合结果不同的「伪流水线」行为——仿真过了、上板不对。修法：时钟块里一律 <=，组合块里一律 =，这是最经典的 Verilog 编码纪律。
LATCH：组合块漏写分支推断出锁存器
always @(*) begin
if (en) q = d; // en 为 0 时 q 保持，推断出 latch
end原因：组合逻辑里 if 没有 else（或 case 没写全），综合工具只能推断一个电平敏感的锁存器来「保持旧值」。 latch 在多数工艺库时序分析困难、还容易被工具链当成意外产物。修法：给 q 在块首赋默认值 q = 1'b0; 再写条件覆盖，或补全 else。顺带一提，本案例的告警输出里 LATCH 本体被 DECLFILENAME 带出的非零退出覆盖了核心信息——-Wall 下风格告警也会把退出码顶成 1，所以 CI 里要么修风格要么豁免。
MULTIDRIVEN：同一寄存器被两个 always 块驱动
always @(posedge clk) q <= a;
always @(posedge clk) q <= b; // q 有两个驱动源原因：一个寄存器物理上只有一个 D 输入端，两个 always 块都写它，综合工具无法映射，仿真器则按某种顺序让后写的覆盖先写的——又是「仿真能跑、综合出错」的典型。修法：合并到一个 always 块里用条件选择，明确优先级。
四、代码卫生告警：不影响功能的冗余与遗漏
剩下三类告警不直接改行为，但每一条都在提示「这里可能写漏了什么」：
| 告警 | 触发代码 | 原文关键句 | 修法 |
|---|---|---|---|
| CASEINCOMPLETE | case 只写 2'b00/2'b01 两个分支 | Case values incompletely covered (example pattern 0x2) | 补 default: 分支，或确认其余取值不可能出现 |
| UNUSED | 8 位寄存器只用了 bit 0 | Bits of signal are not used: 'r'[7:1] | 缩小位宽，或确认是占位逻辑后 waiver |
| UNDRIVEN | wire 被消费但无人驱动 | Signal is not driven: 'ghost' | 接上驱动源；纯占位则删掉 |
CASEINCOMPLETE 值得单独说一句：它和 LATCH 是同一枚硬币的两面——case 没写全在组合块里就会推断 latch，Verilator 两条告警都可能报。UNUSED 在真实项目里出现频率最高（参数化设计里总有几位用不上），通常是 waiver 豁免的第一大户，豁免写法见 verilator lint 实操篇。UNDRIVEN 则经常和 IMPLICIT 结伴出现：拼写错误生成的隐式线网没人驱动，于是同一个笔误同时制造两条告警——遇到 UNDRIVEN 先检查是不是标识符敲错了，这是性价比最高的排查顺序。
采集过程的原始输出很长（195 行），这里摘录 LATCH 案例的完整采集段——注意 lint 的退出码预期为 1，脚本显式把这个「非零」当成正常结果处理：
+ echo '================ lint case: latch.v ================'
================ lint case: latch.v ================
+ verilator --lint-only -Wall /tmp/evidence-src/exp-verilator-lint-error-matrix/latch.v
+ tee lint_latch.log
%Warning-DECLFILENAME: /tmp/evidence-src/exp-verilator-lint-error-matrix/latch.v:2:8: Filename 'latch' does not match MODULE name: 'latch_case'
2 | module latch_case (input wire en, input wire d, output reg q);
| ^~~~~~~~~~
... Use "/* verilator lint_off DECLFILENAME */" and lint_on around source to disable this message.
%Error: Exiting due to 1 warning(s)
+ rc=1
+ echo 'verilator exit code for latch.v: 1 (non-zero expected)'
verilator exit code for latch.v: 1 (non-zero expected)
+ grep -qE '%(Warning|Error)' lint_latch.log
+ echo 'COLLECTED: latch'
COLLECTED: latch读这段摘录抓一个容易误会的点：%Error: Exiting due to 1 warning(s) 不是说存在编译错误，而是 Verilator 的策略——有未豁免的 Warning 就以非零退出。这个设计让 lint 可以直接挂在 CI 里当门禁：退出码非零即失败，不需要解析文本。同时它解释了为什么 lint 输出总是 Warning 开头、Error 收尾。
五、实测实录与九格速查矩阵
完整的逐案例采集实录如下（termshot 卡片摘自 195 行日志的 WIDTH 案例段，完整日志见文末「实验环境」）：
读这份实录抓 Verilator 告警的三段式格式：第一行 %Warning-类型: 文件:行:列: 一句话描述，随后是带行号的源码片段和 ^ 指向出错的具体 token，最后是「怎么豁免」的提示。掌握这个格式后，任何陌生告警都能三十秒内定位到代码。
九类告警汇总成一张速查矩阵，按修复优先级排序：
| 优先级 | 告警 | 一句话病因 | 标准修法 |
|---|---|---|---|
| P0 | IMPLICIT | 拼写错误生成隐式线网 | `default_nettype none + 修正拼写 |
| P0 | UNOPTFLAT | 组合逻辑成环 | 环内插寄存器打拍 |
| P0 | WIDTH | 位宽不匹配静默截断 | 显式位选或改位宽 |
| P1 | MULTIDRIVEN | 一个寄存器多个驱动源 | 合并到单个 always 块 |
| P1 | LATCH | 组合块分支不全 | 赋默认值或补全分支 |
| P1 | BLKSEQ | 时钟块用阻塞赋值 | 时钟块一律 <= |
| P2 | CASEINCOMPLETE | case 覆盖不全 | 补 default: |
| P2 | UNDRIVEN | 线网只消费不驱动 | 接驱动或删除 |
| P2 | UNUSED | 信号只驱动不消费 | 缩位宽或 waiver |
动手复现时建议做两个延伸实验：一是把 -Wall 去掉重跑，对比默认告警集少了哪几条（UNUSED、DECLFILENAME 这类会消失，直观理解 -Wall 的价值）；二是在修好的文件里逐个重新引入错误，看自己能否只凭告警原文猜回错误类型——能猜对八条以上，这张矩阵就算内化了。
这一篇在知识体系里的位置
- 流程篇：verilator lint：--lint-only 静态检查实操、告警分级与 waiver 豁免（lint 工作流与豁免管理，本篇是它的「告警图鉴」补充）；
- 排错延伸：iverilog 常见报错速查（编译期错误与本文的 lint 告警互补）；
- 同系列实验：同步 FIFO Verilog 实现与回归实测（写完 RTL 后先 lint 再仿真，是同一套质量纪律）。
一句话总结
Verilog lint 告警分三档：WIDTH/IMPLICIT/UNOPTFLAT 是会静默改行为的硬伤（当天修），BLKSEQ/LATCH/MULTIDRIVEN 是仿真与综合可能不一致的写法问题（随提交修），UNUSED/UNDRIVEN/CASEINCOMPLETE 是代码卫生（随手清）；Verilator 对未豁免 Warning 一律非零退出，天然适合当 CI 门禁。
实验环境
- 机器/系统：云主机 S6.4XLARGE32 16C32G / Ubuntu 22.04（eda-golden-v1 镜像）
- 工具版本：verilator（eda-golden-v1 镜像自带，
--lint-only -Wall模式） - 日期：2026-10-25
- 完整命令：
bash run.sh（内部循环执行verilator --lint-only -Wall <案例>.v，共 9 个案例：width / caseincomplete / unoptflat / blkseq / unused / undriven / latch / multidriven / implicit）
代码获取
九个造错案例源码与采集脚本已同步到公开仓库：geek-doc.cn/experiments/exp-verilator-lint-error-matrix，克隆后进入该目录执行 bash run.sh 即可复现本文全部告警输出。