iverilog 仿真入门:计数器从编译到 VCD 波形的第一课
这是「EDA 开源工具实操」系列的第 一篇。商用流程的知识在 EDA 专区 已经讲了很多,这个系列换一条路:全部用开源工具(Icarus Verilog、Verilator、Yosys……)真实动手跑,每篇文档的命令、日志、波形都来自写作当次的真实运行。iverilog 仿真入门是整条链路的起点——先把「编译 → 运行 → 看波形」这三步走通,后面的 lint、coverage、cocotb 才有落脚点。
先花半分钟交代主角。Icarus Verilog(命令行叫 iverilog)是 Stephen Williams 从 1998 年维护至今的开源 Verilog 仿真器,支持 IEEE 1364-2005 全部特性和相当一部分 SystemVerilog。它不快(解释执行 .vvp,比 Verilator 的编译到 C++ 慢一个数量级以上),但胜在零安装门槛、报错信息友好、对 Verilog 标准的事件语义实现得扎实——这三个特性加在一起,使它成为全世界数字电路课程的事实标准教学仿真器。本篇不追求性能,追求把仿真这件事的最小闭环跑通。
还要分清一对概念:仿真(simulation)是「给设计喂激励、看它的行为对不对」,本篇做的事;综合(synthesis)是「把 RTL 翻译成门级网表」,那是 Yosys 篇的事。TB 里的 #5、$display 这类语句只能活在仿真世界,综合器会直接无视——所以「TB 不可综合」不是缺陷,是分工。
本文要回答的问题
- iverilog 和 vvp 各管什么?一条最小仿真命令长什么样?
- 一个能跑起来的 testbench 最少需要哪些零件(时钟、复位、
$display、$finish)? $dumpvars怎么把信号写进 VCD 文件?VCD 里记的到底是什么?- 怎么把跑出来的 VCD 跳变「翻译」成波形图来读?
- 第一次用 iverilog 最容易撞上的三类报错各是什么意思、怎么处置?
一、环境:geek-eda:0.1 容器一键复现
实验统一跑在 Docker 容器 geek-eda:0.1 里(Ubuntu 24.04.5 LTS),本篇涉及的工具版本均为容器内实测:
- Icarus Verilog 12.0 (stable)(
iverilog -V第一行:Icarus Verilog version 12.0 (stable)) - 附带
vvp运行时(同包安装) - make、bash 等基础工具
运行命令(把公开仓库的 experiments/ 挂进容器,一条命令出全部产物):
docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp \
-v ~/Project/geek-doc.cn/experiments:/work \
-w /work/eda-lab-iverilog-first-sim geek-eda:0.1 make run代码获取:本实验完整代码(
counter.v、counter_tb.v)、Makefile 与真实运行输出(out/sim.log、out/counter.vcd、out/errors.log)见公开仓库 derekzhuo/geek-doc.cn 的experiments/eda-lab-iverilog-first-sim/。克隆后make run即可复现。
本机装了 iverilog(比如 Mac 上 brew install icarus-verilog,本机实测为 13.0)也可以直接 make run,输出一致;容器只是保证读者拿到的是同一版本、同一结果。
二、实验设计:一个 4 位计数器和它的测试平台
被测设计(DUT,Design Under Test)是能用三句话说清的小东西:同步低有效复位、使能计数、4 位自然回绕。
// counter.v —— 4 位计数器(被测设计)
module counter (
input wire clk,
input wire rst_n, // 低有效同步复位
input wire en, // 计数使能
output reg [3:0] count
);
always @(posedge clk) begin
if (!rst_n)
count <= 4'd0;
else if (en)
count <= count + 4'd1;
end
endmoduleDUT 自己不会动——它没有时钟源。testbench(测试平台,常缩写 TB)的职责就是当「外部世界」:产生时钟和复位、拨动使能、观察输出。下面是 counter_tb.v 的核心零件:
`timescale 1ns/1ps
module counter_tb;
reg clk, rst_n, en;
wire [3:0] count;
counter dut (.clk(clk), .rst_n(rst_n), .en(en), .count(count));
// 时钟:每 5ns 翻转一次,周期 10ns
initial clk = 1'b0;
always #5 clk = ~clk;
initial begin
$dumpfile("out/counter.vcd"); // ① 指定 VCD 文件名
$dumpvars(0, counter_tb); // ② 导出 counter_tb 整个层级
rst_n = 0; en = 0;
#12 rst_n = 1; // 保持复位 12ns 后释放
en = 1;
repeat (20) @(posedge clk); // 让计数器跑 20 拍
// …暂停 3 拍、再跑 5 拍验证回绕,最后:
$display("TEST PASS");
$finish;
end
endmodule几个第一次见一定会问的点:
#5、#12是延时语句,只有仿真器认识,综合成电路时会被忽略——所以它们只能出现在 TB 里。`timescale 1ns/1ps规定#1的物理含义是 1ns,仿真精度到 1ps。TB 和被测文件的 timescale 不一致是新手玄学 bug 的高发区,入门阶段全工程统一即可。$dumpfile/$dumpvars是导出波形的系统任务,下一节细讲。$finish必须有。忘了它,时钟always #5会让仿真永远跑下去,只能 Ctrl+C。
再看 TB 与 DUT 的连接方式:counter dut (.clk(clk), .rst_n(rst_n), ...) 这叫命名端口连接——点号后面是 DUT 的端口名,括号里是 TB 这边的信号名。它对应的另一种是按位置连接 counter dut(clk, rst_n, en, count),短是短,端口一多、顺序一错就是灾难,而且 iverilog 只给一个 warning 未必报错。工程实践中一律用命名连接,顺手把 dut 这个例化名也固定下来——后续层级引用($dumpvars(0, counter_tb)、波形工具里的路径 counter_tb.dut.count)都靠它。
testbench 里出现的系统任务(以 $ 开头的内建命令)在入门阶段就这六个最常用,先把它们的职责边界记住:
| 系统任务 | 作用 | 常见坑 |
|---|---|---|
$display(fmt, ...) | 打印一行文本,类似 printf | 在 posedge 触发时打印的是旧值(见第三节) |
$monitor(fmt, ...) | 括号内任何信号变化就自动打印一行 | 全程打印,长仿真刷屏;入门后用 $display 定点打印更实用 |
$time | 返回当前仿真时间(整数,按 timescale 精度) | 想带小数要用 $realtime |
$dumpfile("名.vcd") | 指定 VCD 输出文件名 | 必须在 $dumpvars 之前调用,否则写入默认名 |
$dumpvars(深度, 模块) | 开始导出波形,深度 0 = 全部层级 | 忘了调用就不会有 VCD,仿真静默跑完 |
$finish | 结束仿真 | TB 没有 $finish 时仿真永不退出 |
另一个值得在入门第一天就建立的直觉:DUT 里用的是非阻塞赋值 <=(描述时序逻辑的惯例),TB 激励里用的是阻塞赋值 =(按顺序一行行执行,符合激励的书写直觉)。两套符号混用是仿真结果「差一拍」玄学问题的主要来源——入门规则就一条:时序逻辑(带时钟沿的 always 块)里用 <=,组合逻辑和 TB 激励里用 =。
三、真实运行:iverilog 编译,vvp 运行
Makefile 里 make run 实际只做两件事:
iverilog -g2012 -o out/counter_sim.vvp counter.v counter_tb.v
vvp out/counter_sim.vvp | tee out/sim.log分工要记牢:iverilog 是编译器,把 Verilog 源码编译成一种中间可执行格式(.vvp 文件);vvp 是运行时,解释执行这个文件,推进仿真时间、执行 $display 和 $dumpvars。这和 GCC + 可执行文件的关系一模一样,只不过「可执行文件」跑的是虚拟的硬件时间。
源文件多了以后,把一长串文件名堆在命令行上既难看又容易漏,iverilog 支持文件清单:把每行一个文件名写进 files.f,用 iverilog -f files.f 读入。本篇只有两个文件用不上,但你要知道这个开关存在——等到自己的项目涨到几十个源文件,第一天就该建这个清单,和 Makefile 一起进版本库。
真实运行输出(完整版在实验目录 out/sim.log):
VCD info: dumpfile out/counter.vcd opened for output.
[5000 ns] clk posedge: rst_n=0 en=0 count=x
[12000 ns] release reset, count=0
[15000 ns] clk posedge: rst_n=1 en=1 count=0
[25000 ns] clk posedge: rst_n=1 en=1 count=1
...
[155000 ns] clk posedge: rst_n=1 en=1 count=14
[165000 ns] clk posedge: rst_n=1 en=1 count=15
[175000 ns] clk posedge: rst_n=1 en=1 count=0
...
[236000 ns] paused 3 clocks, count=4 (should hold)
[286000 ns] after 5 more clocks, count=9 (wrap check)
[286000 ns] TEST PASS: counter works as expected
counter_tb.v:51: $finish called at 286000 (1ps)逐段解读这份日志:
count=x:t=0 时count这个 reg 从没被赋过值,仿真器用x(未知态)表示。这正是必须复位的直观证据——5ns 处第一个时钟沿把复位值 0 打进去,x消失。- 15 → 15:t=15ns 释放复位后第一个时钟沿,
$display打印的仍是 0。不是没计数——always @(posedge clk)块和 DUT 的 always 块在同一时刻执行,$display采样到的是沿到来之前的旧值。这是 Verilog 仿真语义里最容易绊倒新人的点,波形图(下一节)会看得更清楚。 - 15 之后回绕:165ns 处
count=15,175ns 处变回 0——4 位寄存器加到 15 再加 1 自然回绕,符合预期。 - 暂停段:236ns 附近
en=0,连续三个时钟沿 count 都停在 4,验证了使能保持逻辑。 $finish called at 286000 (1ps):仿真在 286ns 正常结束。注意括号里的(1ps)——它来自 timescale 的精度声明。
整个运行从编译到结束不到一秒。iverilog 的编译选项常用就这几个:
| 选项 | 作用 | 本篇是否用到 |
|---|---|---|
-g2012 | 按 SystemVerilog-2012 方言编译(-g2005 等可选) | 是,习惯性加上 |
-o <file> | 指定输出文件名(默认 a.out) | 是 |
-Wall | 打开所有 warning | 报错实验用到 |
-I <dir> | 头文件 `include 搜索路径 | 本篇无 include |
-D <宏> | 命令行定义宏 | 未用 |
-s <模块> | 指定顶层模块(多顶层时消歧) | 未用 |
四、产物解读:VCD 文件和它的波形
$dumpvars(0, counter_tb) 里第一个参数是层级深度:0 表示「从 counter_tb 往下所有层级全部导出」;写 1 则只导 counter_tb 本层、不导 dut 内部。打开真实的 out/counter.vcd,开头是声明段:
$timescale 1ps $end
$scope module counter_tb $end
$var wire 4 ! count [3:0] $end
$var reg 1 " clk $end
$var reg 1 # en $end
$var reg 1 $ rst_n $end
$scope module dut $end
...VCD 不给每个信号存全名,而是发一个短代号(!、"、#、$),后面的值段只记「时刻 + 代号 + 新值」。这就是为什么几十 MB 的仿真也能压成很小的文本文件。值段长这样(真实摘录):
#12000
1#
1$
#15000
b1 !
b1 %
1"读法:#12000 表示时间推进到 12000ps(=12ns),此刻 1#(en 变 1)、1$(rst_n 变 1);#15000 时 b1 !(count 变二进制 1)、1"(clk 变 1)——注意 count 的新值和时钟沿出现在同一时刻,这正是上一节 $display 打印旧值的根源:$display 在 posedge 触发时先执行,非阻塞赋值的新值在随后的 NBA 区域才生效,而 VCD 记录的是所有更新落定之后的最终状态。
把 VCD 前 30ns 的跳变逐拍翻译成波形图,复位与第一次计数一目了然:
对照真实 VCD 逐个沿解读:0–5ns count 是 x(VCD 第 0 时刻 bx %);5ns 第一个时钟沿把复位值 0 打进去(VCD #5000 b0 !);12ns rst_n 与 en 同时拉高(VCD #12000 1# 1$);15ns 时钟沿后 count 变 1、25ns 变 2——每个沿都和上面的 VCD 文本一一对应。
把视野拉到整个使能计数段(15–125ns),能看到 4 位计数器完整的递增序列:
时钟每 10ns 一个周期,count 在每个上升沿之后更新一次:15ns→1、25ns→2……115ns→11,与 VCD 里 #15000 b1、#25000 b10……#115000 b1011 完全吻合。真正调试时你不会手翻 VCD——GTKWave、Surfer 这类波形查看器直接图形化打开它,本系列后续的 iverilog VCD 波形篇 会专门讲 $dumpvars 的层级控制和波形工具对比;本篇只要记住:VCD 是文本、按「时刻+变化」记账、可以被任何波形工具打开。
最后把整条流水线画成一张图,这也是你以后用任何仿真器都不会变的骨架:
源码两份(DUT + TB)一起进 iverilog,产出一个 .vvp;vvp 执行它,分两路出产物:控制台日志给人眼看,VCD 给波形工具看。后续 Verilator、cocotb 篇里这个骨架只会换零件、不会换形状。
「时钟沿和 count 更新出现在同一时刻」这件事,背后是 Verilog 仿真器的事件调度模型,值得展开十行。仿真器把每个时间槽切成若干「区域」,入门阶段只需要记住两个:Active 区域执行普通过程块($display 在这里跑),NBA(Non-Blocking Assignment,非阻塞赋值)区域才把所有 <= 的右值真正写入寄存器。所以同一个上升沿时刻:TB 的 $display 先在 Active 区域打印 count 的旧值,DUT 的 count <= count + 1 随后在 NBA 区域更新,VCD 则等全部更新落定后记录最终值。串起来就是:15ns 处日志打 0,VCD 记 1——两者都没错,只是采样窗口不同。
五、常见报错排查
下面三类报错都是本次在容器里真实触发、日志存于实验目录 out/errors.log 的,附处置方法:
先看一份真实报错现场长什么样(节选 out/errors.log):
=== E1: 只编译 TB,漏掉 DUT ===
counter_tb.v:13: error: Unknown module type: counter
2 error(s) during elaboration.
*** These modules were missing:
counter referenced 1 times.
***
exit=2注意这条报错的措辞是「Unknown module type」而不是「syntax error」——iverilog 能顺利把 counter_tb.v 解析完,是在 elaboration(详细描述,把例化关系连成实例树)阶段才发现找不到 counter 这个模块定义。它还贴心地列出「referenced 1 times」告诉你被引用了几次。看到 during elaboration 这个关键词,排查方向就锁定在「模块名拼写 / 漏传源文件 / 库路径」三选一,不用去翻语法。
| 真实报错 | 触发方式 | 原因 | 处置 |
|---|---|---|---|
counter_tb.v:13: error: Unknown module type: counter | 只编译了 TB:iverilog -o x.vvp counter_tb.v | 漏传 DUT 源文件,elaboration 阶段找不到被例化模块 | 把所有源文件一起传给 iverilog;文件多时写文件清单(-f files.f) |
/tmp/bad.v:3: syntax error + Syntax error in variable list | reg a 行尾少分号 | 语法错误,报错行号指向解析器发现问题的位置,不一定是有问题的行本身 | 从报错行往上几行找;少分号、少 end、括号不配平占这类错误的九成 |
warning: Port 3 (en) of counter expects 1 bits, got 32. Pruning 31 high bits | TB 里把 en 声明成了 32 位 | 端口位宽不匹配,iverilog 截断高位放行 | warning 不等于没事——连接错宽度的信号是功能 bug 温床,改对齐位宽 |
养成两个习惯能避开大部分入门坑:一是编译默认加 -Wall,iverilog 的 warning 大多真有所指;二是 make 里把编译和运行分成两个目标,报错时能一眼分清是编译期问题(语法/连接)还是仿真期问题(逻辑/时序)。
六、动手建议:在这个实验上做三个小改动
入门知识真正变成肌肉记忆靠的是改代码而不是读文档。这份实验留了三个台阶,按顺序做:
- 改位宽:把
counter.v里[3:0]改成[7:0],重跑make run,观察回绕点从 15→0 挪到 255→0,VCD 里b值串变长。体会「位宽只是声明,仿真器不嫌大」。 - 改深度:把
$dumpvars(0, counter_tb)改成$dumpvars(1, counter_tb),重跑后打开 VCD,会发现dut内部的count(代号%)不再被记录——层级深度参数的直观效果。 - 制造 x 传播:把 TB 里的复位段注释掉,直接
en=1开跑。日志里 count 会一直打印x——x + 1在 Verilog 里还是x。这是「不复位就仿真」的经典事故,在 RTL 里无伤大雅,到门级仿真就是噩梦。
每改一次都重跑并对比 out/sim.log 的差异,比单独读十页语法书有效。
VCD 还有个绕不开的话题:体积。它是纯文本,信号多、时间长时文件涨得飞快(百万门级设计跑几毫秒仿真,VCD 上 GB 很正常)。工业界的替代格式是 FST(GTKWave 原生)和 FSDB(Verdi 专有),都是压缩二进制。iverilog 配合 GTKWave 时可以直接在 TB 里把 $dumpfile 的后缀写成 .fst、配合 fst 版 vvp 输出压缩格式——不过入门阶段 VCD 的「文本可读、可 grep、可脚本处理」反而是优点:本篇第四节那种逐行对照跳变的读法,只有在文本格式上才做得这么直白。等你的设计大到 VCD 打开都卡的时候,自然会去换格式。
这一篇在知识体系里的位置
本篇是 eda-lab 仿真线的地基:同一套「编译→运行→波形」骨架会在后续篇目里反复出现。下一步推荐阅读:
- iverilog VCD 波形篇:
$dumpvars层级粒度控制、VCD 瘦身实测; - iverilog 常见报错篇:把本篇第五节的报错池扩大到语法/连接/未声明四大类;
- 商用仿真流程的概念对照见 EDA 专区 仿真相关篇目;计数器这类时序逻辑的底层概念可回看 concepts 专区 的时钟与寄存器相关文章。
总结
iverilog 仿真入门就三步:iverilog 把 DUT 和 testbench 一起编成 .vvp,vvp 运行它并用 $display 打印过程、$dumpvars 把信号变化记成 VCD 文本波形,读懂 VCD 的「时刻+变化」记账法,你就拿到了调试一切数字电路仿真的通用钥匙。