SVUnit User Guide


SVUnit is a simple, well-structured verification framework intended for design and verification engineers writing and running tests against Verilog modules, classes or interfaces. By first verifying the individual pieces of a design or testbench in isolation, we can assume much higher quality of the design or testbench as a whole.

The feature characteristic of SVUnit is ease-of-use, meaning developers can be up-and-running in an hour or less. SVUnit is open-source under Apache 2.0 licensing making it accessible and productive for any engineer with a Verilog simulator.

SVUnit Structure and Workflow

SVUnit uses a hierarchical structure of testrunner, test suite and unit test templates with scripting to handle construction and simulation. The upper layer testrunner and test suite(s) are generated and connected automatically with no intervention required. This allows users to focus on writing unit tests within a script generated unit test template.

The most basic SVUnit arrangement includes a single unit test template with 1 or more unit tests against a single UUT.

Screen Shot 2015-07-03 at 3.23.35 PM

A more likely arrangement is to have several unit test templates in a single directory, each containing unit tests for one of several UUTs. As examples, a design engineer building a subsystem with N modules would have N unit test templates running within a single test suite. Likewise, a verification engineer building a testbench with N transactors would also have N unit test templates running within a single test suite.

Screen Shot 2015-07-03 at 3.23.44 PM

A final, large scale arrangement is one with a test suite for each of M subsystems where each subsystem contains any number of unit test templates and the unit test templates for each subsystem are located in different directories.

Screen Shot 2015-07-03 at 3.23.52 PM

Hierarchy is derived from file/directory structure where all unit test templates located within the same directory are grouped into a test suite.

Installation and Setup

Download to setup is about a 3 minute procedure…

Download the Latest Version of SVUnit from GitHub
  1. Download the latest version of SVUnit from GitHub by clicking the big blue button to the right.
  2. Extract the SVUnit archive
    1. unzip
  3. Source the SVUnit setup script (bash users source Setup.bsh. csh users source Setup.csh)
    1. > cd svunit-code-master
    2. > source Setup.bsh

Creating a Unit Test Template

New unit test templates are created using Usage of is as follows…

Screen Shot 2016-02-17 at 1.48.43 PM

A template can be generated by using any of the -class_name, -module_name, -if_name switches or by specifying a verilog file that contains a definition of the UUT. For example, you can generate a new unit test template for a class called ‘foo’ with:

> -class_name foo

Likewise, if you already have a definition for class ‘foo’ in ‘foo.v’, you can generate a corresponding unit test template with:

> foo.v

The default output for is written to ./<name> The default can be overridden, however, using the -out <file> switch. A different file name and/or directory can be specified as required. The file name, however, must follow the <name> format.

Existing files will not be overwritten unless the -overwrite switch is used.

Integrating the UUT

The template generated by includes an instance of the UUT as well as other important parts of the infrastructure. The UUT does not, however, include any pin level connectivity so connectivity is handled by users. For example, if a template is created for a module named ‘test_module’, an instance of ‘test_module’ is created as:

Screen Shot 2015-07-08 at 10.24.44 AM

If test_module has two outputs, oBus and oPin, and one input, iPin, a user connects them as normal Verilog IO thereby making them accessible within the unit test template.

Screen Shot 2015-07-08 at 10.34.11 AM

Writing Unit Tests

The unit test template includes embedded instructions on structure and position of unit tests:

Screen Shot 2015-07-03 at 4.41.54 PM

Multiple unit tests can be defined in a unit test template. All must be defined between the `SVUNIT_TESTS_BEGIN and `SVUNIT_TESTS_END macros. Individual unit tests are defined using the `SVTEST(<name>) and `SVTEST_END macros. The test <name> must be a valid verilog code block label (i.e. any alphanumeric starting with [_a-zA-Z]). For example, a template with 2 tests called test0 and test1 would be declared as:

Screen Shot 2015-07-03 at 4.44.52 PM

The macros expand to a Verilog code block so any code that is legal within a code block can be used within a unit test. Other required variables, declarations, functions, tasks, etc must be defined outside the BEGIN/END macros. For example, the function helper() can be defined and used within a unit test as:

Screen Shot 2015-07-03 at 4.50.11 PM

SVUnit imposes no limit on the number of unit tests that can be defined with a unit test template.

SVUnit Reporting Macros

SVUnit includes an integrated reporting mechanism such that the exit PASS/FAIL status of every unit test is collected, reported and used to report a cumulative result. To set PASS/FAIL status, SVUnit defines several logging macros that are integrated with the reporting structure.

Screen Shot 2015-07-03 at 4.59.01 PM

The most commonly used macros are `FAIL_IF and `FAIL_UNLESS that take a single boolean expression as input. The `FAIL_IF_EQUAL and `FAIL_UNLESS_EQUAL macros exit based on an ‘===’ comparison of boolean inputs a and b. Likewise, `FAIL_IF_STR_EQUAL and `FAIL_UNLESS_STR_EQUAL do a string comparison between inputs a and b.

Setting Test Exit Status

The reporting macros can be used to verify outputs and response of a UUT and set test exit status according. For example, we can use the `FAIL_IF and `FAIL_UNLESS_EQUAL macros to verify oBus and oPin are driven to the proper state.

Screen Shot 2015-07-08 at 10.37.08 AM

If the conditions described by the macros in either test0 or test1 are not satisfied, the test fails with an assert error and is reported as having failed. Tests are killed immediately at first failure so any code appearing after the failing assert statement does not execute.

Interacting with the UUT

Tests can interact with the UUT using simple procedural assignments to inputs or through helper functions and tasks for more complex interactions. For example, if the state of the oPin and oBus outputs is conditional based on the state of the iPin, oPin and oBus can be verified by driving iPin as necessary:

Screen Shot 2015-07-08 at 10.46.19 AM

NOTE: the addition of the #0 assumes oPin and oBus are asynchronous outputs that require a delta cycle be consumed before they reach their intended state.

Test Setup and Teardown

For behaviour that is repeated before and after every test, the setup() and teardown() tasks in the unit test template are intended to group any logic that is repeated before and/or after every test – the setup() task is run before every test and the teardown() task is run after every test. For example, if the default state of iPin is logic 1, that assignment can be done in the setup task rather than each individual test:

Screen Shot 2015-07-08 at 10.52.09 AM

As a result of moving the ‘iPin = 1’ assignment to the setup() task, test0 and test1 can be simplified to:

Screen Shot 2015-07-08 at 10.53.10 AM

It is recommended that common initialization code be contained in the setup() task. Reset sequence or register initialization, for example, is common logic that should be included in the setup() task. As well, it is recommended that any general cleanup of the UUT or unit test harness be grouped in the teardown() task to avoid polluting the state space for subsequent tests (i.e teardown() is for “cleaning the slate”).

Special Considerations for Unit Testing UVM Components

UVM components require additional infrastructure found in the svunit_uvm_mock_pkg. An additional switch, therefore, is included with to generate a UVM component specific test case template. If, for example, class blah is derived from uvm_component, would be invoked as…
> -uvm -class_name blah

The UVM component test case template includes a UUT wrapper that can be used to instantiate any additional unit test infrastructure, like connections to TLM FIFOs or analysis ports, if required. The UUT wrapper in the test case template is output as…

Screen Shot 2016-02-17 at 6.57.47 AM

The template also includes calls to functions svunit_activate_uvm_component, svunit_deactivate_uvm_component, svunit_uvm_test_start and svunit_uvm_test_finish in the build, setup and teardown tasks to integrate the UVM runflow with the sequential test running behaviour of SVUnit.

Screen Shot 2016-02-17 at 11.25.24 AM

The activate/deactivate functions are used to isolate the component in the uvm_domain such that multiple uvm_components can be tested in series. The start/finish functions are used to invoke phase jumping such that unit tests against against a component can be run iteratively.

Running Unit Tests

SVUnit unit tests are run using runSVUnit. Usage of runSVUnit is as follows…

Screen Shot 2015-07-03 at 3.59.08 PM

Choosing a Simulator

SVUnit can be run using most commonly used EDA simulators using the ‘-s’ switch. Supported simulators currently include Mentor Graphics Questa, Cadence Incisive, Synopsys VCS and Aldec Riviera PRO.


By default, simulation output is written to run.log. The default location can be overridden using the ‘-l’ switch.

Specifying Command-line Macros

SVUnit will pass command line macro defines specified by the ‘-d’ switch directly to the simulator.

Adding Files For Simulation

Through the use of `include directives, both the unit test template and corresponding UUT file are included in compilation making it possible to build and verify on simple designs without any need to specify or maintain file lists. As designs grow, however, more files can be added using standard simulator file lists and the ‘-f’ switch.

NOTE: The file svunit.f is automatically included for compilation provided it exists. Thus, files can be added to svunit.f without having to specify ‘-f svunit.f’ on the command line.

Adding Run Time and/or Compile Time Options

It is possible to specified compile and run time options using the ‘-c_arg’ and ‘-r_arg’ switches respectively. All compile and run time arguments are passed directly to the simulator command line.

Enable UVM Component Unit Testing

For verification engineers unit testing UVM-based components, the ‘-U’ switch must be specified to include relevant run-flow handling.

Specifying a Simulation Directory

By default, SVUnit is run in the current working directory. However, to avoid mixing source files with simulation output, it is possible to change the location where SVUnit is built and simulated using the ‘-o’ switch. It is an error to use the ‘-o’ switch to runSVUnit that doesn’t exist.

Specifying Unit Tests to be Run

By default, runSVUnit finds and simulates all unit test templates within a given parent directory. For short runs, this is recommended practice. However, if simulation times grow to the point where they are long and cumbersome, it is possible to specify specific unit test templates to be run using the ‘-t’ switch. For example, if a parent directory has 12 unit test templates but you only want to run, you can use the ‘-t’ switch as:

> runSVunit -t -s <your simulator>

The ‘-t’ switch can be used to specify multiple unit test templates as:

> runSVunit -t -t -s <your simulator>

Simulator Output

Using built-in logging macros, the logged SVUnit output shows step-by-step run status for each test, unit test template and test suite as well as a cumulative result for the testrunner.

Screen Shot 2015-07-08 at 11.11.01 AM

Support and More Information

To connect with other users, ask questions and share experience, join the SVUnit User Group. Everyone is welcome!

User Guide Feedback

It’d be a big help for me to get your feedback and direction so I can make sure the user guide is actually helping SVUnit users. Please let me know what you think!


13 thoughts on “SVUnit User Guide

  1. Thanks Neil for the User guide.
    It seems that there are a lot of macros used , I think that Mentor guys will not be happy about this 🙂

    I wonder what is the next features you may add in SVUnit

  2. Hi,

    In the section “Enable UVM Component Unit Testing” you write the following note:

    “NOTE: there are additional considerations required for unit testing UVM-based components that are covered later in the user guide.”

    I have not been able to find these additional considerations described later in the user guide?

    1. peter, not added to the user guide yet is the short answer. temporarily, you can refer to the simple_model example in the release package. that shows all the additions you need to verify a uvm component. coincedentally, I was just talking to a colleague about adding the option to for a uvm component that already contains all the additions you need. you might see that in a few weeks. for now refer to the simple_model and that should get you by.


  3. Heyyyy Neil! Thanks for complimenting my shoes, they are still at ottawa 🙂
    I really enjoyed the trial run of SVUNIT. One question about coverage mapping,
    Do you already have any way to link testcast pass/fail measure into a test plan?


    1. hey shannon. good to hear. I don’t have anything that explicitly maps testcase to test plan. I’ve been meaning to rev the logging such that it’s easier to parse and/or integrate with other tools (i.e. jenkins for CI) but haven’t got around to it. if you’ve got some suggestions for how you’d like to see svunit supply that backreference to testplan, please let me know and I’ll see what I can do.


  4. Is there a command line command that I can use to dump a wave file in my output directory. I will post this question in the user group too.

    – Abel

    1. use the -r option when calling runSVUnit and pass it a .do file that contains log -r /*. file contents:
      log -r /*

      then on the command line:
      runSVUnit -s modelsim -r “-do”

  5. Hi, playing a bit with SVUnit – looks very promising! if i understand correctly, UVM “mode” only supports component. how about classes derived from uvm_component – seems it is not supported? tried without the UVM flag in “create” but then it has no notion of UVM objects at all.
    am i missing anything?

  6. Hi! I have a unit test with multiple test, I cannot manage to run a specific test of the unit test file…is it possible ?
    for example: i have

    `SVTEST (test1)

    `SVTEST (test2)

    `SVTEST (test3)

    since I have many test, but I want just to run one of them at a time, for test time reason, is there the possibility ?

    I tried tu run SVUNIT with -t test3 option, but it says ERROR: Unit test ‘test3’ could not be found in directory.
    how can I do ?

    1. hey francesco. the ‘-t’ option doesn’t go to an individual test granularity, just to the * granularity. so if you have multiple * files with tests, you can use ‘-t’ to run one and ignore the rest. that make sense?

  7. Hey Neal –
    the README.txt file (and probably others) still has the XtremeEDA copyright notice. Dunno if that’s still valid.


  8. Hi Neil,
    How would one randomize variables , typically in a uvm env it would be done in a sequence, or an inline constraint in a test how can the sequence be included in the macro
    svunit_activate_uvm_component is for uvm_components not uvm_object?


  9. Hi,

    I am looking for the steps(flow) which run internally when a testbench is created from script and run using runSVUnit.

    **I am not good at perl. is there any python version for scripts

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.