FPGA 与数字 IC 设计 / 系统课时

用 Verilator 跑通首个同步模块

用 Verilator 跑通首个同步模块

用一个带低有效异步复位和计数使能的 4 位计数器,串起 RTL 编写、SystemVerilog 测试平台、Verilator 仿真和 VCD 波形检查。完成后应得到明确的 PASS 结果、退出码 0,以及复位、计数和保持三个阶段正确对齐的信号波形。

学习目标

  • 编写可综合的同步计数器,并区分设计模块与仿真测试平台的职责。
  • 使用 Verilator 编译和运行带时钟、复位、自动检查的 SystemVerilog 测试平台。
  • 通过仿真退出状态和 VCD 波形验证周期行为,定位常见测试错误。

检查工具并准备工程

本例适用于 Verilator 5.x,使用 Linux 或 macOS 命令行环境。需要安装 Verilator、GNU Make 和受支持的 C++ 编译器;建议使用 GCC 10 或更新版本,或支持协程的 Clang。GTKWave 用于查看波形,不参与 RTL 编译。

先检查工具版本:

bash
verilator --version
make --version
c++ --version

预期结果:分别显示 Verilator、Make 和 C++ 编译器的版本信息。Verilator 应为 5.x,版本号与安装路径因环境而异。如果提示 command not found,应先按照操作系统的安装方式补齐工具。

在空目录 rtl-counter-demo 中准备两个文件:

  • counter.sv:可综合的 RTL 设计,不包含仿真时间延迟和打印逻辑。
  • tb_counter.sv:测试平台,负责产生时钟、驱动输入、检查输出并结束仿真。

后续编译命令均在该目录执行。Verilator 默认把生成的 C++ 源码、Makefile 和可执行文件放在 obj_dir 中,不需要手动编写 C++ 仿真入口。

编写可综合的同步计数器

计数器采用以下接口契约:clk 为上升沿有效时钟,rst_n 为低有效异步复位,en 为计数使能,count 为 4 位无符号输出。

当 rst_n=0 时,计数器清零;复位释放后,每个时钟上升沿检查 en。使能为 1 时计数加 1,否则保持原值。4 位计数器从 15 再加 1 时自然回绕到 0。

创建 counter.sv:

systemverilog
`timescale 1ns/1ps
module counter (
    input  logic       clk,
    input  logic       rst_n,
    input  logic       en,
    output logic [3:0] count
);
    // 异步复位立即清零,正常计数仅在时钟上升沿发生
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n)
            count <= 4'd0;
        else if (en)
            count <= count + 4'd1;
    end
endmodule

这里使用 always_ff 明确描述寄存器行为,使用非阻塞赋值 <= 更新时序状态。没有单独编写 else 保持分支,因为触发时未赋新值的寄存器自然保持原值。

该 RTL 不包含 # 延迟、$display 或 $finish,适合后续综合。文件中的 timescale 声明统一了时间单位,但并不让计数器产生实际的硬件延迟。

搭建带自动断言的测试平台

测试需要覆盖三个阶段:复位清零、连续三个周期计数、关闭使能后保持两个周期。时钟周期设置为 10 ns,高低电平各持续 5 ns。

测试平台在时钟下降沿切换输入和检查结果,避开设计寄存器在上升沿使用非阻塞赋值更新时产生的仿真调度竞争。

创建 tb_counter.sv:

systemverilog
`timescale 1ns/1ps
module tb_counter;
    logic clk = 1'b0;
    logic rst_n = 1'b0;
    logic en = 1'b0;
    logic [3:0] count;

    counter dut (
        .clk(clk),
        .rst_n(rst_n),
        .en(en),
        .count(count)
    );

    // 10 ns 周期,5 ns 翻转一次
    always #5 clk = ~clk;

    initial begin
        $dumpfile("wave.vcd");
        $dumpvars(0, tb_counter);

        // 保持复位两个完整周期,并在下降沿检查
        repeat (2) @(negedge clk);
        if (count !== 4'd0)
            $fatal(1, "reset check failed");

        rst_n = 1'b1;
        en = 1'b1;
        repeat (3) @(negedge clk);
        if (count !== 4'd3)
            $fatal(1, "count check failed: %0d", count);

        // 关闭使能后,输出必须保持两个周期
        en = 1'b0;
        repeat (2) @(negedge clk);
        if (count !== 4'd3)
            $fatal(1, "hold check failed");

        $display("PASS reset=0, count=3, hold=3");
        $finish;
    end
endmodule

测试平台里的 dut 是被测设计实例。$dumpfile 指定 VCD 文件名,$dumpvars 指定记录的信号层级。$fatal(1, ...) 会在检查失败时终止仿真并产生非零退出状态;全部通过后才打印 PASS 并执行 $finish。

这里没有直接在 @(posedge clk) 后读取 count,因为该时刻非阻塞赋值可能尚未完成更新。下降沿检查意味着已经经过前一个上升沿的寄存器更新,结果更容易预测。

编译运行并检查退出状态

Verilator 的 --binary 模式会生成 C++ 仿真代码、调用构建工具并得到可执行程序。使用 --top-module 明确选择测试平台作为顶层,而不是把计数器本身作为仿真入口。

在包含两个源文件的目录执行:

bash
set -e
verilator --binary --timing --trace-vcd -Wall --top-module tb_counter counter.sv tb_counter.sv
./obj_dir/Vtb_counter
test -s wave.vcd
echo "exit=0; wave.vcd OK"

预期输出(省略 C++ 编译日志和仿真器自动生成的 $finish 提示):

text
PASS reset=0, count=3, hold=3
exit=0; wave.vcd OK

set -e 使终端在命令返回非零状态时停止继续执行。因此,只有编译、仿真和 VCD 文件检查全部成功,才会打印最后一行。test -s 用于确认波形文件存在且非空。

命令中的主要选项分别承担以下职责:

选项 作用
--binary 生成并构建可执行仿真程序
--timing 支持测试平台的 #5 延迟和事件等待;在当前版本中也是 --binary 隐含启用的能力
--trace-vcd 编译 VCD 波形记录支持
-Wall 启用更完整的 RTL 静态检查警告
--top-module tb_counter 指定仿真顶层模块

仿真成功不能仅以生成 obj_dir 为依据。完整验收需要同时检查编译成功、测试平台输出 PASS、程序退出码为 0,以及 VCD 文件实际生成。

用波形核对每个时钟周期

安装 GTKWave 后,在同一目录打开波形:

bash
gtkwave wave.vcd

预期结果:打开 GTKWave 波形查看窗口,载入 wave.vcd,不会在终端产生固定格式的 PASS 输出。

在信号层级中找到 tb_counter,把 clk、rst_n、en、count 加入波形显示区域,并按相同时间轴观察。对于 count,可以将数据显示进制设置为十进制。

本例应满足以下时间关系:

仿真时刻 输入变化或时钟事件 预期 count
5、15 ns 上升沿,复位有效 0
20 ns 释放复位,使能置 1 0
25 ns 第一个有效计数上升沿 1
35 ns 第二个有效计数上升沿 2
45 ns 第三个有效计数上升沿 3
50 ns 关闭使能 3
55、65 ns 上升沿,使能为 0 3
70 ns 检查通过,结束仿真 3

四位同步计数器在复位计数和保持阶段的信号对齐时序图

波形中最值得检查的是 en 与 count 的对应关系:20 ns 时使能打开,但计数不会立即改变,而是在 25 ns 的下一个上升沿更新;50 ns 时使能关闭,后续上升沿也不再改变计数。

这些现象与同步 RTL 的周期契约一致:输入可以在时钟边沿之间变化,寄存器在指定的有效边沿采样输入并更新状态。

验证失败时能否正确报错

自动化测试不仅要证明正确实现会通过,也要确保错误结果不会被误判为成功。可以做一次故意失败的测试。

  1. 在 tb_counter.sv 中找到计数完成后的检查语句 if (count !== 4'd3)。
  2. 仅把这一处预期值临时改为 4'd4,其他代码保持不变。
  3. 重新执行上一节的 Verilator 编译命令,再运行生成的 Vtb_counter。
  4. 确认仿真报告 count check failed,并且程序以非零状态退出。
  5. 把检查值恢复为 4'd3,重新编译执行,确认 PASS 和退出码 0。

如果编译失败,先查看 -Wall 报出的具体文件与行号,检查端口名称、信号宽度和源文件列表。如果提示找不到 Vtb_counter,检查构建是否成功,以及 --top-module 是否正确。

如果仿真成功却没有波形,检查是否启用了 --trace-vcd、测试平台是否执行了 $dumpfile 和 $dumpvars,并确认在正确的工作目录查找 wave.vcd。

如果计数检查差一个周期,优先检查使能变化发生在哪个边沿、检查代码的事件等待位置,以及是否在非阻塞赋值生效前过早读取输出。不要通过随意增加延迟掩盖错误,而应让测试输入和结果采样遵循明确的周期边界。

最终可交付的最小工程由两个 SystemVerilog 源文件组成,能够通过一条 Verilator 编译命令重建仿真,并同时提供自动检查结果与可人工核对的波形。退出码负责标识测试是否失败,波形负责解释为什么通过或失败;两种检查应当同时保留。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Verilator 跑通首个同步模块

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通