Introducing the open-source system for handling your HDL code on Git
Dr Francesco Gonnella, Birmingham University
Managing HDL code for FPGAs on Git needs particular attention, mainly because the tools to develop it are proprietary and they tend not to be Git friendly. As a result, when you copy HDL projects to Git and try to recreate them, questions often arise like “I haven’t touched anything, so why doesn’t it work?”.
What you want instead is certainty. You want to be absolutely sure that when people clone your repository from Git, they get exactly what they expect, without hidden changes. And the reverse is just as important: knowing what’s actually running on the device. A lab build may be working today, but tomorrow it fails and no one is sure which version it was. You need a way to guarantee traceability, while keeping overhead as low as possible and letting engineers work in the way they’re used to.
Why not just commit everything to Git?
You could, but even Xilinx recommends against committing project files directly. Instead, you need to create a Tool Command Language (Tcl) script that recreates the project locally and many engineers already have custom scripts to do this. But what’s in the project files and why can’t we just put them on Git?
The problem is hard-coded paths which you’ll see in files from vendors like AMD, Altera, Lattice and Microchip. Sometimes they’re self-repairing and Vivado, for example, will fix them and in doing so change them. We don’t want that. We want nothing to be touched and the repository to remain pristine by committing to Git only those files that are needed, not everything from the project folder, which makes it easier to track and debug. The same principle applies to IP cores. Xilinx IP, for example, generates many files that shouldn’t be committed and sometimes can’t be because they require licenses to regenerate. We don’t want this. We want a way to automatically ignore self-generated files and ensure they can be regenerated consistently.
The second problem is certifying that files are truly untouched compared to the repository. Even with good intentions, people say, “I only changed this one thing so it shouldn’t matter.” But it does. That’s why the process must be automatic.
Time to think about Hog
All of the problems I’ve talked about are why we created Hog at CERN. We started by using a Tcl script to recreate projects locally but then we started looking for a better approach. One where we could automatically go from repository → files → build → chip in a reproducible way, and back again from the binary file on the FPGA to the exact source that produced it. We also wanted registers in the device to embed identifiers that link a binary back to its repository version, so we always know what’s running and where to start if changes are needed.
Welcome to Hog which does all of this by embedding the Git commit Simple Hashing Algorithm (SHA) into the binary file and checking that nothing has been touched.
Every binary file produced is also traceable to its source commit. In Continuous Integration (CI) pipelines this happens automatically, but even local builds are checked. If files were changed without being committed, Hog will detect it and prevent the binary from being claimed as clean. In this way, reproducibility is guaranteed.
If you commit, everything is fine. If you don’t, Hog will flag it. And importantly, it requires no extra installations. Engineers often ask, “Why do I need Python or other tools if I only use Vivado?” With Hog, you don’t. All you need is Git and your FPGA toolchain. It runs inside the Tcl shell of Vivado and other IDEs like Altera, Libero, and Diamond. Another principle is ease of collaboration: when you invite someone to join a project, they shouldn’t spend days setting up. They should be able to clone the repository, run the script, and start working immediately.
What you need to use Hog
At its core, Hog is just a set of Tcl scripts less than a megabyte in size and a methodology, a set of prescriptions to follow. You only need what you would need anyway: your source files to build the project (VHDL, Verilog, IPs, and constraints), plus a list of the files that are needed for a project. Since a repository may contain multiple projects or extra files, you also need to list the ones that you want to use. These lists are simple text files. They can also include properties such as “VHDL 2008” or “not used in implementation,” along with project-wide settings like the target FPGA or maximum fan-out. Hog defines where this information should be stored, and ensures it is committed to the repository.
The main feature of Hog is that it runs inside the Tcl shell of the FPGA tools you already use, so there are no extra requirements. You simply add Hog as a Git submodule, no installation is needed, and collaborators don’t need to install anything either. If Hog is updated, you choose when to update your submodule, so your project isn’t broken by changes. This guarantees reproducibility by controlling the files, and traceability by marking each binary with the SHA file that you can follow back to the repository. Equally important, Hog provides ready-made YAML scripts for CI with GitLab or GitHub Actions. With the FPGA tools available on the CI machine, setting up CI is just a matter of writing a few lines of YAML.
In a typical installation, Hog runs on a standard PC with only Vivado installed. You simply clone the repository, enter it, and use the ./Hog/Do VIEW command to see all the project files.
If you want to create the project, you then use the ./Hog/Do CREATE command and Hog rebuilds it locally from the list files and you can then open it in Vivado and work in the GUI as usual. It also works on Linux and Windows, since it runs inside the IDE itself. Git works locally, of course, but you can also use GitHub or GitLab. Hog mainly supports AMD tools, but also works with Altera, Lattice, and Microchip. In some cases you need additional installs because those tools don’t embed Tcl libraries, but the principle is the same.
Finally, for the repository structure Hog requires a particular set of folders. The HDL code itself can be placed wherever you like, and each project sits under a top folder, with subfolders containing the list files and configuration. The idea is to make the workflow correct and reproducible.
How to get started with Hog
Hog is free to use and open-source, and there are two ways to get started: writing the text files by hand or automatically producing them using the Hog buttons in the Vivado GUI. If you create the txt files by hand, you need to list the files used in your project in “.src” text files contained in ./Top/<my_project>/list/. To specify your project’s property you need to create a TOML-style configuration file called ./Top/<my_project>/hog.conf. This is expected to contain a few basic variables with the information needed to build your project. You can define properties such as the target FPGA and, at its simplest, you only need to specify the device, although you can add other settings to match your project (see Figure 2).
Where to go next
Hog is already used by several academic and industrial projects including ATLAS, CMS Phase-I and Phase-II upgrades, ESRF, GAPS, FOOT, NASDAQ and NOKIA.
It’s available at gitlab.com/hog-cern/hog and the documentation can be found at cern.ch/hog. If you’d like to try it:> git clone –recursive https://gitlab.com/hog-cern/hog-examples.git > cd hog-examples > ./Hog/Do CREATE vivado/fifo > vivado ./Projects/vivado/fifo/fifo.xpr
Hog is completely free and developed mainly as a pet project by Davide Cieri and Francesco Gonnella. If you use it, please cite our paper in your articles and proceedings. Here is the citation in BibTeX format.
