{"id":13648102,"url":"https://github.com/dpretet/svut","last_synced_at":"2025-04-22T06:33:01.522Z","repository":{"id":47869716,"uuid":"84708238","full_name":"dpretet/svut","owner":"dpretet","description":"SVUT is a simple framework to create Verilog/SystemVerilog unit tests. Just focus on your tests!","archived":false,"fork":false,"pushed_at":"2024-10-22T09:09:29.000Z","size":773,"stargazers_count":77,"open_issues_count":0,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-18T21:25:42.471Z","etag":null,"topics":["flow","foss","gtkwave","icarus-verilog","mit-license","python","simulation","simulator","surfer","svut","systemverilog","tdd","tdd-utilities","testcase","vcd","verification-methodologies","verilator","verilog"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpretet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-03-12T07:31:41.000Z","updated_at":"2025-04-04T05:36:00.000Z","dependencies_parsed_at":"2025-04-18T21:25:51.465Z","dependency_job_id":"fdd09fde-3ca5-4bd8-890e-ed4c42d25c0e","html_url":"https://github.com/dpretet/svut","commit_stats":null,"previous_names":["damofthemoon/svut"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpretet%2Fsvut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpretet%2Fsvut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpretet%2Fsvut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpretet%2Fsvut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpretet","download_url":"https://codeload.github.com/dpretet/svut/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250183498,"owners_count":21388725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flow","foss","gtkwave","icarus-verilog","mit-license","python","simulation","simulator","surfer","svut","systemverilog","tdd","tdd-utilities","testcase","vcd","verification-methodologies","verilator","verilog"],"created_at":"2024-08-02T01:03:58.332Z","updated_at":"2025-04-22T06:33:01.062Z","avatar_url":"https://github.com/dpretet.png","language":"Python","readme":"# SystemVerilog Unit Test (SVUT)\n\n[![GitHub license](https://img.shields.io/github/license/dpretet/svut)](https://github.com/dpretet/svut/blob/master/LICENSE)\n![Github Actions](https://github.com/dpretet/svut/actions/workflows/ci_ubuntu.yaml/badge.svg)\n![Github Actions](https://github.com/dpretet/svut/actions/workflows/ci_macos.yaml/badge.svg)\n[![GitHub issues](https://img.shields.io/github/issues/dpretet/svut)](https://github.com/dpretet/svut/issues)\n[![GitHub stars](https://img.shields.io/github/stars/dpretet/svut)](https://github.com/dpretet/svut/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/dpretet/svut)](https://github.com/dpretet/svut/network)\n\n\n## Introduction\n\nSVUT is a very simple flow to create a Verilog/SystemVerilog unit test. It is\nwidely inspired by [SVUnit](http://agilesoc.com/open-source-projects/svunit/),\nbut it's written in python and run with [Icarus\nVerilog](http://iverilog.icarus.com/) or\n[Verilator](https://www.veripool.org/verilator/). SVUT follows KISS principle: [Keep It\nSimple, Stupid](https://en.wikipedia.org/wiki/KISS_principle).\n\nHope it can help you!\n\n### How to Install\n\n#### Pypi\n\nSVUT is available on [Pypi](https://pypi.org/project/svut/) and can be installed as following:\n\n```bash\npip3 install svut\n```\n\n#### Git\n\nGit clone the repository in a path. Set up the SVUT environment variable\nand add SVUT to `$PATH`:\n\n```bash\nexport SVUT=$HOME/.svut\ngit clone https://github.com/dpretet/svut.git $SVUT\nexport PATH=$SVUT:$PATH\n```\n\nSVUT relies on [Icarus Verilog](http://iverilog.icarus.com/) as simulation\nback-end. Please install it with your favourite package manager and be sure to\nuse a version greater or equal to v10.2. SVUT is tested with `v10.2` and cannot\nwork with lower version `\u003c= v9.x`.\n\nSVUT can also use [Verilator](https://github.com/verilator/verilator) with a limited support\nfor the moment. A future release will improve it, with example \u0026 tutorial. SVUT is tested with\nversion `\u003e= v4`.\n\n\n### How to use it\n\nTo create a unit test of a verilog module, call the command:\n\n```bash\nsvutCreate your_file.v\n```\n\nNo argument is required. SVUT will create \"your_file_testbench.sv\" which contains your module\ninstanciated and a place to write your testcase(s). Some codes are also commented to describe the\ndifferent macros and how to create a clock or dump a VCD for\n[GTKWave](https://gtkwave.sourceforge.net) or\n[Surfer](https://gitlab.com/surfer-project/surfer). A C++ file being the verilator\ntop level is also generated (`sim_main.cpp`). It can be ignored if you don't use Verilator.\nAn example to understand how to use can be found [here](https://github.com/dpretet/friscv/tree/master/test/common)\n\nTo run a test, call the command:\n\n```bash\nsvutRun -test your_file_testbench.sv\n```\n\nor simply `svutRun` to execute all testbenchs in the current folder.\n\n```bash\nsvutRun\n```\n\nSVUT will scan your current folder, search for the files with `_testbench.sv`\nsuffix and run all tests available. Multiple suffix patterns are\n[possible](https://github.com/dpretet/svut/blob/master/svut/svutRun.py#L46).\n\nsvutRun proposes several arguments, most optional:\n\n- `-test`: specify the testsuite file path or a folder containing tests\n- `-f`: pass the fileset description, default is `files.f`\n- `-sim`: specify the simulator, `icarus` or `verilator`\n- `-main`: specify the C++ main file when using verilator, default is `sim_main.cpp`\n- `-define`: pass verilog defines to the tool, like `-define \"DEF1=2;DEF2;DEF3=3\"`\n- `-vpi`: specify a compiled VPI, for instance `-vpi \"-M. -mMyVPI\"`\n- `-dry-run`: print the commands but don't execute them\n- `-include`: to pass include path, several can be passed like `-include folder1 folder2`\n- `-no-splash`: don't print SVUT splash banner, printed by default\n- `-compile-only`: just compile the testbench, don't execute it\n- `-run-only`: just execute the testbench, if no executable found, also build it\n- `-fst`: dump waveform with FST format. If not specified use VCD format\n\nAll these arguments are common for both the simulators.\n\n# Tutorial\n\nCopy/paste this basic FFD model in a file named ffd.v into a new folder:\n\n```verilog\n`timescale 1 ns / 1 ps\n\nmodule ffd\n    (\n    input  wire aclk,\n    input  wire arstn,\n    input  wire d,\n    output reg  q\n    );\n\n    always @ (posedge aclk or negedge arstn) begin\n        if (arstn == 1'b0) q \u003c= 1'b0;\n        else q \u003c= d;\n    end\n\nendmodule\n```\n\nThen run:\n\n```bash\nsvutCreate ffd.v\n```\n\nffd\\_testbench.v has been dropped in the folder from you called svutCreate. It\ncontains all you need to start populating your testcases. In the header, you\ncan include directly your DUT file (uncomment):\n\n```verilog\n`include \"ffd.v\"\n```\n\nor you can store the path to your file into a `files.f` file, automatically\nrecognized by SVUT. Populate it with the files describing your IP. You can\nalso specify include folder in this way:\n\n```bash\n+incdir+$HOME/path/to/include/\n```\n\nRight after the module instance, you can use the example to generate a clock\n(to uncomment):\n\n```verilog\ninitial aclk = 0;\nalways #2 aclk = !aclk;\n```\n\nNext line explains how to dump your signals values into a VCD file to open a\nwaveform in GTKWave (uncomment):\n\n```verilog\ninitial $dumpvars(0, ffd_unit_test);\ninitial $dumpfile(\"ffd_testbench.vcd\");\n```\n\nTwo functions follow, `setup()` and `teardown()`. Use them to configure the\nenvironment of the testcases:\n- `setup()` is called before each testcase execution\n- `teardown()` is called after each testcase execution\n\nA testcase is enclosed between two specific defines:\n\n```verilog\n`UNIT_TEST(\"TESTNAME\")\n    ...\n`UNIT_TEST_END\n```\n\n`TESTNAME` is a string which will be displayed when test execution\nwill start. Then you can use the macros provided to display information,\nwarning, error and check some signals values. Each error encountered by a\nmacro increments a globla error counter which determine a testsuite status.\nIf the error counter is bigger than `0`, the test is considered as failed.\n\nA testsuite, comprising several `UNIT_TEST`, is declared with another define:\n\n```verilog\n`TEST_SUITE(\"SUITENAME\")\n    ...\n`TEST_SUITE_END\n```\n\nTo test the FFD, add the next line into `setup()` to drive the reset and init the\nFFD input:\n\n```verilog\narstn = 1'b0;\nd = 1'b0;\n#100;\narstn = 1'b1;\n```\n\nand into the testcase:\n\n```verilog\n`FAIL_IF(q);\n```\n\nHere is a basic unit test checking if the FFD output is `0` after reset. Once\ncalled `svutRun` in your shell, you should see something similar:\n\n\u003cp align=\"center\"\u003e\n  \u003c!--img width=\"100\" height=\"100\" src=\"\"--\u003e\n  \u003cimg src=\"readme.jpg\"\u003e\n\u003c/p\u003e\n\nSVUT relies (optionally) on files.f to declare the fileset and define. Follows an example:\n\n```\n...\n+define+MY_DEFINE_SIM1\n+define+MY_DEFINE_SIM2=723\n./ffd.sv\n+incdir+$HOME/work/mylib\n...\n```\n\nThe user can also choose to pass define in the command line, common for both the simulator:\n\n```bash\nsvutRun -test my_testbench.sv -define \"DEF1=1;DEF2;DEF3=3\"\n```\n\nSVUT doesn't check possible collision between define passed in command line\nand the others defined in `files.f`. Double check that point if unexpected\nbehavior occurs during testbench.\n\nFinally, SVUT supports VPI for Icarus. Follow an example to compile and set up\nthe flow of an hypothetic UART, compiled with iverilog and using a define \"PORT\":\n\n```bash\niverilog-vpi uart.c\nsvutRun -vpi \"-M. -muart\" -define \"PORT=3333\" -t ./my_testbench.sv \u0026\n```\n\nNow you know the basics of SVUT. The generated testbench provides prototypes of\navailable macros. Try them and play around to test SVUT. You can find these\nfiles into the example folder.\n\nEnjoy!\n\n\n## License\n\nCopyright 2024 The SVUT Authors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.  imitations under the License.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpretet%2Fsvut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpretet%2Fsvut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpretet%2Fsvut/lists"}