波形查看工具对比:同一份 VCD 用 wavedrom / GTKWave / 文本三轨呈现实测
仿真跑完得到 .vcd,接下来的问题是「怎么看」。社区里最常被提到的名字是 GTKWave,写文档的人推荐 wavedrom,而 CI 流水线上往往只有 grep 和 awk。到底哪个场景该用哪个?波形查看工具对比不能停在功能清单上,得拿同一份真实波形分别走一遍才知道各自的顺手与别扭。本文就把 iverilog VCD 波形 一篇产出的 4 位计数器 counter.vcd 原样拿来,在三条路线上各出一个真实产物:wavedrom 的 WaveJSON 内嵌波形、GTKWave 的无头截图、awk 解码的文本对照表,最后给一张五维对比表和明确的选型结论。VCD 怎么从仿真里生出来,见 iverilog 仿真入门。
本文要回答的问题
- 同一个 VCD,wavedrom、GTKWave、纯文本三种看法各自长什么样、信息有没有丢?
- GTKWave 在没有显示器的容器/CI 里怎么截出真实波形图?缩放参数有什么坑?
- VCD 原文的
$var、标识符、#时间戳逐行怎么读? - 写文档、交互调试、自动化回归三种场景分别该选哪条路线?
一、环境与实验设计
代码获取:本实验完整代码(
counter.vcd、wave-window.json、signals.gtkw、shot.sh、vcd2table.awk)、Makefile 与全部产物见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-wave-viewer-compare/。克隆后make run即可复现。
工具链为 geek-eda:0.2 容器(Ubuntu 24.04;GTKWave Analyzer v3.3.116、Xvfb、ImageMagick 6.9.12,VCD 本身由 Icarus Verilog 12.0 生成)。运行命令:
docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp \
-v ~/Project/geek-doc.cn/experiments:/work \
-w /work/eda-lab-wave-viewer-compare geek-eda:0.2 make run被看的对象 counter.vcd 是一份真实的小波形:10 ns 时钟、12 ns 撤复位、使能后 4 位计数器每拍加一,206 ns 处暂停 3 拍再恢复,全程 286 ns。文件不大(几十行),但麻雀虽小五脏俱全——单比特信号、多比特总线、x 初值、使能暂停全有,足够暴露三条路线的真实差异。这里先回答一个背景问题:为什么同一份波形会存在三种看法?因为三者的「消费方」不同——wavedrom 的消费者是读文档的人,GTKWave 的消费者是调 bug 的工程师本人,文本的消费者是脚本。消费方不同,对呈现形式的要求就完全不同,这正是波形查看工具对比不能只看功能清单的原因。三轨的分工如下:
| 轨 | 工具 | 产物 | 命令(make 目标) |
|---|---|---|---|
| ① 文档内嵌图 | wavedrom(WaveJSON 手写转译) | out/wave-window.json | make wavedrom |
| ② 交互查看器截图 | GTKWave + Xvfb + ImageMagick | out/gtkwave.png | make shot |
| ③ 文本解码 | VCD 原文 + awk 脚本 | out/vcd-excerpt.txt、out/wave-table.txt | make table |
三条轨看的是同一个文件、同一段波形,下面的每个产物都来自本次 make run 的真实输出。
二、轨①:wavedrom——为文档而生的静态波形
wavedrom 不读 VCD,它读 WaveJSON:一段描述「信号名 + 电平串 + 数据标注」的 JSON。我把 VCD 里 10 ns 到 90 ns 这段(复位释放后计数器从 1 数到 8)按真实跳变逐拍转写,时钟每 5 ns 一格:
{ "signal": [
{ "name": "clk", "wave": "0101010101010101" },
{ "name": "rst_n", "wave": "01.............." },
{ "name": "en", "wave": "01.............." },
{ "name": "count", "wave": "x=.=.=.=.=.=.=.=",
"data": ["1", "2", "3", "4", "5", "6", "7", "8"] }
],
"config": { "hscale": 2 }
}每个字符一格(5 ns):clk 的 01 交替对应 5 ns 翻转一次;rst_n 和 en 在第二格(12 ns,落在 10-15 ns 格内)拉高后保持;count 用 = 表示数据相位,data 数组填该相位的值——VCD 里 15 ns 变 1、25 ns 变 2……85 ns 变 8,每两格换一个数,与 counter.vcd 的 b1 % / b10 % 跳变行一一对应。渲染出来就是这张图:
读这张图:第二格处 rst_n、en 同时拉高(这就是 VCD 的 #12000 行 1# 和 1$),此后每个时钟上升沿 count 加一,1→8 八个数据相位清清楚楚。wavedrom 的特点在这里已经看出来了:它是「转译」不是「查看」——你决定展示哪 16 格,它画哪 16 格。好处是产物是静态矢量图,直接嵌进网页/文档,构建期渲染、零依赖;代价是大波形不可能全量转,只适合截取关键窗口做说明性配图。
转写时有三个实操要点。第一,wave 串里一个字符就是一格,格宽由你自己定,本文取 5 ns 正好对齐时钟半周期;如果跳变不对齐格边界(比如 12 ns 的复位沿落在格中间),就近归入一格并在正文说明,不要硬造精度。第二,总线信号用 = 配 data 数组,= 的个数和数组长度必须严格一致,否则渲染不报错但数据整体错位,这是最隐蔽的坑。第三,x 相位(未初始化)要如实保留——本文 count 第一格就是 x,对应 VCD 里 #0 时刻的 bx %,把 x 画成 0 是美化数据,违反「图与 VCD 一致」的底线。
三、轨②:GTKWave——交互调试的标配,无头截图要过两道关
GTKWave 是交互式查看器:左边信号树(SST)勾选信号,右边波形区缩放、打 marker、改进制。交互操作可以固化成 savefile(.gtkw),本实验的 signals.gtkw 预置了 clk / rst_n / en / count[3:0] 四条信号和窗口尺寸。容器里没有显示器,无头截图用 shot.sh 走通,核心四步:
Xvfb :99 -screen 0 1280x800x24 & # 虚拟显示器
DISPLAY=:99 gtkwave counter.vcd signals.gtkw -S /tmp/zoom.tcl &
DISPLAY=:99 import -window root out/gtkwave.png # ImageMagick 抓全屏zoom.tcl 只有两行,却是本次实验踩坑最多的地方:
gtkwave::setWindowStartTime 0
gtkwave::setZoomFactor -18坑在 setZoomFactor 的语义:它是 2 的幂次,负值拉宽、正值收窄,和直觉相反;savefile 里的 *-5.000000 ... 缩放字段同样不讲道理(-5 时窗口只有约 100 ps,波形被压成几条直线)。我实测校准了一组值:-5/-2/8 全灭,-16 太窄,-18 时 286 ns 全程恰好铺满 1280 宽窗口。校准后的真实截图:

读这张图:左侧 SST 树展开 counter_tb 和 dut 层级;信号区显示 marker(105 ns)处的即时值 clk=1 rst_n=1 en=1 count[3:0]=A(十六进制,即十进制 10——VCD 里 105 ns 正是 b1010 %);波形区能看到 clk 的密集方波、rst_n/en 在 12 ns 的上升沿、count 总线的翻转带,以及 206 ns 处 en 拉低后计数器停走的平坦段。和 wavedrom 轨相比,GTKWave 给的是全貌:全程 286 ns 一览无余,marker 指哪读哪,但它需要 GUI 环境(哪怕虚拟的),产物是位图截图,交互能力无法固化进文档。
值得单独说的是 savefile 的价值。.gtkw 是纯文本,里面记录了加载的 dump 文件、选中的信号列表(@22 表示十六进制显示、@28 表示十进制)、层级树展开状态、窗口尺寸和 marker 位置。这意味着「我看到的现场」可以原样交给同事:对方 gtkwave counter.vcd signals.gtkw 一打开就是同样的四条信号、同样的进制、同样的视角,不用口头描述「你展开第二层、把 count 改成 hex」。交互式调试里真正高频的功能——双击波形跳 marker、右键改进制、字母搜索信号名、两组信号做比较——全部可以事后固化进 savefile,这是 GTKWave 相对其他查看器最实用的差异化能力。
四、轨③:文本——VCD 原文与 awk 解码表
第三条轨连「图」都不要。VCD 是 ASCII 文本,直接用眼睛读是可行的。out/vcd-excerpt.txt 的关键段(真实原文):
$var wire 4 ! count [3:0] $end ← 标识符 ! 代表 4 位信号 count
$var reg 1 " clk $end ← 标识符 " 是 clk(注意只占 1 字符)
$var reg 1 # en $end
$var reg 1 $ rst_n $end
...
#12000 ← 时间戳:12000 ps = 12 ns
1# ← en 变 1
1$ ← rst_n 变 1(撤复位)
#15000
b1 ! ← count 变为二进制 1(b 前缀 = 多比特值)
b1 %
1" ← clk 变 1(单比特直接写值+标识符)规则就三条:$var 段把信号名压缩成短标识符省空间;#数字 推进仿真时间(单位由 $timescale 1ps 决定);其后的每一行是「哪个标识符变成什么值」。标识符复用是新手最容易看晕的地方——! 是 TB 层的 count、% 是 DUT 里的 count,两者数值永远一致但 VCD 里各记一份。
头部还有几行值得认一遍:$date / $version 记录生成者和工具版本(排「这个 VCD 是谁生的」类问题时有用);$scope module counter_tb / $upscope 一对括号圈出层级,信号全名 = 层级路径 + 变量名;$enddefinitions 之前全是定义、之后全是数据;#0 处的 $dumpvars ... $end 段是所有信号的初值快照(本例里 bx % 说明上电时 count 未定)。理解了这段结构,任何一个陌生 VCD 你都能徒手读出前几十纳秒发生了什么——这是看波形的基本功,图形工具反而把这一层遮掉了。
当然,长波形靠眼睛数 # 行不现实,所以实验里配了 vcd2table.awk 把跳变聚合成对照表(out/wave-table.txt 真实输出节选):
time(ps) clk rst_n en tb.count dut.count
12000 0 1 1 0 0
15000 1 1 1 1 1
20000 0 1 1 1 1
25000 1 1 1 2 2
...
85000 1 1 1 8 8
206000 0 1 0 4 4
215000 1 1 0 4 4 ← en=0 期间 count 保持 4 不动
245000 1 1 1 5 5 ← 恢复使能后继续计数脚本只有 40 行 awk,逻辑一句话能说清:遇到 # 行先输出上一时间戳聚合好的各信号值,再按标识符更新对应信号,多比特值转十进制。具体拆成三类规则——/^#/ 行负责「结算并翻页」,/^1"/ 这类行更新单比特信号(正则最后一个字符就是标识符),/^b[01xz]+ %/ 这类行更新多比特总线(去掉 b 前缀和标识符后缀后逐位乘 2 累加)。唯一的小坑是初值 bx(未定)要单独一条规则匹配成字符串 "x",如果让它落进二进制转十进制分支,awk 会把 "x" 当 0 参与运算,#0 时刻就显示成全 0——把未定美化成确定值,和 wavedrom 轨画 x 为 0 是同一种错误。
文本轨的信息量其实一条不少——时间、值、谁变了全在表里,只是没有「形」。它的真正价值在自动化:grep、diff、awk 随便组合,预期波形可以写成黄金参考文件做回归比对,这是两条图形轨都做不到的。举个具体用法:把 wave-table.txt 提交为 golden 文件,RTL 改动后重跑 make table,diff 为空说明时序行为没变,diff 的第一行就是第一个行为分歧点——配合 git bisect,这就是一套零依赖的时序回归。
五、五维对比与选型建议
三轨产物摆在一起,按对决策有用的五个维度打分(基于本次实测体验,非功能清单抄录):
| 维度 | wavedrom | GTKWave | 文本(VCD+awk) |
|---|---|---|---|
| 渲染效果 | 矢量、干净、适合印刷/网页 | 位图截图,黑底绿波,工具感强 | 无图形,纯表格 |
| 交互能力 | 无(画死哪段是哪段) | 缩放/marker/进制/搜索最全 | 靠 grep/编辑器查找 |
| 自动化友好 | WaveJSON 可脚本生成,中等 | savefile+Tcl 可预置,截图链路重(Xvfb+ImageMagick+缩放校准) | 最高,全程文本工具 |
| CI 可用 | 可(Node 渲染 SVG) | 勉强(本实验证明了可行,但调试成本高) | 天然适合,黄金文件 diff |
| 学习成本 | WaveJSON 语法半小时 | 界面操作 + savefile/Tcl,数小时 | VCD 格式三条规则,一小时 |
结论很明确,按场景选:
- 写文档/写博客做说明性配图 → wavedrom。截关键窗口(十几拍以内),读者打开页面就看到波形,不依赖任何查看器。本站所有内嵌波形图都走这条轨。
- 交互式调试真实 bug → GTKWave。信号成百上千、要在时间轴上跳来跳去时,它的 marker、搜索、进制切换是刚需;savefile 把排查现场存下来还能分享给同事复现视角。
- 脚本处理与 CI 回归 → 文本。VCD 本身就是文本,awk/grep/diff 直达数据,把「期望波形」做成黄金参考文件比对是零依赖的回归方案。
三者不是互斥而是接力:CI 用文本轨 diff 出差异时间点 → GTKWave 打开现场定位原因 → 修好以后用 wavedrom 把关键窗口画进文档留给后来人。
再把这条接力链说具体一点。回归失败时 CI 日志里只有文本,awk 解码表能直接回答「第几纳秒哪个信号开始不对」,这一步连 VCD 查看器都不用开;拿到时间点后,本地 gtkwave counter.vcd signals.gtkw 把 marker 钉在 206 ns 附近,上下游信号一扫就能定位是激励问题还是设计问题——图形轨的价值在「上下文一览无余」,这是文本表给不了的;修完之后,bug 前后那十几拍往往就是文档里最生动的素材,转写成 WaveJSON 嵌进复盘文章,读者不用装任何工具就能看懂时序。三条轨各管一段生命周期,谁也不替代谁。
还有一个常被忽略的维度是信息保真。三轨看的是同一份数据,但保真度不同:文本轨 100% 保真(就是数据本身);GTKWave 全量加载,保真度也接近 100%,只看你想看的部分;wavedrom 是人工转译的摘要,保真度取决于转写者的核对——本文的 WaveJSON 每一个 = 相位都和 VCD 的跳变行核对过,但这一步是人工的,换个人换个窗口就可能出错。所以涉及「以图为准」的场合(评审、签核),请回到文本轨或 GTKWave 原图,wavedrom 只做说明不做证据。
六、常见坑与排错
本次实验真实踩到的坑,按出现顺序:
- GTKWave 无显示器直接起:报
Could not initialize GTK! Is DISPLAY env var/xhost set?——必须先Xvfb起虚拟屏并设DISPLAY。 - 截图波形被压成直线:缩放语义反直觉,
setZoomFactor负值才拉宽;savefile 的缩放字段同样不可信。对策:像本文一样小步试错校准,把最终值固化进脚本。 - WaveJSON 数据相位对不齐:
data数组个数必须和wave串里=的个数一致,多一个少一个渲染出来就错位——写完和 VCD 的#时间戳行逐拍核对一遍。 - awk 解码把 x 算成 0:
bx行(未初始化)要单独匹配,不能进二进制转十进制分支,否则#0时刻全显示 0 误导读者。
四条坑之外再补一句方法论:三轨产物之间互为校验。本次写作中 wavedrom 的每个数据相位都和 awk 表核过一遍,GTKWave 截图里 marker 值 count=A 又和两轨交叉验证——任何一轨与前两轨矛盾,先怀疑自己的转写/脚本,再怀疑工具。真实实验的「真」不只在于跑过,更在于三份产物互相咬得上。
这一篇在知识体系里的位置
本篇是 eda-lab 波形段的收官篇:上游 iverilog 仿真入门 负责跑出 VCD,iverilog VCD 波形 负责控制 VCD 记什么、记多大,本篇解决「拿到 VCD 之后怎么看」的三条路线选型。后续做 verilator/cocotb 实验时,波形查看沿用本篇结论:文档配图走 wavedrom,本地调试开 GTKWave,回归脚本走文本。
总结
波形查看工具对比的答案不在功能清单而在场景:同一份真实 VCD 三轨实测证明,wavedrom 赢在文档内嵌(矢量、零依赖、但只画截取窗口),GTKWave 赢在交互调试(全貌、marker、但 GUI 依赖重、无头截图要过 Xvfb 和缩放校准两道关),文本轨赢在自动化与 CI(VCD 本来就是 ASCII,awk/grep/diff 直达数据)——CI 文本比对、现场 GTKWave 定位、文档 wavedrom 呈现,三轨接力覆盖全生命周期。