nextpnr

nextpnr -- 便携式FPGA布局布线工具
===============================================

nextpnr 的目标是成为一个供应商中立、时序驱动、开源免费的FPGA布局布线工具。

目前nextpnr支持：
 * 由[Project IceStorm](https://github.com/YosysHQ/icestorm)支持的Lattice iCE40器件
 * 由[Project Trellis](https://github.com/YosysHQ/prjtrellis)支持的Lattice ECP5器件
 * 由[Project Oxide](https://github.com/gatecat/prjoxide)支持的Lattice Nexus器件
 * 由[Project Apicula](https://github.com/YosysHQ/apicula)支持的高云小蜜蜂和Aurora V器件
 * 由[Project Beyond](https://github.com/YosysHQ-GmbH/prjbeyond-db)支持的NanoXplore NG-Ultra器件
 * 由[Project Peppercorn](https://github.com/YosysHQ/prjpeppercorn)支持的Cologne Chip GateMate器件
 * *(实验性)* 由[Mistral](https://github.com/Ravenslofty/mistral)支持的Cyclone V器件
 * *(实验性)* 由[Project Trellis](https://github.com/YosysHQ/prjtrellis)支持的Lattice MachXO2器件
 * *(实验性)* 由[Project X-Ray](https://github.com/F4PGA/prjxray)支持的Xilinx 7系列器件
 * *(实验性)* 用于用户自定义架构的"通用"后端

描述Yosys+nextpnr流程的简要（学术）论文可在[arXiv](https://arxiv.org/abs/1903.10407)上找到。

以下是nextpnr用于iCE40的截图。构建说明和[入门指南](#入门)见下文。

<img src="https://assets.kitploit.com/production/public/readmes/10385/12bab50b683472060ad2a49530d9b6fe58b2c2b70efd1144b849ff83a8a6e80b.png" width="640"/>

另见：
- [常见问题解答](https://github.com/yosyshq/nextpnr/blob/main/docs/faq.md)
- [架构API](https://github.com/yosyshq/nextpnr/blob/main/docs/archapi.md)


先决条件
-------------

构建nextpnr需要安装以下软件包，与所选架构无关：

- CMake 3.25 或更高版本
- 现代C++17编译器（开发时需要`clang-format`）
- Python 3.5 或更高版本，包含开发库（Ubuntu上为`python3-dev`）
  - 对于`nextpnr-himbaechel`需要Python 3.9或更高版本
  - 在Windows上，确保安装与[vcpkg](https://github.com/Microsoft/vcpkg/blob/master/ports/python3/CONTROL)支持的版本相同
- Boost库（Ubuntu上为`libboost-dev libboost-filesystem-dev libboost-thread-dev libboost-program-options-dev libboost-iostreams-dev libboost-dev`或`libboost-all-dev`）
- Eigen3（Ubuntu上为`libeigen3-dev`）
- 需要Yosys来综合demo设计
- 在Windows上使用MSVC构建时，建议使用vcpkg安装依赖。
  - 对于32位构建：`vcpkg install boost-filesystem boost-program-options boost-thread eigen3`
  - 对于64位构建：`vcpkg install boost-filesystem:x64-windows boost-program-options:x64-windows boost-thread:x64-windows eigen3:x64-windows`
  - 对于静态构建，在每个包名后添加`-static`。例如，将`eigen3:x64-windows`改为`eigen3:x64-windows-static`
  - 需要一份与vcpkg中版本匹配的Python副本（当前为Python 3.6.4）。您可以下载[可嵌入的Zip文件](https://www.python.org/downloads/release/python-364/)并解压。您可能需要将可嵌入zip文件中的`python36.zip`解压到一个名为"Lib"的新目录中。
- 在macOS上构建时，需要brew工具。
  - 安装所有需要的包 `brew install cmake python boost eigen`

入门
---------------

首先，运行：

```
git submodule update --init --recursive
```

### nextpnr-ice40

对于iCE40支持，将[Project IceStorm](https://github.com/YosysHQ/icestorm)安装到`/usr/local`或其他位置，并将其作为`-DICESTORM_INSTALL_PREFIX=/usr`传递给CMake。然后使用以下命令构建并安装`nextpnr-ice40`：

```
mkdir -p build && cd build
cmake .. -DARCH=ice40
make -j$(nproc)
sudo make install
```

在Windows上，您可以显式指定路径：

```
cmake . -B build -DARCH=ice40 -DICESTORM_INSTALL_PREFIX=C:/ProgramData/icestorm -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -G "Visual Studio 15 2017 Win64" -DPython3_EXECUTABLE=C:/Python364/python.exe -DPython3_LIBRARY=C:/vcpkg/packages/python3_x64-windows/lib/python36.lib -DPython3_INCLUDE_DIR=C:/vcpkg/packages/python3_x64-windows/include/python3.6
cmake --build build --config Release
```

要构建静态发布版，将目标三元组从`x64-windows`改为`x64-windows-static`并添加`-DBUILD_STATIC=ON`。

一个在iCEstick开发板上运行的简单示例可以在`ice40/examples/blinky/blinky.*`中找到。用法示例：

```
cd ice40/examples/blinky
yosys -p 'synth_ice40 -top blinky -json blinky.json' blinky.v               # 综合为blinky.json
nextpnr-ice40 --hx1k --json blinky.json --pcf blinky.pcf --asc blinky.asc   # 运行布局布线
icepack blinky.asc blinky.bin                                               # 生成二进制比特流文件
iceprog blinky.bin                                                          # 上传设计到iCEstick
```

在GUI模式下运行nextpnr（请参阅下方关于构建带GUI支持的nextpnr的说明）：

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

（使用工具栏按钮或Python命令控制台执行打包、布局、布线和写入输出文件等操作。）

### nextpnr-ecp5

对于ECP5支持，将[Project Trellis](https://github.com/YosysHQ/prjtrellis)安装到`/usr/local`或其他位置，并将其作为`-DTRELLIS_INSTALL_PREFIX=/usr/local`传递给CMake。然后使用以下命令构建并安装`nextpnr-ecp5`：

```
mkdir -p build && cd build
cmake .. -DARCH=ecp5 -DTRELLIS_INSTALL_PREFIX=/usr/local
make -j$(nproc)
sudo make install
```

 - 适用于多种开发板的ECP5流程示例可在[Project Trellis Examples](https://github.com/YosysHQ/prjtrellis/tree/main/examples)中找到。

### nextpnr-nexus

对于Nexus支持，将[Project Oxide](https://github.com/gatecat/prjoxide)安装到`$HOME/.cargo`或其他位置，并将其作为`-DOXIDE_INSTALL_PREFIX=$HOME/.cargo`传递给CMake。然后使用以下命令构建并安装`nextpnr-nexus`：

```
mkdir -p build && cd build
cmake .. -DARCH=nexus -DOXIDE_INSTALL_PREFIX=$HOME/.cargo
make -j$(nproc)
sudo make install
```

 - 适用于多种开发板的Nexus流程示例可在[Project Oxide Examples](https://github.com/gatecat/prjoxide/tree/main/examples)中找到。

### nextpnr-mistral

对于Cyclone V支持，将[Mistral](https://github.com/Ravenslofty/mistral/tree/nextpnr-latest)克隆到`$HOME/mistral`或其他位置，并将此路径作为`-DMISTRAL_ROOT=$HOME/mistral`传递给CMake。然后使用以下命令构建并安装`nextpnr-mistral`：

```
mkdir -p build && cd build
cmake .. -DARCH=mistral -DMISTRAL_ROOT=$HOME/mistral
make -j$(nproc)
sudo make install
```

Cyclone V支持目前是实验性的，测试有限。后端正在进行活跃的API重构，其结构、构建要求和集成点可能会在版本之间发生变化。

### nextpnr-generic

通用目标允许为任意自定义架构运行布局布线。

```
mkdir -p build && cd build
cmake .. -DARCH=generic
make -j$(nproc)
sudo make install
```

如何使用通用流程的示例在[generic/examples](https://github.com/yosyshq/nextpnr/blob/main/generic/examples)中。另见[通用架构文档](https://github.com/yosyshq/nextpnr/blob/main/docs/generic.md)。

### nextpnr-himbaechel

himbaechel目标允许为共享通用结构的较大架构运行布局布线。

#### gowin

对于高云支持，安装[Project Apicula](https://github.com/YosysHQ/apicula)

```
mkdir -p build && cd build
cmake .. -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gowin"
make -j$(nproc)
sudo make install
```

 - 适用于多种开发板的高云流程示例可在[Project Apicula Examples](https://github.com/YosysHQ/apicula/tree/master/examples)中找到。

#### ng-ultra

对于NanoXplore NG-Ultra支持，克隆[Project Beyond DB](https://github.com/yosyshq-GmbH/prjbeyond-db)仓库

```
mkdir -p build && cd build
cmake .. -DARCH="himbaechel" -DHIMBAECHEL_UARCH="ng-ultra" -DHIMBAECHEL_PRJBEYOND_DB=/path/to/prjbeyond-db -DHIMBAECHEL_NGULTRA_DEVICES=ng-ultra
make -j$(nproc)
sudo make install
```

*请注意，二进制比特流创建需要NanoXplore的Impulse工具。*

#### gatemate

对于Cologne Chip GateMate支持，克隆[Project Peppercorn](https://github.com/YosysHQ/prjpeppercorn)

```
mkdir -p build && cd build
cmake .. -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gatemate" -DHIMBAECHEL_PEPPERCORN_PATH=/path/to/prjpeppercorn
make -j$(nproc)
sudo make install
```

### GUI

默认情况下不构建nextpnr GUI，以减少标准无头构建的依赖数量。要启用它，请在CMake命令行中添加`-DBUILD_GUI=ON`，并确保Qt5/Qt6和OpenGL可用：

对于Qt6：
 - 在Ubuntu 22.04 LTS或更高版本上，安装`qt6-base-dev`
 - 对于MSVC vcpkg，安装`qt-base`（32位）或`qt-base:x64-windows`（64位）
 - 对于Homebrew，安装`qt6`并将qt6添加到路径：`echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile`
` - 此更改在下一个终端会话中生效，因此请在构建之前重新打开终端窗口

对于Qt5：
 - 在Ubuntu 22.04 LTS上，安装`qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools`
 - 在其他Ubuntu版本上，安装`qt5-default`
 - 对于MSVC vcpkg，安装`qt5-base`（32位）或`qt5-base:x64-windows`（64位）
 - 对于Homebrew，安装`qt5`并将qt5添加到路径：`echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile`
` - 此更改在下一个终端会话中生效，因此请在构建之前重新打开终端窗口

### 多种架构

要同时为多种架构构建nextpnr，可以在`-DARCH`中使用分号分隔的列表。

```
mkdir -p build && cd build
cmake .. -DARCH="ice40;ecp5"
make -j$(nproc)
sudo make install
```

要构建所有可用的稳定架构，使用`-DARCH=all`。要包含实验性架构（目前是nexus），使用`-DARCH=all+alpha`。

### 每个微架构的Himbächel

要为每个支持的微架构构建单个nextpnr-himbachel可执行文件，请使用`-DHIMBAECHEL_SPLIT`。

```
mkdir -p build && cd build
cmake .. -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gowin;ng-ultra"
make -j$(nproc)
sudo make install
```

在此类构建中，不会生成单个`nextpnr-himbaechel`二进制文件，而是生成两个二进制文件`nextpnr-himbaechel-gowin`和`nextpnr-himbaechel-ng-ultra`。虽然它们一起安装，但每个微架构完全独立于其他微架构，并且只需要其对应的`.../share/himbaechel/<微架构>/`芯片数据库目录即可运行。拆分构建减小了单个分发工件的大小（尽管总大小增加），并允许不同版本的工件共存安装。

交叉编译
-----------------

除了芯片数据库之外，nextpnr还需要`bba`工具为构建系统编译。该工具可以作为单独项目编译：

```
cd bba
cmake .
make
```

这将创建一个`bba-export.cmake`文件。在交叉构建nextpnr时，通过使用`-DBBA_IMPORT=/path/to/bba-export.cmake`提供此文件的路径。

构建nextpnr的附加说明
-------------------------------------

以下命令运行iCE40架构的调试构建，不带GUI、不带Python支持、不带HeAP分析布局器，仅支持HX1K：

```
mkdir -p build && cd build
cmake .. -DARCH=ice40 -DCMAKE_BUILD_TYPE=Debug -DBUILD_PYTHON=OFF -DICE40_DEVICES=1k
make -j$(nproc)
```

要为iCE40架构进行静态构建发布，请使用以下命令：

```
mkdir -p build && cd build
cmake .. -DARCH=ice40 -DBUILD_PYTHON=OFF -DSTATIC_BUILD=ON
make -j$(nproc)
```

HeAP布局器的求解器可以选择使用OpenMP来加速非常大的设计。通过向cmake传递`-DUSE_OPENMP=yes`来启用此功能（编译器支持可能有所不同）。

您可以通过使用`-DCMAKE_INSTALL_PREFIX=/install/prefix`来更改nextpnr的安装位置（通常默认为`/usr/local`）。

开发者说明
--------------------

- 所有代码都使用`clang-format`根据`.clang-format`中的样式规则进行格式化（基于LLVM，增加了缩进宽度，并在类后换行）。
- 要自动格式化所有源代码，运行`make clangformat`。
- 有关架构API的更多文档，请参见wiki。

录制动画
-----------------

- 要保存布局布线的动画录制，请单击工具栏中的录制图标，选择空目录作为录制文件的存储位置，并选择要跳过的帧数。
- 手动启动所有您希望录制的PnR操作
- 再次单击录制图标停止录制
- 转到包含文件的目录并执行 `ffmpeg -f image2 -r 1 -i movie_%05d.png -c:v libx264 nextpnr.mp4`

测试
-------

- 要同时构建测试二进制文件，请使用`-DBUILD_TESTS=ON`，并在`make`之后运行`make test`来运行它们，或者您可以单独运行二进制文件。
- 要使用代码消毒器，请使用`cmake`选项：
  - `-DSANITIZE_ADDRESS=ON`
  - `-DSANITIZE_MEMORY=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++`
  - `-DSANITIZE_THREAD=ON`
  - `-DSANITIZE_UNDEFINED=ON`
- 运行valgrind示例 `valgrind --leak-check=yes --tool=memcheck ./nextpnr-ice40 --json ice40/blinky.json`
- 使用代码覆盖率运行测试，请使用`-DBUILD_TESTS=ON -DCOVERAGE`，并在`make`之后运行`make ice40-coverage`
- 之后在浏览器中打开`ice40-coverage/index.html`查看覆盖率报告
- 注意，生成报告需要`lcov`

链接和参考资料
--------------------

### 综合、仿真和逻辑优化

- [Yosys](https://yosyshq.net/yosys/)
- [Icarus Verilog](http://iverilog.icarus.com/)
- [ABC](https://people.eecs.berkeley.edu/~alanmi/abc/)

### FPGA比特流文档（和工具）项目

- [Project IceStorm (Lattice iCE40)](https://github.com/YosysHQ/icestorm)
- [Project Trellis (Lattice ECP5)](https://yosyshq.github.io/prjtrellis-db/)
- [Project X-Ray (Xilinx 7-Series)](https://github.com/F4PGA/prjxray)
- [Project Chibi (Intel MAX-V)](https://github.com/rqou/project-chibi)

### 其他开源免费FPGA布局布线项目

- [Arachne PNR](https://github.com/cseed/arachne-pnr)
- [VPR/VTR](https://verilogtorouting.org/)
- [SymbiFlow](https://github.com/SymbiFlow/symbiflow-arch-defs)