Writing Scripts

OSVVM scripts are Tcl files named <script-name>.pro, augmented by the OSVVM commands. The examples below come from the scripts of OSVVM’s own verification components.

Running a Simple Test

Running a simulation means: select the library, analyze the files, start the simulation.

library activates a library, like VHDL’s working library. Every following analyze and simulate uses it.
analyze compiles a file. The extension selects the language: *.vhd and *.vhdl are VHDL; *.v, *.sv and *.vh are Verilog / SystemVerilog.
TestName names the test case; simulate runs it.

The files have no paths: relative paths are relative to the directory of the script (Working Directory).

# File: testbench_MultipleMemory.pro
library  osvvm_TbAxi4_MultipleMemory
analyze  TestCtrl_e.vhd
analyze  TbAxi4_MultipleMemory.vhd
analyze  TbAxi4_Shared1.vhd
TestName TbAxi4_Shared1
simulate TbAxi4_Shared1

build ../OsvvmLibraries/AXI4/Axi4/testbench_MultipleMemory/testbench_MultipleMemory.pro

RunTest

When a test case’s file, design unit and test name are the same, RunTest does analyze, TestName and simulate in one command.

An optional second argument names the design unit to simulate, if it differs from the file name; the test case is then named <DesignUnit>(<FileName>).

# Same as: analyze TbAxi4_Shared1.vhd
#          TestName TbAxi4_Shared1
#          simulate TbAxi4_Shared1
RunTest TbAxi4_Shared1.vhd

Including Scripts

Designs are built hierarchically, and so are scripts: a script calls the scripts of its parts with include. Paths are relative to the including script; OsvvmLibraries.pro names directories in OsvvmLibraries.

include accepts a file or a name without extension. For a directory or a name without extension, it takes the first file that exists of:

<Name>.pro
build.pro (in the directory)
<Name>.tcl
<Name>.do
<Name>.dirs, <Name>.files (deprecated, see below)

*.pro and *.tcl files are sourced, *.do files are run with the simulator’s do.

# File: OsvvmLibraries.pro
include ./osvvm/osvvm.pro
include ./Common

if {[DirectoryExists UART]} {
  include ./UART
}
if {[DirectoryExists AXI4]} {
  include ./AXI4
}
if {[DirectoryExists DpRam]} {
  include ./DpRam
}

Script Arguments

Arguments after the script name of include or build are passed to the script in Tcl’s argv / argc and in the Tcl variables ARGC (number of arguments) and ARGV (an array; ARGV(0) is the script name, ARGV(1) the first argument). They are restored when the script returns.

Instead of arguments, consider Tcl procedures or variables set before the call.

include ./TestCases.pro Smoke

# File: TestCases.pro
if {$::ARGC > 0 && $::ARGV(1) eq "Smoke"} {
  RunTest TbSmoke.vhd
}

Conditions

A script is Tcl, so if selects what to run. Helper commands keep the conditions short:

DirectoryExists and FileExists test a path relative to the working directory.
The tool variables, $::osvvm::ToolName and others, select tool specific steps (see Tool Variables).

if {[FileExists TbAxi4_Optional.vhd]} {
  RunTest TbAxi4_Optional.vhd
}

if {$::osvvm::ToolName eq "GHDL"} {
  SkipTest TbAxi4_Verilog.vhd "Needs mixed-language simulation"
} else {
  RunTest TbAxi4_Verilog.vhd
}

Building the OSVVM Libraries

OsvvmLibraries.pro analyzes OSVVM’s utility library and all verification components that are present. Run it with build from the simulation directory.

The log of the build is in <BuildName>/logs/ of the simulation directory (see Build Name and Output).

build ../OsvvmLibraries/OsvvmLibraries.pro

Running OSVVM’s Test Cases

Every OSVVM verification component (VC) comes with its regression tests. RunAllTests.pro runs all tests of a VC, and since scripts are hierarchical, the one of a directory runs all tests below it.

Most VCs and OsvvmLibraries also have RunDemoTests.pro, which runs a small selection.

# AXI4 Full
build ../OsvvmLibraries/AXI4/Axi4/RunAllTests.pro

# AXI4 Full, AXI4 Lite and AXI Stream
build ../OsvvmLibraries/AXI4/RunAllTests.pro

# All verification components
build ../OsvvmLibraries/RunAllTests.pro

# A selection
build ../OsvvmLibraries/RunDemoTests.pro

Deprecated Descriptor Files

include still accepts descriptor files for backward compatibility; new scripts should use *.pro files.

<Name>.dirs lists directories; each is passed to include.
<Name>.files lists files; each is passed to analyze (VHDL or Verilog by extension). A line # library <Name> calls library.

Other lines starting with # and empty lines are ignored.

# File: Axi4.dirs
src
testbench