diff --git a/README.md b/README.md index eaafaaa32..e71c1f637 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,15 @@ The award-winning OpenFPGA framework is the **first open-source FPGA IP generator** supporting highly-customizable homogeneous FPGA architectures. OpenFPGA provides a full set of 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 the first time you learn OpenFPGA, we strongly recommend you to 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/tools/). We also recommend potential users to checkout the summary of [**technical capabilities**](https://openfpga.readthedocs.io/en/master/overview/tech_highlights.html) before compiling. ## Compilation +**A tutorial video about how-to-compile can be found [here](https://youtu.be/F9sMRmDewM0)** + Before start, we strongly recommend you to read the required dependencies at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/compile). It also includes detailed information about docker image. diff --git a/docs/requirements.txt b/docs/requirements.txt index 2236fda06..eb876e494 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -8,6 +8,9 @@ #Handle references in bibtex format sphinxcontrib-bibtex<2.0.0 +# Package required to embed youtube video +sphinxcontrib-yt + #Work-around bug "AttributeError: 'Values' object has no attribute 'character_level_inline_markup'" with docutils 0.13.1 #See: # * https://github.com/sphinx-doc/sphinx/issues/3951 diff --git a/docs/source/conf.py b/docs/source/conf.py index 0b149ed69..510e62c4b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -30,6 +30,14 @@ try: except ImportError: have_sphinxcontrib_bibtex = False +# Import sphinxcontrib.yt +have_sphinxcontrib_youtube = True +try: + import sphinxcontrib.yt +except ImportError: + have_sphinxcontrib_youtube = False + + # -- Project information ----------------------------------------------------- project = u'OpenFPGA' @@ -57,6 +65,7 @@ extensions = [ 'sphinx.ext.graphviz', 'sphinxcontrib.bibtex', 'sphinx.ext.autosectionlabel', + 'sphinxcontrib.yt', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/overview/motivation.rst b/docs/source/overview/motivation.rst index d84675382..8575dd1f0 100644 --- a/docs/source/overview/motivation.rst +++ b/docs/source/overview/motivation.rst @@ -1,6 +1,10 @@ Why OpenFPGA? ------------- +.. note:: If this is the first time you learn OpenFPGA, we strongly recommend you to watch the introduction video. + +.. youtube:: ocODUGcYGqo + OpenFPGA aims to be an open-source framework that enables rapid prototyping of customizable FPGA architectures. As shown in :numref:`fig_openfpga_motivation`, a conventional approach will take a large group of experienced engineers more than one year to achieve production-ready layout and assoicated CAD tools. In fact, most of the engineering efforts are spent on manual layouts and developing ad-hoc CAD support. .. _fig_openfpga_motivation: diff --git a/docs/source/tutorials/compile.rst b/docs/source/tutorials/compile.rst index bbeddf228..1b6266c18 100644 --- a/docs/source/tutorials/compile.rst +++ b/docs/source/tutorials/compile.rst @@ -1,8 +1,12 @@ -.. _compile: +.. _tutorial_compile: How to Compile -------------- +.. note:: We recommend you to watch a tutorial video about how-to-compile before getting started + +.. youtube:: F9sMRmDewM0 + General Guidelines ~~~~~~~~~~~~~~~~~~ OpenFPGA uses CMake to generate the Makefile scripts diff --git a/docs/source/tutorials/design_flow/generate_fabric.rst b/docs/source/tutorials/design_flow/generate_fabric.rst new file mode 100644 index 000000000..7e4d57c7d --- /dev/null +++ b/docs/source/tutorials/design_flow/generate_fabric.rst @@ -0,0 +1,71 @@ +.. _tutorial_generate_fabric: + +Generate Fabric Netlists +------------------------ + +.. note:: You may watch the video representation of this tutorial + +.. youtube:: aJ0OkZ1uh68 + +This tutorial will show an example how to + - generate Verilog netlists for a FPGA fabric + +.. note:: Before running any design flows, please checkout the tutorial :ref:`tutorial_compile`, to ensure that you have an operating copy of OpenFPGA installed on your computer. + + +Prepare Task Configuration File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenFPGA provides push-button scripts for users to run design flows (see details in :ref:`run_fpga_task`). Users can customize their flow-run by crafting a task configuration file. + +Here, we consider an existing test case ``generate_fabric``. +In the `task configuration file `_, you can specify the XML-based architecture files in ``LINE 21`` and ``LINE 25`` that describe the architecture of the FPGA fabric. In this example, we are using a low-cost FPGA architecture similar to the lattice ICE40 series + +Also, in ``LINE 20``, you can specify the openfpga shell script to be executed. Here, we are using an example script which is golden reference to generate Verilog netlists + +.. note:: You can use text editor to customize the configuration file. Here, we use it as is. + + +Run OpenFPGA Task +~~~~~~~~~~~~~~~~~ + +After finalizing your configuration file, you can run the task by calling the python script with the given path to task configuration file. + +.. code-block:: shell + + python3 openfpga_flow/scripts/run_fpga_task.py basic_tests/generate_fabric + +When the flow run is executed, you can visit the runtime directory and check the Verilog netlists. + +Note that your task-run outcomes are stored in the directory called ``latest`` in the same level of your task configuration file. + +The Verilog netlists are generated in the following directory + +.. code-block:: shell + + ${OPENFPGA_PATH}/openfpga_flow/tasks/basic_tests/generate_fabric/latest/k6_frac_N10_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC + +.. note:: ``${OPENFPGA_PATH}`` is the root directory of OpenFPGA + +.. note:: See :ref:`fabric_netlists` for the netlist details. + +In the Verilog files, you can validate if the Verilog description is consistent as your definition in the architecture file. The Verilog files can be then used to drive different tools, such as layout generation *etc*. + +Run icarus iVerilog Compilation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Go to the directory + +.. code-block:: shell + + cd ${OPENFPGA_PATH}/openfpga_flow/tasks/basic_tests/generate_fabric/latest/k6_frac_N10_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH + +Compile with iVerilog command: + +.. code-block:: shell + + iverilog SRC/fabric_netlists.v + +.. note:: Please ensure that iVerilog is installed correctly on your computer + +If compilation is successful, you can see a file ``a.out`` in the directory. diff --git a/docs/source/tutorials/design_flow/index.rst b/docs/source/tutorials/design_flow/index.rst index 82a9ed3e4..5d7f1720e 100644 --- a/docs/source/tutorials/design_flow/index.rst +++ b/docs/source/tutorials/design_flow/index.rst @@ -7,6 +7,8 @@ Design Flows .. toctree:: :maxdepth: 2 + generate_fabric + verilog2verification verilog2gds2 diff --git a/docs/source/tutorials/design_flow/verilog2verification.rst b/docs/source/tutorials/design_flow/verilog2verification.rst index 1455b729a..bffd3960c 100644 --- a/docs/source/tutorials/design_flow/verilog2verification.rst +++ b/docs/source/tutorials/design_flow/verilog2verification.rst @@ -8,6 +8,8 @@ This tutorial will show an example how to - generate Verilog testbenches for a RTL design - run HDL simulation to verify the functional correctness of the implemented FPGA fabric +.. note:: Before running any design flows, please checkout the tutorial :ref:`tutorial_compile`, to ensure that you have an operating copy of OpenFPGA installed on your computer. + Netlist Generation ~~~~~~~~~~~~~~~~~~ We will use the openfpga_flow scripts (see details in :ref:`run_fpga_task`) to generate the Verilog netlists and testbenches.