Repository files navigation

SVUT is a very simple flow to create a Verilog/SystemVerilog unit test. It iswidely inspired bySVUnit,but it's written in python and run withIcarusVerilog orVerilator. SVUT follows KISS principle:Keep ItSimple, Stupid.

Hope it can help you!

SVUT is available onPypi and can be installed as following:

pip3 install svut

Git clone the repository in a path. Set up the SVUT environment variableand add SVUT to$PATH:

export SVUT=$HOME/.svutgit clone https://github.com/dpretet/svut.git$SVUTexport PATH=$SVUT:$PATH

SVUT relies onIcarus Verilog as simulationback-end. Please install it with your favourite package manager and be sure touse a version greater or equal to v10.2. SVUT is tested withv10.2 and cannotwork with lower version<= v9.x.

SVUT can also useVerilator with a limited supportfor the moment. A future release will improve it, with example & tutorial. SVUT is tested withversion>= v4.

To create a unit test of a verilog module, call the command:

svutCreate your_file.v

No argument is required. SVUT will create "your_file_testbench.sv" which contains your moduleinstanciated and a place to write your testcase(s). Some codes are also commented to describe thedifferent macros and how to create a clock or dump a VCD forGTKWave orSurfer. A C++ file being the verilatortop level is also generated (sim_main.cpp). It can be ignored if you don't use Verilator.An example to understand how to use can be foundhere

To run a test, call the command:

svutRun -test your_file_testbench.sv

or simplysvutRun to execute all testbenchs in the current folder.

svutRun

SVUT will scan your current folder, search for the files with_testbench.svsuffix and run all tests available. Multiple suffix patterns arepossible.

svutRun proposes several arguments, most optional:

• -test: specify the testsuite file path or a folder containing tests
• -f: pass the fileset description, default isfiles.f
• -sim: specify the simulator,icarus orverilator
• -main: specify the C++ main file when using verilator, default issim_main.cpp
• -define: pass verilog defines to the tool, like-define "DEF1=2;DEF2;DEF3=3"
• -vpi: specify a compiled VPI, for instance-vpi "-M. -mMyVPI"
• -dry-run: print the commands but don't execute them
• -include: to pass include path, several can be passed like-include folder1 folder2
• -no-splash: don't print SVUT splash banner, printed by default
• -compile-only: just compile the testbench, don't execute it
• -run-only: just execute the testbench, if no executable found, also build it
• -fst: dump waveform with FST format. If not specified use VCD format

All these arguments are common for both the simulators.

Copy/paste this basic FFD model in a file named ffd.v into a new folder:

`timescale1 ns/1 psmoduleffd    (inputwire aclk,inputwire arstn,inputwire d,outputreg  q    );always @ (posedge aclkornegedge arstn)beginif (arstn==1'b0) q<=1'b0;else q<= d;endendmodule

Then run:

svutCreate ffd.v

ffd_testbench.v has been dropped in the folder from you called svutCreate. Itcontains all you need to start populating your testcases. In the header, youcan include directly your DUT file (uncomment):

`include"ffd.v"

or you can store the path to your file into afiles.f file, automaticallyrecognized by SVUT. Populate it with the files describing your IP. You canalso specify include folder in this way:

+incdir+$HOME/path/to/include/

Right after the module instance, you can use the example to generate a clock(to uncomment):

initial aclk=0;always#2 aclk=!aclk;

Next line explains how to dump your signals values into a VCD file to open awaveform in GTKWave (uncomment):

initial$dumpvars(0, ffd_unit_test);initial$dumpfile("ffd_testbench.vcd");

Two functions follow,setup() andteardown(). Use them to configure theenvironment of the testcases:

• setup() is called before each testcase execution
• teardown() is called after each testcase execution

A testcase is enclosed between two specific defines:

`UNIT_TEST("TESTNAME")    ...`UNIT_TEST_END

TESTNAME is a string which will be displayed when test executionwill start. Then you can use the macros provided to display information,warning, error and check some signals values. Each error encountered by amacro increments a globla error counter which determine a testsuite status.If the error counter is bigger than0, the test is considered as failed.

A testsuite, comprising severalUNIT_TEST, is declared with another define:

`TEST_SUITE("SUITENAME")    ...`TEST_SUITE_END

To test the FFD, add the next line intosetup() to drive the reset and init theFFD input:

arstn=1'b0;d=1'b0;#100;arstn=1'b1;

and into the testcase:

`FAIL_IF(q);

Here is a basic unit test checking if the FFD output is0 after reset. OncecalledsvutRun in your shell, you should see something similar:

SVUT relies (optionally) on files.f to declare the fileset and define. Follows an example:

...+define+MY_DEFINE_SIM1+define+MY_DEFINE_SIM2=723./ffd.sv+incdir+$HOME/work/mylib...

The user can also choose to pass define in the command line, common for both the simulator:

svutRun -test my_testbench.sv -define"DEF1=1;DEF2;DEF3=3"

SVUT doesn't check possible collision between define passed in command lineand the others defined infiles.f. Double check that point if unexpectedbehavior occurs during testbench.

Finally, SVUT supports VPI for Icarus. Follow an example to compile and set upthe flow of an hypothetic UART, compiled with iverilog and using a define "PORT":

iverilog-vpi uart.csvutRun -vpi"-M. -muart" -define"PORT=3333" -t ./my_testbench.sv&

Now you know the basics of SVUT. The generated testbench provides prototypes ofavailable macros. Try them and play around to test SVUT. You can find thesefiles into the example folder.

Enjoy!

Copyright 2024 The SVUT Authors

Permission is hereby granted, free of charge, to any person obtaining a copy ofthis software and associated documentation files (the "Software"), to deal inthe Software without restriction, including without limitation the rights touse, copy, modify, merge, publish, distribute, sublicense, and/or sell copiesof the Software, and to permit persons to whom the Software is furnished to doso, subject to the following conditions:

The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE. imitations under the License.