Contents

Project configuration file

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 at 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, specifying 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 specifying at least 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

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.

Vivado Strategies

Vivado strategies are in reality a set of directives that changes different parameters. Unfortunately, Hog is not able to compare the properties set by the strategies against the one specified in the hog.conf file. For this reason, if you specify the STRATEGY inside the hog.conf, you will get a Warning, notifying that the config check is disabled.

To avoid this, we suggest to set the Strategy in Vivado and then regenerate the hog.conf file using the provided button. The new file will then contain all the properties of the chosen strategy, without the STRATEGY parameter itself.

Simulation section (Xilinx only)

Simulation properties can be set individual for each simulation set, or globally for all of them. For example, to set xsim.elaborate.rangecheck property for the simulation set sim_1, you should write

[sim_1]
xsim.elaborate.rangecheck = true

Alternatively, if you want to set this property for all your simulation sets, you should write.

[sim]
xsim.elaborate.rangecheck = true

Remember that individual simset properties have always the priority with respect to the global. So you can set a global property for all your simsets, and change it just for one of them, for example.

Parameters section (Xilinx only)

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

The parameters optional section is used for 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 firmware 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 firmware 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 firmware registers, even if a file is found in the project which is not committed to the repository (The Critical Warning is still raised)

  • EXPORT_XSA: will either force or prevent the export of an XSA file for Xilinx Zynq devices (documentation below)

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 script 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.

Note

It is possible to add (or generate) files to the project using these scripts. From Hog2022.1, you can generate any kind of files using tcl scripts. Hog will save the md5sum of the generated files at creation time into a .hog folder, inside the Projects directory. At synthesis time, the md5sum will be compared against what it has been saved, and if different a Warning message will be printed.

XSA Export for Zynq Devices (Xilinx Only)

For Xilinx Zynq devices, integration of the firmware with the Linux system uses a Xilinx Support Archive (XSA) file.

An XSA file is a zip archive containing files such as Vivado tool versions, part numbers, the compiled firmware bitstream, C headers, and the Hardware Handoff File (HHF) that contains information describing the Processor-to-FPGA-interface implemented in the Vivado Block Designer.

Hog supports the automatic generation of XSA files for Zynq devices.

In the post-bitstream stage of compiling Zynq firmware, Hog will check the FPGA part number. If it is determined to be a Zynq device, Hog will automatically run the write_hw_platform command which is used to export an XSA file from a Vivado project. Detection of a Zynq part is using a simple regex for parts beginning with xc7z or xczu; this will need to be updated in the future as new parts are released by Xilinx.

If automatic detection of a supported device fails, generation of an XSA file can be forced with the EXPORT_XSA property in hog.conf. Conversely, if export of XSA files is not desired, it can be disabled with the same property.

[hog]
# set true to force creation of an XSA
EXPORT_XSA=true
# set false to stop creation of an XSA
EXPORT_XSA=false

previous

Hog Local

next

List Files