List Files¶

A directory named list must be in each of the top project-folders. This directory contains the list files, that are plain text files, used to instruct Hog on how to build your project. Each list file shall contain the list of the files to be added to the project.

For Vivado projects, some properties can also be specified in the list files by adding them after the file name, separated by any number of spaces. Comments can be added using #. A generic list file looks therefore like this,

    source_dir/file1.vhd [prop_1] [prop_2]
    # comment here, for example
    source_dir/file2.vhd [prop_3]
    source_dir/file3.vhd

Hog also supports the use of simple wildcards to specify source files. For example, the three source files above could be added with:

    source_dir/*.vhd [prop]

Note that a property applied to a wildcard source file will be applied to all source files found. Wildcards can be used in the path as well as the filename, e.g. */src/*.vhd. During project creation, the build scripts will print out a note with the files found by the wildcard expansion. Currently there is no way to exclude files from the wildcard (a la in a Gitignore file) so you should make sure you are not adding unwanted files.

Hog uses different kinds of list files, identified by their extension:

.src : used to include HDL files belonging to the same library
.sim : used to include files use for simulation of the same library
.con : used to include constraint files
.prop: used to set some Vivado properties, such as the number of threads used to build the project.
.ext : used to include HDL files belonging to an external library

Note

In .src, .sim, and .con list files, you must use paths relative to the repository location to the files to be included in the project.

Source list files (.src)¶

Hog creates a HDL library1 for each .src list file and assign all the file included in the list file to that library.

For example, if there is a lib_1.src file in the list directory like this:

    source_dir/file1.vhd
    source_dir/file2.vhd
    source_dir/file3.vhd
    IP/ip1.xci
    IP/ip2.xci

the files will be included into the Vivado project in the lib_1 library.

To use them in VHDL2 you should use the following syntax:

  library lib_1
  use lib_1.all

  ...

  u_1 : entity lib_1.a_component_in_lib1
  port map(
    clk => clk,
    din => din,
    dout => dout
  ):

For Vivado projects the following properties can be specified for files in a .src list:

93: (only for .vhd and .vhdl files) File type is VHDL 93. If not specified Hog will use VHDL20083.
XDC: File Type is XDC
nosynth: File will not be used in synthesis
noimpl: File will not be used in implementation
nosim: File will not be used in simulation
locked: ONLY FOR .xci FILES, the IP will not be re-synthesised by the CI. More details in the IP section

Note that Hog for Quartus does not support any by file options.

Simulation list files (.sim)¶

In this files are listed all the HDL files used only for simulations. These include test benches and other files that are not used in synthesis: for example modules used to read and write from and to files.

For each .sim file, Hog creates a so-called “simulation set”.

For more information about simulation and .sim simulation list-files see the specific chapter

Constraint list files (.con)¶

All constraint files must be included by adding them into the .con files. Both .xdc (for Vivado), .sdc and .tcl files can be added here. For Vivado the nosynth and noimpl properties can be specified here, if required.

For example, a .con file looks like:

  constr_source_dir/constr1.xcf           #constraint used for synthesis and implementation
  constr_source_dir/constr2.xcf nosynth   #constraint not used in synthesis
  constr_source_dir/constr3.xcf noimpl    #constraint used in synthesis only

List files are recursive¶

A list file can contain another list file, whose content will be then included.

You can include a mixture of source files and list files, Hog will recognise them by the extension.

This feature can be used if multiple projects on the same repository share a subset of files. A common list file can be created and stored anywhere in the repository and then included in the specific project list files.

If the content of a list file is added recursively, by default Hog uses the file name of the included list file as library name. A custom name can be specified by using the lib keyword as a property of the included list file in the including list file. This is quite convoluted, hopefully the following example will help.

For example, say that foo.src includes bar.src that in turn includes file.vhd, by default the library of file.vhd (and of all other files contained in bar.src) is bar.

To change it to a custom name, the following syntax can be used inside foo.src:

file_a.vhd
file_b.v
...

bar.src lib=my_library

...

Now Hog will set the “my_library” for all the vhdl files contained in bar.src.

Note

This feature is not implemented for Quartus projects.

Properties list files (.prop)¶

Properties list files (.prop) are used to collect a small and optional set of Vivado properties.

Currently supported properties:

maxThreads <N>: sets the number of threads used to build the project. Multi-threading is disabled by default to improve the reproducibility of firmware builds.

Note

Hog for Quartus does not support any by file options.

External list files (.ext)¶

External proprietary files that are protected by copyright and cannot be published on the repository shall be included using the .ext list file. This procedure has to be used ONLY in the exceptional case of files that can not be published because of copyright.

The .ext list file has a special syntax since the md5 hash of each file must be added after the file name, separated by one or more spaces:

/afs/cern.ch/project/p/project/restricted/file_1.vhd  725cda057150d688c7970cfc53dc6db6
/afs/cern.ch/project/p/project/restricted/file_2.xci  c15f520db4bdef24f976cb459b1a5421

The md5 hash can be obtained by running the md5sum command on a bash shell

  md5sum <filename>

the same checksum can be obtained on the Vivado or QuartusPrime tcl shell by using:

  md5::md5 -filename <file name>

Hog, at synthesis time, checks that all the files are there and that their md5 hash matches the one contained in the list file.

Absolute or relative paths in .ext files?

.ext list files must use absolute paths or relative to HOG_EXTERNAL_PATH folder, if defined. To use the firmware Continuous Integration, this path must be accessible to the machine performing the git CI, e.g. can be on a protected afs folder.

Note

This feature is not implemented for Quartus projects.

1: https://www.xilinx.com/support/documentation/sw_manuals/xilinx11/ise_c_working_with_vhdl_libraries.htm
2: Libraries are ignored in Verilog and SystemVerilog
3: Note that VHDL2008 is not supported by the planAhead/ISE synthesis tools.