vunit-yavs

The yavs simulator for VUnit, as a VUnit package. Add it in the run script before anything else, then select yavs with VUNIT_SIMULATOR=yavs:

from vunit import VUnit

vu = VUnit.from_argv()
vu.add_package("vunit-yavs", allow_setup=True)  # first: it provides the simulator
vu.add_vhdl_builtins()
vu.add_library("lib").add_source_files("*.vhd")
vu.main()

pip install vunit-yavs
VUNIT_SIMULATOR=yavs python run.py

The guide goes from installing to running, debugging and coverage, and the debugger tutorial debugs a failing test with --yavs-debug, --yavs-surfer and --yavs-interactive. yavs is found on PATH, or in the directory named by VUNIT_YAVS_PATH. It needs VUnit 5.0.0.dev16 or later (pip install vunit-yavs installs it, a pre-release) and yavs 0.12.0 or later.

Options

Compiling: consecutive files of one library, standard and flags go to yavs analyze in one call. With a VUnit that has --batch-compile and --parallel-compile (5.0.0.dev16 does not have them), those flags work with yavs too (several files per call, several calls at once).

Without yavs.max_threads or --yavs-max-threads no thread count is passed, and yavs runs with its default, unless the token server runs (--threads=min(N, 4) for -p N, below). An explicit --threads in yavs.sim_flags comes after the cap and wins.

Coverage

vu.set_sim_option("enable_coverage", True)      # or run with --yavs-cov=sb
vu.set_sim_option("yavs.cov_kind", ["statement", "branch"])   # the kinds; none is on by default
vu.main(post_run=lambda results: results.merge_coverage("coverage"))

Each simulation writes a yavs coverage database named after its test (yavs run --cov-file). The kinds come from the yavs.cov_kind sim option, else --yavs-cov-kind, else the letters of --yavs-cov=LETTERS; the letters and --yavs-cov-kind are not given together. results.merge_coverage("coverage") merges them into coverage.ycov (yavs cov merge); with --yavs-cov-html DIR or --yavs-cov-fail-under PCT, or arguments in merge_coverage("coverage", args=["--cobertura", "c.xml"]), it then runs yavs cov report on the merged database. A total below the threshold makes the run exit with status 1 after VUnit has written its reports (a JUnit file included). For a CI gate:

VUNIT_SIMULATOR=yavs python run.py --yavs-cov=sbt --yavs-cov-html cov-html --yavs-cov-fail-under 85

Coverage cannot be combined with --yavs-debug. Reports, exclusions and the numbers are in the yavs documentation page on coverage. The coverage options need the yavs release that has yavs cov report --fail-under.

Native libraries of VUnit packages

A VUnit package that loads a native library can ask the simulator interface how: YavsInterface has foreign_language_interface = "VHPIDIRECT" (the VHDL calls the library through foreign subprograms with a "VHPIDIRECT ..." attribute) and native_library_hooks(library_file), which returns the simulator hooks that pass --load=<library_file> to every yavs elab and yavs run (so --elaborate works for a design that calls the library while it is elaborated); native_library_hooks(library_file, args="fat-pointer") selects that argument layout for the library (a run.py without a package gives --load=LIB:args=fat-pointer in yavs.elab_flags). A package registers them with context.register_simulator_hooks("yavs", **YavsInterface.native_library_hooks(library)). The repository's tests/project_foreign is a package that builds a C library, with Python embedded where the host allows it, and a testbench that calls Python from VHDL. A VHDL string reaches the library as one byte per character, and yavs reads a UTF-8 source file as Latin-1 characters: give --encoding=latin1 to yavs.a_flags and (as a sim option) to yavs.global_flags when the library needs the UTF-8 bytes of an accented literal.

Debugging one test

VUNIT_SIMULATOR=yavs python run.py lib.tb.test_name --yavs-debug

yavs waits for a Debug Adapter Protocol client on 127.0.0.1:4711 before the simulation starts; press F5 or run "yavs: Attach" in VS Code with the yavs extension: no launch configuration is needed. Set breakpoints in your own files: with location or check preprocessing on, the debugger maps the rewritten copies to them. When the session ends, the test is reported as usual.

--yavs-debug runs one simulation. A second simulation of the run (a second test, or the same test in another configuration) is an error before yavs starts, naming both tests. --yavs-debug together with --elaborate or -p above 1 is an error at the start. A bare --yavs-debug reads a following test name as its port: put test names first, or write --yavs-debug=4711.

Every simulation (not --yavs-interactive) is started with --exit-on-stdin-close: it ends when the pipe the runner keeps to its standard input closes, so killing only python run.py, even with SIGKILL, does not leave yavs waiting for a debugger on the port. The waves and coverage files of such a run are not finished.

Token server

With -p N --yavs-jobserver (Linux and Windows) the run script starts a token server on 127.0.0.1 and lends the CPU slots of -p N that no test uses to the running simulations. Every simulation runs with --threads=N (at most 4 unless yavs.max_threads or --yavs-max-threads says more) and gets YAVS_TOKENS=<port>:<secret>, a secret of its own; yavs runs its extra threads only on tokens the server lends, and asks for them only while it has work for them. One CPU slot per running test is free, the other N - k (for k running tests) are lent: breadth first (every test gets one extra before any gets a second) and newest test first within a round, at most yavs.max_threads - 1 per test. A token in use is never taken back, so a test that starts while every token is out runs at once: the total is N in the steady state, not at every instant. A simulation gives its tokens back when it stops using them and when it ends in any way, also when it is killed. The tail of a regression, a few long tests on a machine of idle slots, gets faster on designs whose processes run in parallel well. If the server cannot start (a blocked local socket) the run warns and every simulation uses one thread.

The console

VUNIT_SIMULATOR=yavs python run.py lib.tb.test_name --yavs-interactive

The test stops at time 0 at a yavs> prompt. All commands of the yavs console work (run, step, examine, force, break, restart, source, help, quit), and this package adds VUnit's own, which behave as in VUnit's other simulator interfaces. They are also in the Debug Console under --yavs-debug.

The yavs restart goes back to time 0 with the design as loaded; vunit_restart compiles first. Init files are files of console commands; $vunit_tb_path and $vunit_tb_name are replaced as VUnit defines them. When you quit, the test is reported as usual. A session that compiled at vunit_compile and failed keeps the old design loaded.

Licence

Mozilla Public License 2.0 (https://mozilla.org/MPL/2.0/), see the header of each file.