## Usage (`Hog/Do` Script) ```{warning} Outdated Documentation! This documentation version is out of date. Please check the [latest version 2026.1](https://hog.readthedocs.io/en/latest/). ``` The `Hog/Do` script is a versatile tool designed to assist in managing hardware design projects and workflows. This chapter provides an overview of the available directives and options, and their usage. A typical execution of the `Do` command is therefore: ```shell ./Hog/Do [] ``` You are not obliged to use the `Hog/Do` script, except that for creating the project. Once this is create you can open the project with the standard IDE tools, and work in your prefered environment (e.g. with a graphical interface). ### Directives Directives determine the primary action that the `Hog/Do` script will perform. The available directives are case-insensitive: - `CREATE` or `C`: Create the project, replacing it if it already exists. - `WORKFLOW` or `W`: Launch the complete workflow, creating the project if it does not exist. - `CREATEWORKFLOW` or `CW`: Create the project (even if existing) and launch the complete workflow. - `SIMULATE` or `S`: Simulate the project, creating it if it does not exist. - `IMPLEMENT`: Run the implementation only. The project must already exist and be synthesized. - `SYNTHESIS`: Run the synthesis only, creating the project if it does not exist. - `LIST` or `L`: Only list all the projects. - `HELP` or `H`: Display the help screen. By "building" or "workflow" we mean the complete build of the project: IP synthesis, Synthesis, Implementation, and binary file generation. ### Command Options The `Hog/Do` script supports several command-line options that modify its behavior. Each option can be used to customize the execution of the script: - `-no_bitstream`: If set, the bitstream file will not be produced. - `-recreate`: If set, the project will be re-created if it already exists. - `-no_reset`: If set, runs (synthesis and implementation) won't be reset before launching them. - `-check_syntax`: If set, the HDL syntax will be checked at the beginning of the workflow. - `-njobs `: Specifies the number of jobs. The default is 4. - `-ext_path `: Sets the absolute path for external libraries. - `-lib `: Specifies the compiled simulation library path. - `-synth_only`: If set, only the synthesis will be performed. - `-impl_only`: If set, only the implementation will be performed. This assumes synthesis was already done. - `-simset `: Defines simulation sets, separated by commas, to be run. Effective only for the `SIMULATE` directive. - `-verbose`: If set, the script will be launched in verbose mode. ### Usage Examples #### Create a project To create a new project (or replace an existing one): ```bash ./Hog/Do CREATE MyProject ``` #### Creating a Project and Launching Workflow To create a new project (or replace an existing one) and launch the complete workflow: ```bash ./Hog/Do -recreate WORKFLOW MyProject ``` or ```bash ./Hog/Do CREATEWORKFLOW MyProject ``` The project will be created in `Projects/MyProject`. These directories should be ignored in the `.gitignore` file to avoid to accidentally commit the to the repository. #### Simulating a Project (Vivado-only) To simulate an existing project, creating it if not existing: ```bash ./Hog/Do SIMULATE MyProject ``` Project simulation can be run using shell, Vivado GUI or Vivado Tcl console. 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-List-files). If a simulator different from Vivado Xsim is used, the Vivado libraries must be compiled by the user in a directory. They can be compiled using the shell command `Hog/Init.sh` or by using the tcl commands [`Hog/Tcl/utils/compile_simlib.tcl`](06-Hog-utils). If this command is used, the simulation libraries will be stored into `./SimulationLib`. #### Running Synthesis Only To perform synthesis on an existing project or create it if not existing: ```bash ./Hog/Do SYNTHESIS MyProject ``` #### Listing Projects To list all available projects: ```bash ./Hog/Do LIST ``` #### Displaying Help To view the help screen: ```bash ./Hog/Do HELP ``` ### Running the workflow using Vivado/Quartus GUI In a Hog handled project, the firmware workflow can always be run normally from the IDE (Vivado, Quartus) GUI, Hog integrated scripts will run automatically. To run the IP synthesis, for example, right click on each IP and click the "Generate Output Products" button. To synthesise the project, click on "Run Synthesis" button (on the left). Finally, click on "Run Implementation" and "Generate Bitstream" buttons (on the left). :::{note} Under Quartus always run a full compilation flow after recreating a project. Running a single module will cause errors due the Hog generics not being set to any value[^value]. ::: [^value]: As a workaround you can give default values to the Hog generics (e.g. X"00000000") in your top level file. ### Collecting workflow products After the firmware workflow is completed, Hog will automatically copy many relevant files to the `bin` directory in the root of your repository. This folder should be ignored by git by means of the `.gitignore` file. The files copied into the `bin` directory are: - The binary files (`.bin` and `.bit`) properly renamed according to the `git describe` - (optional) The `.ltx` ILA files (if ILA cores are used in the project) - All the reports produced during synthesis and implementation - (Vivado only) All the `runme.log` files produced during synthesis and implementation. They will be renamed according to the run name - (optional) All the IPbus XML files used in the project, as specified in the `xml.lst` list file - A `versions.txt` file containing all the values of versions, SHAs, time, date that are passed to the top module of the project - (Vivado only) In the HOG-CI (or if you launch the workflow with the script) a timing file containing the timing values of the project (WNS, TNS, WHS, THS). The file is called `timing_ok.txt` if all the timing requirements were met, otherwise it is called `timing_error.txt`. ### Simulating with Vivado GUI Using the GUI, you can run only one simulation set at the time. First of all select the simulation set you want to run, by right clicking on simulation set name in project sources window. Then click on "Run Simulation" button (on the left). Note that using the GUI, Vivado or Quartus will use the simulation software specified in your [project `hog.conf` file](01-conf).