Hog general overview

In this section, we will describe how a project is set up using Hog locally and for the Continuous Integration (CI). We will make no assumptions on the code you already have. If you already have a repository with code in it, you can also refer to this section: How to convert existing project to hog.

Project directory structure

Hog relies on some fixed directories and file names in the HDL repository. A typical directory structure is shown in the following picture.

HDL source files, together with constraint files and simulation files can be located anywhere in the repository. In the example shown in the figure above, they are located in the myproj directory and, possibly, in the library_1 and library_2 directories.

Note

The HDL source files can be stored anywhere in the repository. It is not mandatory to follow the presented folder structure. A Hog-based repository requires only the Hog submodule and a Top folder, organised as explained in the following paragraph.

A Hog-handled repository can contain multiple (Vivado/Quartus) projects, each of them corresponding to a subdirectory of the Top folder. Each one of these subfolders is referred to as the “top project-directory”. In the figure above we have just one project called myproj. Each top project-directory must contain all of the following:

  • A tcl file that must have the same name as top project-folder (plus the .tcl extension). We will call this file the “project tcl file” or “project tcl script”.

  • A list subdirectory containing the so-called list files i.e. special text files containing the names of the source files to be included in the project.

In the figure, the project is called myproj hence the project tcl file is called myproj.tcl.

When you create the project, running the Hog/CreateProject.sh, Hog runs the project tcl file using Vivado or Quartus and creates the complete project in another directory, in our case Projects/myproj. In this directory, you will find the typical Vivado or Quartus file structure.

Multiple projects or multiple repositories?

As it is now clear, a Hog-handled repository can contain multiple projects. You may wonder when it is the case of having many projects in the same repository and when you want to create different repositories.

Using different projects in the same git repository

You should use many projects in the same repository when they share a significant amount of code. In this case, the version of the repository will be shared among all the projects. This is meaningful if the projects are strongly interconnected and it is unlikely for a project to change version without any modification to the others.

A typical use case is when the projects are intended for different devices (FPGAs) mounted on the same board.

To keep different parts of the project conceptually separated, it is possible to use many libraries as explained in the following. In this case, Hog evaluates the version (and the SHA) independently for each library, so it is possible to tell at a glance if two binary files share the same library.

For example, you can have an FPGA with an “infrastructure” library containing all the circuitry to handle communication with the external world, and an “algorithm” library, containing the actual part of the design that processes data. Hog libraries will allow you to tell if two different binary files are generated using the same source code for the algorithm but they have different infrastructure.

Using different git repositories

If you don’t have any code sharing between two HDL projects, or if the shared code is minimal, you may think of having different repositories.

In this case, everything will be decoupled, as the two repositories are two completely unlinked things. All that is explained in this guide will have to be done with both repositories and you can also, in principle, use two different versions of Hog.

In case you have a shared part of the code, to avoid code repetition, you can include the shared code as a git submodule. This must be a third git repository, also independent from the previous two.

If the code contained in the submodule is not meant to be working standalone, it is not necessary to include Hog in it.

Hog directory

The Hog repository should be included as a submodule into your HDL repository, following these rules:

  1. Hog must be in the root path of your repository

  2. The directory name must be “Hog”

Moreover, it is recommended not to include the submodule protocol explicitly, it is much better to inherit it from the repository Hog is included into.

To obtain this you can run the following commands in the root folder of your repository.

	git submodule add <protocol>://gitlab.cern.ch/Hog/Hog.git
	git config --file=.gitmodules submodule.Hog.url ../Hog/Hog.git
	git submodule sync
	git submodule update --init --recursive --remote

Remember to choose your protocol among ssh, https, git, or krb5. Also note that ../Hog/Hog.git must be replaced with the correct path, relative to your repository. A git error will be generated by git submodule update --init --recursive --remote if the path is not properly set. Alternatively, you could add the submodule normally and then edit the .gitmodules file, as explained here.

Source directories

Source directories contain HDL files used for synthesis. HDL files can be placed anywhere in your repository, but it is advised to arrange them according to their library1. We suggest putting HDL files belonging to separate libraries in separate folders although this is not mandatory. The exact structure or name of this folder is not enforced.

Top-level entity

The top module of your project must be called top_<project_name>. This module can be contained in any file stored anywhere in the repository as long as it is linked in a .src file.

Hog extracts repository information (git commit 7-digit SHA and numeric version stored in git tags) and feeds the resulting values to the design using VHDL generics or Verilog parameters. A full list of these can be found in the Hog generics section. A template for the top-level file (in VHDL and Verilog) is available in the Hog/Template directory. A full description of the templates can be found in the available templates section.

Git submodules

Hog is designed to handle git submodules with no additional effort, i.e. if you use some code contained in a git repository you can simply add it to your project using the standard git command:

    git submodule add <submodule_url>

Submodules can be placed anywhere in the repository and files can be added to your projects through Hog list files. normally2.

Top directory

The Top directory must be located in the root folder of the repository:

    Repo/Top

It contains one directory for each of your projects (say proj_1, proj_2, proj_3):

    Repo/Top/proj_1
    Repo/Top/proj_2
    Repo/Top/proj_3

As previously mentioned, these 3 directories are called the “top project-directories”.

Top project-directory

Each of the project directories must contain the tcl file that generates the project. The .tcl file contained in the project directory must contain the instructions to build your project. They must be named as follows:

    Repo/Top/<project_name>/<project_name>.tcl

To trigger all Hog functionalities, the last line of the tcl script must be:

    source $PATH_REPO/Hog/Tcl/create_project.tcl

A template for the <project_name>.tcl file is available in the Hog/Template directory. A full description of the template can be found in the available templates section. More information on the tcl script can be found in the project tcl file section.

If you want some custom operation to be performed before the project creation (e.g. you want to create a source file using a Tcl script), you can insert your instruction before this line. If you want some custom operation to be performed after the project is created, you can add the Tcl instruction after the create_project.tcl call. Do this at your own risk.

List directory

A directory named list must be in each of the top project-folders. This directory contains the list files, that are plain text files, used to instruct Hog on how to build your project. Each list file contains the names of the files to be added to the proj_1 project. Hog uses different kinds of list files, identified by their extension:

  • .src : used to include HDL files belonging to the same library

  • .sim : used to include files use for simulation of the same library

  • .con : used to include constraint files

  • .prop: used to set some Vivado properties, such as the number of threads used to build the project.

  • .ext : used to include HDL files belonging to an external library

Note

In .src, .sim, and .con list files, you must use paths relative to the repository location to the files to be included in the project.

Absolute or relative paths in .ext files?

By default .ext file use absolute paths. The only other option is to define the environmental variable HOG_EXTERNAL_PATH. If this is defined, Hog will interpret the entries in the .ext file as relative to HOG_EXTERNAL_PATH. To use the firmware Continuous Integration, external files must be accessible to the machine performing the git CI, e.g. can be on a protected afs folder.

More information on the list file can be found in the dedicated list files section.

IP files

The only file needed by Hog to handle an IP is the .xci file. It can be saved anywhere in the repository, but we suggest to store all the IPs in the same folder (e.g. repo/IP), since, for each folder containing IPs, you need to create also a .gitignore file ensuring that only the .xci file is committed to the Gitlab repository.

To add an IP core, that must be created in out-of-context mode. The .xci file shall be then saved in a folder with the same name (e.g. repo/IP/ip_name/ip_name.xci). Now you can add the .xci normally to any .src list file in the list folder of your project.

IP initialisation files (.coe)

Please note that the .gitignore template provided by Hog adds constraints on the IP folder. Out of all the files contained in repo/IP/ folder, git will pick up only .xci files. Files with different extensions will be ignored. If you have .coe files for RAM initialisation or analogous files, please make sure to store these files in a separate folder and point to them in the IP directory by using a relative path.

Auto-generated directories

The following directories are generated at different stages of library compilation or synthesis/implementation time. These directories should never be committed to the repository, for this reason, they are listed in the .gitignore file. You can always delete any of these directories with no big consequences: they can always be regenerated by Vivado/Quartus or Hog scripts.

The Projects folder

When you generate a project with Hog, it will create a sub-directory Projects here. When everything is generated, this directory contains one subdirectory for each project in the repository, containing the Vivado (Quartus) project-file .xpr (.qpf). The names of the sub-directory and the project file are always matching. In our case:

    Repo/Projects/proj_1/proj_1.xpr
    Repo/Projects/proj_2/proj_2.xpr
    Repo/Projects/proj_3/proj_3.xpr

The Repo/Projects/proj_3/ directory also contains Vivado automatically generated files, among which the Runs directory:

    Repo/Projects/proj_1/proj_1.runs/

That contains one sub-folder for every Vivado run with all the IPs in your project, the default Vivado synthesis run (synth_1) and implementation run (impl_1). Hog will also copy IPbus XMLs and generated binary files into Repo/Projects/proj_1/proj_1.runs/ at synthesis/implementation time.

SimulationLib

Modelsim or Questasim compiled libraries will be placed here and automatically linked to your project. The library compilation can be done automatically if the vsim executable is in your PATH and you launch the hog/Init.sh script.

Optional directories

Doxygen

The doxygen directory contains the files used to generate the HDL documentation. A file named doxygen.conf should be in this directory, together with all the files needed to generate your Doxygen documentation. VHDL is well supported with Doxygen version 1.8.13 ore later, so Hog will not use any older version.


1

The concept of library does not exist in Verilog and SystemVerilog

2

Before Hog version 2021.1, there used to be restrictions on where the submodule could be located in the repository and special list files were used to include files from submodules.