Continuous integration with VHDL

Skippable introduction

During this lockdown (like almost everyone) I have a lot of free time, so I decided to give a look at my to do list. In the looong term goals part where you can find impossible goals like "save the world" or "learn haskell" there was "learn vhdl", too.

Now or never

That's what I thought. So here I am, reading the awesome free range vhdl book and getting started with the first examples. I am debugging my nonsense signals produced by my nonsense code with Vivado WebPACK, which has some limitations, but it's free and it's a decent tool if you are learning.

Why writing tests

Anyway, getting the output right and going to the next exercise reminded me of old dark ages when I was hacking my main and adding print everywhere to know if my code was working. Yes, your code might work now, when the sun is high and you haven't touched a single comma of your codebase. But what if new requirements comes in or you have to fix a bug? You will unavoidably have to change your code. At that point how will you be sure that you didn't break anything?

Yes, tests is the right answer. 💯 And once you get used to them I can ensure you will never go back! In particular, I get used to repeatable tests and big green check marks that ensure you that your program does not work only on your computer and that you haven't forget to git add some files.

So I thought: "why don't I try to setup Continuous integration for a VHDL project?" 😀


Disclaimer: I am not a VHDL expert, please double check everything you are going to read

Easy, right? Unfortunately there was no GitHub actions that matched the word "vhdl" on the github actions marketplace. And there's a very good reason for that. Hardware description languages like VHDL or Verilog are not like common programming languages where nowadays everything is open source. Most of the people, uses whatever the FPGA maker provides them, which includes proprietary libraries and so on and of course this stuff is not intended to be used with docker and things like that.

Anyway, for my simple examples I didn't need vendor proprietary libraries, therefore I was free to explore open source solutions to run and tests my code 😀

I choose to use ghdl (an open-source simulator for the VHDL language) and vunit (an open source unit testing framework for VHDL/SystemVerilog).

It turns out that there is a really handy docker image hosted on the docker hub, which provides both vunit and ghdl.

It was super easy to create a GitHub action based on this image, so meet Vunit Action, a GitHub action that let you do CI with your VHDL projects! You can find how I used this action in my vhdl examples.

So yes, finally there is at least one match for the word "vhdl" in the Github action Marketplace 😅

EDIT: Lars Asplund (VUnit maintainer) contacted me and we moved the github action under the VUnit github organisation. You can find the action here 🎉