Working with an Existing Hog-Handled Repository

This section is intended for developers who are starting to work with an existing HDL project managed by Hog.

All the instructions below can be executed either in a Linux shell or in Git Bash on a Windows machine.

Tip

To open a Git Bash session, navigate to the desired directory, right-click on the folder, and select “Open Git Bash here.”

For all of the following steps to work, the Vivado (or Quartus/PlanAhead/Libero/Diamond) executable must be in your PATH environment variable. That is, if you type vivado in your terminal, the program should start. If you intend to use ModelSim, QuestaSim, Riviera, or another Xilinx-supported simulation software, the vsim executable must also be in your PATH.

Requirements

• Git (version 2.9.3 or greater) installed, and basic knowledge of git.

• Vivado, PlanAhead, Quartus, Libero, Diamond or GHDL installed and in the PATH.

  • Libero, Diamond and GHDL require also tcllib to be installed in your system.

• If using third-party simulators with Vivado, you also need to have vsim in the PATH.

Cloning the Repository

First, clone the repository (referred to as repo from now on). Go to the repository website, choose your preferred protocol (ssh, https, krb5), and copy the clone link.

git clone --recursive <protocol>://gitlab.com/repo.git

Now you have all the source code and scripts you need in the repo folder.

Note

Choose the protocol that works for you: ssh, https, or krb5. The --recursive option automatically clones all included submodules. While an HDL repository may or may not include other submodules, the Hog scripts are always included as a submodule. If you cloned the repository without the --recursive option (or if it did not work, which can happen on Windows), you will need to initialize and update the submodules manually:

git submodule init
git submodule update

Creating IDE Projects

To start working, create the IDE project you are interested in (let’s call it project1). Navigate into the repository and run:

./Hog/Do CREATE project1

This will create the project in the Projects/project1 directory. Inside this directory, you will find the Vivado .xpr file (or the Quartus .qpf or PlanAhead .xise file).

You can now open the project file with the GUI and synthesise/implement the project.

Note

In the Quartus GUI, you must always run a full compile process after creating a new project; otherwise, the synthesis process will fail. Due to the Quartus structure, only running the full compilation flow ensures that Hog generics are properly set.

If you do not know the project name, run ./Hog/Do LIST to see a list of existing projects in the repository.

To create all projects in the repository, you can run the Hog initialisation script:

./Hog/Init.sh

This script can also compile ModelSim/QuestaSim/Riviera libraries, add custom Hog buttons to the Vivado GUI, and convert existing HDL projects to Hog.

Adding a New File to the Project

When you open project1, you can work with the GUI (almost) as usual.

The Hog/Do script you ran has integrated Hog’s Tcl scripts into the Vivado/PlanAhead/Quartus project. From now on, Hog scripts will run automatically every time you start the compilation workflow or any step in the workflow. In particular, the pre-synthesis script will interact with your local git repository and embed its version and git commit SHA into your HDL project.

We say almost as usual because there is one exception: modifying the IDE project structure (e.g., changing project properties or adding/renaming project files).

Adding a new file (HDL code, constraint, IP, etc.) to the project using the GUI is not enough. You must also add the file name to one of Hog’s list files, as explained below.

Suppose you want to add a new file located at repo/dir1/file1.hdl.

First, add the new file (unknown to git) to the repository:

cd repo
git add ./dir1/file1.hdl
git commit -m "Add new file file1.hdl"
git push

Now that the file is safely on git, you need to add it to the Hog project so that other developers who clone the repository will see the file in their project.

Note

Not all files in the git repository are part of a project: there can be non-HDL files, obsolete files, or new files not ready for use. Some files may be part of one project but not another. For example, the repository could contain project2 and project3, each using different subsets of files.

This is a new file, unknown to Hog for now, and you want it to be included in the project the next time you run the Hog/Do script. To do this, add the file name and path of file1.hdl to a Hog list file. The list files are located in repo/Top/project1/list/.

Manually Updating the List File

Assume the list file you want to update is lib1.src. Open the file with a text editor and add the file name and path on a new line.

Now that the new file is included in a list file, you can close the project and recreate it by running ./Hog/Do CREATE <project name> again.

There is also a quicker option: add the file with the GUI and add it to a .src list file. If you do this in Vivado, make sure to select the correct library when adding the file. The library must have the same name as the .src file to which you added the source file. In our example, the HDL file was added to lib1.src, so the library to choose is lib1. You can select the library in the Vivado GUI from a drop-down menu when adding the file.

This procedure is valid for any kind of source file. If your file is a constraint file, add it to a .con list file in the list directory, e.g., repo/Top/project1/list/lib1.con.

Renaming a File Already in the Project

If you need to rename or move a file (e.g., from path1/f1.hdl to path2/f2.hdl), do so and update the name in the appropriate list file.

Don’t forget to rename the file in git as well:

git mv path1/f1.hdl path2/f2.hdl
git commit -m "Renamed f1.hdl to f2.hdl"
git push

Changing a Project Property

If you change a project property in the GUI, make sure the change is propagated to the repository. To do this, modify the hog.conf file of the specific project and add or update the property.

Generally, the easiest way is to copy and adapt what Vivado/Quartus/ISE writes in the Tcl console when you change the property. This helps you find the exact property name and value.

For more details about the hog.conf file, see the dedicated section in the Hog manual.

Tip

An easy way to check if you have modified hog.conf correctly is to close the project and recreate it using ./Hog/Do CREATE <project>. When you open the project again, verify that the property you modified is set as intended.

What Can Go Wrong?

If you make a mistake (e.g., add a non-existent file, create a list file with an invalid extension, etc.), you will get an error when you run the Hog/Do script. Read Hog’s error message and try to fix the issue.

If you make a mistake with Vivado libraries or forget to update the list files, the error will appear at synthesis time because Vivado will not be able to find the component.

Automatically Updating Hog Files

Warning

This feature is currently only supported for Vivado.

Hog provides a Tcl script (check_list_files.tcl) to help manage list and hog.conf files.

Users can work normally within the Vivado GUI, adding new files to projects (and selecting the proper library). Afterwards, they can automatically update the list and configuration files using the Hog buttons:

To check if the list files and hog.conf file are up to date, click the CHK button or run the following command (from a bash console):

vivado -mode batch -notrace -source <repository_path>/Hog/Tcl/utils/check_list_files.tcl -tclargs -project <project name>

Automatically Update List Files

To update the sources and constraint list files, click the Hog LIST button on the Vivado toolbar or run:

vivado -mode batch -notrace -source <repository_path>/Hog/Tcl/utils/check_list_files.tcl -tclargs -project <project name> -recreate -force

Note

• New VHDL files will be added to repo/Top/<project>/list/<library>.src

• New constraint files will be added to repo/Top/<project>/list/default.con

• Other files (Verilog, IPs, etc.) will be added to repo/Top/<project>/list/default.src

Automatically Update Simulations

To update the simulation list files, click the Hog SIM button on the Vivado toolbar or run:

vivado -mode batch -notrace -source <repository_path>/Hog/Tcl/utils/check_list_files.tcl -tclargs -project <project name> -recreate_sim -force

Note

This will update both the source files used for simulation and its properties.

Automatically Update hog.conf

If you change a project property (e.g., synthesis or implementation strategy, maximum fanout), update the hog.conf file to ensure the modification is propagated to the repository. You can either click the CONF button on the Vivado toolbar or run:

vivado -mode batch -notrace -source <repository_path>/Hog/Tcl/utils/check_list_files.tcl -tclargs -project <project name> -recreate_conf -force

Adding a New IP

To add a new IP core (e.g., my_ip1), create it in out-of-context mode and save the .xci file (and only that) in a subfolder of your repository.

Similarly, for Quartus, you can add the .ip file to your repository. If your target FPGA only supports .qip files (e.g., Intel Max10 FPGAs), you must add the folder in which the IP was generated to your project.

Note

You can store IPs anywhere in your repository.

For example: repo/some_folder/my_ip1/my_ip1.xci. Pay particular attention to the .gitignore file.

When Vivado synthesises IPs, it creates many additional files where the .xci file is located. To avoid committing these files to the repository, use a .gitignore file.

Note

Every file that is not a .xci file inside the directory containing the IP must be ignored by git.

This can be specified in a global .gitignore file or in local .gitignore files in each directory used to store IPs.

The .gitignore file provided in Hog templates assumes you are storing your IPs in a single directory called IP at the root of your repository.

Once the IP is created and added to the repository, add the .xci file to any source list file in the list folder of your project.

IP Initialization Coefficient Files (.coe, .mif)

If you have a .coe or .mif file for RAM initialization, you can store it anywhere in the repository. Be sure to specify the path to this file as a relative path when customizing the IP. Additionally, the coefficient file must also be included in a Hog .src list file.

Note

Browsing to the file location using the GUI will cause the absolute path to be loaded in the textbox. Be sure to replace this with a relative path.

The default .gitignore will tell git to ignore all files other than the .xci in the IP folder. To add your coefficient files to the repository, either exclude them in the .gitignore or store them in a different directory.

A Few Things Before Getting to Work

Here are a few details and suggestions that can be useful when working with a Hog-handled repository.

Commit Before Starting the Workflow

All Hog scripts handling version control are automatically added to your project, allowing you to create reproducible and traceable binary files—even when running locally. This will happen only if you commit your local changes before running synthesis. You don’t have to push—just commit locally, then push when your work is ready.

If you don’t commit, Hog will alert you with a Critical Warning at the beginning of synthesis.

Different List Files

As explained above, source files from different list files will be added to your project in different “libraries”: the name of each library is the name of the list file. When working with components from different list files, you need to formally include the libraries and reference the component from its library. For example, in VHDL:

library lib1;
use lib1.all;

...

u_1 : entity lib1.a_component_in_lib1
  port map(
    clk  => clk,
    din  => din,
    dout => dout
  );

If working within the same library, you can use the “work” library