OpenPARF

🕹 OpenPARF is an open-source FPGA placement and routing framework build upon the deep learning toolkit PyTorch. It is designed to be flexible, efficient, and extensible.

OpenPARF

More About OpenPARF

OpenPARF is an open-source framework for FPGA rapid placement and routing, which can run on both CPU and GPU. OpenPARF provides a number of APIs to enable researchers to quickly prototype their own FPGA algorithms and evaluate their performance on real FPGA hardware.

At a granular level, OpenPARF is a framework that consists of the following components:

Component	Description
`openparf`	The core placement and routing tool
`openparf.ops`	A collection of operators that allow the implementation of various P&R algorithms
`openparf.placement`	A set of APIs for performing placement tasks
`openparf.routing`	A set of APIs for performing routing tasks
`openparf.py_utils`	Provides other utility functions for Python convenience

OpenPARF provides a compilation stack to integrate your placement and routing algorithms into operators that can be used in Python. You can extend OpenPARF as needed, making it the ideal environment for FPGA optimization enthusiasts.

Elaborating Further:

A Multi-Electrostatic-based FPGA P&R Framework

OpenPARF is a powerful FPGA P&R framework that utilizes a multi-electrostatic-based approach to achieve optimal results with respect to routed wirelength and placement speed. OpenPARF supports the following features:

- A wide range of logical unit types including LUT, FF, DSP, BRAM, IO, Distributed RAM, and Shift Register
- Support for SLICEL and SLICEM CLB heterogeneous types
- Clock routing constraints
- ...

OpenPARF has proven to be a powerful tool, outperforming the state-of-the-art academic FPGA P&R tools in terms of wired length and placement speed. With a 0.4-12.7% improvement in routed wirelength and a speedup of over 2X in placement, OpenPARF is a highly efficient FPGA P&R framework that offers optimized results with minimal manual intervention.

Reference Flow

Demo

The following are the visualization for electrostatic fields in benchmark ISPD2016/FPGA06.

LUT	FF	DSP	BRAM

Installation

From Source

Prerequisites

If you are installing from source, you will need:

Python 3.7 or above
C++ compiler with C++14 support, recommended to use GCC 7.5. Other version may also work, but have not been tested.
PyTorch 1.7.1. Other version may also work, but have not been tested. Please refer to the next section to install PyTorch through conda environment.
Gurobi 9.5, other version may also work, but have not been tested. Please make sure to obtain a valid license and follow the installation instructions provided on the Gurobi website. Please refer to the next section to install Gurobi.
NVIDIA CUDA 11.0 (optional, if compiled with CUDA support). Other versions may also work, but have not been tested. If CUDA is found, the project can run on the GPU implementation, otherwise it will only run on the CPU implementation.

Install Dependencies

We highly recommend installing an Anaconda or Mamba environment. You will get controlled dependency versions regardless of your Linux distro.

# * create and activate conda environment
conda create --name openparf python=3.7
conda activate openparf

# * common packages
conda install cmake boost bison

# * Pytorch 1.7.1. Other version may also work, but have not been tested.
conda install pytorch==1.7.1 torchvision==0.8.2 cudatoolkit=11.0 -c pytorch

# * python packages
pip install hummingbird-ml pyyaml

Install Gurobi

Permit me to illuminate the exquisite process of installing Gurobi, using the recommended Gurobi 9.5.1 as a quintessential example:

Download the gurobi9.5.1_linux64.tar.gz, and then extract it to a location of your choosing, aptly referred to as <your Gurobi home>.
Next, you must obtain a license for Gurobi. To do so, you must first create an account on the Gurobi website. Once you have created an account, you will be able to request an license. Once you receive your license, you will be able to download it from the Gurobi website. The license will be a file with the extension .lic. Save this file to a location of your choosing, aptly referred to as <your Gurobi license path>.
Finally, you must set the following environment variables. You can do so by adding the following lines to your ~/.bashrc file.

export GUROBI_HOME="<your Gurobi home>/linux64"
# For example,
# export GUROBI_HOME="/home/jingmai/softwares/gurobi951/linux64"
export GRB_LICENSE_FILE="<your Gurobi license path>"
# For example,
# export GRB_LICENSE_FILE="/home/jingmai/licenses/gurobi.lic"
export PATH="${PATH}:${GUROBI_HOME}/bin"
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${GUROBI_HOME}/lib"

Get the OpenPARF Source

git clone --recursive https://github.com/PKU-IDEA/OpenPARF.git

Install OpenPARF

Assuming that OpenAPRF is a subfolder in the current directory, i.e., ./OpenPARF is the path to the OpenPARF source code.

mkdir build
cd build
cmake ../OpenPARF -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DPYTHON_EXECUTABLE=$(which python) -DPython3_EXECUTABLE=$(which python) -DCMAKE_INSTALL_PREFIX=<installation directory>
make -j8
make install

Where <installation directory> is the directory where you want to install OpenPARF (e.g., ../install).

Adjust Build Options (Optional)

You can adjust the configuration of cmake variables optionally (without buiding first), by doing the following.

CMAKE_INSTALL_PREFIX: The directory where you want to install OpenPARF (e.g., ../install).
CMAKE_BUILD_TYPE: The build type, can be Release or Debug. Default is Release.
USE_CCACHE: Whether to use ccache to speed up compilation. Default is OFF.

Getting Started

ISPD 2016/2017 Benchmarks

Obtaining Benchmarks

To obtain the benchmarks, you can download the benchmark zip files from the provided Google Drive links. There are separate links for ISPD 2016 and ISPD 2017 FPGA Placement Benchmarks.

💡 Toggle to see how to download files from Google Drive in command line

Click on the download button in the browser (e.g. Chrome)

Copy the download link from the browser

Use the curl command in the terminal to download the file
curl <url> --output <output filename>

Once the files have downloaded, extract their contents to the <installation directory>/benchmarks folder. You should then have two new directories, one for ISPD 2016 and another for ISPD 2017. Remember to keep these benchmark directories separate as OpenPARF supports ISPD2016 and ISPD2017 benchmarks.

<installation directory>/benchmarks
├── ispd2016
├── ispd2017

Running the Benchmarks

To run the benchmarks, navigate to the installation directory and execute the following command:

cd <installation directory>
python openparf.py --config unittest/regression/ispd2016/FPGA01.json

Note that the openparf.py script requires the --config option to specify the configuration file to use. The appropriate configuration file for the benchmark should exist in the corresponding directory (unittest/regression/ispd2016/) before running the command. Other benchmarks can also be run by selecting the appropriate configuration from their respective directory such as unittest/regression/ispd2016 and unittest/regression/ispd2017.

It is essential to ensure all dependencies and the Python environment have been correctly set up before running the command. Once everything is in order, the benchmark will commence, and the outcomes will be sent to the output directory.

Adjust Benchmark Options (Optional)

OpenPARF allows configuration of benchmark parameters using JSON. Default parameters can be found in openparf/params.json, while users can use --config to pass custom parameters which will override defaults. For example:

python openparf.py --config unittest/regression/ispd2016/FPGA01.json

The parameter configuration in unittest/regression/ispd2016/FPGA01.json will override the defaults in openparf/params.json.

Common modifiable parameters include

gpu: Enable GPU acceleration or not. Default is 0.
result_dir: Specify the directory to save P&R results.
route_flag: Enable routing or not. Default is 0.

For more detailed information on parameters, please see the description field in openparf/params.json.

More Advanced Usages

More advanced usages are available to customize the benchmark run.

Running Benchmarks in Batches

We also provide scripts to run ISPD2016 and ISPD2017 in batches. Navigate to the installation directory and execute the following commands:

cd <installation directory>
# ispd 2016
<source directory>/scripts/run_ispd2016_benchmark.sh
# ispd 2017
<source directory>/scripts/run_ispd2017_benchmark.sh

The results can be found in <installation directory>/../ispd2016_log and <installation directory>/../ispd2017_log, respectively. Please refer to the script for specific configurations.

Vivado Flow for Placement Evaluation

If you are looking to evaluate a placement algorithm, you can do so directly with OpenPARF. Alternatively, you can import the placement results from OpenPARF into Vivado for evaluation. This is particularly useful if you are competing in the ISPD 2016/2017 contest and want to use the Vivado flow for placement evaluation. The official websites for ISPD offer instructions on how to load the placement results into the Vivado flow.

When you import the OpenPARF placement result file into Vivado, it will be located in <result dir>/<benchmark name>.pl (e.g., results/FPGA01/FPGA01.pl). Keep in mind that the <result dir> and <benchmark name> are parameters set within the JSON configuration.

NOTE that if you want the evaluate the placement via Vivado, you can disable the routing stage in OpenPARF by simply setting the route_flag to 0 before running the tool.

Resources

ISPD 2016: Routability-Driven FPGA Placement Contest
- Official ISPD 2016 FPGA Placement benchmarks can be downloaded from here.
ISPD 2017: Clock-Aware FPGA Placement Contest

Releases and Contributing

We appreciate all contributions. If you are planning to contribute back bug-fixes, please do so without any further discussion.

If you plan to contribute new features, utility functions or extensions, please first open an issue and discuss the feature with us. Sending a PR without discussion might end up resulting in a rejected PR, because we might be taking the core library in a different direction than you might be aware of.

The Team

OpenPARF is maintained by PKU-IDEA Lab at Peking University, supervised by Prof. Yibo Lin.

Jing Mai, Jiarui Wang and Yibai Meng composed the initial release.

Publications

Jing Mai, Jiarui Wang, Zhixiong Di, Guojie Luo, Yun Liang and Yibo Lin, "OpenPARF: An Open-Source Placement and Routing Framework for Large-Scale Heterogeneous FPGAs with Deep Learning Toolkit", International Conference on ASIC (ASICON), 2023. [paper]
Jing Mai, Yibai Meng, Zhixiong Di, and Yibo Lin, “Multi-electrostatic FPGA placement considering SLICEL-SLICEM heterogeneity and clock feasibility,” in Proceedings of the 59th ACM/IEEE Design Automation Conference (DAC), San Francisco California: ACM, Jul. 2022, pp. 649–654. doi: 10.1145/3489517.3530568. [paper]
Jiarui Wang, Jing Mai, Zhixiong Di, and Yibo Lin, “A Robust FPGA Router with Concurrent Intra-CLB Rerouting,” in Proceedings of the 28th Asia and South Pacific Design Automation Conference (ASP-DAC), Tokyo Japan: ACM, Jan. 2023, pp. 529–534. doi: 10.1145/3566097.3567898. [paper]

CLICK ME to show the bibtex.

@inproceedings{PLACE_ASICON23_Mai_OpenPARF,
  title       = {OpenPARF: An Open-Source Placement and Routing Framework for Large-Scale Heterogeneous FPGAs with Deep Learning Toolkit},
  author      = {Jing Mai and Jiarui Wang and Zhixiong Di and Guojie Luo and Yun Liang and Yibo Lin},
  booktitle   = {International Conference on ASIC (ASICON)}
  year        = {2023},
}

@inproceedings{PLACE_DAC22_Mai,
  title        = {Multi-electrostatic {FPGA} placement considering {SLICEL-SLICEM} heterogeneity and clock feasibility},
  author       = {Jing Mai and Yibai Meng and Zhixiong Di and Yibo Lin},
  booktitle    = {ACM/IEEE Design Automation Conference (DAC)},
  pages        = {649--654},
  year         = {2022},
}

@inproceedings{ROUTE_ASPDAC2023_Wang,
  title     = {{{A Robust FPGA Router with Concurrent Intra-CLB Rerouting}}},
  author    = {Jiarui Wang and Jing Mai and Zhixiong Di and Yibo Lin},
  booktitle = {IEEE/ACM Asia and South Pacific Design Automation Conference (ASPDAC)},
  pages     = {529--534},
  year      = {2023}
}

License

This software is released under BSD 3-Clause License, Please refer to LICENSE for details.

lilinshanghaitech/OpenPARF