Merge branch '17-2026-2' into 'develop'

site

.DS_Store

build

venv

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

:::{warning}

**Files must be managed through Hog list files, not the IDE GUI.** If you add, remove, or rename files directly in the IDE, those changes will be lost the next time the project is recreated with `./Hog/Do CREATE`.

- **Vivado users**: you can use the [Hog buttons](../02-User-Manual/01-Hog-local/02a-Hog-Buttons.md) in the Vivado toolbar to automatically sync GUI changes back to the list files.

- **All other IDEs (Quartus, Libero, Diamond)**: always add new files to a list file in `Top/<project>/list/` manually first.

See [Adding a New File to the Project](#adding-a-new-file-to-the-project) below.

:::

:::{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.

:::

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

:::{note}

**List file types**: Hog uses five types of list files, distinguished by extension:

- `.src` — HDL source files (VHDL, Verilog, SystemVerilog) and user IPs (`.xci`)

- `.con` — Constraint files (`.xdc`, `.sdc`, `.tcl`)

- `.sim` — Simulation source files

- `.ext` — External source files (paths outside the repository) and IPs

- `.ipb` — IPbus XML address map files

Each file lists the paths of source files relative to the repository root, one per line. See the [List Files](../02-User-Manual/01-Hog-local/02-List-files.md) section for full details.

:::

### Manually Updating the List File

Assume the list file you want to update is `lib1.src`.

| CHECKLIST         | CL    | Check that list and configuration files on disk match what is on the project.                     |

| CHECKSYNTAX       | CS    | Check the HDL syntax of the project. Only for Vivado, Quartus and Libero projects.     |

| CHECKYML          | YML   | Check that the ref to Hog repository in the .gitlab-ci.yml file, matches the one in Hog submodule.                 |

| COCOTB            | —     | Generate a ready-to-use Python script integrating a Hog project with the cocotb hardware verification framework.    |

| COMPSIMLIB        | COMPSIM      | Compiles the simulation library for the chosen simulator with Vivado.                                 |

| CREATE            | C     | Create or replace a project                                     |

| CREATEWORKFLOW    | CW    | Creates the project -even if existing- and launches the complete workflow.                        |

| SIMULATION        | S     | Run simulation (creates project if needed)                      |

| SYNTH             |       | Run synthesis only                                              |

| TREE              | T     | Print the design hierarchy for the chosen project.              |

| VERSION           | VER   | Prints the version of a Hog project. With `-describe`, prints the Hog describe string instead. |

| VHDLLS            | VHDL  | Generates a `.toml` configuration file for the VHDL-LS Language Server |

| VIEW              | V     | Print Hog list file contents                                    |

| WORKFLOW          | W     | Run full workflow (synth + impl + bitstream)                    |

- **Generate IPbus XMLs:**

  ```sh

  ./Hog/Do XML MyProject -generate

  ./Hog/Do IPBUS MyProject -generate

  ```

- **Get the version of an Hog project:**

  ```bash

  ./Hog/Do VERSION <project_name> [options]

  ./Hog/Do VER <project_name> [options]

  ```

## Directives' descriptions

```

**Options:**

- `verbose` — Enable verbose output.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `ext_path <path>` — Absolute path for external libraries.

- `verbose` — Enable verbose output.

- `-ext_path <path>` — Absolute path for external libraries.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `ext_path <path>` — Absolute path for external libraries.

- `recreate` — Re-create the project if it already exists.

- `verbose` — Enable verbose output.

- `-ext_path <path>` — Absolute path for external libraries.

- `-recreate` — Re-create the project if it already exists.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `verbose` — Enable verbose output.

- `-verbose` — Enable verbose output.

---

#### COCOTB (`COCOTB`)

**Description:**

Generate a ready-to-use Python script that integrates a Hog project with the [cocotb](https://www.cocotb.org/) hardware verification framework. The command reads the project's Hog list files, resolves the full compile order (respecting library dependencies), and emits a self-contained Python file that calls `cocotb_tools.runner` to compile every HDL source and run a test against a chosen simulator. For more details, see [CocoTB Support](../02-User-Manual/01-Hog-local/16-Cocotb.md).

**Usage:**

```shell

./Hog/Do COCOTB <project_name> [options]

```

**Options:**

| Option | Description |

|---|---|

| `-lib <path>` | Path to a pre-compiled simulation library (e.g. `SimulationLib/`). Can also be set via the `HOG_SIMULATION_LIB_PATH` environment variable. |

| `-ext_path <path>` | Absolute path for source files stored externally to the git repository. |

| `-verbose` | Enable verbose/debug output. |

---

```

**Options:**

- `dst_dir <path>` — Output directory for the compiled library.

- `verbose` — Enable verbose output.

- `-dst_dir <path>` — Output directory for the compiled library.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `ext_path <path>` — Absolute path for external libraries.

- `lib <path>` — Simulation library path.

- `vivado_only` — If project is vivado-vitis, create only the Vivado project (Vitis project creation is skipped).

- `vitis_only` — If project is vivado-vitis, create only the Vitis project (Vivado project creation is skipped). If an XSA is not given, a pre-synth XSA will be created.

- `xsa <path>` — Path to an existing XSA file for Vitis project.

- `verbose` — Enable verbose output.

- `-ext_path <path>` — Absolute path for external libraries.

- `-lib <path>` — Simulation library path.

- `-vivado_only` — If project is vivado-vitis, create only the Vivado project (Vitis project creation is skipped).

- `-vitis_only` — If project is vivado-vitis, create only the Vitis project (Vivado project creation is skipped). If an XSA is not given, a pre-synth XSA will be created.

- `-xsa <path>` — Path to an existing XSA file for Vitis project.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `check_syntax` — Check HDL syntax at the beginning.

- `ext_path <path>` — Absolute path for external libraries.

- `njobs <n>` — Number of parallel jobs (default: 4).

- `no_bitstream` — Do not produce the bitstream file.

- `synth_only` — Only perform synthesis.

- `vivado_only` — If project is vivado-vitis, vitis project will not be created.

- `vitis_only` — If set, and project is vivado-vitis create only vitis project. If an xsa is not given, a pre-synth xsa will be created.

- `verbose` — Enable verbose output.

- `-check_syntax` — Check HDL syntax at the beginning.

- `-ext_path <path>` — Absolute path for external libraries.

- `-njobs <n>` — Number of parallel jobs (default: 4).

- `-no_bitstream` — Do not produce the bitstream file.

- `-synth_only` — Only perform synthesis.

- `-vivado_only` — If project is vivado-vitis, vitis project will not be created.

- `-vitis_only` — If set, and project is vivado-vitis create only vitis project. If an xsa is not given, a pre-synth xsa will be created.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `check_syntax` — Check HDL syntax before implementation.

- `ext_path <path>` — Absolute path for external libraries.

- `njobs <n>` — Number of parallel jobs (default: 4).

- `no_bitstream` — Do not produce the bitstream file.

- `no_reset` — Do not reset runs before launching.

- `recreate` — Re-create the project if it already exists.

- `verbose` — Enable verbose output.

- `-check_syntax` — Check HDL syntax before implementation.

- `-ext_path <path>` — Absolute path for external libraries.

- `-njobs <n>` — Number of parallel jobs (default: 4).

- `-no_bitstream` — Do not produce the bitstream file.

- `-no_reset` — Do not reset runs before launching.

- `-recreate` — Re-create the project if it already exists.

- `-verbose` — Enable verbose output.

---

#### IPBUS (`IPBUS` or `IPB`)

```

**Options:**

- `dst_dir <argument>` —  For reports, IPbus XMLs, set the destination folder (default is in the ./bin folder).

- `generate` — For IPbus XMLs, it will re create the VHDL address decode files.

- `verbose` — If set, launch the script in verbose mode

- `-dst_dir <argument>` — For reports, IPbus XMLs, set the destination folder (default is in the ./bin folder).

- `-generate` — For IPbus XMLs, it will re-create the VHDL address decode files.

- `-verbose` — If set, launch the script in verbose mode.

---

```

**Options:**

- `all` — List all projects, including test projects.

- `verbose` — Enable verbose output.

- `-all` — List all projects, including test projects.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `check_syntax` — Check HDL syntax before elaboration.

- `recreate` — Re-create the project if it already exists.

- `verbose` — Enable verbose output.

- `-check_syntax` — Check HDL syntax before elaboration.

- `-recreate` — Re-create the project if it already exists.

- `-verbose` — Enable verbose output.

---

#### SIGASI (`SIGASI` or `SIG`)

**Description:**

Create a `.csv` file for use with Sigasi Visual HDL. For more information, see the section [Using Hog with Sigasi Visual HDL](../02-User-Manual/01-Hog-local/03c-sigasi.md).

Create a `.csv` file for use with Sigasi Visual HDL. For more information, see the section [Using Hog with Sigasi Visual HDL](../02-User-Manual/01-Hog-local/10-Sigasi.md).

**Usage:**

```

```

**Options:**

- `verbose` — Enable verbose output.

- `-verbose` — Enable verbose output.

---

```

**Options:**

- `check_syntax` — Check HDL syntax before simulation.

- `compile_only` — If set, the simulation libraries will be compiled, but not run.

- `ext_path <path>` — Absolute path for external libraries.

- `lib <path>` — Simulation library path.

- `recreate` — Re-create the project if it already exists.

- `scripts_only` — If set, the simulation scripts will be generated, but the simulation will not be run.

- `simset <sets>` — Simulation sets to run (comma-separated).

- `verbose` — Enable verbose output.

- `-check_syntax` — Check HDL syntax before simulation.

- `-compile_only` — If set, the simulation libraries will be compiled, but not run.

- `-ext_path <path>` — Absolute path for external libraries.

- `-lib <path>` — Simulation library path.

- `-recreate` — Re-create the project if it already exists.

- `-scripts_only` — If set, the simulation scripts will be generated, but the simulation will not be run.

- `-simset <sets>` — Simulation sets to run (comma-separated).

- `-verbose` — Enable verbose output.

The simulation files and properties, such as the selected simulator, possible wave files or do files are set as explained in the section [Simulation list files](../02-User-Manual/01-Hog-local/02-List-files).

**Options:**

- `verbose` — Enable verbose output.

---

#### SYNTHESIS (`SYNTH`)

```

**Options:**

- `check_syntax` — Check HDL syntax before synthesis.

- `ext_path <path>` — Absolute path for external libraries.

- `njobs <n>` — Set the maximum number of parallel jobs for the synthesis (default: 4).

- `recreate` — Re-create the project if it already exists.

- `verbose` — Enable verbose output.

- `-check_syntax` — Check HDL syntax before synthesis.

- `-ext_path <path>` — Absolute path for external libraries.

- `-njobs <n>` — Set the maximum number of parallel jobs for the synthesis (default: 4).

- `-recreate` — Re-create the project if it already exists.

- `-verbose` — Enable verbose output.

#### TREE (`TREE` or `T`)

**Description:**

```

**Options:**

- `compile_order` — Print the compilation order instead of the hierarchy.

- `ext_path <path>` — Absolute path for external libraries.

- `ignore <pattern>` — Ignore modules matching the given pattern.

- `include_gen_prods` — Include IP generated products in the hierarchy.

- `include_ieee` — Include IEEE and STD library components in the hierarchy.

- `light` — Print a simplified hierarchy (without file paths).

- `output <file>` — Write the hierarchy into the specified file.

- `top <module>` — Specify a different top module for the hierarchy.

- `verbose` — Enable verbose output.

- `-compile_order` — Print the compilation order instead of the hierarchy.

- `-ext_path <path>` — Absolute path for external libraries.

- `-ignore <pattern>` — Ignore modules matching the given pattern.

- `-include_gen_prods` — Include IP generated products in the hierarchy.

- `-include_ieee` — Include IEEE and STD library components in the hierarchy.

- `-light` — Print a simplified hierarchy (without file paths).

- `-output <file>` — Write the hierarchy into the specified file.

- `-top <module>` — Specify a different top module for the hierarchy.

- `-verbose` — Enable verbose output.

#### VERSION (`VERSION` or `VER`)

**Description:**

Prints the version of a Hog project. With `-describe`, prints the Hog describe string instead.

**Usage:**

```bash

./Hog/Do VERSION <project_name> [options]

./Hog/Do VER <project_name> [options]

```

**Options:**

| Option | Description |

|---|---|

| `-describe` | Print the Hog describe string instead of the plain version number. |

| `-ext_path <path>` | Absolute path for external IP libraries. |

| `-verbose` | Enable verbose/debug output. |

#### VHDLLS (`VHDLLS` or `VHDL`)

**Description:**

Generate a [VHDL-LS](https://github.com/VHDL-LS/rust_hdl) configuration file (`vhdl_ls_<project>.toml`) for a Hog project. The file maps each Hog library to its VHDL source files and can be used directly (or merged into) the `vhdl_ls.toml` consumed by the language server, enabling IDE features such as go-to-definition and diagnostics in editors like VS Code. Non-VHDL files are skipped. For more details, see [VHDL-LS Support](../02-User-Manual/01-Hog-local/17-vhdlls.md).

**Usage:**

```shell

./Hog/Do VHDLLS <project_name> [options]

```

**Options:**

- `-verbose` — Enable verbose/debug output.

#### VIEW (`VIEW` or `V`)

```

**Options:**

- `verbose` — Enable verbose output.

- `-verbose` — Enable verbose output.

#### WORKFLOW (`WORKFLOW` or `W`)\

./Hog/Do WORKFLOW <project_name> [options]

```

**Options:**

- `bitstream_only` — Only generate the bitstream, assuming synthesis and implementation are already done.

- `check_syntax` — Check HDL syntax at the beginning.

- `ext_path <path>` — Absolute path for external libraries.

- `impl_only ` — Only perform implementation. This assumes synthesis is already done.

- `njobs <n>` — Number of parallel jobs (default: 4).

- `no_bitstream` — Do not produce the bitstream file.

- `recreate` — Re-create the project if it already exists.

- `synth_only` — Only perform synthesis.

- `verbose` — Enable verbose output.

- `-bitstream_only` — Only generate the bitstream, assuming synthesis and implementation are already done.

- `-check_syntax` — Check HDL syntax at the beginning.

- `-ext_path <path>` — Absolute path for external libraries.

- `-impl_only` — Only perform implementation. This assumes synthesis is already done.

- `-njobs <n>` — Number of parallel jobs (default: 4).

- `-no_bitstream` — Do not produce the bitstream file.

- `-recreate` — Re-create the project if it already exists.

- `-synth_only` — Only perform synthesis.

- `-verbose` — Enable verbose output.

- `vivado_only` — If project is vivado-vitis, only run the Vivado workflow (Vitis build is skipped).

- `vitis_only` — If set, and project is vivado-vitis, run only the Vitis build. If an XSA is not given, a pre-synth XSA will be created.

- `-vitis_only` — If set, and project is vivado-vitis, run only the Vitis build. If an XSA is not given, a pre-synth XSA will be created.

- `xsa <path>` — Path to an existing XSA file for Vitis projects.

### CUSTOM COMMANDS

:::{note}

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

:::

# Glossary

Key terms used throughout the Hog documentation.

---

**Bitstream**

The binary file produced at the end of the FPGA build flow (synthesis + implementation). It is programmed onto the FPGA device to configure its logic. Hog embeds the project version and git SHA into the bitstream so that every binary file is traceable back to its exact source code.

---

**Block Design (BD)**

A Vivado-specific visual design entry method where logic blocks are connected graphically. The design is stored as a `.bd` file, which should be committed to the repository and added to a `.src` list file.

---

**Describe string**

A human-readable string that uniquely identifies the state of a project, combining the version tag, the number of commits since that tag, the short git SHA, and a `dirty` suffix if the repository had uncommitted changes at build time. Example: `1.2.3-5-gabcdef0-dirty`. Retrieved with `./Hog/Do VERSION <project> -describe`.

---

**Dirty repository**

A repository that has uncommitted local changes. Hog detects a dirty state at synthesis time and issues a Critical Warning, setting the version to `0.0.0`. This guarantees that only clean, committed states produce valid version numbers.

---

**`hog.conf`**

The project configuration file, located at `Top/<project>/hog.conf`. It tells Hog which FPGA device to target, which synthesis and implementation strategies to use, how many parallel jobs to run, and optionally defines generics to pass to the top-level HDL module. A template is available at `Hog/Templates/hog_vivado.conf`. See [hog.conf reference](../02-User-Manual/01-Hog-local/01-conf.md).

---

**Hog buttons**

Custom buttons added to the Vivado GUI toolbar by Hog. They allow Vivado users to check and update Hog list files directly from within the IDE, without leaving Vivado. See [Hog Buttons](../02-User-Manual/01-Hog-local/02a-Hog-Buttons.md).

---

**Hog submodule**

The Hog scripts are included in every Hog-managed repository as a git submodule at `Hog/`. This means Hog itself is version-controlled alongside your design. When cloning, use `git clone --recursive` to ensure the submodule is fetched.

---

**Implementation**

The place-and-route step of the FPGA build flow, which follows synthesis. It maps the netlist produced by synthesis onto the physical resources of the target FPGA device. Run with `./Hog/Do IMPLEMENTATION <project>`.

---

**IP (Intellectual Property core)**

A pre-built, reusable design block provided by the IDE vendor or a third party. In Vivado, IPs are represented by `.xci` files. These files should be committed to the repository and listed in a `.src` or `.ext` list file.

---

**Library**

In Hog, a library is a named group of HDL source files. Each `.src` list file defines one library: the library name is the filename without the `.src` extension (e.g., `mylib.src` defines library `mylib`). This library name must match the HDL library declaration in your VHDL or Verilog files, and in Vivado it corresponds to the compile library set in the Sources panel.

---

**List file**

A plain-text file in `Top/<project>/list/` that lists the source files belonging to a Hog project, one path per line (relative to the repository root). Hog reads these files to populate the IDE project. 

See [List Files](../02-User-Manual/01-Hog-local/02-List-files.md) for full details.

---

**Project top-directory**

The per-project subdirectory inside `Top/`, named after the project (e.g., `Top/myproject/`). It contains the `hog.conf` configuration file and the `list/` subdirectory with all list files.

---

**Reproducibility**

The guarantee that building the same committed state of the repository produces an identical binary. Hog enforces this by requiring all source files to be committed to git before synthesis.

---

**Simulation set**

A named group of simulation source files, defined by a `.sim` list file. Hog creates one IDE simulation set per `.sim` file. Run a specific set with `./Hog/Do SIMULATION <project> -simset <name>`. See [Simulation](../02-User-Manual/01-Hog-local/02b-Simulation.md).

---

**Synthesis**

The first step of the FPGA build flow, which translates HDL source code into a technology-mapped netlist for the target device. Run with `./Hog/Do SYNTH <project>`.

---

**Top directory**

The `Top/` folder at the root of the repository. It contains one subdirectory per Hog project. The name of each subdirectory becomes the project name used in all `Hog/Do` commands.

---

**Top module**

The highest-level HDL entity or module in the design hierarchy — the one that gets synthesised and implemented. It is usually specified in `hog.conf` under the `[main]` section as `top_module`.

---

**Traceability**

The ability to identify exactly which source code revision produced a given binary file. Hog embeds the git SHA and version into the bitstream at synthesis time, so any binary can be matched back to its exact repository state.

---

**Version**

A semantic version string (e.g., `1.2.3`) derived from the most recent git tag on the current branch. Hog reads this automatically at synthesis time and embeds it in the binary. Retrieve it with `./Hog/Do VERSION <project>`.

---

**Workflow**

The full FPGA build sequence: synthesis → implementation → bitstream generation. Run the complete workflow with `./Hog/Do WORKFLOW <project>`. Individual steps can also be run separately with `SYNTH`, `IMPLEMENTATION`, and `WORKFLOW -bitstream_only`.