Merge pull request #938 from lnis-uofu/xt_doc

Misc documentation updates

README.md

@@ -1,5 +1,7 @@
 # Getting Started with OpenFPGA <img src="./docs/source/overview/figures/OpenFPGA_logo.png" width="200" align="right">
-[![linux build](https://github.com/LNIS-Projects/OpenFPGA/workflows/linux_build/badge.svg)](https://github.com/LNIS-Projects/OpenFPGA/actions?query=workflow%3Alinux_build)
+[![Test](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/build.yml/badge.svg)](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/build.yml)
+[![Cell Library Tests](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/cell_lib_test.yml/badge.svg)](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/cell_lib_test.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Documentation Status](https://readthedocs.org/projects/openfpga/badge/?version=master)](https://openfpga.readthedocs.io/en/master/?badge=master)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/lnis-uofu/OpenFPGA/master?urlpath=vscode)
 
@@ -7,88 +9,23 @@ Version: see [`VERSION.md`](VERSION.md)
 
 ## Introduction
 
-The award-winning OpenFPGA framework is the **first open-source FPGA IP generator** supporting highly-customizable homogeneous FPGA architectures. OpenFPGA provides complete EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification. OpenFPGA opens the door to democratizing FPGA technology and EDA techniques with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers.
+The award-winning OpenFPGA framework is the **first open-source FPGA IP generator with silicon proofs** supporting highly-customizable FPGA architectures. OpenFPGA provides complete EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification. OpenFPGA opens the door to democratizing FPGA technology and EDA techniques with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers.
 
 **If this is your first time working with OpenFPGA, we strongly **recommend you watch the** [introduction video about OpenFPGA](https://youtu.be/ocODUGcYGqo)**
 
 A quick overview of OpenFPGA tools can be found [**here**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/tools/).
 We also recommend potential users check out the summary of [**technical capabilities**](https://openfpga.readthedocs.io/en/master/overview/tech_highlights/#) before compiling.
 
+**Before asking for help, please checkout the** [Frequently Asked Questions](https://github.com/lnis-uofu/OpenFPGA/discussions/937)
+
 ## Compilation
 
 **A tutorial **video about **how to compile** can be** found [here](https://youtu.be/F9sMRmDewM0)**
 
-Before starting, we strongly recommend you read the required dependencies at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/).
+Detailed guidelines are available at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/).
+Before starting, we strongly recommend you read the required dependencies and ensure that they are correctly installed.
 It also includes detailed information about the docker image.
 
----
-
-**Compilation Steps:**
-
-```bash
-# Clone the repository and go inside it
-git clone https://github.com/LNIS-Projects/OpenFPGA.git && cd OpenFPGA
-make all
-```
-
----
-
-**Quick Compilation Verification**
-
-To quickly verify the tool is well compiled, the user can run the following command from the OpenFPGA root directory.
-```bash
-source openfpga.sh
-run-task compilation_verification --debug --show_thread_logs
-```
-
-*Python3 and iVerilog v10.1+ are required. GUI will pop up if enabled during compilation.*
-
----
-
-**Supported Operating Systems**
-
-We currently target OpenFPGA for:
- 1. Ubuntu 18.04
- 2. Red Hat 7.5
-
-*The tool was tested with these operating systems. It might work with earlier versions and other distributions.*
-
-## Running with pre-built docker image
-
-```bash
-# To get the docker image from the repository,
-docker pull ghcr.io/lnis-uofu/openfpga-master:latest
-
-# To invoke openfpga_shell
-docker run -it ghcr.io/lnis-uofu/openfpga-master:latest openfpga/openfpga bash
-```
-
-## Backward compatibility with OpenFPGA v1.1
-
-OpenFPGA v1.2 is a major upgrade over v1.1, which upgrades the internal VPR engine.
-The (VPR) architecture files used with v1.1 may not be compatible with v1.2.
-
-You can upgrade your architecture files with script
-
-```bash
-python3 openfpga_flow/scripts/arch_file_updater.py \
-    --input_file ${v1.1_arch_file} \
-    --output_file ${v1.2_compatible_arch_file}
-```
-
-Or, If you want to stay with v1.1, the final build was (tag: [_OpenFPGA:v1.1.541](https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
-))
-
-```bash
-https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
-```
-
-or you can download the docker image
-
-```bash
-docker pull ghcr.io/lnis-uofu/openfpga-master:v1.1.541
-```
-
 ## Documentation
 
 OpenFPGA's [full documentation](https://openfpga.readthedocs.io/en/master/) includes tutorials, descriptions of the design flow, and tool options.
@@ -96,3 +33,29 @@ OpenFPGA's [full documentation](https://openfpga.readthedocs.io/en/master/) incl
 ## Tutorials
 
 You can find a set of [tutorials](https://openfpga.readthedocs.io/en/master/tutorials/), with which you get familiar with the tool and use OpenFPGA for various purposes.
+
+## Backward Compatibility
+
+If you were using an old version of OpenFPGA and are now interested to move to the latest version, please check out the [developer guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/back_compatibile).
+
+## License
+
+All the codes are under MIT license, with the exception of submodules, e.g., VTR, Yosys and Yosys-plugin, which are distributed under its own (permissive) terms. See their full license for details.
+
+## How to Cite
+
+Please use the following paper as a general citation for OpenFPGA:
+
+X. Tang, E. Giacomin, B. Chauviere, A. Alacchi and P. -E. Gaillardon, "OpenFPGA: An Open-Source Framework for Agile Prototyping Customizable FPGAs," in IEEE Micro, vol. 40, no. 4, pp. 41-48, 1 July-Aug. 2020, doi: 10.1109/MM.2020.2995854.
+
+Bibtex:
+
+```
+@ARTICLE{9098028,  author={Tang, Xifan and Giacomin, Edouard and Chauviere, Baudouin and Alacchi, Aurélien and Gaillardon, Pierre-Emmanuel},  journal={IEEE Micro},   title={OpenFPGA: An Open-Source Framework for Agile Prototyping Customizable FPGAs},   year={2020},  volume={40},  number={4},  pages={41-48},  doi={10.1109/MM.2020.2995854}}
+```
+
+A list of related publications can be found [here](https://openfpga.readthedocs.io/en/master/reference/).
+
+## Contributing to OpenFPGA
+
+Please read the [contributor guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/contributor_guide) if you would like to contribute to OpenFPGA.

docs/source/appendix/acknowledge.rst

@@ -0,0 +1,21 @@
+.. _acknowledgement:
+
+Acknowledgement
+===============
+
+We are thankful to the organizations which support the OpenFPGA project and build the growing community.
+
+.. figure:: ./figures/uofu_logo.png
+      :width: 30%
+.. figure:: ./figures/lnis_logo.png
+      :width: 30%
+.. figure:: ./figures/darpa_logo.png
+      :width: 30%
+.. figure:: ./figures/google_logo.png
+      :width: 30%
+.. figure:: ./figures/quicklogic_logo.png
+      :width: 30%
+.. figure:: ./figures/rapidsilicon_logo.png
+      :width: 30%
+.. figure:: ./figures/rapidflex_logo.png
+      :width: 30%

docs/source/appendix/contact.rst

@@ -9,7 +9,7 @@ Prof. Pierre-Emmanuel Gaillardon
 
 pierre-emmanuel.gaillardon@utah.edu
 
-Technical Details about FPGA-SPICE/Verilog/Bitstream/SDC:
+Technical Details about EDA and Software:
 
 Dr. Xifan Tang
 

docs/source/appendix/figures/rapidflex_logo.png:Zone.Identifier

@@ -0,0 +1,3 @@
+[ZoneTransfer]
+ZoneId=3
+HostUrl=https://rapidflex.cn/wp-content/uploads/2022/04/Untitled-design-49.png

docs/source/appendix/index.rst

@@ -0,0 +1,9 @@
+
+.. toctree::
+   :maxdepth: 1
+
+   contact
+
+   acknowledge
+
+   reference

docs/source/appendix/z_reference.bib

@@ -104,3 +104,30 @@ volume={},
 number={},
 doi={10.1109/ICFPT47387.2019.00039},
 pages={247-250},}
+
+@ARTICLE{XTang_ieeemicro_2020,  author={Tang, Xifan and Giacomin, Edouard and Chauviere, Baudouin and Alacchi, Aurélien and Gaillardon, Pierre-Emmanuel},  journal={IEEE Micro},   title={OpenFPGA: An Open-Source Framework for Agile Prototyping Customizable FPGAs},   year={2020},  volume={40},  number={4},  pages={41-48},  doi={10.1109/MM.2020.2995854}}
+
+@article{XTang_woset_2020,
+  title={OpenFPGA: Towards Automated Prototyping for Versatile FPGAs},
+  author={Tang, Xifan and Gore, Ganesh and Giacomin, Edouard and Alacchi, Aur{\'e}lien and Chauviere, Baudouin and Gaillardon, Pierre-Emmanuel},
+  journal={Workshop on Open-Source EDA Technology},
+  year={2020}
+}
+
+@inproceedings{GGore_ispd_2021,
+author = {Gore, Ganesh and Tang, Xifan and Gaillardon, Pierre-Emmanuel},
+title = {A Scalable and Robust Hierarchical Floorplanning to Enable 24-Hour Prototyping for 100k-LUT FPGAs},
+year = {2021},
+isbn = {9781450383004},
+publisher = {Association for Computing Machinery},
+address = {New York, NY, USA},
+url = {https://doi.org/10.1145/3439706.3447047},
+doi = {10.1145/3439706.3447047},
+abstract = {Physical design for Field Programmable Gate Array (FPGA) is challenging and time-consuming, primarily due to the use of a full-custom approach for aggressively optimize Performance, Power and Area (P.P.A.) of the FPGA design. The growing number of FPGA applications demands novel architectures and shorter development cycles. The use of an automated toolchain is essential to reduce end-to-end development time. This paper presents scalable and adaptive hierarchical floorplanning strategies to significantly reduce the physical design runtime and enable millions-of-LUT FPGA layout implementations using standard ASIC toolchains. This approach mainly exploits the regularity of the design and performs necessary feedthrough creations for global and clock nets to eliminate any requirement of global optimizations. To validate this approach, we implemented full-chip layouts for modern FPGA fabric with logic capacity ranging from 40 to 100k LUTs using a commercial 12nm technology. Our results show that the physical implementation of a 128k-LUT FPGA fabric can be achieved within 24-hours, which has not been demonstrated by any previous work. Compared to previous work, the runtime reduction of 8x is obtained for implementing 2.5k LUTs FPGA device.},
+booktitle = {Proceedings of the 2021 International Symposium on Physical Design},
+pages = {135–142},
+numpages = {8},
+keywords = {reconfigurable computing, hierarchical design, physical design, fpga design},
+location = {Virtual Event, USA},
+series = {ISPD '21}
+}

docs/source/dev_manual/back_compatible.rst

@@ -0,0 +1,30 @@
+.. dev_manual_backward_compatibility::
+
+Backward compatibility
+======================
+
+OpenFPGA v1.1
+-------------
+
+OpenFPGA v1.2 is a major upgrade over v1.1, which upgrades the internal VPR engine.
+The (VPR) architecture files used with v1.1 may not be compatible with v1.2.
+
+You can upgrade your architecture files with script
+
+.. code-block:: bash
+
+  python3 openfpga_flow/scripts/arch_file_updater.py \
+      --input_file ${v1.1_arch_file} \
+      --output_file ${v1.2_compatible_arch_file}
+
+Or, If you want to stay with v1.1, the final build was (tag: `OpenFPGA:v1.1.541 <https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541>`_))
+
+.. code-block:: bash
+
+  https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
+
+or you can download the docker image
+
+.. code-block:: bash
+
+  docker pull ghcr.io/lnis-uofu/openfpga-master:v1.1.541

docs/source/dev_manual/cicd_setup.rst

@@ -1,6 +1,7 @@
+.. dev_manual_cicd_setup::
 
 CI/CD setup
-------------
+-----------
 
 OpenFPGA implements CI/CD system using Github actions.
 The following figure shows the Actions implements flow.
@@ -70,13 +71,15 @@ in which case the docker image compiled for the latest master branch is used for
 
     The OpenFPGA soure is compiled with the following set of compilers.
 
-      #. gcc-5
-      #. gcc-6
       #. gcc-7
       #. gcc-8
       #. gcc-9
-      #. clang-6.0
+      #. gcc-10
+      #. gcc-11
+      #. clang-6
+      #. clang-7
       #. clang-8
+      #. clang-10
 
     The docker images for these build enviroment are available on `github packages <https://github.com/orgs/lnis-uofu/packages>`_.
 

docs/source/dev_manual/index.rst

@@ -2,8 +2,15 @@
 .. toctree::
    :maxdepth: 1
 
-   ci_cd_setup/index
-
    version_number
 
+   back_compatible
+
+   contributor_guidelines
+
+   cicd_setup
+
    regression_tests
+
+   tcl_api
+

docs/source/dev_manual/tcl_api.rst

@@ -0,0 +1,33 @@
+.. _dev_manual_tcl_api:
+
+Tcl API
+-------
+
+OpenFPGA can be loaded to a Tcl shell in the format of shared library.
+OpenFPGA's Tcl APIs are generated by SWIG during compilation. 
+By integrating OpenFPGA to Tcl, developers can utilize OpenFPGA commands in a common shell with other EDA tools, considering most of modern EDA tools adopt Tcl as their user interface.
+Currently, Tcl 8.6 is supported. Other versions may also work.
+
+Here are the steps to follow:
+
+- Compile OpenFPGA with SWIG enabled. See details in :ref:`tutorial_compile`.
+- The shared library of OpenFPGA is available under the ``build/openfpga/openfpgashell.so``
+- Launch a tcl shell and load the shared library. For example
+
+.. code-block::
+
+  load openfpga_shell.so
+
+- Create a new OpenFPGA shell object. For example
+
+.. code-block::
+
+  std::OpenfpgaShell my_shell
+
+- OpenFPGA command can be called by through a sub command ``run_command``. For example, the command ``read_openfpga_arch`` (see :ref:`openfpga_setup_commands` for details) is now run in the following way: 
+
+.. code-block::
+
+  my_shell run_command "read_openfpga_arch --file ~/OpenFPGA/openfpga_flow/openfpga_arch/k4_N4_40nm_bank_openfpga.xml" 
+
+

docs/source/dev_manual/version_number.rst

@@ -33,11 +33,13 @@ To update the version number, please follow the rules:
 Version updates are made in the following scenario
 
 - When a minor milestone is achieved, the minor revision number can be increased by 1. The following condition is considered as a minor milestone:
+
   - a new feature has been developed.
   - a critical patch has been applied.
   - a sufficient number of small patches has been applied in the past quarter. In other words, the minor revision will be updated by the end of each quarter as long as there are patches.
 
 - When several minor milestones are achieved, the major revision number can be increased by 1. The following condition is considered as a major milestone:
+
   - significant improvements on Quality-of-Results (QoR).
   - significant changes on user interface.
   - a techical feature is developed and validated by the community, which can impact the complete design flow.

docs/source/faq.rst

@@ -1,47 +0,0 @@
-.. _faq:
-
-Frequently Asked Questions
-==========================
-
-Where is the best place to get help with OpenFPGA?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Currently, we have an active github issues page found `here <https://github.com/lnis-uofu/OpenFPGA/issues>`_. Users can see if their 
-questions have already been answered by searching the open or closed issues, and users are recommended to post questions there first. 
-Asking questions on the github issues page allows us to answer the question for everyone who may be experiencing similar problems as 
-well.
-
-What should I do if check-in tests failed when first installing OpenFPGA?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, check to make sure all dependencies for OpenFPGA and Python have been installed and are up-to-date on the desired device. To see the full
-list of depenencies, please visit 
-`our github dependencies page <https://github.com/lnis-uofu/OpenFPGA/blob/master/.github/workflows/install_dependencies_build.sh>`_. 
-This issue has been discussed `in issue 280 <https://github.com/lnis-uofu/OpenFPGA/issues/280>`_.
-
-
-How to sweep design parameters in a task run of OpenFPGA design flow?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Testing multiple script parameters for a variable is possible by modifying the task.conf file. Doing so will create a job for 
-each combination of the variables. A solution is discussed `in issue 228 <https://github.com/lnis-uofu/OpenFPGA/issues/228>`_.
-
-
-How do I setup OpenFPGA to be used by multiple users on a single device?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-OpenFPGA can support multiple users on a shared device using the environment variable ``OPENFPGA_ROOT``. The OpenFPGA script for 
-running tasks needs ``OPENFPGA_ROOT`` to be the path to the OpenFPGA root directory. Users can then run the script on a task in the
-current working directory. A solution is discussed `in issue 209 <https://github.com/lnis-uofu/OpenFPGA/issues/209>`_.
-
-
-How do I contribute to OpenFPGA?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Users of OpenFPGA that are interested in contributing must complete the following: 
-
-    - Create a branch. For external collaborators, please fork the repository first and create a branch in the fork.
-    - Creatre a pull request and fill out our pull request template. It is easy for us to acknowledge and review your pull request.	
-    - Wait or keep debugging until all the CI tests pass.	
-    - Request for a review. You may expect several rounds of review and discussion before the pull request is approved.
-

docs/source/index.rst

@@ -34,9 +34,7 @@ Welcome to OpenFPGA's documentation!
    :maxdepth: 2
    :caption: Appendix
 
-   contact
+   appendix/index
-   reference
-   faq
 
 For more information on the VTR see vtr_doc_ or vtr_github_
 

docs/source/manual/arch_lang/config_protocol.rst

@@ -69,14 +69,14 @@ It will use the circuit model defined in :numref:`fig_ccff_config_chain`.
 .. _fig_ccff_fpga:
 
 .. figure:: figures/ccff_fpga.png
-   :scale: 60%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of a configuration chain to program core logic of a FPGA 
 
 
 .. figure:: figures/multi_region_config_chains.png
-   :scale: 100%
+   :width: 100%
    :alt: map to buried treasure
  
    Examples of single- and multiple- region configuration chains
@@ -101,7 +101,7 @@ When the decoder of sub block, e.g., the LUT, is enabled, each memory cells can
 .. _fig_frame_config_protocol_example:
 
 .. figure:: figures/frame_config_protocol_example.png
-   :scale: 25%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of a frame-based memory organization inside a Logic Element
@@ -111,7 +111,7 @@ When the decoder of sub block, e.g., the LUT, is enabled, each memory cells can
 .. _fig_frame_config_protocol:
 
 .. figure:: figures/frame_config_protocol.png
-   :scale: 60%
+   :width: 100%
    :alt: map to buried treasure
  
    Frame-based memory organization in a hierarchical view
@@ -141,7 +141,7 @@ Users can customized the number of memory banks to be used across the fabrics. B
 .. _fig_memory_bank:
 
 .. figure:: figures/memory_bank.png
-   :scale: 30%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of (a) a memory organization using memory decoders; (b) single memory bank across the fabric; and (c) multiple memory banks across the fabric.
@@ -181,7 +181,7 @@ The BL and WL protocols can be customized through the XML syntax ``bl`` and ``wl
 .. _fig_memory_bank_decoder_based:
 
 .. figure:: figures/memory_bank_decoder.svg
-   :scale: 30%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of (a) a memory organization using address decoders; (b) single memory bank across the fabric; and (c) multiple memory banks across the fabric.
@@ -190,7 +190,7 @@ The BL and WL protocols can be customized through the XML syntax ``bl`` and ``wl
 .. _fig_memory_bank_flatten:
 
 .. figure:: figures/memory_bank_flatten.svg
-   :scale: 30%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of (a) a memory organization with direct access to BL/WL signals; (b) single memory bank across the fabric; and (c) multiple memory banks across the fabric.
@@ -198,7 +198,7 @@ The BL and WL protocols can be customized through the XML syntax ``bl`` and ``wl
 .. _fig_memory_bank_shift_register:
 
 .. figure:: figures/memory_bank_shift_register.svg
-   :scale: 30%
+   :width: 100%
    :alt: map to buried treasure
  
    Example of (a) a memory organization using shift register chains to control BL/WLs; (b) single memory bank across the fabric; and (c) multiple memory banks across the fabric.
@@ -230,7 +230,7 @@ In the standalone configuration protocol, every memory cell of the core logic of
 .. _fig_vanilla_config_protocol:
 
 .. figure:: figures/vanilla_config_protocol.png
-   :scale: 30%
+   :width: 100%
    :alt: map to buried treasure
  
    Vanilla (standalone) memory organization in a hierarchical view

docs/source/overview/motivation.rst

@@ -12,7 +12,7 @@ OpenFPGA aims to be an open-source framework that enables rapid prototyping of c
 .. _fig_openfpga_motivation:
 
 .. figure:: ./figures/openfpga_motivation.png
-   :scale: 50%
+   :width: 100%
    :alt: OpenFPGA: a fast prototyping framework for customizable FPGAs
 
    Comparison on engineering time and effort to prototype an FPGA using OpenFPGA and conventional approaches [All the layout figures are publishable under the proper licenses]
@@ -28,7 +28,7 @@ The rest of this section will focus on detailed motivation for each of them, as
 .. _fig_openfpga_framework:
 
 .. figure:: ./figures/openfpga_framework.svg
-   :scale: 50%
+   :width: 100%
    :alt: OpenFPGA framework
 
    OpenFPGA: a unified framework for chip designer and FPGA programmer
@@ -49,12 +49,12 @@ programmable fabric and the configuration peripheral.
 .. _fig_openfpga_arch_lang_coverage:
 
 .. figure:: ./figures/openfpga_arch_lang_coverage.png
-   :scale: 15%
+   :width: 100%
    :alt: OpenFPGA architecture description language enabling fully customizable FPGA architecture and circuit-level implementation
 
    OpenFPGA architecture description language enabling fully customizable FPGA architecture and circuit-level implementation
 
-The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
+The technical details can be found in our papers :cite:`XTang_TVLSI_2019` :cite:`XTang_FPL_2019`.
 
 FPGA-Verilog
 ~~~~~~~~~~~~
@@ -68,12 +68,12 @@ FPGA-Verilog is designed to output flexible and standard Verilog netlists, enabl
 .. _fig_fpga_verilog_motivation:
 
 .. figure:: ./figures/fpga_verilog_motivation.svg
-   :scale: 25%
+   :width: 100%
    :alt: Flexible netlist format support by FPGA-Verilog to enable various backend choices
 
    FPGA-Verilog enabling flexible backend flows
 
-The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
+The technical details can be found in our papers :cite:`XTang_ieeemicro_2020` :cite:`XTang_woset_2020` :cite:`GGore_ispd_2021`
 
 FPGA-SDC
 ~~~~~~~~
@@ -88,13 +88,13 @@ Our flow automatically generates two sets of SDC files.
 .. _fig_fpga_sdc_motivation:
 
 .. figure:: ./figures/fpga_sdc_motivation.png
-   :scale: 25%
+   :width: 100%
    :alt: FPGA-SDC enabling iterative timing constrained backend flow
 
    FPGA-SDC enabling iterative timing constrained backend flow
 
 
-The technical details can be found in our FPL'19 paper :cite:`XTang_FPL_2019`.
+The technical details can be found in our papers :cite:`XTang_FPL_2019` :cite:`XTang_ieeemicro_2020` :cite:`XTang_woset_2020`.
 
 
 FPGA-Bitstream
@@ -102,7 +102,7 @@ FPGA-Bitstream
 
 EDA support is essential for end-users to implement designs on a customized FPGA. OpenFPGA provides a general-purpose bitstream generator FPGA-Bitstream for any architecture that can be described by VPR. As the native CAD tool for any customized FPGA that is produced by FPGA-Verilog, FPGA-Bitstream is ready to use once users finalize the XML-based architecture description file. This eliminates the huge engineering efforts spent on developing bitstream generators for customized FPGAs. Using FPGA-Bitstream, users can launch (1) Verilog-to-Bitstream flow, the typical implementation flow for end-users; (2) Verilog-to-Verification flow. OpenFPGA can output Verilog testbenches with self-testing features to validate users' implemetations on their customized FPGA fabrics.
 
-The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
+The technical details can be found in our papers :cite:`XTang_TVLSI_2019` :cite:`XTang_FPL_2019`.
 
 FPGA-SPICE
 ~~~~~~~~~~
@@ -114,4 +114,4 @@ FPGA-SPICE aims at generating SPICE netlists and testbenches for the FPGA archit
 
 SPICE modeling for FPGA architectures requires detailed transistor-level modeling for all the circuit elements within the considered FPGA architecture. However, current VPR architectural description language :cite:`JLuu_FPGA_2011` does not offer enough transistor-level parameters to model the most common circuit modules, such as multiplexers and LUTs. Therefore, we are developing an extension on the VPR architectural description language to model the transistor-level circuit designs.
 
-The technical details can be found in our ICCD’15 paper :cite:`XTang_ICCD_2015` and TVLSI'19 paper :cite:`XTang_TVLSI_2019`.
+The technical details can be found in our papers :cite:`XTang_ICCD_2015` :cite:`XTang_TVLSI_2019`.

docs/source/tutorials/getting_started/compile.rst

@@ -9,8 +9,21 @@ How to Compile
 
   .. youtube:: F9sMRmDewM0
 
-General Guidelines
+Supported Operating Systems
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenFPGA is continously tested with Ubuntu 20.04. 
+It might work with earlier versions and other distributions.
+
+In addition to continous integration, our community users have tested OpenFPGA on their local machines using the following operating systems:
+
+- CentOS 7.8
+- CentOS 8
+- Ubuntu 18.04
+- Ubuntu 21.04
+
+Build Steps
+~~~~~~~~~~~
 OpenFPGA uses CMake to generate the Makefile scripts.
 In general, please follow the steps to compile
 
@@ -20,13 +33,13 @@ In general, please follow the steps to compile
   cd OpenFPGA
   make all
 
-.. note:: OpenFPGA requires gcc/g++ version >5
+.. note:: OpenFPGA requires gcc/g++ version > 7 and clang version > 6.
 
 .. note:: cmake3.12+ is recommended to compile OpenFPGA with GUI
 
 .. note:: Recommend using ``make -j<int>`` to accelerate the compilation, where ``<int>`` denotes the number of cores to be used in compilation.
 
-.. note:: VPR's GUI requires gtk-3, and can be enabled with ``cmake .. -DVPR_USE_EZGL=on``
+.. note:: VPR's GUI requires gtk-3, and can be enabled with ``make .. CMAKE_FLAGS="-DVPR_USE_EZGL=on"``
 
 **Quick Compilation Verification**
 
@@ -62,6 +75,8 @@ The following options are available for a custom build
   - ``DOPENFPGA_WITH_TEST=[ON|OFF]``: Enable/Disable the test build
   - ``DOPENFPGA_WITH_YOSYS=[ON|OFF]``: Enable/Disable the build of yosys. Note that when disabled, the build of yosys-plugin is also disabled
   - ``DOPENFPGA_WITH_YOSYS_PLUGIN=[ON|OFF]``: Enable/Disable the build of yosys-plugin.
+  - ``DOPENFPGA_WITH_VERSION=[ON|OFF]``: Enable/Disable the build of version number. When disabled, version number will be displayed as an empty string.
+  - ``DOPENFPGA_WITH_SWIG=[ON|OFF]``: Enable/Disable the build of SWIG, which is required for integrating to high-level interface.
 
 .. warning:: By default, only required modules in *Verilog-to-Routing* (VTR) is enabled. On other words, ``abc``, ``odin``, ``yosys`` and other add-ons inside VTR are not built. If you want to enable them, please look into the dedicated options of CMake scripts.  
 
@@ -76,7 +91,7 @@ In particular, OpenFPGA requires specific versions for the following dependencie
   version >3.12 for graphical interface
 
 :iverilog:
-  version 10.1+ is required to run Verilog-to-Verification flow
+  version 10.3+ is required to run Verilog-to-Verification flow
   
 :python dependencies:
   python packages are also required:
@@ -85,12 +100,10 @@ In particular, OpenFPGA requires specific versions for the following dependencie
 
   python3 -m pip install -r requirements.txt
 
-
 .. _install_dependencies_build: https://github.com/lnis-uofu/OpenFPGA/blob/master/.github/workflows/install_dependencies_build.sh
 
-
+Running with pre-built docker image
-Running with the docker image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Users can skip the traditional installation process by using the Dockerized version
 of the OpenFPGA tool. The OpenFPGA project maintains the docker image/Github package of