|
|
# Project description
|
|
|
# Introduction
|
|
|
h3. 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.
|
|
|
|
|
|
The goal of the project is to provide HDL developers with tools, whose
|
|
|
aim is to solve typical problems connected with simulation and
|
|
|
synthesis.
|
|
|
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.
|
|
|
|
|
|
# Simulation
|
|
|
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.
|
|
|
|
|
|
For the time being we are attached to Modelsim as the best tool for HDL
|
|
|
simulation. All of the scripts are intended to use this tool.
|
|
|
### 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.
|
|
|
|
|
|
When compiling VHDL files for simulation, one must ensure their correct
|
|
|
order. In every project there is a dependency tree among files - 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. There are no
|
|
|
major obstacles when simulating Xilinx projects. The Project Navigator
|
|
|
can automatically generate a bash script using Modelsim for any project.
|
|
|
The script ensures correct compilation order and that all dependencies
|
|
|
will be met.
|
|
|
For Altera there is no tool for this purpose delivered by the vendor.
|
|
|
### 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).
|
|
|
|
|
|
The aim of the prepared scripts is to help the developer with this
|
|
|
activity. They can automatically build dependency tree based on project
|
|
|
file and source files and put them write them down in makefile-style.
|
|
|
The complete instruction on using this is provided in the [Document](/documents/50).
|
|
|
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.
|
|
|
h3. 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:
|
|
|
|
|
|
# Synthesis
|
|
|
- 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.
|
|
|
|
|
|
Synthesis of large projects is a time and resource-consuming process. It
|
|
|
makes the edit-compile-test cycle unreasonably long and makes 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.
|
|
|
This work is done by the provided scripts. They support synthesis with
|
|
|
xst, synplify and quartus\_sh (which is shell binding for Altera's
|
|
|
Quartus IDE).
|
|
|
|
|
|
The scripts provide support for different versions of tools (at least
|
|
|
for xst now). The developer can indicate which version of the tool is
|
|
|
expected to be used. This requires installing all desired versions of
|
|
|
the software on the dedicated machine.
|
|
|
The complete instruction on using this is provided in the [Document](/documents/50).
|
|
|
|
|
|
# Things to do
|
|
|
|
|
|
- Add server configuration description to pdf
|
|
|
- Add support for different Synplify versions (if needed)
|
|
|
- Complete support for xst
|
|
|
- Test simulation with more designs
|
|
|
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
|
|
|
h1. Features
|
|
|
Hdlmake consists of two major ingredients which are described below.
|
|
|
h5. 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.
|
|
|
h1. 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.
|
|
|
h1. Additional features
|
|
|
h3. Injecting files list into an ISE project file
|
|
|
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
|
|
|
|