[doc] streamline frontpage README. Move details to online documentation. Easier for newbee to find guidelines
This commit is contained in:
tangxifan
parent
1f0f13ce0d
commit
ff31f91d0b
79
README.md
79
README.md
|
|
@ -1,5 +1,7 @@
|
|||
# Getting Started with OpenFPGA <img src="./docs/source/overview/figures/OpenFPGA_logo.png" width="200" align="right">
|
||||
[](https://github.com/LNIS-Projects/OpenFPGA/actions?query=workflow%3Alinux_build)
|
||||
[](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/build.yml)
|
||||
[](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/cell_lib_test.yml)
|
||||
[](https://github.com/psf/black)
|
||||
[](https://openfpga.readthedocs.io/en/master/?badge=master)
|
||||
[](https://mybinder.org/v2/gh/lnis-uofu/OpenFPGA/master?urlpath=vscode)
|
||||
|
||||
|
|
@ -18,77 +20,10 @@ We also recommend potential users check out the summary of [**technical capabili
|
|||
|
||||
**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 +31,7 @@ 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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -7,3 +7,5 @@
|
|||
version_number
|
||||
|
||||
regression_tests
|
||||
|
||||
back_compatible
|
||||
|
|
|
|||
|
|
@ -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 the docker image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Running with pre-built 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue