Repository files navigation

Project Trellis enables a fully open-source flow for ECP5 FPGAs usingYosysfor Verilog synthesis andnextpnr for place and route.Project Trellis itself provides the device database and tools for bitstream creation.

Install the dependencies for Project Trellis:

• Python 3.5 or later, including development libraries (python3-dev on Ubuntu)
• A modern C++14 compiler (Clang is recommended)
• CMake 3.5 or later
• Boost
• Git
• Recent OpenOCD for device programming (--enable-ftdi required if building from source)

Clone the Project Trellis repository and download the latest database:

 git clone --recursive https://github.com/YosysHQ/prjtrellis

Installlibtrellis and associated tools. Youmust runcmake from the libtrellis directory.Out-of-tree builds are currently unsupported when coupled withnextpnr:

cd libtrelliscmake -DCMAKE_INSTALL_PREFIX=/usr/local .makesudo make install

Clone and installlatest git master versions (Yosys 0.8 is not sufficient for ECP5 development) ofYosysandnextpnr according to their own instructions. Ensureto include theECP5 architecture when building nextpnr; and point it towards your prjtrellisfolder. (for example:cmake -DARCH=ecp5 -DTRELLIS_INSTALL_PREFIX=/usr/local .)

You should now be able to build theexamples.

The following features are currently working in the Yosys/nextpnr/Trellis flow.

• Logic slice functionality, including carries
• Distributed RAM inside logic slices
• All internal interconnect
• Basic IO, including tristate, usingTRELLIS_IO primitives; LPF files and DDR inputs/outputs
• Block RAM, using either inference in Yosys or manual instantiation of the DP16KD primitive
• Multipliers using manual instantiation of the MULT18X18D primitive. Inference and more advanced DSP featuresare not yet supported.
• Global networks (automatically promoted and routed in nextpnr)
• PLLs
• Transcievers (DCUs)

Project Trellis supports all ECP5 devices and should work with any development board. The followingboards have been tested and confirmed working:

• Lattice ECP5-5G Versa Development Kit
• Lattice ECP5 Evaluation Board
• Radiona ULX3S (open hardware)
• TinyFPGA Ex (coming soon)

Project Trellis documents the Lattice ECP5 bit-stream format and internal architecture. Current documentation islocated in machine-readable format inprjtrellis-dband is alsopublished online as HTML.

This repository contains both tools and scripts which allow you to document thebit-stream format of Lattice ECP5 series FPGAs.

More documentation can be found published onprjtrellis ReadTheDocs site -this includes;

• Highlevel Bitstream Architecture
• Overview of DB Development Process
• libtrellis Documentation

This follows the lead ofProject X-Ray - which is documentingthe bitstream format for the Xilinx Series 7 devices.

Currently Project Trellis is tested on Arch Linux, Ubuntu 17.10 andUbuntu 16.04.

Install the dependencies:

• Lattice Diamond 3.10(only required if you want to run fuzzers, not required as an end user or to explore the database)
• Python 3.5 or later, including development libraries (python3-dev on Ubuntu)
• A modern C++14 compiler (Clang is recommended)
• CMake 3.5 or later
• Boost

For a generic environment:

source environment.sh

Optionally, modifyuser_environment.sh and rerun the above command if needed.

Build libtrellis:

cd libtrelliscmake .make

(Re-)creating parts of the database, for example LUT interconnect:

cd fuzzers/ECP5/001-plc2_routingTRELLIS_JOBS=`nproc` python3 fuzzer.py

The documentation is done through a "black box" process were Diamond is asked togenerate a large number of designs which then used to create bitstreams. Theresulting bit streams are then cross correlated to discover what different bitsdo.

This follows the same process asProject 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 theidea 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 ProjectTrellis databases. It is written with C++, with Python bindings exposed usingpybind11 so that fuzzers and utilities can be written in Python.

Instead of downloading thecompiled part database,it can also be created from scratch. However, this proceduretakes several hours, even on a decent workstation.First, the empty reference bitstreams and the tile layout must be createdbased on the initial knowledge provided in themetadatadirectory.Then, running all fuzzers in order will produce a database whichdocuments the bitstream format in the database directory.

UMG and UM5G devices may be stripped fromdevices.jsonto 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.shcd fuzzers/ECP5/001-plc2_routingTRELLIS_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-worldtesting and demos possible.

There are a couple of guidelines when contributing to Project Trellis which arelisted here.

All contributions should be sent asGitHub Pull requests.

All code in the Project Trellis repository is licensed under the very permissiveISC Licence. A copy can be found in theCOPYING file.

All new contributions must also be released under this license.

By contributing you agree to thecode of conduct. Wefollow the open source best practice of using theContributorCovenant for our Code of Conduct.