## Simulation ```{warning} Outdated Documentation! This documentation version is out of date. Please check the [latest version 2026.1](https://hog.readthedocs.io/en/latest/). ``` Hog supports all simulation software currently supported by Vivado (see the full list [here](https://www.xilinx.com/products/design-tools/vivado/simulation.html)), as well as standalone GHDL simulations. Hog simulation has been tested with Vivado Simulator (also called Xsim), Mentor Graphics QuestaSim, Mentor Graphics ModelSim, and Aldec Riviera Pro. The simulation setup is always handled by Vivado, as if the simulation button in the GUI was clicked; the simulation run is then performed with the selected simulation software. ```{note} Currently, simulation is not supported under other IDEs. Complete support will be included in future releases. ``` ### Hog Simulation List Files (Hog2025.2) Simulations are organized into "simulation sets." Hog creates a simulation set for each `.sim` [list file](02-List-files.md) in the top project folder (`Top/myproj/list`). Starting from Hog2025.2, `.sim` list files can include both the list of simulation source files and simulation properties. The new list files follow a TOML-like structure with the following sections: - `[files]`: List of simulation source files. - `[properties]`: Properties for the simulation set. - `[generics]`: Generics to be passed to the top testbench file. - `[hog]`: Hog-specific simulation properties. An example simulation list file in the new format: ```ini # Simulator xsim # Generated by Hog on 2025-06-30 13:50:09 [properties] ACTIVE=1 RUNTIME=10us TOP=TB_fifo XSIM.SIMULATE.RUNTIME=10us [files] sources/sim/tb_fifo.vhd sources/sim/TB_example_wave.do sources/sim/TB_example.udo [generics] MYGENERIC=1 [hog] HOG_SIMPASS_STR="Simulation Passed" ``` It is also possible to have multiple simulation libraries in the same simulation file set. To do so, assign the `lib=library_name` property to the included file or sim list file in the `.sim` list file in the top simulation folder. For example, if you have a simulation list file called `mysim` in your top project folder with the following content: ```ini [files] src/top_sim.vhd src/lib1/lib1_sim.vhd lib=lib1 src/lib2/lib2.sim lib=lib2 ``` This will create a simulation file set `mysim` with three libraries: `mysim`, `lib1`, and `lib2`. Hog also allows you to generate `.sim` files automatically by clicking the [Hog SIM Button](02a-Hog-Buttons.md) in the Vivado GUI. To set a particular simset as the active one, set the `ACTIVE` property to `1` in your `.sim` file under the relevant simset section. If no active simset is specified, Hog will set the last created simulation set as active by default. ### Generics Section (Vivado Only) Starting from Hog2023.1, you can pass generic values to the top simulation file in your Vivado project by defining them in the `[generics]` section of the `.sim` file. For example: ```ini [generics] MY_GENERIC_INT=0 MY_GENERIC_STRING="a string" MY_GENERIC_HEX=4'h7 ``` The value of the generics should resemble the generic's type in your top testbench file. E.g. for the above generics the definition should look like, ```vhdl entity my_tb is generic ( MY_GENERIC_INT : integer; MY_GENERIC_STRING : string; MY_GENERIC_HEX : std_logic_vector(3 downto 0) -- To use HEX, the length of the vector should be multiple of 4 ); end entity top_module; ``` :::{warning} This feature is not yet supported in Quartus. ::: ### Hog Section (Vivado Only) From Hog2024.2, you can use the optional `[hog]` section to specify Hog directives valid for the simulation project. Supported properties include: - `HOG_SILENT_SIM`: Runs the simulation with the `-quiet` option. - `HOG_SIMPASS_STR`: Defines a simulation pass string. Hog will parse the simulation log and return an error exit if the provided string is not found. Otherwise, the simulation will rely on the simulator exit code. **When to use this directive:** In some simulators, a failure in the simulation is not considered an error, meaning no error exit code is returned by the simulator. As a result, when running a simulation in GitLab CI, the simulation job could be detected as successful even if a failure is present. Known simulators with this issue include: QuestaSim/ModelSim, Aldec Riviera, and Xcelium. Examples of working simulation pass strings for different simulation libraries: | Simulator library | PASS string | | -----------------------------------------------| ------------------------ | | UVVM (Universal VHDL Verification Methodology) | ">> Simulation SUCCESS:" | An example of the `[hog]` section defining `HOG_SIMPASS_STR` when using QuestaSim and UVVM: ```ini [hog] HOG_SIMPASS_STR=">> Simulation SUCCESS:" ``` ### Project Simulator The simulation software is set at the project level in Vivado. To change it, modify the `target_simulator` property in the `main` section of your [hog.conf file](01-conf.md). ```{note} Vivado does not allow running different simulations with different simulators automatically. If you want to do this locally, you must manually switch the simulator in the simulation settings each time. The setting is valid at the project level for all simulation sets. If you change the simulator by clicking in the Vivado GUI, the change will not be propagated to the repository. ``` #### Simulation Library When using external simulation software, you must specify the path to the compiled simulation library. By default, Hog sets this path to `repo_path/SimulationLib`, where `repo_path` is the root folder of your git repository. If the `HOG_SIMULATION_LIB_PATH` environment variable is defined (as in Continuous Integration; see [GitLab CI/CD setup](../02-Hog-CI/03-GitLab-CI/01-setup-CI.md) and [GitHub Actions](../02-Hog-CI/04-GitHub.md)), Hog will use that path. You can also specify the simulation library path when creating the project using the `--lib` flag: ```bash ./Hog/Do CREATE -lib ``` ### The sim.conf File It is still possible to configure simulation properties using a file called `./Top//sim.conf`, with a syntax similar to `hog.conf`. In this case, the `.sim` file should only include the list of simulation sources without TOML headers. :::{warning} `sim.conf` files are expected to be phased out in Hog2026.1. We advise you to migrate to the new `.sim` list file format as soon as possible. If you use the Hog SIM button to recreate your simulation configuration files, Hog will remove the `sim.conf` file and write all configuration inside the `.sim` list files. ::: Simulation properties can be set individually for each simulation set or globally for all sets. For example, to set the `xsim.elaborate.rangecheck` property for the simulation set `sim_1`, write: ```ini [sim_1] xsim.elaborate.rangecheck = true ``` Alternatively, to set this property for all your simulation sets: ```ini [sim] xsim.elaborate.rangecheck = true ``` ### Simulation in CI If the simulation job is configured in your project's CI, [Hog CI](../02-Hog-CI/01-CI-Introduction.md) will automatically run the simulation sets. The CI stage will fail if any simulation fails. Therefore, each simulation set should be designed to fail if any unwanted behavior is present. Even though Vivado does not allow different simulators in the same project, in Hog CI you can specify a different software to be used in each set. This can be done by adding one of the following lines at the top of the `.sim` list file: ``` #Simulator xsim # For Vivado Simulator #Simulator questa # For QuestaSim Simulator #Simulator modelsim # For ModelSim Simulator #Simulator riviera # For Aldec Riviera Simulator #Simulator activehdl # For Aldec Active-HDL Simulator #Simulator ies # For IES Simulator #Simulator vcs # For Synopsys VCS Simulator #Simulator ghdl # For GHDL Simulator #Simulator skip_simulation # To skip the simulation in the CI ``` If you do not specify the simulator software, Hog will use ModelSim as the default. If you do not want a specific simulation set to be simulated by the CI, use `skip_simulation`. An example `.sim` list file: ```ini #Simulator xsim [files] tb_source_dir/tb_for_lib1.vhd wave_source_dir/wave_lib1.tcl do_source_dir/dofile_lib1.do tb_source_dir/another_file.vhd [properties] TOP=TB_FOR_LIB1 ``` ### Simulating Without GUI If you want to run the simulation locally without using the GUI (as in CI), you can use the `Hog/Do` script: ```bash ./Hog/Do SIMULATE [-lib_path ] [-simset ] [-quiet] [-recreate] ``` This script will launch all the simulation sets in the specified project, using the software specified in the `.sim` file, and will skip the simulation if `skip_simulation` is specified. More details can be found [here](../../01-Getting-Started/00-Hog-Do.md#simulating-a-project-vivado-only). --- ### GHDL Simulations Starting from Hog2025.2, it is possible to run GHDL simulations and create GHDL-only projects. To use GHDL, ensure that both `ghdl` and `tcllib` are installed on your machine. To run a simulation set with GHDL, add `#Simulator ghdl` as the first line of your `.sim` set file. For example: ```ini #Simulator ghdl [files] tb_source_dir/tb_for_lib1.vhd [properties] TOP=TB_FOR_LIB1 options="-frelaxed" run_options="--assert-level=note" ``` In the `[properties]` section, you can specify the options and run options that Hog should pass to GHDL using the `options` and `run_options` properties, as shown above. To launch the simulation, simply execute: ```bash ./Hog/Do SIM [-simset ] ``` Replace `` with the name of the project you want to simulate. Use the `-simset` option to specify the simulation sets to run.