Hog: HDL on git

Introduction

Coordinating firmware development among many international collaborators is becoming a very widespread problem. Guaranteeing firmware synthesis with Place and Route reproducibility and assuring traceability of binary files is paramount.

Hog tackles these issues by exploiting advanced git features and integrating itself with HDL IDEs: Xilinx Vivado, Xilinx ISE (planAhead)[1], Intel Quartus[2], Microchip Libero[3]. The integration with these tools intends to reduce as much as possible useless overhead work for the developers.

If you want to be informed of any published Hog release, please register to our Newsletter.

What’s new in Hog 2023.1?

The main features included in this new release are:

• Reduced Hog printouts and included -verbose option

• Define and pass user generics to top module (Xilinx and Libero) and top simulation files. Please refer to the generics sections of the project and simulation configuration file chapters, for more details.

• Added support to Microchip Libero SoC. More details on how to use Hog with Libero are described in the dedicated chapter.

• Added option to run the Hog-CI with Apptainer or Docker images. For the instructions, have a look at the dedicated chapter in the CI section.

• Support to multiple release branches and new automatic tagging scheme. More informations here.

• The IP handling system (copying synthesised IPs to/from EOS or a local directory) was improved. The description of the Hog IP handling is available in the dedicated chapter.

• Support to GitHub actions to run the Hog-CI. The documentation on how to setup GitHub to run the Hog-CI are available in the specific chapter.

What is Hog?

Hog is a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a Git repository.

Hog is included as a submodule in the HDL repository in a Hog directory and allows developers to create the Vivado/PlanAhead/Quartus/Libero project(s) locally and synthesise/implement it or start working on it.

The main features of Hog are:

• a simple and effective way to maintain HDL code on git

• ensure the code was not modified before building binary files

• ensure traceability of binary files (even if produced locally)

• multi-platform compatibility, working both with Windows and Linux

• reducing code duplication creating multiple projects sharing the same top level file

• compatibility and support for IPBus

• automatic creation of Sigasi project

Hog-CI features are:

• yaml files to run continuous integration in your Gitlab/GitHub repository

• automatic tag creation for versioning

• automatic GitLab/GitHub release creation (including timing and utilisation reports, changelog, and binary files)

• automatic changelog in the release note

• the possibility to store the output binary files on EOS

Everything is as transparent as we could think of. Hog is designed to use just a small fraction of your time to set up your local machine and get you to work to the HDL design as soon as possible.

Rationale

For synthesis and Place and Route (P&R) reproducibility, we need absolute control of:

• HDL source files

• Constraint files

• IDE settings (such as synthesis and implementation strategies)

For traceability, every time we produce a binary firmware file, we must:

• Know exactly how the binary files were produced

• Be able to go back to that point in the repository

To do this, Hog automatically embeds the git commit SHA into the binary file together with a more understandable numeric version M.m.p. Moreover, it automatically renames the file, including the version and inserts the hexadecimal value of the SHA so that it can be retrieved (using a text editor) in case files are renamed.

Another important principle in Hog is to reduce to the minimum the time needed for an external developer to get up to speed to work on an HDL project. For this reason, Hog does not rely on any external tool or library. Only git (from version 2.9.3) and on those tools you must already have to synthesise, implement (Vivado/PlanAhead/Quartus) and simulate (Modelsim/Questasim/Riviera) the design.

To start working on any project contained in a Gitlab repository handled with Hog, you just need to:

git clone --recursive <HDL repository>
cd <HDL repository>
./Hog/CreateProject.sh <project_name>

The project will appear in ./Projects/<project> and you can open it with your Vivado (ISE/Quartus) GUI.

Tip

If you don’t know the project name, just run ./Hog/CreateProject.sh and a list will be displayed.

What is in the Hog directory

The Hog directory contains several Tcl and Shell scripts.

E.g. you can run:

./Hog/Init.sh

to initialise the repository locally, following the instructions.

You can always have a look by yourself. Most of the scripts have a -h option to give you detailed instructions.

One of the most important script is

./Hog/CreateProject.sh <my_project>

that creates the Vivado/PlanAhead/Quartus/Libero project locally into the Projects directory. When creating the project, Hog integrates a set of Tcl scripts (contained in Hog/Tcl/integrated) into the IDE software. If you don’t know the project name, just launch ./Hog/CreateProject.sh to find out the names of the projects in the repository.

Another useful scripts is

./Hog/LaunchWorkflow.sh <my_project>

which runs the complete workflow of the desired HDL project, creating the binary files in the bin directory.

At last

./Hog/LaunchSimulation.sh <my_project>

runs the simulation workflow. Other scripts are stored inside the Hog/Tcl and Hog/Other directories.

Top directory

A directory called Top must be in the root of the repository and it contains a sub-directory for each Vivado/PlanAhead/Quartus project in the repository. These “project directories” can be arranged in a more complex structure of directories if needed.

Each of the project directories has a fixed easy-to-understand structure and contains everything that is needed to re-create the Vivado/PlanAhead/Quartus/Libero project locally, apart from the source files that can be stored anywhere in the repository.

Tip

Source files are the HDL files (.vhd, .v) but also the constraint files (.xdc, .sdc, .qsf, .tcl, …) and the IP files (.xci, .ip, .qip, …)

Contacts

Are you a git enthusiast? And a Tcl fan? Join us and read the Developing for Hog section.

To report a problem or suggest a feature, use the git issues in the Hog git repository. Please check in existing and solved issues before opening a new one.

For questions related to Hog, please get in touch with Hog support.

For anything related to this site, please get in touch with Davide Cieri

If you want to be informed of any published Hog release, please register to our Newsletter.

---

[1]

Hog provides a minimal support for earlier generations of Xilinx chips using the planAhead tool. The planAhead GUI is very similar to Vivado and should be very familiar to Vivado users. Under the hood it still uses the same tools as ISE but provides a Tcl-scriptable front-end that allows for easy integration with Hog. It has been tested only in version 14.7 and has some limitations, but does allow you to create, compile and keep track of the versioning of a project both locally and in the gitlab CI/CD.

[2]

Not all Hog features are supported for Quartus. If a feature described in the documentation is supported only by Xilinx IDEs, it is clearly stated. If some of the functions you are looking for are not cited in the documentation they might be scheduled for development in a future release

[3]

Libero SoC does not include a full version of the tcllib package, required by several functions in Hog. Developers must install tcllib on their machine, and set an environmental variable to tell Hog where to find the package. For Libero Hog does not provide support to core container files (e.g. .xci files in Vivado), so instead they must be generated by a Libero Tcl command which can be added to the Hog project using the post-creation.tcl file.