Hog Continuous Integration¶

Hog Continuous Integration (CI) makes use of the Gitlab CI/CD tool. The main features of Hog CI are:

Control that merging branches are up-to-date with targets
Create and builds Vivado projects
Generate FPGA binary and report files with embedded git commit SHA
Automatically generate VHDL code documentation using doxygen
If configured, store IP generated files and implementation project results in a user-defined EOS folder
Automatically tag the Gitlab repository and, if enabled, create a release with the binary files and auto-produced changelog

Three pipelines are employed, triggered by the following actions:

Merge Request Pipeline: triggered by each commit into a non-Draft merge request branch
Master Pipeline: triggered by each commit into the master branch
Tag Pipeline: triggered by the creation of a new official tag (starting with “v*”)

Merge Request Pipeline¶

The Merge Request pipeline simulates, synthesises and implements the chosen HDL projects. If specified, it stores the resulting outputs to an EOS repository and creates the doxygen documentation.

The stages of the Merge Request pipeline are the following:

Merge: checks that all the required Hog environmental variables are set up and that the source branch is not outdated with respect to the target branch. If it is, the pipeline fails and asks the user to update the source branch.
Generation: the workflow of all the projects is launched.
Collect: Collects all the artefacts from the previous stages and, if enabled, produces the Doxygen documentation. If EOS is used, it copies the implementation outputs and the Doxygen documentation to the EOS repository.

During the generation step, Hog-CI performs the following steps:

Creates a Vivado/Quartus project for each project specified in the .gitlab-ci.yml file. It checks also that the Hog submodule in the repository is the same as the one specified in the CI configuration file. Finally, for Vivado projects, it checks the syntax of the HDL codes, before moving to the next stage.
Optionally handles the IPs, only if the option to use the EOS repository to store the IP results and retrieve them is enabled via the HOG_IP_EOS_PATH environment variable.
Synthesises the projects. An option to run only up to the synthesis stage is available.
Implements the projects and creates the bitstreams. An option to disable the bitstream creation is available. During this stage the implementation timing results and project version are also written in the merge request page.

A new feature of Gitlab-CI allows to run also dynamically-generated CIs. This feature is still in a preliminary status, therefore it is not advised to use it in your main project. Nevertheless, from Hog 2020.2 a novel dynamically-generated CI can be employed. For more details, refer to the Dynamic CI Section.

Moreover, from Hog2021.1, users can also add custom jobs to the MR pipeline, before and after the Generation stage, and after the Collect stage. For more details, see the Custom User CI Stages section.

Master Pipeline¶

The Master pipeline consists only of one stage (Merge), which tags the repository according to the Merge Request description. Assuming the latest tag was vA.B.C, the pipeline will

increase A, if the MR description contains the keyword “MAJOR_VERSION”
increase B, if the MR description contains the keyword “MINOR_VERSION”
increase C, in the other cases.

Tag Pipeline¶

The Tag pipeline, is triggered by the Master pipeline when the official Tag is created.

The goal of this pipeline is to create a release (if enabled) and archive the product of the firmware workflow, including the binary files. On the Release the timing results and the project versions are also added.

If EOS is enabled, Hog-CI also copies the binary files and logs to the EOS official storage, creating a new sub-folder with the name of the new tag.