Project configuration file#

Hog reads all the project properties from a configuration file called ./Top/<my_project>/hog.conf to generate the HDL project.

The hog.conf file is expected to contain atl least few basic variables with the information needed to build your project. This section contains a full recipe to write a hog.conf file for your project.

Templates for a Vivado, PlanAhead and Quartus project can be found under ./Hog/Templates/hog_*.conf.

This is an example of the minimal hog.conf file needed for a Vivado project, specyfing only the device:

#vivado
[main]
PART = xc7a35tcpg236-1

Telling Hog the HDL compiler to be used#

The first line of your configuration file is expected to be a comment indicating which HDL compiler to be used to generate your project. The following tools are recognised:

  • #vivado

  • #planahead

  • #vivadoHLS

  • #quartus

If this line is not available Hog will assume your project is a Vivado project, but will give you a warning.

Warning

PlanAhead and Quartus are currently partially supported. vivadoHLS option is foreseen in the next releases.

Main section: project variables#

The configuration file needs to contain a “main” section specifiyng at least the the following variables:

PART#

The PART variable indicates the target device code for your project. This variable is mandatory. It must be chosen among the ones provided by the chosen HDL compiler. As an example for a Xilinx Virtex-7 FPGA it could be set to xc7vx330tffg1157-2. Note that the exact code will depend on the full characteristics of the device you are using, e.g. number of logic cells, package, speed grade, etc.

FAMILY#

The FAMILY variable indicates the device family. This variable is mandatory for Quartus only. The value must be chosen among the ones provided by the chosen HDL compiler. As an example for a Intel MAX10 FPGA it must be set to “MAX 10”. Please note that the variable value is included in quotation marks.

Synthesis and implementation sections (Xilinx only)#

In Vivado you can set properties at 3 levels: project, synthesis, implementation. To do this you need to create the specific section of your hog.conf file: “main”, “synth_1”, “impl_1”.

This is an example of a configuration file for a Vivado project that includes several properties:

#vivado
[main]
PART = xc7vx550tffg1927-2

[synth_1]
STEPS.SYNTH_DESIGN.ARGS.RETIMING = true

[impl_1]
steps.write_bitstream.args.bin_file = 1
STEPS.OPT_DESIGN.ARGS.DIRECTIVE = Default
STRATEGY = "Performance_Retiming"

To find out the exact name and value of the property, use Vivado GUI to click on the checkbox you like.

This will make Vivado run the set_property command in the Tcl console.

Then copy and paste the name and the values from the Vivado Tcl console into the lines below.

Parameters section (Xilinx only)#

Vivado projects contain volatile parametres that must be set before launching each run: synthesis and implementation.

The “Parameters” optional section is used fot this purpose. The most important volatile parameter is MAX_THREADS that specifies how many cores to use in synthesis and implementation.

By default Hog sets this value to 1 to assure that the binary files production is deterministic.

This is an example of the parameters section:

[parameters]
MAX_THREADS = 16

Hog section#

The optional Hog section is used to specify Hog directives valid for the project.

The supported properties are:

  • ALLOW_FAIL_ON_CONF: will not set the version to 0 in firmnware registers, even if the conf file is modified with respect to the project (The Critical Warning is still raised)

  • ALLOW_FAIL_ON_LIST: will not set the version to 0 in firmnware registers, even if any of the list files is modified with respect to the project (The Critical Warning is still raised)

  • ALLOW_FAIL_ON_GIT: will not set the version to 0 in firmnware registers, even if a file is found in the project which is not committed to the repository (The Critical Warning is still raised)

Running additional scripts#

If you wish to run some scripts before creating your project you can add a Tcl file called ./Top/<my_project>/pre-creation.tcl. This can be used to generate additional files to be included in your project.

If you want to run a acript after the project is created, you can add a Tcl file called ./Top/<my_project>/post-creation.tcl.

This can be used, for example, to integrate a pin assignment in your Quartus project. To do this export your pin assignment as a tcl script form the Quartus Pin planner (File > Export) and source the resulting script after calling ./Hog/Tcl/create_project.tcl.

Warning

It is possible to add files to the project using these scripts. This is not recommended but still allowed. Please note that adding a file in this way will generate critical warnings beacuse Hog will notice that a file that is incluided in the project is not in the list files. To avoid that Hog also sets the version to 0 in the firmware registers use the ALLOW_FAILON_LIST and ALLOW_FAIL_ON_GIT properties described above.”