Introduction to Hdlmake
Rationale
Maintaining VHDL projects either for Altera or for Xilinx is a source of many problems. When using Modelsim for simulating VHDL designs there is no tool for dependency generation. The developer has to manually generate the dependencies between files and modules, as well as compilation order. This is laborious and consumes developer's time.
Synthesis of large projects is a time and resource-consuming process. It makes the edit-compile-test cycle unreasonably long and makes it harder to introduce trivial modifications to the hardware. Apart from this, much of the system resources like memory or CPU time are consumed and synthesis makes running other application harder. The solution for this problem is to set up a dedicated server solely for the purpose of synthesis. This allows to delegate this demanding task to a fast machine, while the developer's computer remains still useful.
The aim of the project is to offer multiple functionalities whose aim is to make the VHDL coder's life easier. Nevertheless, its principal goal is to provide means for performing simulation and synthesis for VHDL projects.
Python
The script is written in Python and is checked under Python 2.7. There were some issues with compatibility in Python 3.1 but they have been resolved. The best efforts have been made to ensure compatibility between versions but there is no guarantee of correct behavior in the newest versions of Python.
Required environment
Hdlmake is basically written for use in the Linux environment. It was tested and developed under Ubuntu 10.04. For the time being there are no perspectives for moving to Windows (there is also no need at the moment).
For most of the options, Python is the only thing that is required to
make it work.
In order to perform remote synthesis you should equip your system with a
ssh client and rsync.
Way of use
The basis for Hdlmake are configuration files called ``manifests''. Those files have form of Python scripts and therefore must obey its syntax. They should also have Python extension (.py). As Hdlmake supports synthesis and simulation, they are used for both testbenches and top modules. The major goal of the manifests is to describe the structure of the project:
- what is the module's ancestor (if needed),
- for parent modules; what modules it is made of? where to take them from? where to store them locally?
- what are the local files, that should be used in synthesis or simulation,
- what is the target library for a module (in a VHDL sense),
- what is the name of the project,
- which ISE version should be used,
- which qsh (Quartus Shell) version should be used, etc.
Whenever you want to run Hdlmake for any reason, you should prepare a
manifest.py file containing all the needed variables. Description of
available variables can be found in section \ref{subsec:vars}. For a
quick overview you can also use the built-in user help.
Hdlmake makes use also of run arguments. In general, their purpose is to
indicate the action that should be taken by the script. Some of them are
also used for specifying additional parameters that are not enclosed in
manifests. All supported actions are listed in an appropriate section.
Features
Hdlmake consists of two major components which are described below.
File-based project description
Hdlmake defines a way to describe projects that consist of smaller
modules. Many times developers keep these modules together in a single
repository, even though it is cleaner to store them separately. When
some of these modules are reused across several projects, it can cause a
mess. Hdlmake offers easy and convenient way to specify where to find
necessary modules. There is no need to store them permanently on the
local hard disk.
It is of course up to a developer how a project is divided into smaller
parts. All files can be stored in one folder and kept in one repository,
but this seems to be a bit inconvenient. Everyone should use a structure
that he feels comfortable with.
Helper script for project-related operations
When your project is properly described with manifest files, then you can take advantage of written scripts. You can write makefiles for simulation, do synthesis on other machines over a network. You can fetch needed modules recursively and automatically and get rid of them whenever you want.
Basic run scenarios
In order to Hdlmake developer has to put all python files together in one directory. \verbhdlmake.py must have execution rights. Next it is necessary to change current directory to this one that contains a manifest. From there \verbhdlmake.py must be run with one or more arguments.
Makefile preparation (option -k)
Makefile preparation is one of the most basic features that Hdlmake can be used for. It relieves a developer of creating makefiles by hand. When compiling VHDL files for simulation, one must ensure their correct order. In every project there are more or less complicated dependencies between all project files, that can be expressed in a form of dependency tree - one file makes use of data from an other file by e.g. including it. Each file may not be compiled until all files it is dependent on are compiled, otherwise the compilation process will fail.
In order to use it, Hdlmake must be run from the directory containing a manifest. It is assumed that all needed modules were previously fetched. When run, Hdlmake starts with reading the top module and recursively collecting modules that are parts of the current design. You can specify modules that are stored locally, in a git or in a SVN repository.
When the list of used modules is ready, Hdlmake checks if any of those modules has in its manifest a list of files, that should be used in the testbench. If not, all of the module's files are added to the list of files. In the next step, Hdlmake scans all of the listed files and tries to figure out dependencies between them by analyzing each file's content. They are next written down as a makefile in the testbench's directory.
Fetching submodules for a top module (option -f)
Hdlmake offers a short way of describing project structures. It is assumed that a projects can consist of modules, that are stored in different places (locally or a repo). The same thing is about each of those modules - they can be based on other modules. Hdlmake can fetch all of them and store them in specified places. For each module one can specify a target catalog with manifest variable \verbfetcho. Its value must be a name (existent or not) of a folder. The folder may be located anywhere in the file system. It must be then a relative path (Hdlmake support solely relative paths).
Synthesizing projects remotely (option -r)
Another valuable feature of Hdlmake is the ability to perform VHDL synthesis on a remote machine instead of running it on your desktop. Both Altera's qsh and Xilinx' ISE-command-line-tools are supported. In comparison with local synthesis, remote synthesis has several advantages:
- Developer can run synthesis on a fast machine, instead oh his slow machine
- Developer is not forced to install new software in case when his computer is not equipped with particular version of software
- Synthesis is a resource-consuming process. When someone runes it on a remote machine, his own computer remains usable
- Common synthesis server allows to unify synthesis projects. Usually, when developing a project in a team, all team members have different version of software tools. These tools are complex and their versions are not always fully compatible with each other. When collaborating developers share the same machine for synthesis they can always be sure that the synthesis will run correctly.
In order to make command-line synthesis possible, for both Altera and
Xilinx a project for vendor's IDE must be created - this is Quartus and
ISE respectively. For Xilinx a .tcl file must exist in addition. This
file can be generated when selecting ``Project'' and then ``Generate
.tcl s
Synthesis server and username for logging in on the synthesis server can
be specified with run parameters:--synth-server
and --synth-user
accordingly.
Synthesizing projects locally (option -l)
It is also possible to perform synthesis on the local machine. For this purpose server and username are not necessary.
Additional features
Verbose mode (option -v)
For debugging purpose and having more control over what is happening you can run Hdlmake in verbose mode. In this mode most of the intermediate data structures are printed
Manifest variables description
The description can be found on Manifest-variables-description
Run arguments description
The description can be found on Run-arguments-summary
Examples
Use examples can be found in the project user documentation https://www.ohwr.org/project/hdl-make/wikis/documents