nextpnr/README.md

nextpnr -- a portable FPGA place and route tool

nextpnr aims to be a vendor neutral, timing driven, FOSS FPGA place and route tool.

nextpnr was started by SymbioticEDA as an experimental replacement for the existing Arachne-PNR base toolchain (hence the name nextpnr). Focusing on supporting timing driven place and route for multiple FPGA architectures from the ground up, the experiment has proven successful and we believe nextpnr is on its way to being a suitable replacement for all users of Arachne-PNR.

Currently nextpnr supports;

• Lattice iCE40 devices supported by Project IceStorm,
• (experimental) Lattice ECP5 devices supported by Project Trellis,
• (experimental) a "generic" back-end for user-defined architectures

We hope to see Xilinx 7 Series thanks to Project X-Ray and even more vendor's FPGAs supported in the future. We would love your help in developing this awesome new project.

Here is a screenshot of nextpnr for iCE40. Build instructions and getting started notes and an FAQ can be found below.

Prerequisites

The following packages need to be installed for building nextpnr, independent of the selected architecture:

• CMake 3.3 or later
• Modern C++11 compiler (clang-format required for development)
• Qt5 or later (qt5-default for Ubuntu 16.04)
• Python 3.5 or later, including development libraries (python3-dev for Ubuntu)
  • on Windows make sure to install same version as supported by vcpkg
• Boost libraries (libboost-dev or libboost-all-dev for Ubuntu)
• Latest git Yosys is required to synthesise the demo design
• For building on Windows with MSVC, usage of vcpkg is advised for dependency installation.
  • For 32 bit builds: vcpkg install boost-filesystem boost-program-options boost-thread boost-python qt5-base
  • For 64 bit builds: vcpkg install boost-filesystem:x64-windows boost-program-options:x64-windows boost-thread:x64-windows boost-python:x64-windows qt5-base:x64-windows
• For building on macOS, brew utility is needed.
  • Install all needed packages brew install cmake python boost boost-python3 qt5
  • Do not forget to add qt5 in path as well echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile

Getting started

nextpnr-ice40

To build the iCE40 version of nextpnr, install icestorm with chipdbs installed in /usr/local/share/icebox. Then build and install nextpnr-ice40 using the following commands:

cmake -DARCH=ice40 .
make -j$(nproc)
sudo make install

A simple example that runs on the iCEstick dev board can be found in ice40/blinky.*. Usage example:

cd ice40
yosys -p 'synth_ice40 -top blinky -json blinky.json' blinky.v               # synthesize into blinky.json
nextpnr-ice40 --hx1k --json blinky.json --pcf blinky.pcf --asc blinky.asc   # run place and route
icepack blinky.asc blinky.bin                                               # generate binary bitstream file
iceprog blinky.bin                                                          # upload design to iCEstick

Running nextpnr in GUI mode:

nextpnr-ice40 --json blinky.json --pcf blinky.pcf --asc blinky.asc --gui

(Use the toolbar buttons or the Python command console to perform actions such as pack, place, route, and write output files.)

nextpnr-ecp5

For ECP5 support, you must download Project Trellis, then follow its instructions to download the latest database and build libtrellis.

cmake -DARCH=ecp5 .
make -j$(nproc)
sudo make install

• For an ECP5 blinky, first synthesise using yosys blinky.ys in ecp5/synth.

• Then run ECP5 place-and route using ./nextpnr-ecp5 --json ecp5/synth/blinky.json --basecfg ecp5/synth/ulx3s_empty.config --bit ecp5/synth/ulx3s.bit

• Note that ulx3s_empty.config contains fixed/unknown bits to be copied to the output bitstream

• You can also use --textcfg out.config to write a text file describing the bitstream for debugging

• More examples of the ECP5 flow for a range of boards can be found in the Project Trellis Examples.

• Currently the ECP5 flow supports LUTs, flipflops and IO. IO must be instantiated using TRELLIS_IO primitives and constraints specified using LOC and IO_TYPE attributes on those instances, as is used in the examples.

nextpnr-generic

The generic target allows to run place and route for an arbitrary custom architecture.

cmake -DARCH=generic .
make -j$(nproc)
sudo make install

TBD: Getting started example for generic target.

Additional notes for building nextpnr

Use cmake -D options to specify which version of nextpnr you want to build.

Use -DARCH=... to set the architecture. It is semicolon separated list. Use cmake . -DARCH=all to build all supported architectures.

The following runs a debug build of the iCE40 architecture without GUI and without Python support and only HX1K support:

cmake -DARCH=ice40 -DCMAKE_BUILD_TYPE=Debug -DBUILD_PYTHON=OFF -DBUILD_GUI=OFF -DICE40_HX1K_ONLY=1 .
make -j$(nproc)

Notes for developers

• All code is formatted using clang-format according to the style rules in .clang-format (LLVM based with increased indent widths and brace wraps after classes).
• To automatically format all source code, run make clangformat.
• See the wiki for additional documentation on the architecture API.

Testing

• To build test binaries as well, use -DBUILD_TESTS=ON and after make run make tests to run them, or you can run separate binaries.
• To use code sanitizers use the cmake options:
  • -DSANITIZE_ADDRESS=ON
  • -DSANITIZE_MEMORY=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
  • -DSANITIZE_THREAD=ON
  • -DSANITIZE_UNDEFINED=ON
• Running valgrind example valgrind --leak-check=yes --tool=memcheck ./nextpnr-ice40 --json ice40/blinky.json

FAQ

Which tool chain should I use and why?

• If you wish to do new research into FPGA architectures, place and route algorithms or other similar topics, we suggest you look at using Verilog to Routing.

• If you are developing FPGA code in Verilog for a Lattice iCE40 and need an open source toolchain, we suggest you use nextpnr.

• If you are developing FPGA code in Verilog for a Lattice iCE40 with the existing Arachne-PNR toolchain, we suggest you start thinking about migrating to nextpnr.

• If you are developing Verilog FPGA code targeted at the Lattice ECP5 and need an open source toolchain, you may consider the extremely experimental ECP5 support in nextpnr.

• If you are developing FPGA code in VHDL you will need to use either a version of Yosys with Verific support or the vendor provided tools due to the lack of open source VHDL support in Yosys.

Why didn't you just improve Arachne-PNR?

Arachne-PNR was originally developed as part of Project IceStorm to demonstrate it was possible to create an open source place and route tool for the iCE40 FPGAs that actually produced valid bitstreams.

For it's original purpose it has served the community extremely well. However, it was never designed to support multiple different FPGA devices, nor more complicated timing driven routing used by most commercial place and route tools.

It felt like extending Arachne-PNR was not going to be the best path forward, so SymbioticEDA decided to invest in an experiment around creating a replacement. nextpnr is the result of that experiment and we believe well on it's way to being a direct replacement for Arachne-PNR (and hence why it is called nextpnr).

Arachne-PNR does X better!

If you have a use case which prevents you from switching to nextpnr from Arachne, we want to hear about it! Please create an issue following the Arachne-PNR regression template and we will do our best to solve the problem!

We want nextpnr to be a suitable replacement for anyone who is currently a user of Arachne.

Why are you not just contributing to Verilog to Routing?

We believe that Verilog to Routing is a great tool and many of the nextpnr developers have made (and continue to make) contributions to the project.

VtR is an extremely flexible tool but focuses on research around FPGA architecture and algorithm development. If your goal is research, then we very much encourage you to look into VtR further!

nextpnr takes a different approach by focusing on users developing FPGA code for current FPGAs.

We also believe that support for real architectures will enable interesting new research. nextpnr (like all place and route systems). depends heavily on research groups like the VtR developers to investigate and push forward FPGA algorithms in new and exciting ways.

What is VPR?

VPR is the "place and route" tool from Verilog To Routing. It has a similar role in an FPGA development flow as nextpnr.

What about SymbiFlow?

We expect that as nextpnr matures, it will become a key part of the SymbiFlow. For now, while still in a more experimental state SymbioticEDA will continue to host the project.

For the moment SymbiFlow is continuing to concentrate on extending Verilog to Routing tool to work with real world architectures.

Who is working on this project?

nextpnr was started as an experiment by SymbioticEDA but hopes to grow beyond being both just an experiment and developed by a single company. Like Linux grew from Linus Torvalds experiment in creating his own operating system to something contributed too by many different companies, are hope is the same will happen here.

The project has already accepted a number of contributions from people not employed by SymbioticEDA and now with the public release encourages the community to contribute too.

What is Project Trellis?

Project Trellis is the effort to document the bitstream format for the Lattice ECP5 series of FPGAs. It also includes tooling around bitstream creation.

Project Trellis is used by nextpnr to enable support for creation of bitstreams for these parts.

What is Project X-Ray?

Project X-Ray is the effort to document the bitstream format for the Xilinx Series 7 series of FPGAs. It also includes tooling around bitstream generation for these parts.

While nextpnr currently does not support these Xilinx parts, we expect it will soon by using Project X Ray in a similar manner to Project Trellis.

What is Project IceStorm?

Project IceStorm was both a project to document the bitstream for the Lattice iCE40 series of parts and a full flow including Yosys and Arachne-PNR for converting Verilog into a bitstream for these parts.

As the open source community now has support for multiple different FPGA parts, in the nextpnr documentation we generally use Project IceStorm to mean the tools that fulfil the same role as Project Trellis or Project X-Ray.

Links and references

Synthesis, simulation, and logic optimization

• Yosys
• Icarus Verilog
• ABC

FPGA bitstream documentation (and tools) projects

• Project IceStorm (Lattice iCE40)
• Project Trellis (Lattice ECP5)
• Project X-Ray (Xilinx 7-Series)
• Project Chibi (Intel MAX-V)

Other FOSS FPGA place and route projects

• Arachne PNR
• VPR/VTR
• SymbiFlow
• Gaffe
• KinglerPAR