Introduction to Hdlmake
Rationale
Maintaining VHDL projects either for Altera or for Xilins is a source of many problems. When using Modelsim for simulating VHDL designs there is no tool for dependencies generation. The developer has to think up the dependencies between files and modules, as well as compilation order, on his own. 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 petty modifications to the hardware. Apart from that much of 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 for synthesis purpose only. 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 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 have been some issues with compatibility in Python 3.1 but they have been resolved. Nevertheless, there can occur some unexptected problems following that the Python maintainer don't hesitate to remove functions or change calling syntax. I did my best to ensure compatibility but there is no guarantee for proper working in the newest versions of Python.
Required environment
Hdlmake is basically written for use in 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, by the way).
For the most options Python is the only thing that you need 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 exstension (.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 any),
- 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 have
prepared manifest.py file containing all needed variables. Description
of available variables you can find in a section below. You can also use
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 specifing additional parameteter that are not enclosed in
manifests. All supported actions are listed in an appropriate section
below
Features
Hdlmake consists of two major ingredients which are described below.
File-based project description
Hdlmake defines a way to describe projects that consist of smaller
modules. Usually developers kept these modules together, altough each of
them ``deserved'' an own repository. When some of these modules are
reused accross several projects, then there can appear 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 analizing 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