Intellectual Properties (IP)#

IP and BD files can be stored anywhere in your repository or in submodules. However, particular care must be taken to avoid that files generated by Vivado or Quartus are kept separated and not committed to the repository, unless you want to keep the IP in a locked status.

To achieve this, these simple rules must be followed:

  • each ip or bd file (.xci/.bd for Vivado) must be contained in a sub-folder called with the same name as the .xci/.bd file (extension excluded).

  • only the ip/bd file must be committed to the repository (e.g. .xci/.bd for Vivado, .ip for Quartus)

  • a .gitignore file must be used to tell git to ignore all non-ip files, a template is provided in the Templates directory.

Basically for each IP in your project run:

  mkdir -p path_to_your_ips/ip_name/
  cp ../old_repo/ip_name.xci path_to_your_ips/ip_name/

Then you must add the .xci/.bd files to the .src list file you want, in this case we will use a separate file called IP.src. You can use the following script if you like:

  for i in $( ls path_to_your_ips/* ); do \
    echo $i/$i.xci >> Top/myproject/list/myproject.src;
  done

Note

There is no concept of library for the IPs, so we prefer to put them in a separate .src file. You can put them in the same list file as your other source files if you wish. Just open Top/myproject/list/myproject.src with a text editor and add them there.

As usual, you can check that the files are correctly picked up by regenerating the project ./Hog/Do CREATE myproject If you are satisfied with the changes, you can commit your work.

  git add path_to_your_ips
  git add Top/myproject/list/IP.src
  git commit -m "Adding IP Files"

Keep the IP locked (Vivado only)#

Sometimes you might want an IP to be kept in a locked status, for example, when you are using an older version of the IP and want to prevent Vivado to update it. This can be achieved by committing to the repository the entire folder where the .xci file is located and by removing the dedicated .gitignore. Then, in your .src list file you can specify the locked property for your IP as following.

    IP/ip1.xci locked

You can achieve the same result, by unticking the IS_MANAGED property of your IP in the Vivado GUI.

XCIX (IP Core Containers)#

For Ultrascale devices, Xilinx allows the creation of core container for IPs (see the Xilinx documentation). These are binary files that contain both the IP definition (.xci) and the generated products.

Warning

XCIX and git Binary files are not preferred for revision control. It is recommended to use XCI file instead, which allows you to diff IP in a revision control environment to see if anything has changed.

If you decide to commit an .xcix file to Git, ensure it is committed after synthesis. Failing to do so will result in the file undergoing changes during synthesis,leading to a dirty bit stream.

IP initialisation files (.coe, .mif)#

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

Creating the IPs/BDs with a Tcl script (Hog > 2022.1, Vivado Only)#

Users can also create IPs or BDs after that the project has been created, using TCL scripts. In this case, the .xci or .bd files shall not be included in the .src list files. The TCL scripts, on the other hand, should be listed with the property source, as in the following example list.

mypath/file.vhd
mypath/script.tcl source

In this case, Hog will source the script script.tcl after the creation of the project. Naturally, it is also possible to generate the IPs/BDs using the integrated post-creation.tcl script (see here).

Speed up the IP synthesis (Optional)#

In order to save resources and possibly speed up the workflow, Hog can automatically the products of the IP synthesis to/from an external directory. The external path is specified via the HOG_IP_PATH environment variable.

If the aforementioned environment variable is defined, Hog will copy all the needed IPs to the project directory during the project creation. The synthesised products are copied to the external directory after the synthesis stage.

The IPs are archived in the IP path using the md5 hash of the .xci file, so if an IP is modified, it will be copied again.

It is recommended to clean the IP path regularly as Hog will not delete old IP products.

If you have a CERN account you can use EOS file system to store the IP products, this is particularly useful for the CI. Hog will automatically detect if the IP storage path is on EOS or on the running machine, verifying that the path starts with /eos/ or not.