Documenting the Lattice ECP5 bit-stream format.
Switch branches/tags
Nothing to show
Clone or download
daveshah1 Merge pull request #45 from cr1901/row-col1
Refactor out duplicate "tile name to location mapping".
Latest commit 7f28f11 Nov 12, 2018
Permalink
Failed to load latest commit information.
.github docs: Updating README and related documents May 10, 2018
database Adding initial structure based on prjxray. Mar 5, 2018
docs docs: Updating libtrellis docs and adding text config doc Jul 18, 2018
examples examples: Update EVN example Nov 10, 2018
experiments experiments: Adding proof-of-concept interconnect fuzzer May 10, 2018
fuzzers fuzzers: Copy PLL1 config to BANKREF4 Nov 11, 2018
libtrellis libtrellis: Expose name to row-column mapping in Pytrellis. Nov 12, 2018
metadata/ECP5 metadata: Fix globals JSON Sep 29, 2018
minitests timing: Add a IO timing fuzzer Oct 28, 2018
misc examples: Update EVN example Nov 10, 2018
third_party Adding initial structure based on prjxray. Mar 5, 2018
timing timing: Add EBR cell fuzzer for a few modes Oct 28, 2018
tools util/tools: Use the C++ implementation to map tile names to locations. Nov 12, 2018
util util/tools: Use the C++ implementation to map tile names to locations. Nov 12, 2018
.gitignore infra: Adding 'Getting Started' scripts and updating README May 19, 2018
.update-contributing.py docs: Updating README and related documents May 10, 2018
CODE_OF_CONDUCT.md Adding initial structure from Project X-Ray. Mar 5, 2018
CONTRIBUTING.md docs: Updating README and related documents May 10, 2018
COPYING Adding initial structure from Project X-Ray. Mar 5, 2018
README.md Update README.md Nov 3, 2018
create-empty-db.sh infra: Adding 'Getting Started' scripts and updating README May 19, 2018
devices.json devices.json: Add max_row, max_col, and col_bias. Nov 12, 2018
diamond.sh timing: Infrastructure for cell timing fuzzers Oct 28, 2018
diamond_tcl.sh util: Adding a Python/ispTcl interface library May 12, 2018
download-latest-db.sh infra: Adding 'Getting Started' scripts and updating README May 19, 2018
environment.sh timing: Adding a basic cell timing fuzzer Oct 28, 2018

README.md

Project Trellis

For FPGA Toolchain Users

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.

Getting Started

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 including boost-python
  • Git

Clone the Project Trellis repository and download the latest database:

 git clone https://github.com/SymbiFlow/prjtrellis
 cd prjtrellis
 ./download-latest-db.sh

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.

Current Status

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, using TRELLIS_IO primitives. Pin location and IO type must be specified as attributes on these primitives, separate IO constraint files are not yet implemented.
  • 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 features are not yet supported.
  • Global networks (automatically promoted and routed in nextpnr)

Development Boards

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

For Developers

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 follows the lead of Project X-Ray - which is documenting the bitstream format for the Xilinx Series 7 devices.

Quickstart Guide

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

Install the dependencies:

  • Lattice Diamond 3.10
  • 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 including boost-python

For a generic environment:

source environment.sh

Optionally, modify user_environment.sh and rerun the above command if needed.

Get a head start by downloading current database:

# Give the argument;
# - https if you to use the https protocol (default)
# - git+ssh if you want to use git+ssh protocol
# - git if you want to use the git protocol
./download-latest-db.sh

Alternatively, if you want to start from scratch:

./create-empty-db.sh

Build libtrellis:

cd libtrellis
cmake .
make

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

cd fuzzers/001-plc2_routing
TRELLIS_JOBS=`nproc` python3 fuzzer.py

Process

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.

Parts

Minitests

There are also "minitests" which are small tests of features used to build fuzers.

Fuzzers

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.

Tools

Miscellaneous tools for exploring the database and experimenting with bitstreams.

Util

Python libraries used for fuzzers and other purposes

libtrellis

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.

Database

Running the all fuzzers in order will produce a database which documents the bitstream format in the database directory.

Credits

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.

Contributing

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

Sending

All contributions should be sent as GitHub Pull requests.

License

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.

Code of Conduct

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.