Introduction to VUnit

Michał Barczak, Application Engineer at Aldec

Like(0) Comments (0)

In the realms of HDL code verification, where precision and efficiency are crucial, a great hero has emerged; VUnit. This open-source framework for VHDL/SystemVerilog has been making waves in the industry, offering a unique approach to verification that promises to revolutionize the way we test and validate HDL code.

In this blog, we will explore how VUnit integrates seamlessly with Aldec’s Riviera-PRO simulator, and we will highlight the benefits of that integration. So, grab a seat, get comfortable, and let us dive into the world of VUnit and uncover its secrets.

What is VUnit?

VUnit stands out as an open-source framework designed to automate unit testing and verification in FPGA development. It features the functionality needed to realize continuous and automated testing of HDL code.

Importantly, VUnit does not replace traditional testing methodologies, it rather complements/enhances them by supporting a “test early and often” approach through automation. It provides a flexible and user-friendly environment for writing and running testbenches, enabling developers to easily validate their designs and catch bugs early in the development cycle.

VUnit reduces the overhead of testing by supporting automatic discovery of testbenches and compilation order as well as including libraries for common verification tasks. It improves the speed of development by supporting incremental compilation and by enabling large testbenches to be split up into smaller independent tests. Additionally, VUnit enhances project quality by enabling the execution of extensive regression suites on a continuous integration server.

Why Should We Use the VUnit Framework?

VUnit has become popular among engineers - both hobbyists and professionals - for several reasons; but here's why it stood out for me personally:

Streamlined Unit Testing and Verification Processes: VUnit simplifies the entire process, making it more efficient.
Efficient Multicore Operations: VUnit is optimized for multicore systems, speeding up simulations significantly.
Python-based: VUnit is developed in Python, one of the most widely used programming languages, which makes it easy to script and extend.
Plenty of Online Resources: There are many examples and tutorials available online to help you get started.
Active Maintenance and Support: The project is actively maintained by its founders, ensuring ongoing improvements.
Easy to Implement: The framework is user-friendly, with an intuitive interface that does not require extensive setup.
Open Source: The entire project is open source, making it accessible to everyone.
Advanced Features: VUnit offers a message-passing mechanism for communication between testbench components, debugging options, the ability to launch test cases in the simulator GUI, CI/CD server integration, and much more.

Enhancing Development with VUnit Integration in Aldec Simulators

Aldec's simulators, Riviera-PRO and Active-HDL, both offer robust support for VUnit features, making them valuable tools for developers. For Linux users, like me, Riviera-PRO stands out as a particularly attractive option. To dive deeper into this integration, let us explore a detailed block diagram that outlines the seamless workflow of VUnit with our simulators.

Figure 1: Block Diagram of VUnit with Aldec Simulators

Figure 1 illustrates the key components necessary for VUnit to operate effectively: built-in features, user-written HDL code files, simulator interface selection via the PATH variable, and Python script execution initiating VUnit's main function. This process leads to the launch of VUnit VHDL or SV runners, initiating simulation, verification, and testing procedures.

But how does it all come together in practice? Let us take a closer look at the topic.

How to Prepare a Project to Run with VUnit

In this blog post, our focus is on seamlessly integrating VUnit with VHDL projects. However, SystemVerilog users can find a guide on the official VUnit website here.

VUnit is lightweight. A typical setup adds eight lines to your normal testbench code and one extra line for each test case in that testbench. Everything is pure VHDL so it can be run without the run.py script if you want to. The typical run.py script is four lines of code plus one extra line for each VHDL library you want to create and each directory where you want the test runner to scan for source files.

Imagine you have a design consisting of multiple source files and a single testbench file. To enhance organization, place your source files in a directory named 'src' and your testbench file in another named 'tb'. You will need a Python script to connect everything and run VUnit.

Writing the Python run-script

This script is often referred to as a Python run-script or test runner. Let us name it 'run.py'. Do not worry if you are not well-versed in Python; it is more like a copy and paste exercise. Figure 2 shows the basic structure of the script file, and we will examine the most important lines. Prepare the script and place it in the same directory as your 'src' and 'tb' directories.

Figure 2: Base VUnit run.py Script for HDL Simulation

Now, let us discuss some key points:

Line 4 - this imports the VUnit library.
Line 7 - then we create VUnit instance.
Line 11 - next we add the built-in utilities. Note: ensure you use vu.add_sv_builtins() if your project includes SystemVerilog sources.
Line 14 – this creates a library that includes all source and testbench files.
Lines 17 and 20 add these sources to the library.
Line 23 - sets an additional simulation option to enable data profiling during simulation.
Line 26 - this completes the process by running the main VUnit function; which scans all HDL files, resolves dependencies, compiles necessary files in correct order, and identifies testbenches and test cases.

This concludes our overview of the Python run script. For further details on simulation and compilation options, refer to the official VUnit GitHub page here and Aldec's Riviera-PRO online documentation here.

Modifying Your Testbench for VUnit

Next, modify your existing testbench slightly to make it compatible with the Python run script. VUnit provides a structured approach that automates much of this setup. Refer to the example testbench structure below for guidance.

Figure 3: Base VHDL Testbench File Compatible with VUnit

The testbench should begin by including the VUnit context and declaring the entity. Within the entity, the runner_cfg should be declared as a generic. This configuration enables you to customize settings during the simulation run. For example, you can specify the output files directory using the runner configuration.

Ensure your testbench includes a call to test_runner_setup() at the start of the simulation and ends with test_runner_cleanup() to terminate it properly. Between these calls, you should place your main simulation process code.

The typical operation of unit testing is to divide the testbench into smaller test cases, i.e., a test suite. To do this you need a while loop with if and elsif statements. Only one if statement will be active in each iteration. Each if statement is an independent test. If you want to have some shared data for tests you need to place it outside of the while loop.

Remember to remove any testbench termination code such as calls to std.env.finish, or end-of-simulation assertions; a VUnit testbench must conclude with test_runner_cleanup() call.

For more detailed information, visit the VUnit user guide here.

Summary and Conclusion

In conclusion, VUnit is a game-changer in HDL verification, offering a flexible and efficient framework that enhances the testing and validation of HDL code.

With its seamless integration with simulators like Aldec’s Active-HDL and Riviera-PRO, VUnit simplifies automated unit testing, enabling engineers to catch bugs early and improve overall code quality. Also, its open-source nature, combined with a vibrant community, ensures continuous evolution to meet the ever-changing needs of FPGA development.

By adopting VUnit, you streamline your workflow, leveraging features like multithreaded processing and incremental compilation to accelerate development cycles. Whether you are an experienced engineer or just starting, VUnit equips you with the tools to elevate your projects and achieve higher standards in HDL design and verification.

If you are not currently using Active-HDL or Riviera-PRO, you can request free evaluation licenses for fully functional versions of the tools here.

If you are ready to further explore VUnit and walk through the example, we invite you to visit the next blog in this series by clicking here.