Example GitLab Project#

An example Hog-handled repository is available at hog-cern/hog-examples.

Clone the Repository#

To clone the repository, run the following commands in a terminal:

mkdir Workdir
cd Workdir
git clone --recursive https://gitlab.com/hog-cern/hog-examples.git

Repository Structure#

~/Work/Hog/hog-examples/ [main] tree -L 1
.
├── BD                     # Vivado Block Design Folder
├── diamond                # Lattice Diamond HDL source files
├── dlx                    # GHDL project's source files
├── example_max10          # Quartus project's source files
├── Hog                    # Hog Submodule
├── hog-commands           # Custom Hog's commands
├── IP                     # Vivado/Quartus IP Folder
├── IP_repository          # Vivado User IP Repository
├── README.md              # Readme file
├── sources                # Vivado/Libero HDL sources
├── Top                    # Hog Top Project Folder
└── vpk120                 # Versal HDL soures

The repository contains several example Hog projects for different IDEs, and it is already set up to run Hog-CI. Inside the Top folder, projects are grouped by IDE:

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/
Top
├── diamond               # Diamond Projects
├── ghdl                  # GHDL Projects
├── ise                   # ISE/PlanAhead Projects
├── libero                # Libero Projects
├── quartus               # Quartus Projects
├── repo.conf             # Hog Repository Configuration File
└── vivado                # Vivado Projects

Vivado Projects#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/vivado
Top/vivado
├── abacus      # Digilent Basys3 Abacus Project
├── bd_design   # Project with a block design (.bd file)
├── bd_tcl      # Block design created using BD/bd.tcl script
├── fifo        # Project containing an IP block (.xci)
├── microblaze  # Block design with MicroBlaze processor, created using post-creation.tcl
├── proj.1      # Variant of the fifo project using Hog Flavour feature
├── proj.2      # Variant of proj.1 with flavour number set to 2
└── vpk120      # Example Versal project

To run a Vivado project, ensure Vivado 2022.2 is in your path. To use a different version, modify the first line of the corresponding Top/vivado/<proj>/hog.conf file.

To create a Vivado project (e.g., abacus), run:

./Hog/Do CREATE vivado/abacus

This will create the project in Projects/vivado/abacus/abacus.xpr. You can open it with the Vivado GUI or run the workflow from the command line:

./Hog/Do WORKFLOW vivado/abacus

This approach applies to all other projects. Check the Hog console logs to better understand the workflow.

Vivado-Vitis Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/vivado-vitis
Top/vivado_vitis
└── classic_zynqmp  # Example Vivado and Vitis Classic project for ZYNQ MPSoC

To run the projects, you need to have Vivado 2022.2 and Vitis 2022.2 available in your path. If you wish, to run another Vivado version, simply modify the first line of the corresponding Top/vivado_vitis/<proj>/hog.conf file. Note that Vivado Classic is not supported for versions after 2023.2.

Explore the content of each project, to well understand how Hog handles the different source files. To create a complete Vivado-Vitis project, e.g. for the vivado_vitis/classic_zynqmp project, run the command below from the main path of your repository:

./Hog/Do CREATE vivado_vitis/classic_zynqmp

This will create a folder Projects/vivado_vitis/classic_zynqmp, where the Vivado project classic_zynqmp.xpr will be created, and another folder Projects/vivado_vitis/classic_zynqmp/vitis_classic with the Vitis workspace.

Optionally, if you only want to create a Vivado project, run the command below from the main path of your repository:

./Hog/Do CREATE vivado/vivado_vitis_zynqmp --vivado_only

Or similarly, if you only want to create a Vitis project, run the command below from the main path of your repository:

./Hog/Do CREATE vivado_vitis/classic_zynqmp --vitis_only

You can then open the Vivado or Vitis projects with the respcective GUIs, or launching the Vivado synthesis and implementaition as well as the Vitis build workflow with the Do command:

./Hog/Do WORKFLOW vivado_vitis/classic_zynqmp

Optionally, if you only want to build the Vitis project, run the command below from the main path of your repository:

./Hog/Do CREATE vivado/vivado_vitis_zynqmp --vivado_only

Quartus Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/quartus
Top/quartus
└── example_max10 # Project with a simple counter, PLL .qip file, and .qsys files

To run the project, ensure Quartus 23.1 is in your path. To create and build the project:

./Hog/Do CREATE quartus/example_max10
./Hog/Do WORKFLOW quartus/example_max10

You can also open the project in the Quartus GUI. The project file is located at Projects/quartus/example_max10/example_max10.qpf.

Libero Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/libero
Top/libero
└── example_libero # Project with a simple adder and FIFO IP created via post-creation.tcl

To run the project, ensure Libero SoC 2022.2.0.10 is in your path. To create and build the project:

./Hog/Do CREATE libero/example_libero
./Hog/Do WORKFLOW libero/example_libero

You can also open the project in the Libero GUI. The project file is at Projects/libero/example_libero/example_libero.prjx.

ISE/PlanAhead Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/ise
Top/ise
└── example_planAhead

To run the project, ensure ISE 14 is in your path. To create and build the project:

./Hog/Do CREATE ise/example_planAhead
./Hog/Do WORKFLOW ise/example_planAhead

You can also open the project in the ISE GUI. The project is stored in Projects/ise/example_planAhead.

Diamond Project#

➜  hog-examples git:(ghdl) ✗ tree -L 1 Top/diamond
Top/diamond
└── example_diamond

To run the project, ensure Diamond 3.14 is in your path. To create and build the project:

./Hog/Do CREATE diamond/example_diamond
./Hog/Do WORKFLOW diamond/example_diamond

You can also open the project in the ISE GUI. The project is stored in Projects/diamond/example_diamond.

GHDL Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/ghdl
Top/ghdl

To simulate the project with GHDL, ensure GHDL is in your path and tcllib is installed. To run the simulation:

./Hog/Do SIM ghdl

Continuous Integration#

Hog-CI is set up for this repository using static pipelines. See the .gitlab-ci.yml for configuration details. This main configuration file includes the individual CI configuration YAML files for each project. For example:

include:
  - local: 'Top/vivado/fifo/gitlab-ci.yml'

This includes the configuration for the vivado/fifo project. Each individual configuration file specifies which jobs will be run. For example, for the vivado/fifo project:

GEN:vivado/fifo:
    extends: .generate_project
    variables:
      extends: .vars
      PROJECT_NAME: vivado/fifo

SIM:vivado/fifo:
    extends: .simulate_project
    variables:
      extends: .vars
      PROJECT_NAME: vivado/fifo

The main .gitlab-ci.yml also contains global variable settings, which are propagated to each stage. These variables can be overwritten in the variables section of each job configuration.

Note

Variables set in the GitLab CI/CD settings of the repository cannot be overwritten in the YAML configurations.

This setup results in build and simulation jobs being run in the CI. You can see an example pipeline at this link.

Dynamic CI#

A merge request is open in the repository to configure Hog-CI using the dynamic GitLab CI/CD feature. See the updated .gitlab-ci.yml for a simpler and more flexible configuration.