极客工场

Appearance

共 2,192 字预计阅读约 7 分钟

GTKWave VCD 解析失败：区分截断、结构错误与空波形 ​

更新时间：2026-10-31。GTKWave VCD 解析失败可能发生在文件传输、文本加工或仿真导出任一环节。本文用 Icarus 正常生成的波形作对照，再构造可重复的错误文件；若连 VCD 都没有生成，应先查 iverilog 缺少 dumpvars。

本文要回答的问题 ​

  • No symbols in VCD file 是文件损坏，还是文件里本来就没有信号？
  • 截断、残缺 header 和残缺 $var 定义的报错位置有什么不同？
  • 为什么 GTKWave 返回 0，日志里仍有解析错误，结束时间还可能变成 0？
  • 怎样修复具体结构，并用时间范围和退出码共同验收？

先说答案：先保留原始文件，再同时看诊断、退出码和起止时间。本次截断与变量定义错误返回 255；残缺 header 虽返回 0，却出现 Unknown VCD identifier 且时间范围缩成 [0,0]。无信号 VCD 也会报 No symbols，应与损坏文件分开处理。

一、GTKWave VCD 解析失败要沿结构逐层定位 ​

VCD（Value Change Dump，值变化转储）先写 $date、$version、$timescale 等 header，再写 $scope 与 $var 定义，最后才是 #时间 和值变化。文件末尾没有统一的「完整结束」记录，所以文件非空、前几行可读，都不能证明主体完整。

eda/ts-gtkwave-vcd-parse-error.md D2 示意图

读图时先分红色两类根因：结构错误要修文件或导出过程，无信号要修记录范围，二者不能共用「补几个值变化」的办法。蓝色是诊断，橙色是修复，绿色是验收。尤其不要把 No symbols 单独当成损坏判据，它也会出现在合法的空层次中。

二、用正常导出的 VCD 建立时间范围基线 ​

对照文件由 Icarus Verilog 12.0 直接生成，包含一个时钟和四位计数器。$dumpvars(0, tb) 记录整个测试平台，仿真在 15000 ps 结束。这样后续看到 [0] start time 与 [15000] end time，才知道它们对应完整波形，而不是随便一个「加载成功」。

verilog
initial begin
    $dumpfile("build/good.vcd");
    $dumpvars(0, tb);
    clk = 1'b0;
    count = 4'd0;
    #5 clk = 1'b1;
    count = 4'd1;
    #5 clk = 1'b0;
    count = 4'd2;
    #5 $finish;
end

无界面检查使用 xvfb-run -a gtkwave -x -f build/good.vcd：-f 指定文件，-x 在加载后退出，Xvfb 只提供命令运行所需的虚拟显示。这里记录的是 GTKWave 3.3.116 自身的加载诊断，不用其他转换器的接受结果代替它。

另一个对照模块执行 $dumpvars(0, tb_empty)，但模块内不声明任何信号。它会真实创建 VCD，却只留下层次结构。这个用例专门回答「文件存在但无波形」：问题在记录对象为空，不在文件系统权限，也不等于内容被截断。

三、字节位置帮助区分截断与定义结构错误 ​

实验中的截断文件只保留正常 VCD 的前 13 行，结束于变量定义之后、$enddefinitions 之前。header 故障则把 $scope module tb $end 改成缺少 $end 的形式；定义故障单独删除时钟 $var 行末尾的 $end。三种改动都确定、可复跑，不依赖随机损坏。

正常、截断与残缺 header 的加载结果并不相同

正常文件返回 0，时间范围为 0–15000。截断文件在字节 177 附近报 VCD search table NULL，随后返回 255，说明索引所需的后续结构不存在。此时正确修复是重新运行仿真或重新传输完整文件；仅在末尾补一个 $end，无法找回丢失的信号和值变化。

残缺 $scope 的结果更能说明退出码的局限：GTKWave 在字节 268 报未知标识符 !，返回码却是 0，但结束时间已变成 0。! 本来是时钟的合法标识符，因为前面的作用域没有闭合，它出现在了解析器无法接受的上下文。排错时应从报错点向前检查配对结构，不要只盯着这个字符。

变量定义缺失 $end 则在字节 133 直接给出 $VAR parse error，并返回 255。与截断相比，它的错误更早、更具体。手工合并 VCD、用正则提取信号或拼接多个仿真片段时，应重点检查每个 $scope、$var 是否保留完整一行及其结束符。

四、时间回退和空波形是另外两类问题 ​

时间样本在正常文件末尾追加 #not_a_time 和一次值变化。非法时间文本被解析成回退，GTKWave 给出 Time backtracking detected，尽管最终仍返回 0、起止时间也仍是 0–15000。因此「时间范围正确」只能证明已有主体可读，不能抵消任何诊断。

exp-log
--- parse bad-time ---
$ xvfb-run -a gtkwave -x -f build/bad-time.vcd

GTKWave Analyzer v3.3.116 (w)1999-2023 BSI

VCDLOAD | Time backtracking detected in VCD file!
[0] start time.
[15000] end time.
Exiting early because of --exit request.
exit=0

--- parse bad-definition ---
$ xvfb-run -a gtkwave -x -f build/bad-definition.vcd

GTKWave Analyzer v3.3.116 (w)1999-2023 BSI

Near byte 133, $VAR parse error encountered with 'tb.$end'
No symbols in VCD file..nothing to do!
exit=255

--- parse empty ---
$ xvfb-run -a gtkwave -x -f build/empty.vcd

GTKWave Analyzer v3.3.116 (w)1999-2023 BSI

No symbols in VCD file..nothing to do!
exit=255
--- repair header structure and parse again ---

--- parse repaired-header ---
$ xvfb-run -a gtkwave -x -f build/repaired-header.vcd

GTKWave Analyzer v3.3.116 (w)1999-2023 BSI

[0] start time.
[15000] end time.
Exiting early because of --exit request.
exit=0

空层次文件没有任何 $var，所以同样返回 255 和 No symbols，却没有字节解析错误。修复应回到测试平台：确认 $dumpvars 的作用域确实含信号、实例名称没有写错，并检查是否把记录范围限制在空模块。若信号存在但值始终不变，那是平波，不是空文件，排查方向也不同。

时间回退通常来自片段乱序拼接、多个仿真各自从 0 开始，或后处理破坏 #数字 行。应按时间戳重新审查生成流程，而不是把警告过滤掉。尤其不能把多次运行直接首尾相接后仍称为单一时间轴；需要多段波形时，分开文件往往更清楚。

五、修复后必须重新加载，而不是只看文本像对了 ​

本次修复只给 $scope module tb 补回缺失的 $end，生成新文件后再次运行同一 GTKWave 命令。上面日志末尾显示返回 0，且时间范围恢复为 0–15000，没有未知标识符诊断，才构成闭环。原错误文件仍保留，便于确认修的是哪一处。

实际项目可按这个顺序验收：先对正常小样确认工具能读；再保存失败文件的副本和完整命令；按最早的字节错误修结构，按 $var 是否缺失查记录范围；最后重新导出或生成新文件。不要用忽略警告、删除报错信号或只改扩展名作为修复，也不要让旧波形掩盖本轮没有生成新文件的问题。

如果波形来自持续集成或远程仿真，还要把传输纳入检查。仿真进程返回成功，只代表它已经写完自己看到的文件；后续压缩、下载或同步仍可能中断。可在导出端记录字节数，在接收端核对，再对最终落盘的文件执行加载检查。不要只检查本地缓存副本，因为它可能与读者实际下载到的文件不是同一份。对于反复出现的截断，优先修导出与传输链路，而不是每次手工补文本。

实验环境 ​

  • 机器/系统：Linux 容器，geek-eda:0.2 镜像
  • 工具版本：GTKWave 3.3.116（3.3.116-1build2）、Icarus Verilog 12.0 stable、Xvfb
  • 日期：2026-10-31
  • 完整命令：bash run.sh；脚本生成正常与空层次 VCD，构造四类错误，逐一执行 xvfb-run -a gtkwave -x -f，最后修复 $scope 结构并复跑

代码获取 ​

测试平台、故障构造与复跑脚本位于公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-gtkwave-vcd-parse-error。安装 GTKWave、Xvfb 和 Icarus Verilog 后进入目录执行 bash run.sh；运行产物集中在 build/。

这一篇在知识体系里的位置 ​

本篇处理波形已经落盘后的 GTKWave VCD 解析失败。若需要区分控制台日志与波形生成选项，可看 vvp 日志与跟踪选项；若 dump 系统任务本身缺失，则回到 iverilog 缺少 dumpvars。其他仿真与波形问题可从 EDA 排错目录继续定位。

总结 ​

GTKWave VCD 解析失败要同时看诊断、退出码和时间范围：截断常破坏后续索引，残缺 $scope 或 $var 会把合法标识符置于错误上下文，时间回退可能只给警告，空层次则会无可显示信号。截断应重新完整导出，结构错误要修具体配对，空波形要修 $dumpvars 范围；修复后重新加载并确认诊断消失、时间范围恢复，才算完成。