Build structured VHDL verification with OSVVM

Problem and objective

An initial self-checking testbench can report results through individual assertions. As tests and reusable components accumulate, consistent error counting, reporting and build scripts become more important. This note introduces OSVVM using a small counter. It separates VHDL checking logic from tool startup and shows a documented entry point for Riviera-PRO. The limited scope makes result management visible without requiring a complex bus architecture.

Prerequisites and version contract

You need VHDL-2008 knowledge, a suitable simulator and a fully prepared OSVVM revision. The documented Aldec workflow requires a legitimately usable Riviera-PRO installation. The vendor and OSVVM describe corresponding integration paths; the project must confirm its particular combination of simulator version, OSVVM revision and licence. This note neither activates an evaluation nor assumes free commercial simulator use.

The actual free-tool comparison used the OSVVM utility library tagged 2026.09, commit 716d751566b4fb6479f69c38cc01790744c911b7. GHDL 6.0.0 on Windows analysed the VHDL-2008 selection of that library and executed the original test. The OSVVM downloads page and official repository establish the version context. A complete Riviera-PRO Tcl run was not performed. OSVVM downloads and releases; OSVVM: OsvvmLibraries.

Architecture and responsibilities

The DUT remains the four-bit counter from the VHDL testbench note. The new testbench generates stimuli and calls OSVVM affirmations to compare actual and expected results. Test completion generates a summary report. The project script assigns sources to a library and starts the test. This division prevents checking intent, library setup and result evaluation from becoming mixed in an opaque script.

examples/
  counter/rtl/counter.vhd      # unverändertes DUT
  osvvm/tb_counter_osvvm.vhd  # eigener OSVVM-Test
  osvvm/counter.pro           # Projektbeschreibung
  sim-riviera/               # getrennte erzeugte Arbeitsdaten

OSVVM-Installation außerhalb der eigenen Quellen:
  OsvvmLibraries/            # geprüfter Stand mitsamt Submodulen

Keep the OSVVM revision in use unchanged. An unplanned update during debugging can change results and make comparison harder. For the complete OsvvmLibraries project, submodules must also match the selected revision. The utility commit alone does not identify every verification component and script. A team should therefore record the parent project’s revision and its submodules together.

Step 1: Prepare the OSVVM revision

Follow the official OsvvmLibraries instructions and select an approved release. The repository points to libraries, scripts and documentation. After obtaining it, check that subdirectories containing required components are actually populated. The presence of the main directory alone is insufficient for a project using submodules. Keep the original DUT versioned independently in your own project directory.

Create a separate working directory before the first simulator run. This distinguishes generated libraries and results from their inputs. For the Tcl entry point below, the OSVVM_HOME environment variable contains the actual absolute path to OsvvmLibraries. Set it locally; no installation path is invented here. Verify the directory in the terminal or simulator environment before starting.

Step 2: Initialise the scripting environment in Riviera-PRO

# In der Tcl-Konsole von Riviera-PRO ausführen.
if {![info exists ::env(OSVVM_HOME)]} {
    error "OSVVM_HOME muss auf die lokale Installation zeigen"
}
set osvvmRoot [file normalize $::env(OSVVM_HOME)]
source [file join $osvvmRoot Scripts StartUp.tcl]
build $osvvmRoot
# Anschließend aus examples/sim-riviera:
build ../osvvm/counter.pro

OSVVM documents initialisation through StartUp.tcl for Riviera-PRO. For Active-HDL, the project describes a different entry point with the Tcl scripting environment enabled. Product names are therefore not interchangeable command parameters. When transferring the workflow, follow the current instructions for the appropriate adapter and avoid simultaneously active older script revisions on the search path. OSVVM simulation scripts.

The first build prepares the selected library revision; the second processes your project. A failed library build must be resolved first. Retrying with a mixture of partly available old libraries can create a misleading impression of success. Record the first clean build and repeat it in a new output directory after a substantial version change.

Step 3: An original testbench with affirmations

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
library osvvm;
context osvvm.OsvvmContext;

entity tb_counter_osvvm is
  generic (INJECT_FAILURE : boolean := false);
end entity;

architecture test of tb_counter_osvvm is
  signal clk : std_logic := '0';
  signal rst : std_logic := '1';
  signal enable : std_logic := '0';
  signal q : unsigned(3 downto 0);
begin
  clk <= not clk after 5 ns;
  dut : entity work.counter(rtl) port map (clk, rst, enable, q);

  stimulus : process
    procedure step(r, e : std_logic; expected : natural) is
    begin
      wait until falling_edge(clk);
      rst <= r;
      enable <= e;
      wait until rising_edge(clk);
      wait for 1 ns;
      AffirmIfEqual(std_logic_vector(q),
        std_logic_vector(to_unsigned(expected, q'length)), "Zaehlerwert");
    end procedure;
  begin
    SetAlertLogName("eda_counter");
    step('1', '0', 0);
    for n in 1 to 20 loop
      step('0', '1', n mod 16);
    end loop;
    step('0', '0', 4);
    step('1', '1', 0);
    AffirmIf(not INJECT_FAILURE, "Negativtest darf im Normallauf nicht aktiv sein");
    -- Funktionsvariante liefert die Fehleranzahl als Abschlussstatus.
    std.env.stop(EndOfTestReports);
    wait;
  end process;

  watchdog : process
  begin
    wait for 2 us;
    Alert("Watchdog: Test nicht rechtzeitig beendet", FAILURE);
    std.env.stop(EndOfTestReports);
    wait;
  end process;
end architecture;

The step procedure follows the simple example: inputs change at the falling edge and comparison occurs after the rising edge. AffirmIfEqual manages the comparison result count. SetAlertLogName gives the test a readable name, which becomes useful when output from several test cases is combined. The calls used were checked against the official package declarations. OSVVM AlertLogPkg source.

Test completion deliberately uses the function form of EndOfTestReports. Its return value is passed to std.env.stop. In the verified GHDL workflow, a failed affirmation then also produced a non-zero process status. In the first trial, a parameterless stop had returned exit code 0 despite a FAILED report. This observation illustrates why an informative summary and a correct machine-readable status must be tested separately. OSVVM ReportPkg source.

Step 4: Create the project file

# Vom OSVVM-build-Befehl relativ zu dieser Datei ausgewertet.
library eda_counter
analyze ../counter/rtl/counter.vhd
analyze tb_counter_osvvm.vhd
TestName counter_basic
simulate tb_counter_osvvm

The counter.pro file sits alongside the OSVVM testbench. In the OSVVM project workflow, relative source paths are resolved against the corresponding project file. The library name eda_counter separates this example from other designs. The testbench reference work.counter then denotes the library into which the testbench itself is analysed. A differently named physical simulator directory does not alter that logical meaning.

Step 5: Evaluate results and the negative test

The actual positive GHDL test reported 24 affirmations checked, 24 passed at 236 ns and returned exit code 0. The negative run with INJECT_FAILURE=true reported one failed check, 23 passed affirmations and exit code 1. These figures describe our small test in the stated free-tool environment. They are neither Aldec output nor evidence about the complete OSVVM test suite.

The same positive and negative cases still need to run in the Riviera project. Check the result report, test completion and propagation of the status to a parent batch process. A working graphical simulation does not yet establish how its calling process exits. An automated run also needs an external time limit: a simulation-time watchdog cannot protect against every infinite loop that makes no time progress.

Troubleshooting and extensions

If osvvm.OsvvmContext cannot be found, check library setup and mapping. Missing package functions often indicate mixed revisions. A report containing no executed checks is not a successful test. Verify that the stimulus process actually runs and reaches the expected affirmations. For a timeout, investigate the clock and waiting conditions before increasing the limit.

The example deliberately uses neither random stimuli nor functional coverage. These capabilities can be added once requirements and observation points are clear. A protocol test may then benefit from separating driver, monitor and reference model. Record the seed alongside the result. Coverage should capture situations of specific interest and must not be mistaken for proof of correctness.

Actual test status and next step

Executed: an original VHDL test against OSVVM Utility 2026.09 using GHDL 6.0.0, including positive and negative cases. Not executed: the Riviera-PRO or Active-HDL adapter, a complete OsvvmLibraries build, Aldec reports and licence operation. The related vendor steps are described using the documentation; their execution in an Aldec environment has not been demonstrated.

As a next step, transfer a small existing module test into the same structure. The article on OSVVM, VUnit and UVM provides context; the regression note demonstrates a complementary approach to automated result evaluation.

Sources and date

Research checked on 19 October 2026. OSVVM: OsvvmLibraries, OSVVM simulation scripts, OSVVM downloads and releases, OSVVM AlertLogPkg source, OSVVM ReportPkg source, GHDL simulation runtime options.