## Intellectual Properties (IP)
```{warning} Outdated Documentation!
    This documentation version is out of date. Please check the [latest version 2026.1](https://hog.readthedocs.io/en/latest/).
```

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:

```bash
  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:

```bash
  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.

```bash
  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.

```bash
    IP/ip1.xci locked
```

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

##### 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.

```bash
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](01-conf.md#running-additional-scripts)).

### 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.