极客工场

Appearance

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

iverilog 仿真跑完无波形输出：$dumpfile/$dumpvars 缺漏排查速查 ​

更新时间：2026-10-29。FAQ 速查页，属于开源 EDA 排错系列，总入口见 开源 EDA 报错排错中心。照 iverilog 第一次仿真 跑通流程后，最常见的下一步诉求是看波形——可 vvp 跑完了，目录里却没有 VCD 文件，或者文件倒是生成了、GTKWave 打开却空空如也。iverilog 对此一个报错都不给：VCD 记录不是默认开启的，它只在 testbench 主动调用 $dumpfile/$dumpvars 后才开始工作，少了这一步仿真照常结束、仿真器认为一切正常。所以「iverilog 仿真跑完无波形输出」不是编译错误也不是仿真错误，而是记录开关没打开，排查方向与语法报错完全不同。

本文要回答的问题 ​

  • 仿真正常结束、目录里却没有任何 .vcd 文件，第一嫌疑是什么？
  • VCD 文件生成了但只有几十行、GTKWave 里没波形，又是什么机制？
  • $dumpfile/$dumpvars/$dumpoff/$dumpon 四个系统任务各自管什么？
  • 补上 dump 语句后怎么确认 VCD 内容真的完整？

排查主线一图速览 ​

这张流程图把「无波形输出」的排查压成一条主线加一个分叉：先看文件存在与否，再看内容形态，两类现场分别指向不同的根因，最后修复复跑收尾。颜色只表达语义：红是入口现象与命中的根因，蓝是排查动作，橙是修复动作，绿是复跑确认。

eda/ts-iverilog-vcd-dumpvars-missing.md D2 示意图

读这张图抓一个分叉：ls *.vcd 的结果就是分水岭。文件根本不存在，问题在「记录从未开始」；文件存在但内容只有头部，问题在「记录开始了又被关掉」或「仿真根本没跑到有变化的时刻」。两条路修复动作不同，不要混为一谈。

一、现场复现：仿真跑完了，VCD 没有 ​

实验设计一个最小电路：blink.v 是复位后每拍翻转的 LED 闪烁模块，testbench 给 100ns 时钟与复位激励。第一个 testbench tb_blink_nodump.v 故意不写任何 dump 语句——这是很多教程示例的真实样子，仿真功能完全正常，只是没有任何波形记录。

verilog
// tb_blink_nodump.v：功能仿真正常，但忘写 $dumpfile/$dumpvars
`timescale 1ns/1ps
module tb_blink;
    reg clk = 1'b0;
    reg rst_n = 1'b0;
    wire led;

    blink dut (.clk(clk), .rst_n(rst_n), .led(led));

    always #5 clk = ~clk;

    initial begin
        #12 rst_n = 1'b1;
        #100;
        $display("sim done, led=%b", led);
        $finish;
    end
endmodule

编译、仿真、ls 查文件，三步走完就是完整现场。下面这张终端实录卡是真实跑出来的记录（完整命令见文末实验环境）：vvp 正常打印 $finish 结束，但 ls *.vcd 直接报 no matches found——目录里一个 VCD 都没有。

iverilog 仿真正常结束但无任何 VCD 生成

注意实录里没有任何报错：编译通过、仿真到 112000ps 正常 $finish。这正是这个坑迷惑人的地方——iverilog 不会因为「你没要求记录波形」而警告你，它默认你就不想看波形。和 iverilog syntax error near token 那种编译器指着行号报错的体验完全不同，这里工具全程沉默，线索只能靠自己去文件系统里找。

二、工具与版本：四个系统任务各管什么 ​

本实验用 Icarus Verilog 13.0（iverilog -V 输出 Icarus Verilog version 13.0 (stable)），仿真器前端是 iverilog、执行器是 vvp。VCD 记录完全由 testbench 里的四个系统任务控制：

系统任务作用不写会怎样
$dumpfile("name.vcd")指定输出文件名vvp 用默认名（不同版本默认行为不一，有的直接不落盘）
$dumpvars(0, tb_top)从指定层次开始记录信号变化，0 = 全部深度没有任何记录，仿真跑完无 VCD
$dumpoff暂停记录（长仿真跳过无关段落用）不影响
$dumpon恢复记录之前 $dumpoff 过就一直是空段

关键点：$dumpvars 是唯一的「开始记录」开关，缺了它一切都免谈。第二个参数必须是 testbench 的顶层模块名，写错层次（比如写成 dut 内部子模块）不会报错，只是记录范围变了。

三、第二类现场：VCD 生成了，GTKWave 打开是空的 ​

文件存在但没波形，典型诱因是 $dumpoff 之后忘记 $dumpon。复现用的 tb_blink_dumpoff.v 在 initial 块开头先 $dumpfile + $dumpvars，紧接着 $dumpoff——本意是跳过复位前的抖动段，结果后面忘了 $dumpon，整个仿真期间记录一直处于关闭状态。

verilog
    initial begin
        $dumpfile("blink_off.vcd");
        $dumpvars(0, tb_blink);
        $dumpoff;          // 暂停记录，之后忘记 $dumpon
        #12 rst_n = 1'b1;
        #100;
        $display("sim done, led=%b", led);
        $finish;
    end

这种现场 vvp 还会给一行迷惑性提示 VCD info: dumpfile blink_off.vcd opened for output——文件确实被「打开」了，让不少人以为记录正常。但打开文件不等于在写波形：wc -l 只有 20 行，tail 看到的全是 $var/$scope/$enddefinitions 头部定义，后面没有任何 #时间戳 开头的值变化段。GTKWave 能认出信号列表，却没有任何波形数据可画。

dumpoff 后忘 dumpon：VCD 只有 20 行头部，无波形数据

实录里 tail -5 的最后一行是 $enddefinitions $end——文件到信号定义就戛然而止。判断 VCD 是否空壳的一句话口诀：找 # 开头的行，找不到就是没记到任何波形（grep -c '^#' file.vcd 为 0 或只有 #0 都算空壳）。

四、排查清单：四类诱因对照 ​

现场可能原因快速验证处置
目录里没有任何 .vcdtestbench 忘写 $dumpvars源码里 grep dumpvars 无命中补上 $dumpfile + $dumpvars 复跑
目录里没有任何 .vcd只跑了 iverilog 编译，没跑 vvpshell 历史里查有没有 vvp 命令补跑 vvp <输出文件>
VCD 存在但只有头部$dumpoff 后忘 $dumpongrep -c '^#' 几乎为 0补 $dumpon 或删掉误加的 $dumpoff
VCD 存在但只有 #0 附近数据仿真时间太短/$finish 提前对照激励时长与 $finish 时刻延长仿真时间
VCD 在别的目录$dumpfile 写了相对路径，运行目录不对工程全局 find . -name '*.vcd'统一运行目录或写绝对路径
GTKWave 空白但 VCD 有数据查看器没添加信号到波形窗口VCD 里 grep 到有 #时间戳 段在 GTKWave 里把信号拖进窗口

最常见的是前两行——iverilog 的静默机制决定了「没波形」绝大多数时候是记录根本没被请求，而不是记录失败。

五、修复代码与复跑确认 ​

修复就是在 initial 块开头补上两行。层次参数写 0 表示从 tb_blink 往下全深度记录，dut 内部的信号也一并收进 VCD：

verilog
    initial begin
        $dumpfile("blink.vcd");      // 指定波形文件名
        $dumpvars(0, tb_blink);      // 从 tb_blink 顶层开始全层次记录
        #12 rst_n = 1'b1;
        #100;
        $display("sim done, led=%b", led);
        $finish;
    end

复跑后 wc -l blink.vcd 从 0 变成 86 行，头部 head 能看到 $scope module dut 证明层次记录生效，tail 能看到 #105000 时刻 led 信号 0!→1! 的翻转记录——波形数据真实在文件里了。

补上 dumpfile/dumpvars 复跑：86 行 VCD 含 dut 层次与翻转记录

实录里两段对照很清楚：head -25 段里 $scope module tb_blink 与 $scope module dut 两级层次齐全，三个信号各有 $var 定义；tail -8 段里 #100000、#105000、#110000 的时间戳与 0!/1" 的翻转值就是 led 与 clk 在跳变的直接证据。到这一步再把 VCD 喂给 GTKWave，波形就出来了；查看器侧的选型对比见 iverilog VCD 波形查看。

工程上还有两个值得养成的习惯：一是 dump 语句固定写在 initial 块第一行，与激励代码物理分开，避免 $dumpoff/$dumpon 夹在中间被漏看；二是需要跳过无关长段时才用 $dumpoff，且成对出现后立即 grep 一遍确认 $dumpon 存在，把「忘了恢复」消灭在编译前。

实验环境 ​

  • 机器/系统：Mac mini M4 / macOS 15
  • 工具版本：Icarus Verilog version 13.0 (stable)（iverilog -V 真实输出）
  • 日期：2026-10-29
  • 完整命令：iverilog -o simv_nodump tb_blink_nodump.v blink.v && vvp simv_nodump；iverilog -o simv_off tb_blink_dumpoff.v blink.v && vvp simv_off；iverilog -o simv tb_blink.v blink.v && vvp simv；配合 ls *.vcd / wc -l / head / tail 取证

代码获取 ​

本文全部实验代码（blink.v 与三个 testbench、Makefile）已同步到公开仓库 geek-doc.cn/experiments/iverilog-vcd-dumpvars-missing，克隆后 make nodump / make dumpoff / make fixed 分别复现两类现场与修复版。

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

本篇是开源 EDA 排错簇中「仿真波形记录」节点的 FAQ 页：仿真流程本身的第一次跑通见 iverilog 第一次仿真，拿到 VCD 之后的查看器使用见 iverilog VCD 波形查看，编译期另一类「工具沉默」问题（语法报错定位）见 iverilog syntax error near token，更多工具报错从 开源 EDA 报错排错中心 按入口分流。

总结 ​

iverilog 仿真跑完无波形输出的根因几乎总是记录开关没打开：VCD 记录不是默认行为，testbench 必须显式 $dumpfile + $dumpvars(0, 顶层名)，少了这两行仿真照常结束且工具全程零报错；VCD 文件存在但 GTKWave 空白则是 $dumpoff 后忘 $dumpon，判据是文件里找不到 # 开头的值变化段。排查先 ls *.vcd 分两类现场，再按清单对号入座，补上 dump 语句复跑并用 wc -l/tail 核对时间戳与翻转记录，即可闭环。