nextpnr -- a portable FPGA place and route tool =============================================== nextpnr aims to be a vendor neutral, timing driven, FOSS FPGA place and route tool. Currently nextpnr supports: * Lattice iCE40 devices supported by [Project IceStorm](http://www.clifford.at/icestorm/) * *(experimental)* Lattice ECP5 devices supported by [Project Trellis](https://github.com/SymbiFlow/prjtrellis) * *(experimental)* a "generic" back-end for user-defined architectures We hope to see Xilinx 7 Series thanks to [Project X-Ray](https://github.com/SymbiFlow/prjxray) and even more FPGA families supported in the future. We would love your help in developing this awesome new project! A brief (academic) paper describing the Yosys+nextpnr flow can be found on [arXiv](https://arxiv.org/abs/1903.10407). Here is a screenshot of nextpnr for iCE40. Build instructions and [getting started notes](#getting-started) can be found below. See also: - [F.A.Q.](docs/faq.md) - [Architecture API](docs/archapi.md) 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](https://github.com/Microsoft/vcpkg/blob/master/ports/python3/CONTROL) - Boost libraries (`libboost-dev libboost-filesystem-dev libboost-thread-dev libboost-program-options-dev libboost-python-dev libboost-dev` or `libboost-all-dev` for Ubuntu) - Eigen3 (`libeigen3-dev` for Ubuntu) is required to build the analytic placer - 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 eigen3` - 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 eigen3:x64-windows` - For static builds, add `-static` to each of the package names. For example, change `eigen3:x64-windows` to `eigen3:x64-windows-static` - A copy of Python that matches the version in vcpkg (currently Python 3.6.4). You can download the [Embeddable Zip File](https://www.python.org/downloads/release/python-364/) and extract it. You may need to extract `python36.zip` within the embeddable zip file to a new directory called "Lib". - For building on macOS, brew utility is needed. - Install all needed packages `brew install cmake python boost boost-python3 qt5 eigen` - 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](http://www.clifford.at/icestorm/) with chipdbs installed in `/usr/local/share/icebox`, or another location, which should be passed as `-DICEBOX_ROOT=/path/to/share/icebox` (ensure to point it to `share/icebox` and not where the icebox binaries are installed) to CMake. Then build and install `nextpnr-ice40` using the following commands: ``` cmake -DARCH=ice40 . make -j$(nproc) sudo make install ``` On Windows, you may specify paths explicitly: ``` cmake -DARCH=ice40 -DICEBOX_ROOT=C:/ProgramData/icestorm/share/icebox -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -G "Visual Studio 15 2017 Win64" -DPYTHON_EXECUTABLE=C:/Python364/python.exe -DPYTHON_LIBRARY=C:/vcpkg/packages/python3_x64-windows/lib/python36.lib -DPYTHON_INCLUDE_DIR=C:/vcpkg/packages/python3_x64-windows/include/python3.6 cmake --build . --config Release ``` To build a static release, change the target triplet from `x64-windows` to `x64-windows-static` and add `-DBUILD_STATIC=ON`. A simple example that runs on the iCEstick dev board can be found in `ice40/examples/blinky/blinky.*`. Usage example: ``` cd ice40/examples/blinky 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](https://github.com/SymbiFlow/prjtrellis), then follow its instructions to download the latest database and build _libtrellis_. ``` cmake -DARCH=ecp5 -DTRELLIS_ROOT=/path/to/prjtrellis . make -j$(nproc) sudo make install ``` - For an ECP5 blinky on the 45k ULX3S board, 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 --textcfg ecp5/synth/ulx3s_out.config` - Create a bitstream using `ecppack ulx3s_out.config ulx3s.bit` - Note that `ulx3s_empty.config` contains fixed/unknown bits to be copied to the output bitstream - More examples of the ECP5 flow for a range of boards can be found in the [Project Trellis Examples](https://github.com/SymbiFlow/prjtrellis/tree/master/examples). ### nextpnr-generic The generic target allows running placement and routing for arbitrary custom architectures. ``` 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 a semicolon separated list. Use `cmake . -DARCH=all` to build all supported architectures. The following runs a debug build of the iCE40 architecture without GUI, without Python support, without the HeAP analytic placer and only HX1K support: ``` cmake -DARCH=ice40 -DCMAKE_BUILD_TYPE=Debug -DBUILD_PYTHON=OFF -DBUILD_GUI=OFF -DBUILD_HEAP=OFF -DICE40_HX1K_ONLY=1 . make -j$(nproc) ``` To make static build relase for iCE40 architecture use the following: ``` cmake -DARCH=ice40 -DBUILD_PYTHON=OFF -DBUILD_GUI=OFF -DSTATIC_BUILD=ON . make -j$(nproc) ``` The HeAP placer's solver can optionally use OpenMP for a speedup on very large designs. Enable this by passing `-DUSE_OPENMP=yes` to cmake (compiler support may vary). You can change the location where nextpnr will be installed (this will usually default to `/usr/local`) by using `-DCMAKE_INSTALL_PREFIX=/install/prefix`. It is possible to pre-generate `.bba` files. This can come in handy when building on time-constrained cloud instances, or in situations where python is unable to use modules. To do this, specify the path to pre- generated `.bba` files by passing `-DPREGENERATED_BBA_PATH=` to cmake. 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` - Running tests with code coverage use `-DBUILD_TESTS=ON -DCOVERAGE` and after `make` run `make ice40-coverage` - After that open `ice40-coverage/index.html` in your browser to view the coverage report - Note that `lcov` is needed in order to generate reports Links and references -------------------- ### Synthesis, simulation, and logic optimization - [Yosys](http://www.clifford.at/yosys/) - [Icarus Verilog](http://iverilog.icarus.com/) - [ABC](https://people.eecs.berkeley.edu/~alanmi/abc/) ### FPGA bitstream documentation (and tools) projects - [Project IceStorm (Lattice iCE40)](http://www.clifford.at/icestorm/) - [Project Trellis (Lattice ECP5)](https://symbiflow.github.io/prjtrellis-db/) - [Project X-Ray (Xilinx 7-Series)](https://symbiflow.github.io/prjxray-db/) - [Project Chibi (Intel MAX-V)](https://github.com/rqou/project-chibi) ### Other FOSS FPGA place and route projects - [Arachne PNR](https://github.com/cseed/arachne-pnr) - [VPR/VTR](https://verilogtorouting.org/) - [SymbiFlow](https://github.com/SymbiFlow/symbiflow-arch-defs) - [Gaffe](https://github.com/gaffe-logic/gaffe) - [KinglerPAR](https://github.com/rqou/KinglerPAR)