183 lines
7.2 KiB
Markdown
183 lines
7.2 KiB
Markdown
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!
|
|
|
|
Here is a screenshot of nextpnr for iCE40. Build instructions and
|
|
[getting started notes](#getting-started) can be found below.
|
|
|
|
<img src="https://i.imgur.com/0spmlBa.png" width="640"/>
|
|
|
|
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` 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](http://www.clifford.at/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](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).
|
|
|
|
- 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 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 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)
|
|
```
|
|
|
|
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)
|
|
```
|
|
|
|
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)
|
|
|