Gracefully Ending a VHDL Testbench Simulation

When a VHDL testbench reaches the end of its intended execution, you’ll want the simulator to halt cleanly and, if possible, return control to any calling script. This article reviews the most common and reliable techniques for stopping a simulation across major VHDL simulators, with code examples for ModelSim, Vivado, and Tcl scripts.

1. Using the finish Procedure (VHDL‑2008)

The finish routine from the std.env package is the most straightforward way to end a testbench that has completed without errors. Compile only the testbench in VHDL‑2008; the RTL can remain in an earlier standard.

use std.env.finish;
...
SEQUENCER_PROC : process
begin
  -- Insert testbench logic here
  wait until stop_condition;
  report "Calling 'finish'";
  finish;
end process;

By default, finish will prompt the GUI to confirm termination. If you prefer automatic exit—especially in batch mode—add the -onfinish stop switch to vsim:

vsim -onfinish stop work.using_finish_tb

When run in batch mode (vsim -c), the simulator exits cleanly and control returns to the shell, which is ideal for regression scripts:

jonas@ubuntu:~/stop_tb$ vsim -c -do 'vsim work.using_finish_tb; run -all'
# …
# ** Note: Calling 'finish'
#    Time: 1 ms  Iteration: 0  Instance: /using_finish_tb
# End time: 22:58:31 on Jun 21,2020, Elapsed time: 0:00:00
# Errors: 0, Warnings: 8
jonas@ubuntu:~/stop_tb$

Two overloads exist: procedure FINISH; and procedure FINISH (STATUS : INTEGER);. The status value is simulator‑dependent, so relying on it for exit codes is discouraged. In ModelSim you can explicitly set the shell exit code with exit -code <value> in a Tcl script.

2. Using the stop Procedure (VHDL‑2008)

The stop routine pauses the simulation—useful for manual inspection or resuming later. It behaves like a breakpoint.

use std.env.stop;
...
SEQUENCER_PROC : process
begin
  wait until stop_condition;
  report "Calling 'stop'";
  stop;
end process;

In a script‑driven workflow, stop will drop you into a Tcl shell, so the script will hang unless you issue exit manually. This is why finish is generally preferred for automated runs.

3. Leveraging an Assertion Failure

Some designers terminate a testbench by deliberately causing an assertion failure. This method works in all VHDL versions and requires no extra imports:

SEQUENCER_PROC : process
begin
  wait until stop_condition;
  assert false report "Test: OK" severity failure;
end process;

While it guarantees simulator termination, the console will report a failure even though the test succeeded, which can be misleading in automated regression tools that treat failures as errors.

4. Controlling Termination with Tcl Callbacks

For more flexible control—such as inspecting signals or performing cleanup—you can tie a VHDL signal to a Tcl callback. The VHDL testbench signals a boolean stop_condition when all test cases finish.

signal stop_condition : boolean;

begin
  -- Example: toggle after 1 ms
  stop_condition <= not stop_condition after 1 ms;
  SEQUENCER_PROC : process
  begin
    -- testbench logic
    wait;  -- keep the process dormant
  end process;

ModelSim

when {stop_condition} {
  stop
  echo "Test: OK"
}
run -all

When stop_condition becomes true, the callback runs, prints a message, and pauses the simulation. You can replace stop with exit to quit the simulator immediately.

Vivado

set sim_fileset sim_1
launch_simulation -simset [get_filesets $sim_fileset]
add_condition -notrace stop_condition {
    stop
    puts "Test: OK"
}
run all

The -notrace flag suppresses command echoing, keeping the console output clean.

Final Recommendation

Across all major simulators, the VHDL‑2008 finish procedure remains the most portable and script‑friendly choice. It cleanly terminates the simulation in both GUI and batch environments without lingering interactive prompts.

Nevertheless, Tcl callbacks offer powerful debugging capabilities when you need to pause the simulation and inspect or manipulate signals on the fly.

Download Example Projects

ModelSim users can receive a zip archive containing four illustrative testbenches by submitting their email address below. (Vivado users can replicate the examples with minimal effort.)