Python Interface

The Python interface of VUnit is exposed through the VUnit class that can be imported directly from the vunit module.

Public API

class vunit.ui.VUnit

The public interface of VUnit

Example:
from vunit import VUnit
add_array_util(library_name='vunit_lib')

Add array utility package

add_com(library_name='vunit_lib', use_debug_codecs=None)

Add communication package

Parameters:use_debug_codecs

Use human readable debug codecs

None: Use command line argument setting

False: Never use debug codecs

True: Always use debug codecs

add_compile_option(name, value, allow_empty=False)

Add compile option to all files

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
  • allow_empty – To disable an error when no source files were found

Note

Only affects files added before the option is set.

add_external_library(library_name, path, vhdl_standard=None)

Add an externally compiled library as a black-box

Parameters:
  • library_name – The name of the external library
  • path – The path to the external library directory
  • vhdl_standard – The VHDL standard used to compile files into this library, if None the VUNIT_VHDL_STANDARD environment variable is used
Returns:

The created Library object

Example:
prj.add_external_library("unisim", "path/to/unisim/")
add_library(library_name, vhdl_standard=None)

Add a library managed by VUnit.

Parameters:
  • library_name – The name of the library
  • vhdl_standard – The VHDL standard used to compile files into this library, if None the VUNIT_VHDL_STANDARD environment variable is used
Returns:

The created Library object

Example:
library = prj.add_library("lib")
add_osvvm(library_name='osvvm')

Add osvvm library

add_source_file(file_name, library_name, preprocessors=None, include_dirs=None, defines=None, vhdl_standard=None, no_parse=False)

Add source file to library

Parameters:
  • file_name – The name of the file
  • library_name – The name of the library to add the file into
  • include_dirs – A list of include directories
  • defines – A dictionary containing Verilog defines to be set
  • vhdl_standard – The VHDL standard used to compile this file, if None VUNIT_VHDL_STANDARD environment variable is used
  • no_parse – Do not parse file for dependency or test scanning purposes
Returns:

The SourceFile which was added

Example:
prj.add_source_file("file.vhd", "lib")
add_source_files(pattern, library_name, preprocessors=None, include_dirs=None, defines=None, allow_empty=False, vhdl_standard=None, no_parse=False)

Add source files matching wildcard pattern to library

Parameters:
  • pattern – A wildcard pattern matching the files to add or a list of files
  • library_name – The name of the library to add files into
  • include_dirs – A list of include directories
  • defines – A dictionary containing Verilog defines to be set
  • allow_empty – To disable an error if no files matched the pattern
  • vhdl_standard – The VHDL standard used to compile these files, if None VUNIT_VHDL_STANDARD environment variable is used
  • no_parse – Do not parse file(s) for dependency or test scanning purposes
Returns:

A list of files (SourceFileList) which were added

Example:
prj.add_source_files("*.vhd", "lib")
enable_check_preprocessing()

Inserts error context information into VUnit check_relation calls

enable_location_preprocessing(additional_subprograms=None, exclude_subprograms=None)

Inserts file name and line number information into VUnit check and log subprograms calls. Custom subprograms can also be added. Must be called before adding any files.

Parameters:
  • additional_subprograms – List of custom subprograms to add the line_num and file_name parameters to.
  • exclude_subprograms – List of VUnit subprograms to exclude from location preprocessing. Used to avoid location preprocessing of other functions sharing name with a VUnit log or check subprogram.
Example:
prj.enable_location_preprocessing(additional_subprograms=['my_check'],
                                  exclude_subprograms=['log'])
classmethod from_args(args, compile_builtins=True)

Create VUnit instance from args namespace. Intended for users who adds custom command line options. See vunit.vunit_cli.VUnitCLI class to learn about adding custom command line options.

Parameters:
  • args – The parsed argument namespace object
  • compile_builtins – Do not compile builtins. Used for VUnit internal testing.
Returns:

A VUnit object instance

classmethod from_argv(argv=None, compile_builtins=True)

Create VUnit instance from command line arguments.

Parameters:
  • argv – Use explicit argv instead of actual command line argument
  • compile_builtins – Do not compile builtins. Used for VUnit internal testing.
Returns:

A VUnit object instance

Example:
from vunit import VUnit
prj = VUnit.from_argv()
get_compile_order(source_files=None)

Get the compile order of all or specific source files and their dependencies.

A dependency of file A in terms of compile order is any file B which must be successfully compiled before A can be successfully compiled.

This is not the same as all files required to successfully elaborate A. For example using component instantiation in VHDL there is no compile order dependency but the component instance will not elaborate if there is no binding component.

Parameters:source_files – A list of SourceFile objects or None meaing all
Returns:A list of SourceFile objects in compile order.
get_implementation_subset(source_files)

Get the subset of files which are required to successfully elaborate the list of input files without any missing dependencies.

Parameters:source_files – A list of SourceFile objects
Returns:A list of SourceFile objects which is the implementation subset.
get_source_file(file_name, library_name=None)

Get a source file

Parameters:
  • file_name – The name of the file as a relative or absolute path
  • library_name – The name of a specific library to search if not all libraries
Returns:

A SourceFile object

get_source_files(pattern='*', library_name=None, allow_empty=False)

Get a list of source files

Parameters:
  • pattern – A wildcard pattern matching either an absolute or relative path
  • library_name – The name of a specific library to search if not all libraries
  • allow_empty – To disable an error if no files matched the pattern
Returns:

A SourceFileList object

library(library_name)

Get a library

Parameters:library_name – The name of the library
Returns:A Library object
main()

Run vunit main function and exit

set_compile_option(name, value, allow_empty=False)

Set compile option of all files

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
  • allow_empty – To disable an error when no source files were found
Example:
prj.set_compile_option("ghdl.flags", ["--no-vital-checks"])

Note

Only affects files added before the option is set.

set_generic(name, value, allow_empty=False)

Set a value of generic in all configurations

Parameters:
  • name – The name of the generic
  • value – The value of the generic
  • allow_empty – To disable an error when no test benches were found
Example:
prj.set_generic("data_width", 16)

Note

Only affects test benches added before the generic is set.

set_parameter(name, value, allow_empty=False)

Set value of parameter in all configurations

Parameters:
  • name – The name of the parameter
  • value – The value of the parameter
  • allow_empty – To disable an error when no test benches were found
Example:
prj.set_parameter("data_width", 16)

Note

Only affects test benches added before the parameter is set.

set_sim_option(name, value, allow_empty=False)

Set simulation option in all configurations

Parameters:
  • name – The name of the simulation option (See Simulation options)
  • value – The value of the simulation option
  • allow_empty – To disable an error when no test benches were found
Example:
prj.set_sim_option("ghdl.flags", ["--no-vital-checks"])

Note

Only affects test benches added before the option is set.

class vunit.ui.Library

User interface of a library

add_compile_option(name, value, allow_empty=False)

Add compile option to all files within the library

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
  • allow_empty – To disable an error when no source files were found

Note

Only affects files added before the option is set.

add_source_file(file_name, preprocessors=None, include_dirs=None, defines=None, vhdl_standard=None, no_parse=False)

Add source file to library

Parameters:
  • file_name – The name of the file
  • include_dirs – A list of include directories
  • defines – A dictionary containing Verilog defines to be set
  • vhdl_standard – The VHDL standard used to compile this file, if None library default is used
  • no_parse – Do not parse file for dependency or test scanning purposes
Returns:

The SourceFile which was added

Example:
library.add_source_file("file.vhd")
add_source_files(pattern, preprocessors=None, include_dirs=None, defines=None, allow_empty=False, vhdl_standard=None, no_parse=False)

Add source files matching wildcard pattern to library

Parameters:
  • pattern – A wildcard pattern match the files to add
  • include_dirs – A list of include directories
  • defines – A dictionary containing Verilog defines to be set
  • allow_empty – To disable an error if no files matched the pattern
  • vhdl_standard – The VHDL standard used to compile these files, if None library default is used
  • no_parse – Do not parse file(s) for dependency or test scanning purposes
Returns:

A list of files (SourceFileList) which were added

Example:
library.add_source_files("*.vhd")
entity(name)

Get an entity within the library

Parameters:name – The name of the entity
Returns:A TestBench object
Raises:KeyError
get_source_file(file_name)

Get a source file within this library

Parameters:file_name – The name of the file as a relative or absolute path
Returns:A SourceFile object
get_source_files(pattern='*', allow_empty=False)

Get a list of source files within this libary

Parameters:
  • pattern – A wildcard pattern matching either an absolute or relative path
  • allow_empty – To disable an error if no files matched the pattern
Returns:

A SourceFileList object

get_test_benches(pattern='*', allow_empty=False)

Get a list of test benches

Parameters:
  • pattern – A wildcard pattern matching the test_bench name
  • allow_empty – To disable an error when no test benches were found
Returns:

A list of TestBench objects

module(name)

Get a module within the library

Parameters:name – The name of the module
Returns:A TestBench object
Raises:KeyError
name

The name of the library

set_compile_option(name, value, allow_empty=False)

Set compile option for all files within the library

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
  • allow_empty – To disable an error when no source files were found
Example:
lib.set_compile_option("ghdl.flags", ["--no-vital-checks"])

Note

Only affects files added before the option is set.

set_generic(name, value, allow_empty=False)

Set a value of generic within all configurations of test benches and tests this library

Parameters:
  • name – The name of the generic
  • value – The value of the generic
  • allow_empty – To disable an error when no test benches were found
Example:
lib.set_generic("data_width", 16)

Note

Only affects test benches added before the generic is set.

set_parameter(name, value, allow_empty=False)

Set a value of parameter within all configurations of test benches and tests this library

Parameters:
  • name – The name of the parameter
  • value – The value of the parameter
  • allow_empty – To disable an error when no test benches were found
Example:
lib.set_parameter("data_width", 16)

Note

Only affects test benches added before the parameter is set.

set_sim_option(name, value, allow_empty=False)

Set simlation option within all configurations of test benches and tests this library

Parameters:
  • name – The name of the simulation option (See Simulation options)
  • value – The value of the simulation option
  • allow_empty – To disable an error when no test benches were found
Example:
lib.set_sim_option("ghdl.flags", ["--no-vital-checks"])

Note

Only affects test benches added before the option is set.

test_bench(name)

Get a test bench within this library

Parameters:name – The name of the test bench
Returns:A TestBench object
Raises:KeyError
class vunit.ui.SourceFileList

A list of SourceFile

add_compile_option(name, value)

Add compile option to all files in the list

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
add_dependency_on(source_file)

Add manual dependency of these files on other file(s)

Parameters:source_file – The file(s) which this file depends on
Example:
other_file = lib.get_source_file("other_file.vhd")
files.add_dependency_on(other_file)
set_compile_option(name, value)

Set compile option for all files in the list

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
Example:
files.set_compile_option("ghdl.flags", ["--no-vital-checks"])
class vunit.ui.SourceFile

A single file

add_compile_option(name, value)

Add compile option to this file

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
add_dependency_on(source_file)

Add manual dependency of this file other file(s)

Parameters:source_file – The file(s) which this file depends on
Example:
other_files = lib.get_source_files("*.vhd")
my_file.add_dependency_on(other_files)
get_compile_option(name)

Return compile option of this file

Parameters:name – The name of the compile option (See Compilation options)
library

The library of the source file

name

The name of the SourceFile

set_compile_option(name, value)

Set compile option for this file

Parameters:
  • name – The name of the compile option (See Compilation options)
  • value – The value of the compile option
Example:
my_file.set_compile_option("ghdl.flags", ["--no-vital-checks"])
vhdl_standard

The VHDL standard applicable to the file, None if not a VHDL file

class vunit.ui.TestBench

User interface of a test bench. A test bench consists of one or more Test cases. Setting options for a test bench will apply that option all test cases belonging to that test bench.

add_config(name, generics=None, parameters=None, pre_config=None, post_check=None, sim_options=None)

Add a configuration of this test bench or to all test cases within it by copying the default configuration.

Multiple configuration may be added one after another. If no configurations are added the default configuration is used.

Parameters:
  • name – The name of the configuration. Will be added as a suffix on the test name
  • generics – A dict containing the generics to be set in addition to the default configuration
  • parameters – A dict containing the parameters to be set in addition to the default configuration
  • pre_config – A function to be called before test execution, replaces the default if not None The function accepts an optional first argument output_path which is the filesystem path to the directory where test outputs are stored. An optional second argument simulator_output_path is the filesystem path to the simulator working directory. Please note that simulator_output_path is shared by all test runs. The user must take care that test runs do not read or write the same files asynchronously. It is therefore recommended to use output_path in favor of simulator_output_path. The function must return True or the test will fail
  • post_check – A function to be called after test execution, replaces the default if not None The function must accept a string which is the filesystem path to the directory where test outputs are stored. The function must return True or the test will fail
  • sim_options – A dict containing the sim_options to be set in addition to the default configuration
Example:

Given a test bench that by default gives rise to the test lib.test_bench and the following add_config calls:

for data_width in range(14, 15+1):
    for sign in [False, True]:
        test_bench.add_config(
            name="data_width=%s,sign=%s" % (data_width, sign),
            generics=dict(data_width=data_width, sign=sign))

The following tests will be created:

  • lib.test_bench.data_width=14,sign=False
  • lib.test_bench.data_width=14,sign=True
  • lib.test_bench.data_width=15,sign=False
  • lib.test_bench.data_width=15,sign=True
get_tests(pattern='*')

Get a list of tests

Parameters:pattern – A wildcard pattern matching the test name
Returns:A list of Test objects
library
Returns:The library that contains this test bench
name
Returns:The entity or module name of the test bench
scan_tests_from_file(file_name)

Scan tests from another file than the one containg the test bench. Useful for when the top level test bench does not contain the tests.

Such a structure is not the preferred way of doing things in VUnit but this method exists to accommodate legacy needs.

Parameters:file_name – The name of another file to scan for tests

Warning

The nested module containing the tests needs to be given the runner_cfg parameter or generic by the instantiating top level test bench. The nested module should not call its parameter or generic runner_cfg but rather nested_runner_cfg to avoid the VUnit test scanner detecting and running it as a test bench. In SystemVerilog the NESTED_TEST_SUITE macro should be used instead of the TEST_SUITE macro.

set_generic(name, value)

Set a value of generic within all configurations of this test bench or test cases within it

Parameters:
  • name – The name of the generic
  • value – The value of the generic
Example:
test_bench.set_generic("data_width", 16)
set_parameter(name, value)

Set a value of parameter within all configurations of this test bench or test cases within it

Parameters:
  • name – The name of the parameter
  • value – The value of the parameter
Example:
test_bench.set_parameter("data_width", 16)
set_post_check(value)

Set post_check function of all configurations of this test bench or test cases within it

Parameters:value – The post_check function
set_pre_config(value)

Set pre_config function of all configurations of this test bench or test cases within it

Parameters:value – The pre_config function
set_sim_option(name, value)

Set simulation option within all configurations of this test bench or test cases within it

Parameters:
  • name – The name of the simulation option (See Simulation options)
  • value – The value of the simulation option
Example:
test_bench.set_sim_option("ghdl.flags", ["--no-vital-checks"])
test(name)

Get a test within this test bench

Parameters:name – The name of the test
Returns:A Test object
class vunit.ui.Test

User interface of a single test case

add_config(name, generics=None, parameters=None, pre_config=None, post_check=None, sim_options=None)

Add a configuration to this test copying the default configuration.

Multiple configuration may be added one after another. If no configurations are added the default configuration is used.

Parameters:
  • name – The name of the configuration. Will be added as a suffix on the test name
  • generics – A dict containing the generics to be set in addition to the default configuration.
  • parameters – A dict containing the parameters to be set in addition to the default configuration.
  • pre_config – A function to be called before test execution, replaces the default if not None. The function may accept a string which is the filesystem path to the directory where test outputs are stored. The function must return True or the test will fail
  • post_check – A function to be called after test execution, replaces the default if not None. The function must accept a string which is the filesystem path to the directory where test outputs are stored. The function must return True or the test will fail
  • sim_options – A dict containing the sim_options to be set in addition to the default configuration.
Example:

Given the lib.test_bench.test test and the following add_config calls:

for data_width in range(14, 15+1):
    for sign in [False, True]:
        test.add_config(
            name="data_width=%s,sign=%s" % (data_width, sign),
            generics=dict(data_width=data_width, sign=sign))

The following tests will be created:

  • lib.test_bench.data_width=14,sign=False.test
  • lib.test_bench.data_width=14,sign=True.test
  • lib.test_bench.data_width=15,sign=False.test
  • lib.test_bench.data_width=15,sign=True.test
name
Returns:the entity or module name of the test bench
set_generic(name, value)

Set a value of generic within all configurations of this test

Parameters:
  • name – The name of the generic
  • value – The value of the generic
Example:
test.set_generic("data_width", 16)
set_parameter(name, value)

Set a value of parameter within all configurations of this test

Parameters:
  • name – The name of the parameter
  • value – The value of the parameter
Example:
test.set_parameter("data_width", 16)
set_post_check(value)

Set post_check function of all configurations of this test

Parameters:value – The post_check function
set_pre_config(value)

Set pre_config function of all configurations of this test

Parameters:value – The pre_config function
set_sim_option(name, value)

Set simulation option within all configurations of this test

Parameters:
  • name – The name of the simulation option (See Simulation options)
  • value – The value of the simulation option
Example:
test.set_sim_option("ghdl.flags", ["--no-vital-checks"])

Compilation Options

Compilation options allow customization of compilation behavior. Since simulators have differing options available, generic options may be specified through this interface. The following compilation options are known.

ghdl.flags
Extra arguments passed to ghdl -a command during compilation. Must be a list of strings.
incisive.irun_vhdl_flags
Extra arguments passed to the Incisive irun command when compiling VHDL files. Must be a list of strings.
incisive.irun_verilog_flags
Extra arguments passed to the Incisive irun command when compiling Verilog files. Must be a list of strings.
modelsim.vcom_flags
Extra arguments passed to ModelSim vcom command. Must be a list of strings.
modelsim.vlog_flags
Extra arguments passed to ModelSim vlog command. Must be a list of strings.
rivierapro.vcom_flags
Extra arguments passed to Riviera PRO vcom command. Must be a list of strings.
rivierapro.vlog_flags
Extra arguments passed to Riviera PRO vlog command. Must be a list of strings.
activehdl.vcom_flags
Extra arguments passed to Active HDL vcom command. Must be a list of strings.
activehdl.vlog_flags
Extra arguments passed to Active HDL vcom command. Must be a list of strings.

Note

Only affects source files added before the option is set.

Simulation Options

Simulation options allow customization of simulation behavior. Since simulators have differing options available, generic options may be specified through this interface. The following simulation options are known.

vhdl_assert_stop_level
Will stop a VHDL simulation for asserts on the provided severity level or higher. Valid values are "warning", "error", and "failure". This option takes precedence over the fail_on_warning pragma.
disable_ieee_warnings
Disable ieee warnings Boolean
pli
A list of PLI files A list of file names
ghdl.flags
Extra arguments passed to ghdl --elab-run command before executable specific flags. Must be a list of strings. Must be a list of strings.
incisive.irun_sim_flags
Extra arguments passed to the Incisive irun command when loading the design. Must be a list of strings.
modelsim.vsim_flags
Extra arguments passed to vsim when loading the design. Must be a list of strings.
modelsim.vsim_flags.gui
Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over modelsim.vsim_flags. Must be a list of strings.
modelsim.init_files.after_load
A list of user defined DO/TCL-files that is sourced after the design has been loaded. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a list of strings.
modelsim.init_file.gui
A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a string.
rivierapro.vsim_flags
Extra arguments passed to vsim when loading the design. Must be a list of strings.
rivierapro.vsim_flags.gui
Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over rivierapro.vsim_flags. Must be a list of strings.
rivierapro.init_files.after_load
A list of user defined DO/TCL-files that is sourced after the design has been loaded. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a list of strings.
rivierapro.init_file.gui
A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a string.
activehdl.vsim_flags
Extra arguments passed to vsim when loading the design. Must be a list of strings.
activehdl.vsim_flags.gui
Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over activehdl.vsim_flags. Must be a list of strings.
activehdl.init_file.gui
A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. Must be a string.
ghdl.elab_flags
Extra elaboration flags passed to ghdl --elab-run. Must be a list of strings.
ghdl.sim_flags
Extra simulation flags passed to ghdl --elab-run. Must be a list of strings.

Configurations

In VUnit Python API the name configuration is used to denote the user controllable configuration of one test run such as generic/parameter settings, simulation options as well as the pre_config and post_check callback functions.

Configurations can either be unique for each test case or must be common for the entire test bench depending on the situation. For test benches without test such as tb_example in the User Guide the configuration is common for the entire test bench. For test benches containing tests such as tb_example_many the configuration is done for each test case. If the run_all_in_same_sim pragma has been used configuration is performed at the test bench level even if there are individual test within since they must run in the same simulation.

In a VUnit all test benches and test cases are created with an unnamed default configuration which is modified by different methods such as set_generic etc. In addition to the unnamed default configuration multiple named configurations can be derived from it by using the add_config method. The default configuration is only run if there are no named configurations.

Adding Custom Command Line Arguments

It is possible to add custom command line arguments to your run.py scripts using the VUnitCLI class.

class vunit.vunit_cli.VUnitCLI(description=None)

VUnit command line interface

parse_args(argv=None)

Parse command line arguments

Parameters:argv – Use explicit argv instead of actual command line argument
Returns:The parsed argument namespace object

A VUnitCLI object has a parser field which is an ArgumentParser object of the argparse library.

from vunit import VUnitCLI, VUnit

# Add custom command line argument to standard CLI
# Beware of conflicts with existing arguments
cli = VUnitCLI()
cli.parser.add_argument('--custom-arg', ...)
args = cli.parse_args()

# Create VUNit instance from custom arguments
vu = VUnit.from_args(args=args)

# Use args.custom_arg here ...
print(args.custom_arg)