2014 Release
Introduction
Current Master is a great job with powerful improvements over previous hdlmake releases, but it remains unstable and most of the projects in OHR rely on the older ISYP/v1.0 versions.
Bringing the current Master to a stable and well documented status is the primary target of the action covered by this document.
This wiki page contains the outcomes derived from the analysis of the Master branch current status and a set of proposals intended to improve and stabilize the hdlmake tool.
Development repository
Current work for this upgrade action is being developed on the hdlmake repository under the 2014 branch.
https://www.ohwr.org/project/hdl-make/tree/2014/
Documentation
Command syntax and run arguments name/behavior have changed from ISYP/v1.0 to current Master, but the documentation it's not very clear about this issue.
The most of the documentation is intended for the older versions, and only this link covers how to migrate an older design/script to the current Master Masterforisypusers.
"doc" folder in sources
It includes two pdf files that are not valid for current master as they are ISYP/v1.0 related.
- hdlmake_manual.pdf: this is old, points to ISYP/v1.0 information. It only mentions VHDL supported, while some of the current hdlmake actions support Verilog, VHDL and even some other HDL languages such as System Verilog.
- hdlmake_quick_start.pdf: this is old, related with ISYP/v1.0.
It also includes a document source file in La(tex) format.
- hdlmake.tex: this is supposed to be the actual user document specific for current Master code, but it seems to be targeted to ISYP/v1.0 again and only points to VHDL support.
Wiki content
The older ISYP/v1.0 and current Master related info is mixed across the wiki.
- Manifest-variables-description: this content is from ISYP. Some of the critical variables for current Master are not listed: e.g. syn_tool
- Run-arguments-summary: the argument syntax is from ISYP, but the argument set doesn't match with the actual code/binary.
Proposal
- Compile all the stuff related with ISYP/v1.0 and set a clear wiki section for this older stuff.
- Write a new user documentation for Master in texinfo format:
- Add a complete feature list and a full related parameters/arguments/options user reference.
- Introduce a set of example tutorials covering the most important features.
- Generate developer doc by using a standard code documentation tool (Epydoc or Sphinx)
Demos
There is only a single test in the Master source code (Xilinx ISIM simulation). Creating a separated repository with new tests is listed as one of the desired new features that needs to be done.
Learn by example*: use the same demo projects for both documentation/tutorial and regression testing. The core features we want to test are those the users would like to use.
Test setup
A state-of-the-art test setup environment has been deployed in order to evaluate/test the current Master status and coverage.
Some of the tests that have already been used for this analysis are in the hdlmake test folder under the 2014 repository branch.
The following table indicates the most important testground features:
| Operating System | Ubuntu 14.04 LTS "Trusty Tahr" |
|---|---|
| Python Version | Python 2.7.6 (Python3 not supported) |
| Architecture | i386, amd64, armhf [1] |
- [1] All of those hdlmake actions not relying on a local ISE/Quartus install can be executed from an ARM based processor running an embedded Linux. e.g. Remote synthesis runs OK with minor fixes if a valid xise project is provided.
Proposal
- Develop a list of features that are going to be validated/documented
- Include a simple test/demo example for every feature we want to validate/document.
Synthesis
Brand biased feature set
| Action | ISE (Xilinx) | Quartus (Altera) |
|---|---|---|
| Project Generation | YES | YES |
| Synthesis | YES | NO |
Xilinx ISE is the only supported tool for synthesis -- Altera Quartus synthesis not supported.
NOTE:* GSI uses hdlmake current Master for building Altera projects, and then launch the synthesis by executing a Quartus shell custom script:
- GSI Repository: https://github.com/stefanrauch/bel_projects.
Remote Synthesis
In order to run remote synthesis makefile, an ISE project file must be provided. The problem is that we need a local Xilinx toolchain install in order to generate this project from a Makefile.
This situation may led to ISE project version mismatch between Locally generated xise file and the remote synthesis deploy.
Handling Higher Level Hardware Descriptions
Higher level abstraction such as Xilinx IP Cores and embedded hardware processors are not well managed by ISE tool. The "de-facto" standard workflow for handling this Xilinx design stuff is based on PlanAhead tool.
PlanAhead supports:
- IP (xco): Support for Xilinx coregen components has already been requested in the next issue #938.
- Embedded cores (xps): Zynq dual core ARM Cortex-A9 Processing System is supported. This device is currently being used for testing Libre-FDATool and AsyncArt OHR projects by using custom PlanAhead tcl scripts.
Proposal
- Add support for Makefile generation handling local/remote Quartus synthesis.
- Add remote project generation for both Quartus and ISE.
- Add PlanAhead support for handling Xilinx coregen/DSP/embedded-CPU hardware descriptions.
Simulation
Each simulation makefile builds a run project/workspace and then specific actions need to be executed depending on the simulation tool being handled.
Tool coverage
| Tool | VHDL | Verilog |
|---|---|---|
| ISIM | YES | YES |
| Modelsim | YES | YES |
| Icarus Verilog | NO | YES |
| GHDL | PARTIAL [2] | NO |
*: some GHDL support work was made in a separate branch. This is not included in master and follows an older software design (2 years old).
Proposal
- Add a set of common unified simulation flow commands and output for the different (e.g. run for X time and dumps the signals to a vcd file).
- Fix and merge GHDL support. This is the only "Free/Libre" real alternative for VHDL simulation.
- Allow for remote simulation. Simulation is an ideal remote feature because of the same reasons Synthesis is.
Device Family Support
In order to generate an ISE or a Quartus project, the device family parameter is required. In the current Master, the family support is very limited.
The way in which hdlmake calculates the family from the device ID requires a constant database update as new device families are introduced in the market (e.g. Zynq family).
In adition, some naming schemes are not supported in the current automatic calculation (e.g. Spartan3E, Spartan3AN...), as already discussed on hdlmake mailing list.
Xilinx supported families
| Key | Family |
|---|---|
| XC6S | Spartan6 |
| XC3S | Spartan3 |
| XC6V | Virtex6 |
| XC5V | Virtex5 |
| XC4V | Virtex4 |
| XC7K | Kintex7 |
| XC7A | Artix7 |
Altera supported families
| Key | Family |
|---|---|
| EP2AGX | Arria II GX |
| EP3C | Cyclone III |
Proposal
- Add family as an optional Manifest parameter, in this way we are not limiting the use of new devices.
- If not family option value is provided in the Manifest, hdlmake will try to get the family name from the device parameter.
- Upgrade the automatic family calculation algorithm and database.
- Add to the documentation an entry with how to get the valid device, speed-grade, package and family parameters from datasheet or device marking.
New Features
These are the new features that are listed as not or partially implemented in the following wiki entry: NewFeatures.
| N | Name |
|---|---|
| 1 | Better HDLMAKE_COREDIR handling |
| 6 | Screen support for remote synthesis. |
| 9 | Fetch modules to a single directory, whatever the structure of the project is. |
| 15 | Fix all OHWR issues |
| 19 | Add finer control for synthesis stages |
| 20 | Arrange a separate repository with test projects |
| 21 | Add support for Windows OS |
| 22 | No binary in repo |
Proposal
- Implement the new features to be done.
Issues
Some of the issues marked as solved are not applied in master -- may they be on a branch?.
The following are a couple of examples that are now fixed in 2014 branch:
- Add binary configuration file generation property in synthesis #637.
- Hierachy Separator property breaks ISE synthesis -- this was reported to the mailing list but a issue was not filled.
Proposal
- Mantain the current solved status for all the issues.
- Re-open the previous issues if a related misbehavior is reported in the future.
12 May 2014