OSVVM Scripting: One Script to Run them All

I don’t know about you, but I am tired of having to learn a new set of switches and methods to do the same tasks I already know how to do in another simulator.

What I want is one script to rule run them all.

To implement this, OSVVM has created a TCL based API layer that provides a tool independent means to simulate (and perhaps in the future synthesize) your design. The API uses TCL procedures to create the abstraction layers – which is why they have the extension .pro. The scripts are executable TCL, so the full power of TCL can be used when needed (such as is in osvvm.pro).

OSVVM Scripting Roots

Like many other approaches, we started with a list. The list evolved into a file of commands so we could specify library name, file to compile, and design to simulate. To get tool independence, we used variables. Unfortunately the number of variables and variations grew until it became overwhelming and lacked capability.

So we refactored and recoded the commands as TCL procedures. Each command has two layers. The outer API layer implements the command names (such as library, analyze, and simulate) and handles common tasks. The inner layer personalizes the operations for each vendor.

This two layer approach to scripting is necessary as how Aldec’s Riviera-PRO does libraries and how Synopsys’ VCS does libraries is wildly different and would be a challenge to do with only variables. With the additional procedure layer, practically anything is possible – especially with dynamic languages like TCL. We use TCL because many of the simulators run TCL natively. TCL is also easy to run in a Linux environment using tclsh.

We have a team in our community that are working on a Python version of the scripts. So if you prefer Python, that is coming.

Basic Scripts

At the heart of running a simulation is setting the library, compiling files, and starting the simulation. To do this, we use library, analyze, and simulate. The following is an excerpt from the scripts used to run OSVVM verification component library regressions.

library osvvm_TbAxi4_MultipleMemory
analyze TestCtrl_e.vhd
analyze TbAxi4_MultipleMemory.vhd
analyze TbAxi4_Shared1.vhd
simulate TbAxi4_Shared1


In OSVVM scripting, calling library activates the library. Hence, there is no need to specify the library in analyze and simulate. This is consistent with VHDL’s sense of the “working library”.

Some of the scripts support additional capability. For example when we run simulate in the above script on Aldec’s Riviera-PRO simulator, simulate will automatically run the scripts Aldec.tcl, RivieraPRO.tcl, TbAxi4_Shared1.tcl, and wave.do if they exist.

OSVVM’s scripting methodology runs in GHDL, Aldec’s Riviera-PRO and Active-HDL, Siemen’s ModelSim and QuestaSim, Synopsys’ VCS and Cadence’s Xcelium. Xilinx XSIM is currently a work in progress.

OSVVM uses this scripting methodology to facilitate running regressions on all of these simulators – with just one set of scripts.

Creating layers of scripts

In TCL, source (or with EDA tools do) is used to run lower level scripts. For an EDA tool, there are two directories of interest, the directory the tool is running in and the script directory. EDA tool settings are directory dependent, so the script cannot change directories. This forces the script to manage the location of the files referenced in the script. This makes for awkward scripting.

To address this situation, OSVVM adds include. Include manages both the run directory and the script directory. All calls to the OSVVM script API that reference a file, reference the file relative to the current script directory – rather than the run directory. Hence, a script only needs to reference files relative to its location, making path references simple. It also simplifies directory structure changes to a project.

The script, OsvvmLibraries.pro shown below, is the starting point for compiling all of OSVVM. It simply calls the scripts from the OSVVM Utility library, Verification Component Common library, UART verification component library, and AXI4 verification component libraries using include.

include ./osvvm/osvvm.pro
include ./Common/Common.pro
include ./UART/UART.pro
include ./AXI4/AXI4.pro


OSVVM also adds build. Build is a layer on top of include (it calls include) that creates a logging point. For each build, OSVVM creates collects all tool output into a log file for the entire build in ./logs/<tool_name>-<version>/<build>.log.  In 2021.09 and 2021.10 (to be released shortly) we add to that YAML, HTML, and JUnit XML reporting. I will talk about that shortly in a post about the 2021.10 release.

In general, build is called from the simulator API (when we run something) and include is called from scripts.

To compile all of the OSVVM libraries, use build as shown below. Since this is a build, it will create a corresponding log file in the logs directory.
build <path_to_OsvvmLibraries>/OsvvmLibraries.pro

Getting Started Running OSVVM Scripts and OSVVM Regressions

Get OSVVM

You can get OSVVM by either downloading from osvvm.org or cloning the repository using git:
git clone --recursive https://github.com/osvvm/OsvvmLibraries

Start Up the OSVVM Scripts

For Aldec’s Riviera-PRO and Siemen’s ModelSim/QuestaSim do
source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
For Aldec’s Active-HDL do
scripterconf -tcl
source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
For GHDL (running in MSYS2) do
winpty tclsh
source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
For Synopsys’ VCS do
rlwrap tclsh
source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartVCS.tcl
For Cadence’s Xcelium do (this is a work in progress)
rlwrap tclsh
source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartXcelium.tcl


Compile OSVVM

build <path_to_OsvvmLibraries>/OsvvmLibraries.pro

Run OSVVM’s Verification Component Regression Suite

build <path_to_OsvvmLibraries>/RunAllTests.pro

Scripting is a Work In Progress

We are continually improving our scripting. Over the next several releases, we have plans to add:
• Comprehensive Test Reporting in HTML and JUnit XML (in 2021.10)
• Activating code coverage collection (in a simulator independent manner)
• Create simulation levels: Batch, Interactive, Debug to manage what information to keep

Interested in helping out? Join us.

2 Comments

1. 

   JJ April 15, 2022, 00:50 Log in to Reply

   Hi, I installed and am currently running OSVVM on my project, I have to say its been a great experience, I normally write my test benches in system verilog but we write mostly vhdl so i stumbled upon osvvm and like it alot, soo much I would like to extend the capability to synthesis. If i get it working correctly, I would like to contribute to the project if allowed to…

2. 

   Jim Lewis April 15, 2022, 03:10 Log in to Reply

   Hi JJ,
   Contributions are welcome.
   Best Regards,
   Jim