Merge pull request #218 from lnis-uofu/dev

Add tutorial videos to Documentation

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. 
 

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

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.

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:

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

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 <https://github.com/lnis-uofu/OpenFPGA/blob/master/openfpga_flow/tasks/basic_tests/generate_fabric/config/task.conf>`_, 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.

docs/source/tutorials/design_flow/index.rst

@@ -7,6 +7,8 @@ Design Flows
 .. toctree::
    :maxdepth: 2
 
+   generate_fabric
+
    verilog2verification
 
    verilog2gds2

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.