Concepts

Directories

Simulation Directory

The simulation directory is the directory in which the simulator runs. OSVVMOpen Source VHDL Verification Methodology keeps its absolute path in the variable ::osvvm::CurrentSimulationDirectory.

Simulators write library mappings and other files into this directory, and OSVVM puts its output there: the libraries (VHDL_LIBS), the build results and reports, and index.html with an overview of all builds.

Create a separate directory for simulations, for example sim or temp next to OsvvmLibraries. Cleaning up is then just deleting and recreating it.

• 📁OsvvmLibraries
• ▾▸📁simCurrentSimulationDirectory

  • ▾▸📁VHDL_LIBS

    • 📁<ToolName>-<Version>compiled libraries
  • 📁<BuildName>results of a build
  • 📄index.htmlall builds
  • 📄index.yml

Working Directory

The working directory is the directory of the script that is currently running. OSVVM keeps it in the variable ::osvvm::CurrentWorkingDirectory.

All OSVVM commands that take a path resolve a relative path against the working directory. So a script names its files relative to its own location, no matter from where it is called.

include and build set the working directory to the directory of the script they run, and restore it afterwards.

# File: OsvvmLibraries/AXI4/Axi4/src/build.pro
# The working directory is .../AXI4/Axi4/src
analyze Axi4Manager.vhd
analyze Axi4Subordinate.vhd

Don’t use Tcl’s cd

Caution

Don’t use TclTool Command Language’s cd.

cd changes the simulation directory and loses the library mappings and other information the simulator keeps there. To work relative to another directory inside a script, change the working directory with ChangeWorkingDirectory; like cd, it accepts a relative or an absolute path.

To get a path relative to the working directory, for a command or for Tcl, use JoinWorkingDirectory.

If you used cd anyway, LinkCurrentLibraries maps all libraries OSVVM knows into the new simulation directory.

ChangeWorkingDirectory src
analyze Axi4Manager.vhd

LinkLibraryDirectory [JoinWorkingDirectory RelativePath]

Don’t use Tcl’s source or a simulator’s do

Caution

Don’t use Tcl’s source or a simulator’s do to run OSVVM scripts.

include runs a script with source (or do for a *.do file), but it also sets the working directory to the script’s directory and restores it afterwards. With source or do, the script would have to manage its paths itself.

# Instead of:  source ../src/build.pro
include ../src

Builds and Includes

include runs another script. Scripts are composed hierarchically like the design: a script includes the scripts of its sub-directories.

build is include plus a logging point. It’s called from the simulator’s console (or a start-up script) to run a script and:

• starts a new log file for everything the script and the simulator print,

• collects the results of all test suites and test cases the script runs,

• creates the build reports when the script finishes (see Reports).

A build inside a running build acts like include.

# In the simulator's console:
build ../OsvvmLibraries/OsvvmLibraries.pro

# Inside a script:
include ./osvvm/osvvm.pro
include ./Common

Build Name and Output

The build name is derived from the script: <directory>_<script>, where <directory> is the name of the directory containing the script. If both names are equal, the build name is just the script name. A script can set another name with BuildName.

All results of a build go into a directory of that name in the simulation directory:

• <BuildName>.html, .xml, .yml: the build summary report (HTMLHyperText Markup Language), as JUnit XML and as YAMLYAML Ain't Markup Language;

• logs/: the log file of the build, as text and as HTML;

• reports/<TestSuite>/: one report per test case;

• results/<TestSuite>/: files the test cases write.

OpenBuildHtml opens the build summary report of the last build.

# in directory "example"
build ../RunExample.pro

• ▾▸📁example_RunExample

  • 📄example_RunExample.html
  • 📄example_RunExample.xml
  • 📄example_RunExample.yml
  • ▾▸📁logs

    • 📄example_RunExample.log
    • 📄example_RunExample_log.html
  • ▾▸📁reports

    • ▾▸📁Example

      • 📄TbExample.html
  • ▾▸📁results

    • 📁Example

Test Suites and Test Cases

A build runs test cases, grouped into test suites. The reports summarize the build per test suite and per test case.

• TestSuite starts a test suite. Test cases outside a test suite belong to the test suite Default.

• A test case is one simulation. Its name is the name of the simulated design unit, or the name set with TestName before simulate.

• The test case name must match the name the testbench sets with SetTestName (OSVVM’s SetAlertLogName). Otherwise, the test case fails, unless the setting FailOnVhdlNameNotMatchTestName is false.

• RunTest combines analyze, TestName and simulate for a file whose design unit has the same name as the file.

• SkipTest lists a test case as skipped, with a reason, in the reports.

TestSuite Axi4Full
library   osvvm_TbAxi4

analyze   TestCtrl_e.vhd
analyze   TbAxi4.vhd

RunTest   TbAxi4_BasicReadWrite.vhd
RunTest   TbAxi4_RandomReadWrite.vhd
SkipTest  TbAxi4_Interrupt.vhd "Not ready yet"