verilator coverage:line/toggle 覆盖率收集实操与报表解读
本篇是 eda-lab 开源 EDA 工具实操系列「仿真段」的一篇,主打 verilator coverage 这条链路:怎么用 --coverage 编译收集代码覆盖率、怎么用 verilator_coverage 工具把二进制 .dat 翻成能读的报表、以及——最关键的——拿到报表之后怎么逐点判断「没覆盖的那几行到底意味着什么」。覆盖率的方法论(代码覆盖与功能覆盖的分工、收敛流程)在 代码与功能覆盖率 和 代码覆盖率和功能覆盖率有什么区别 里讲得很透,本篇用开源工具把「收集 → 解读 → 补激励 → 再看报表」这个闭环亲手跑两遍,所有百分比都来自真实输出。
本文要回答的问题
- Verilator 的
--coverage到底收集哪几类覆盖点?line、toggle、branch 各是什么意思? - 仿真跑完
coverage.dat在哪?为什么用--binary跑完却死活找不到这个文件? verilator_coverage --write-info输出的 LCOV 报表怎么读?DA:行号,次数里次数为 0 说明了什么?- 一份「覆盖率上不去」的报表,怎么定位是激励缺了哪一段?
- 行覆盖 100% 了就万事大吉吗?toggle 覆盖能额外暴露什么?
环境
实验统一跑在 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-coverage geek-eda:0.1 make run代码获取:本实验完整 RTL(
counter.v)、两个 testbench(tb_naive.v/tb_full.v)、自定义 C++ main(sim_main.cpp)、Makefile 与两轮真实输出(out/*.log、out/*.dat、out/*.info)见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-verilator-coverage/。克隆后make run即可复现。
一、实验设计:一个刻意留盲区的计数器
被测设计(DUT)是一个 8 位计数器 counter.v,带异步复位、同步清零(clr)、使能(en)和溢出标志(ovf)。它的 always 块天然分出四条互斥路径,正好用来观察覆盖率:
always @(posedge clk or negedge rst_n) begin
if (!rst_n) begin // 路径 A:异步复位
count <= 8'd0; ovf <= 1'b0;
end else if (clr) begin // 路径 B:同步清零
count <= 8'd0; ovf <= 1'b0;
end else if (en) begin // 路径 C:使能计数
count <= count + 8'd1;
if (count == 8'hFF) begin // 路径 D:溢出置标志
ovf <= 1'b1;
end
end
end实验分两轮,testbench 一简一全:
| 轮次 | testbench | 激励内容 | 故意留下的盲区 |
|---|---|---|---|
| 第一轮 | tb_naive.v | 上电 rst_n=1 不动,en=1 数 20 拍就 $finish | 复位分支、clr 分支、溢出路径、高位翻转 |
| 第二轮 | tb_full.v | 复位拉低 3 拍释放 → en=1 数 300 拍(必然溢出)→ clr 拉高清零 → en=0 空转 | 无(设计目标) |
整体数据流用一张图说清楚——RTL 经过 --coverage 编译后,仿真时每命中一个覆盖点就累加计数,仿真结束由 C++ main 显式落盘 .dat,再由 verilator_coverage 转成报表:
这个流程里最容易踩的坑就在「仿真期 → 报表期」的交界:Verilator 5.020 的 --binary 生成的默认 main 函数不会调用 VerilatedCov::write(),跑完仿真目录里根本没有 coverage.dat。解决办法是自带一个 sim_main.cpp,在 final() 之后显式写出:
topp->final();
// 关键一步:把 line/toggle 覆盖率写到 coverage.dat
VerilatedCov::write(COV_FILE);这也是本实验 Makefile 用 --cc --exe --build 而不是 --binary 的原因——不是炫技,是 --binary 这条路在 5.020 上确实拿不到覆盖率数据。
二、第一轮:朴素 TB 的真实覆盖率
make naive 编译运行 tb_naive.v,仿真日志(out/run_naive.log):
NAIVE done, count=19 ovf=0
- tb_naive.v:22: Verilog $finish数了 20 拍、没溢出,ovf 从头到尾是 0——已经能预感覆盖率不会好看。verilator_coverage --write-info 导出的 LCOV 报表(out/coverage_naive.info)里 counter.v 部分原文:
SF:counter.v
DA:5,39
DA:6,1
DA:7,1
DA:8,0
DA:9,0
DA:10,0
DA:12,20
DA:13,0
...
DA:22,0
end_of_recordDA:行号,命中次数 是 LCOV 的标准记法。逐行对照源码解读几个关键行:
DA:8,0与DA:10,0:第 8 行是clr端口、第 10 行是ovf端口,命中 0 次——TB 从没拉过clr,ovf也从未翻转,直接对应设计里两条没走的路径。DA:12,20:always 块本体命中 20 次,正好是 TB 数的 20 拍,说明「计数」这条路径确实被反复执行了。DA:13,0:复位分支体一次没进——TB 把rst_n恒置 1,路径 A 完全没测到。
LCOV 只导出行覆盖;toggle(翻转覆盖)和 branch(分支覆盖)的点在二进制 .dat 里。统计 .dat 里 page 字段归类,counter.v 的完整覆盖点数据:
| 覆盖类型 | 覆盖点总数 | 命中 | 覆盖率 | 未命中点 |
|---|---|---|---|---|
| line(行) | 3 | 1 | 33.3% | 复位分支体、clr 分支体 |
| toggle(翻转) | 13 | 8 | 61.5% | clr、ovf、count[5]、count[6]、count[7] |
| branch(分支) | 4 | 2 | 50% | if(count==FF) 的真分支、if(en) 的假分支 |
toggle 覆盖的未命中点特别值得展开:13 个翻转点里有 8 个挂在 count 的 8 根 bit 线上(每 bit 一个点),count[5]/[6]/[7] 未命中不是「这些线坏了」,而是只数了 20 拍,计数器最高才到 19(二进制 10011),高 3 位从头到尾保持 0,自然没有翻转。这是 toggle 覆盖最典型的读法:它告诉你激励的值域覆盖不够,而不是代码没跑到。
三、第二轮:补全激励后的真实对比
tb_full.v 按盲区逐条补激励:复位拉低 3 拍覆盖路径 A;数 300 拍让计数器走完 0→255 全程,必然命中 count==8'hFF 的溢出路径 D;再拉 clr 覆盖路径 B;最后 en=0 空转几拍,把 if(en) 的假分支也补上。运行日志(out/run_full.log):
FULL done, count=0 ovf=0
- tb_full.v:39: Verilog $finish结尾 count=0 是 clr 清零后的结果,符合预期。两轮的 .dat 统计放一张表里对比,这是本篇最核心的一张表:
| 覆盖类型 | 朴素 TB | 补全 TB | 提升手段 |
|---|---|---|---|
| line | 1/3 = 33.3% | 3/3 = 100% | 补复位脉冲 + clr 脉冲 |
| toggle | 8/13 = 61.5% | 13/13 = 100% | 数满 300 拍覆盖全值域 |
| branch | 2/4 = 50% | 4/4 = 100% | 溢出 + en 空转补真假两分支 |
再看补全后的 LCOV 报表(out/coverage_full.info)摘录,重点看原来为 0 的行:
SF:counter.v
DA:8,2
DA:10,2
DA:13,2
DA:19,7
DA:20,300
DA:21,1
DA:22,1DA:13,2:复位分支体命中 2 次——TB 拉了一次复位,期间跨了两个时钟沿。DA:21,1/DA:22,1:溢出判断和置位各命中 1 次,正好对应 300 拍里唯一一次 0xFF→0x00 翻转。DA:20,300:计数语句命中 300 次,与激励拍数严丝合缝。
命中次数和激励拍数能对上,是验证「覆盖率数据可信」最朴素的办法——如果 DA:20 不是 300,反而要怀疑 TB 或收集链路出了问题。
四、读报表的三个实战判据
两轮实验跑完,提炼三条读 verilator coverage 报表时真正用得上的判据:
第一,先看 toggle 未命中点,它最便宜也最诚实。 行覆盖可以靠「随便跑点什么」刷上去,但 count[7] 翻没翻过、复位脚拉没拉过,报表里一目了然。第一轮 61.5% 的 toggle 覆盖直接指出了「值域不够」和「控制脚没动」两类问题,比行覆盖的信息量大。
第二,命中 0 次的路径优先对激励清单,而不是改 RTL。 第一轮报表里路径 A/B/D 全是 0,这不是 RTL 写错了,是 TB 的激励清单缺项。真实项目里覆盖率卡住的排查方法与此同理,覆盖率不收敛:卡在 9x% 的排查与收尾 讲的就是这套分诊思路。
第三,行覆盖 100% 不等于验证完了。 本实验的 DUT 没有功能覆盖(covergroup),三个 100% 只说明「每行代码都跑过、每根线都翻过、每个分支真假都走过」,并不能证明「计数器在所有场景下都算对」——比如 clr 和 en 同拍拉高的优先级行为,行覆盖根本不管。这正是 覆盖率到了 100% 为什么还可能漏 bug 展开的话题。
五、常见报错排查(本次实验真实触发)
| 报错原文 | 触发场景 | 处置 |
|---|---|---|
%Error-NEEDTIMINGOPT: Use --timing or --no-timing | TB 里有 #5 延时或 @(posedge clk) 事件控制,但没给时序模式 | 编译加 --timing(5.020 对带延时 TB 的必选项) |
%Warning-TIMESCALEMOD ... %Error: Exiting due to 1 warning(s) | TB 写了 `timescale 而 DUT 没写,Verilator 把告警当错误退出 | DUT 顶部补 `timescale 1ns/1ps,或加 -Wno-TIMESCALEMOD |
跑完仿真找不到 coverage.dat | 用 --binary 编译,生成的默认 main 不写覆盖率 | 改 --cc --exe --build + 自定义 main 调 VerilatedCov::write()(见本文第一节) |
.info 里只有 DA: 行,看不到 toggle | --write-info 只导出行覆盖,这是 LCOV 格式本身的限制 | toggle/branch 统计直接解析 .dat,或加 --annotate 生成带标注源码 |
四条里前三条都是本次实验从踩坑到修复的完整闭环,Makefile 的最终形态就是修完这三处之后的样子。顺带一提,想在上仿真之前就挡住一批问题,可以先跑静态检查,Verilator 高速仿真与 lint 覆盖了 --lint-only 的用法。
这一篇在知识体系里的位置
本篇属于 eda-lab 实操系列的仿真段,向上承接方法论层的 代码与功能覆盖率(讲清 line/toggle/branch/功能覆盖的分工),横向衔接同系列的 verilator lint 实操(仿真前的静态防线)与后续的 cocotb 入门(用 Python 写 TB 后同口径收集覆盖率)。当覆盖率报表成为日常之后,覆盖率收敛流程 是把这些点管理成「可签核状态」的下一步。
总结
verilator coverage 的完整链路是 --coverage 编译插桩 → 仿真命中计数 → 自定义 main 显式 VerilatedCov::write() 落盘 .dat → verilator_coverage --write-info 出报表;本次实测朴素 TB 只拿到 line 33.3% / toggle 61.5% / branch 50%,按未命中点逐条补激励(复位、clr、溢出、值域)后三轮收敛到 100%——报表不是终点,未命中点才是补激励的清单。