Usage (Hog/Do Script)#
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.
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 preferred environment (e.g. with a graphical interface).
Usage#
To use Hog/Do, specify a directive along with any required arguments and options:
./Hog/Do <directive> [arguments] [options]
<directive>: The action to perform (e.g., CREATE, SYNTH, IMPLEMENTATION, SIMULATION, HELP, etc.).[arguments]: Required arguments for the directive, usually the project name (e.g.,<project_name>).[options]: Optional flags or parameters to modify the command’s behavior.
You can display help for any directive by running:
./Hog/Do <directive> HELP
This will show detailed usage and available options for the specified directive.
Common Directives#
Note: All directives are case-insensitive. For example,
CREATE,create, orCrEaTeare all valid and equivalent.
Directive |
Alias |
Description |
|---|---|---|
BUTTONS |
B |
Add Hog buttons to the Vivado GUI, to check and recreate Hog list and configuration files. |
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. |
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. |
HELP |
H |
Display this help message or specific help for each directive |
IMPLEMENTATION |
I |
Run implementation (project must be synthesized) |
IPBUS |
IPB |
Copy, check or create the IPbus XMLs for the project. |
LIST |
L |
List projects in the repository |
RTLANALYSIS |
RTL |
Elaborate the RTL analysis report for the chosen project. (Vivado only) |
SIGASI |
SIG |
Create .csv for Sigasi to be used with Sigasi Visual HDL |
SIMULATION |
S |
Run simulation (creates project if needed) |
SYNTH |
Run synthesis only |
|
TREE |
T |
Print the design hierarchy for the chosen project. |
VIEW |
V |
Print Hog list file contents |
WORKFLOW |
W |
Run full workflow (synth + impl + bitstream) |
Examples#
List all projects:
./Hog/Do LIST -all
Create a project:
./Hog/Do CREATE MyProject -recreate
Run full workflow:
./Hog/Do WORKFLOW MyProject
Run simulation for a specific set:
./Hog/Do SIMULATION MyProject -simset set1
Check syntax:
./Hog/Do CHECKSYNTAX MyProject
Generate IPbus XMLs:
./Hog/Do XML MyProject -generate
Directives’ descriptions#
CHECKLIST (CHECKLIST or CL)#
Description: Check that list and configuration files on disk match what is in the project.
Usage:
./Hog/Do CHECKLIST <project_name>
Options:
ext_path <path>— Absolute path for external libraries.verbose— Enable verbose output.
CHECKSYNTAX (CHECKSYNTAX or CS)#
Description: Check the syntax of the project (Vivado, Quartus, and Libero only).
Usage:
./Hog/Do CHECKSYNTAX <project_name>
Options:
ext_path <path>— Absolute path for external libraries.recreate— Re-create the project if it already exists.verbose— Enable verbose output.
CHECKYAML (CHECKYML or YML)#
Description:
Check that the ref to the Hog repository in .gitlab-ci.yml matches the one in the Hog submodule.
Usage:
./Hog/Do CHECKYML
Options:
verbose— Enable verbose output.
COMPSIMLIB (COMPSIMLIB or COMPSIM)#
Description: Compile the simulation library for the chosen simulator (Vivado only).
Usage:
./Hog/Do COMPSIMLIB <simulator> [options]
Options:
dst_dir <path>— Output directory for the compiled library.verbose— Enable verbose output.
CREATE (CREATE or C)#
Description: Create the project, replacing it if it already exists.
Usage:
./Hog/Do CREATE <project_name>
Options:
ext_path <path>— Absolute path for external libraries.lib <path>— Simulation library path.vivado_only— If project is vivado-vitis, vitis project will not be created.verbose— Enable verbose output.
CREATEWORKFLOW (CREATEWORKFLOW or CW)#
Description: Create the project (even if it exists) and run the complete workflow.
Usage:
./Hog/Do CREATEWORKFLOW <project_name>
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.
HELP (HELP or H)#
Description: Display the help message or specific help for each directive.
Usage:
./Hog/Do HELP
Options: None
IMPLEMENTATION (IMPLEMENTATION or I)#
Description: Run only the implementation step. The project must already exist and be synthesized.
Usage:
./Hog/Do IMPLEMENTATION <project_name>
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.
IPBUS (IPBUS or IPB)#
Description: Copy, check, or create the IPbus XML files for the project.
Usage:
./Hog/Do IPBUS <project_name> [options]
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
LIST (LIST or L)#
Description: List all projects in the repository.
Usage:
./Hog/Do LIST [options]
Options:
all— List all projects, including test projects.verbose— Enable verbose output.
RTLANALYSIS (RTLANALYSIS or RTL)#
Description: Elaborate the RTL analysis report for the chosen project (Vivado only).
Usage:
./Hog/Do RTL <project_name> [options]
Options:
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.
Usage:
./Hog/Do SIGASI <project_name> [options]
Options:
verbose— Enable verbose output.
SIMULATION (SIMULATION or S) - Vivado and GHDL only#
Description: Simulate the project, creating it if it does not exist (unless using GHDL).
Usage:
./Hog/Do SIMULATION <project_name> -simset <simset>
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.
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.
Options:
verbose— Enable verbose output.
SYNTHESIS (SYNTH)#
Description: Run only the synthesis step, creating the project if it does not exist.
Usage:
./Hog/Do SYNTH <project_name> [options]
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.
TREE (TREE or T)#
Description: Print the design hierarchy for the chosen project. For more details, see Design Hierarchy.
Usage:
./Hog/Do TREE <project_name> [options]
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.
VIEW (VIEW or V)#
Description: Print the contents of Hog list files in a tree-like fashion. For more details, see Hog List Files.
Usage:
./Hog/Do VIEW <project_name> [options]
Options:
verbose— Enable verbose output.
WORKFLOW (WORKFLOW or W)\#
Description: Run the full workflow (synthesis, implementation, and bitstream generation). Usage:
./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.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.-xsa <path>— Path to an existing XSA file for Vitis projects.
CUSTOM COMMANDS#
Hog allows you to define your own custom commands that can be executed using the Hog/Do script.
./Hog/Do <custom_command> [arguments] [options]
This feature enables you to extend the functionality of Hog and automate specific tasks tailored to your workflow.
For more information on how to create custom commands, refer to the section Custom Hog/Do commands.
Running the workflow using Vivado/Quartus GUI#
In a Hog handled project, the HDL 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[1].
Collecting workflow products#
After the HDL 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 (
.binand.bit) properly renamed according to thegit describe(optional) The
.ltxILA files (if ILA cores are used in the project)All the reports produced during synthesis and implementation
(Vivado only) All the
runme.logfiles produced during synthesis and implementation. They will be renamed according to the run name(optional) All the IPbus XML files used in the project listed in the
.ipblist filesA
versions.txtfile 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.txtif all the timing requirements were met, otherwise it is calledtiming_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.
