| commit | dc4120e76750ed372feab637f299585908431c35 | [log] [tgz] |
|---|---|---|
| author | Nathan Rossi <nathan@nathanrossi.com> | Wed Jun 19 17:29:30 2019 +1000 |
| committer | Nathan Rossi <nathan@nathanrossi.com> | Wed Jun 19 17:29:30 2019 +1000 |
| tree | 72be566c46e3f8670291d63cd890b7a24084d7dd | |
| parent | 3293c4f8a0a3cdd817833bcafa3889d71b7ef3ba [diff] |
libtrellis: Add support for portable execution with trellis database In order to execute the ecpmulti, ecppack and ecpunpack programs they must be able to access the trellis database files. These files are installed alongside the tools in the data directory (normally /usr/share). To enable portable execution of these programs such that they can access the database relative to their executables path the programs must be built with the relative path embedded and also be able to access the executables path at run time. Since libtrellis already depends on Boost it makes sense to use the Boost dll module. This module provides the 'program_location' function which can be used with the 'boost::filesystem::path' to build the absolute path to the database at run time. The only downside with the use of the Boost dll module is that a unused component of the included source relies on certain dynamic linker functions which requires linking to libdl on some platforms. This however is easily handled by the CMAKE_DL_LIBS variable which expands to the correct linker arg on targets that require linking with the dynamic linker. The Boost dll module was only added in 1.61. In order to support older versions of Boost such as that of Ubuntu 16.04 (1.58), a local implementation of 'program_location' is added which is based on the 'proc_self_dirname' implementation from yosys. This version is chosen due to its use in a number of tools similar to libtrellis (e.g. icestorm) but also due to its ISC license which matches libtrellis. This implementation is conditionally used if the Boost dll module is unavailable. The cmake configuration is also changed to generate a relative path from datadir to bindir, this path is then provided during the build as TRELLIS_RPATH_DATADIR. Note: ecppll does not currently use the trellis database Signed-off-by: Nathan Rossi <nathan@nathanrossi.com>
Project Trellis enables a fully open-source flow for ECP5 FPGAs using Yosys for Verilog synthesis and nextpnr for place and route. Project Trellis itself provides the device database and tools for bitstream creation.
Install the dependencies for Project Trellis:
python3-dev on Ubuntu)--enable-ftdi required if building from source)Clone the Project Trellis repository and download the latest database:
git clone --recursive https://github.com/SymbiFlow/prjtrellis
Install libtrellis and associated tools. You must run cmake from the libtrellis directory. Out-of-tree builds are currently unsupported when coupled with nextpnr:
cd libtrellis cmake -DCMAKE_INSTALL_PREFIX=/usr . make sudo make install
Clone and install latest git master versions (Yosys 0.8 is not sufficient for ECP5 development) of Yosys and nextpnr according to their own instructions. Ensure to include the ECP5 architecture when building nextpnr; and point it towards your prjtrellis folder.
You should now be able to build the examples.
The following features are currently working in the Yosys/nextpnr/Trellis flow.
TRELLIS_IO primitives; LPF files and DDR inputs/outputsProject Trellis supports all ECP5 devices and should work with any development board. The following boards have been tested and confirmed working:
Project Trellis documents the Lattice ECP5 bit-stream format and internal architecture. Current documentation is located in machine-readable format in prjtrellis-db and is also published online as HTML.
This repository contains both tools and scripts which allow you to document the bit-stream format of Lattice ECP5 series FPGAs.
More documentation can be found published on prjtrellis ReadTheDocs site - this includes;
This follows the lead of Project X-Ray - which is documenting the bitstream format for the Xilinx Series 7 devices.
Currently Project Trellis is tested on Arch Linux, Ubuntu 17.10 and Ubuntu 16.04.
Install the dependencies:
python3-dev on Ubuntu)For a generic environment:
source environment.sh
Optionally, modify user_environment.sh and rerun the above command if needed.
Build libtrellis:
cd libtrellis cmake . make
(Re-)creating parts of the database, for example LUT interconnect:
cd fuzzers/ECP5/001-plc2_routing TRELLIS_JOBS=`nproc` python3 fuzzer.py
The documentation is done through a “black box” process were Diamond is asked to generate a large number of designs which then used to create bitstreams. The resulting bit streams are then cross correlated to discover what different bits do.
This follows the same process as Project X-Ray - more documentation can be found here.
There are also “minitests” which are small tests of features used to build fuzers.
Fuzzers are the scripts which generate the large number of bitstream.
They are called “fuzzers” because they follow an approach similar to the idea of software testing through fuzzing.
Miscellaneous tools for exploring the database and experimenting with bitstreams.
Python libraries used for fuzzers and other purposes
libtrellis is a library for manipulating ECP5 bitstreams, tiles and the Project Trellis databases. It is written with C++, with Python bindings exposed using Boost::Python so that fuzzers and utilities can be written in Python.
Instead of downloading the compiled part database, it can also be created from scratch. However, this procedure takes several hours, even on a decent workstation. First, the empty reference bitstreams and the tile layout must be created based on the initial knowledge provided in the metadata directory. Then, running all fuzzers in order will produce a database which documents the bitstream format in the database directory.
UMG and UM5G devices may be stripped from devices.json to ceate the database only for non-SERDES chip variants. Obviously, SERDES related fuzzers are not able to run in this case.
source environment.sh ./create-empty-db.sh cd fuzzers/ECP5/001-plc2_routing TRELLIS_JOBS=`nproc` python3 fuzzer.py ... (run more fuzzers)
Thanks to @tinyfpga for the original inspiration, and @mithro for the name and initial support.
Thanks to @q3k, @emard and @tinyfpga for their donations of ECP5 hardware that have made real-world testing and demos possible.
There are a couple of guidelines when contributing to Project Trellis which are listed here.
All contributions should be sent as GitHub Pull requests.
All code in the Project Trellis repository is licensed under the very permissive ISC Licence. A copy can be found in the COPYING file.
All new contributions must also be released under this license.
By contributing you agree to the code of conduct. We follow the open source best practice of using the Contributor Covenant for our Code of Conduct.