riscv
/
OpenFPGA
mirror of https://github.com/lnis-uofu/OpenFPGA.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Documentation updates

This commit is contained in:
Ganesh Gore 2023-02-03 16:22:38 -07:00
parent f82da04932
commit 9d71b8ebd0
6 changed files with 81 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/conf.py
View File

@ -185,7 +185,7 @@ texinfo_documents = [
]
bibtex_bibfiles = ["z_reference.bib"]
bibtex_bibfiles = ["./appendix/z_reference.bib"]
# -- Options for Epub output -------------------------------------------------

2
docs/source/dev_manual/index.rst
View File

@ -6,8 +6,6 @@
back_compatible
contributor_guidelines
cicd_setup
regression_tests

42
docs/source/tutorials/arch_modeling/quick_start.rst
View File

@ -6,13 +6,13 @@ A Quick Start
In this tutorial, we will consider a simple but representative FPGA architecture to show you how to
- Adapt a VPR architecture XML file to OpenFPGA acceptable format
- Create an OpenFPGA architecture XML file to customize the primitive circuits
- Create a simulation setting XML file to specify the simulation settings
- Create a simulation setting XML file to specify the simulation settings
Through this quick example, we will introduce the key steps to build your own FPGA based on a VPR architecture template.
.. note:: These tips are generic and fundamental to build any architecture file for OpenFPGA.
Adapt VPR Architecture
Adapt VPR Architecture
~~~~~~~~~~~~~~~~~~~~~~
We start with the VPR architecture `template
<https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/arch/timing/k4_N4_90nm.xml>`_.
@ -23,7 +23,7 @@ This file models a homogeneous FPGA, as illustrated in :numref:`fig_k4n4_arch`.
.. figure:: ./figures/k4n4_arch.png
:scale: 100%
K4N4 FPGA architecture
K4N4 FPGA architecture
A summary of the architectural features is as follows:
- An array of tiles surrounded by a ring of I/O blocks
@ -45,8 +45,8 @@ The ``<pb_type name="io">`` under the ``<complexblocklist>`` should be adapted t
<input name="outpad" num_pins="1"/>
<output name="inpad" num_pins="1"/>
<!-- A mode denotes the physical implementation of an I/O
This mode will not be used by packer but is mainly used for fabric verilog generation
<!-- A mode denotes the physical implementation of an I/O
This mode will not be used by packer but is mainly used for fabric verilog generation
-->
<mode name="physical" packable="false">
<pb_type name="iopad" blif_model=".subckt io" num_pb="1">
@ -92,10 +92,10 @@ Note that, there are several major changes in the above codes, when compared to
- We remove the ``clock`` port of I/O is actually a dangling port.
- We specify that the phyical ``mode`` to be disabled for VPR packer by using ``packable=false``. This can help reduce packer's runtime.
Since, we have added a new BLIF model ``subckt io`` to the architecture modeling, we should update the ``<models>`` XML node by adding a new I/O model.
Since, we have added a new BLIF model ``subckt io`` to the architecture modeling, we should update the ``<models>`` XML node by adding a new I/O model.
.. code-block:: xml
<models>
<!-- A virtual model for I/O to be used in the physical mode of io block -->
<model name="io">
@ -154,7 +154,7 @@ These parts are organized as follows in the XML file.
...
</circuit_library>
<!-- Configuration protocol definition -->
<!-- Configuration protocol definition -->
<configuration_protocol>
...
</configuration_protocol>
@ -409,7 +409,7 @@ For the routing architecture, we specify the ``circuit_model`` to be used as rou
<segment name="L4" circuit_model_name="chan_segment"/>
</routing_segment>
.. note:: For a correct binding, the name of connection block, switch block and routing segment should match the name definition in your VPR architecture description!
.. note:: For a correct binding, the name of connection block, switch block and routing segment should match the name definition in your VPR architecture description!
For each ``<pb_type>`` defined in the ``<complexblocklist>`` of VPR architecture, we need to specify
@ -423,25 +423,25 @@ For each ``<pb_type>`` defined in the ``<complexblocklist>`` of VPR architecture
.. code-block:: xml
<pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/>
<pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/>
.. note:: Mode-selection bits should be provided as the default configuration for a configurable resource. In this example, an I/O cell has a configuration bit, as defined in the ``<circuit_model name="iopad">``. We specify that by default, the configuration memory will be set to logic ``1``.
- The physical ``<pb_type>`` for any ``<pb_type>`` in the operating modes (mode other than the physical mode). This is required to translate mapping results from operating modes to their physical modes, in order to generate bitstreams. It is required to provide full hierarchy of the ``pb_type``. For example,
- The physical ``<pb_type>`` for any ``<pb_type>`` in the operating modes (mode other than the physical mode). This is required to translate mapping results from operating modes to their physical modes, in order to generate bitstreams. It is required to provide full hierarchy of the ``pb_type``. For example,
.. code-block:: xml
<pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/>
<pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/>
.. note:: Mode-selection bits should be provided so as to configure the circuits to be functional as required by the operating mode. In this example, an I/O cell will be configured with a logic ``1`` when operating as an input pad.
- The circuit model used to implement interconnecting modules. The interconnect name should match the definition in the VPR architecture file. For example,
- The circuit model used to implement interconnecting modules. The interconnect name should match the definition in the VPR architecture file. For example,
.. code-block:: xml
<interconnect name="crossbar" circuit_model_name="mux_2level"/>
.. note:: If not specified, each interconnect will be binded to its default ``circuit_model``. For example, the crossbar will be binded to the default multiplexer ``<circuit_model name="mux_1level_tapbuf">``, if not specified here.
.. note:: If not specified, each interconnect will be binded to its default ``circuit_model``. For example, the crossbar will be binded to the default multiplexer ``<circuit_model name="mux_1level_tapbuf">``, if not specified here.
.. note:: OpenFPGA automatically infers the type of circuit model required by each interconnect.
@ -452,9 +452,9 @@ The complete annotation is shown as follows:
<pb_type_annotations>
<!-- physical pb_type binding in complex block IO -->
<pb_type name="io" physical_mode_name="physical"/>
<pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/>
<pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/>
<pb_type name="io[outpad].outpad" physical_pb_type_name="io[physical].iopad" mode_bits="0"/>
<pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/>
<pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/>
<pb_type name="io[outpad].outpad" physical_pb_type_name="io[physical].iopad" mode_bits="0"/>
<!-- End physical pb_type binding in complex block IO -->
<!-- physical pb_type binding in complex block CLB -->
@ -474,7 +474,7 @@ Simulation Settings
~~~~~~~~~~~~~~~~~~~
OpenFPGA needs an XML file where detailed simulation settings are defined.
The simulation settings contain critical parameters to build testbenches for verify the FPGA fabric.
The simulation settings contain critical parameters to build testbenches for verify the FPGA fabric.
You may create an XML file `k4_n4_openfpga_simulation.xml` and then add contents shown as follows.
@ -520,7 +520,7 @@ The ``<clock_setting>`` is crucial to create clock signals in testbenches.
.. note:: FPGA has two types of clocks, one is the operating clock which controls applications that mapped to FPGA fabric, while the other is the programming clock which controls the configuration protocol.
In this example, we specify
In this example, we specify
- the operating clock will follow the maximum frequency achieved by VPR routing results
- the number of operating clock cycles to be used will follow the average signal activities of the RTL design that is mapped to the FPGA fabric.
@ -539,7 +539,7 @@ The ``<monte_carlo num_simulation_points="2"/>`` are the options for SPICE simul
Here we specify that for each testbench, we will consider two Monte-Carlo simulations to evaluate the impact of process variations.
The ``<measurement_setting>`` specify how the output signals will be measured for delay and power evaluation.
Here we specify that
Here we specify that
- for slew calculation (used in power estimation), we consider from the 5% of the ``VDD`` to the 95% of the ``VDD`` for both rising and falling edges.
- for delay calculation, we consider from the 50% of the ``VDD`` of input signal to the 50% of the ``VDD`` of output signals for both rising and falling edges.

62
docs/source/tutorials/getting_started/compile.rst
View File

@ -1,7 +1,10 @@
.. _tutorial_compile:
How to Compile
--------------
Installation
------------
Compiling Source
~~~~~~~~~~~~~~~~
.. note:: We recommend you to watch a tutorial `video <https://youtu.be/F9sMRmDewM0>`_ about how-to-compile before getting started
@ -10,9 +13,9 @@ How to Compile
.. youtube:: F9sMRmDewM0
Supported Operating Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^
OpenFPGA is continously tested with Ubuntu 20.04 and partially on Ubuntu 22.04
OpenFPGA is continously tested with Ubuntu 20.04 and partially on Ubuntu 22.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:
@ -24,7 +27,8 @@ In addition to continous integration, our community users have tested OpenFPGA o
- Ubuntu 22.04
Build Steps
~~~~~~~~~~~
^^^^^^^^^^^
OpenFPGA uses CMake to generate the Makefile scripts.
In general, please follow the steps to compile
@ -55,7 +59,7 @@ To quickly verify the tool is well compiled, users can run the following command
.. _tutorial_compile_build_options:
Build Options
~~~~~~~~~~~~~
^^^^^^^^^^^^^
General build targets are available in the top-level makefile. Call help desk to see details
@ -80,16 +84,16 @@ The following options are available for a custom build
- ``DOPENFPGA_WITH_SWIG=[ON|OFF]``: Enable/Disable the build of SWIG, which is required for integrating to high-level interface.
- ``OPENFPGA_ENABLE_STRICT_COMPILE=[ON|OFF]``: Specifies whether compiler warnings should be treated as errors (e.g. -Werror)
.. 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.
.. 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.
.. option:: CMAKE_GOALS=<string>
Specify the build target for CMake system. For example, ``cmake_goals=openfpga`` indicates that only openfpga binary will be compiled. For a detailed list of targets, use ``make list_cmake_targets`` to show. By default, all the build targets will be included.
Specify the build target for CMake system. For example, ``cmake_goals=openfpga`` indicates that only openfpga binary will be compiled. For a detailed list of targets, use ``make list_cmake_targets`` to show. By default, all the build targets will be included.
.. _tutorial_compile_dependencies:
Dependencies
~~~~~~~~~~~~
^^^^^^^^^^^^
Dependencies can be installed upon the use of OpenFPGA on different systems
In general, OpenFPGA requires specific versions for the following dependencies:
@ -99,7 +103,7 @@ In general, OpenFPGA requires specific versions for the following dependencies:
:iverilog:
version 10.3+ is required to run Verilog-to-Verification flow
Ubuntu 20.04
^^^^^^^^^^^^
@ -113,9 +117,9 @@ Ubuntu 20.04
.. include:: regtest_dependencies.sh
:code: shell
.. note:: Python packages are also required
.. code-block::
python3 -m pip install -r requirements.txt
@ -137,9 +141,9 @@ Ubuntu 22.04
.. include:: regtest_dependencies.sh
:code: shell
.. note:: Python packages are also required
.. code-block::
python3 -m pip install -r requirements.txt
@ -150,18 +154,20 @@ Ubuntu 22.04
:code: shell
Running with pre-built docker image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running 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
the latest stable version of OpenFPGA in the following repository
of the OpenFPGA tool. T
he OpenFPGA project maintains the docker image/Github package of every commit pushed to the `master` branch.
You can find full list of avaialble packages
`openfpga-master <https://github.com/orgs/lnis-uofu/packages/container/package/openfpga-master>`_.
This image contains precompiled OpenFPGA binaries with all prerequisites installed.
To use most recent version please use :latest tag (as shown in the following source) or you can pin to specific version by using tag `ghcr.io/lnis-uofu/openfpga-master:v1.1.541` or to specific master commit using short first 8 characters of commit SHA `ghcr.io/lnis-uofu/openfpga-master:62ec82c1`.
This image contains precompiled OpenFPGA binaries with all prerequisites already installed.
.. code-block:: bash
# To get the docker image from the repository,
# To get the docker image from the repository,
docker pull ghcr.io/lnis-uofu/openfpga-master:latest
# To invoke openfpga_shell
@ -174,8 +180,20 @@ This image contains precompiled OpenFPGA binaries with all prerequisites install
mkdir work
docker run -it -v work:/opt/openfpga/ ghcr.io/lnis-uofu/openfpga-master:latest bash
# Inside container
# Inside container
source openfpga.sh
cd work
cd work
create_task _my_task yosys_vpr
Running on Binder
~~~~~~~~~~~~~~~~~
If user want to quickly evaluate the OpenFPGA functionality without any local installation, you can use the Binder service to quickly provision a low-end compute unit with docker and visual studio code.
Please click the following link to launch the Binder instance.
.. image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/lnis-uofu/OpenFPGA/master?urlpath=vscode
.. note:: The storage on Binder session is not permanent and the session is completely removed if inactive. Make sure yopu download or commit files if there are any important changes.

4
docs/source/tutorials/getting_started/index.rst
View File

@ -3,12 +3,14 @@
Getting Started
---------------
.. toctree::
:maxdepth: 2
compile
demo
shell_shortcuts
tools

23
docs/source/tutorials/getting_started/shell_shortcuts.rst
View File

@ -1,17 +1,18 @@
OpenFPGA shortcuts
------------------
OpenFPGA Shell Commands
-----------------------
OpenFPGA provides `bash`/`zsh` shell-based shortcuts to perform all essential functions and navigate through the directories. Go to the OpenFPGA directory and source ``openfpga.sh``
OpenFPGA provides `bash`/`zsh` shell-based shortcuts to perform all essential functions and navigate through the directories. Go to the OpenFPGA directory and source ``openfpga.sh``,
.. code-block:: bash
export OPENFPGA_PATH=<path-to-openfpga-repository-root>
cd ${OPENFPGA_PATH} && source openfpga.sh
.. note::
The OpenFPGA shortcut works with only a bash-like shell. e.g., `bash`/`zsh`/`fish,` etc.
Shortcut Commands
^^^^^^^^^^^^^^^^^
Commands
^^^^^^^^
Once the ``openfpga.sh`` script is sourced, you can run any following commands directly in the terminal.
@ -38,13 +39,21 @@ Once the ``openfpga.sh`` script is sourced, you can run any following commands d
for example ``create-task _my_task_copy basic_tests/generate_fabric`` create a copy of the ``basic_tests/generate_fabric`` task in
the current directory with ``_my_task_copy`` name.
.. option:: run-modelsim
.. option:: goto_task <task_name> <run_num[default 0]>
This command navigate shell to specific run-directory of the given task.
For example `goto_task lab1 2` will change directory to `run002` runt directory of `lab2`
.. option:: clear-task-run <task_name>
Clears all run diretories of the given task
.. option:: run-modelsim <task_name>
This command runs the verification using ModelSim.
The test benches are generated during the OpenFPGA run.
**Note**: users need to have ``VSIM`` installed and configured
.. option:: run-regression-local
This script runs the regression test locally using the current version of OpenFPGA.