docs: 'understanding' moved to f4pga

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>

docs/customizing-makefiles.rst

@@ -6,7 +6,7 @@ This tutorial walks you through how to do that.
 
 If you would like to use methods other than a Makefile to build and compile your designs (such as python or bash
 scripts) or if you would like to learn more about the various F4PGA commands used by the common Makefile to build and
-compile designs take a look at the :ref:`Understanding` page.
+compile designs take a look at the :doc:`F4PGA Documentation <f4pga:index>` page.
 
 Example
 -------

docs/development/running-ci-locally.rst

@@ -1,5 +1,5 @@
-Running "CI" locally
+Running CI locally
-####################
+##################
 
 The CI uses a bunch of scripts in the `.github/scripts/ <./.github/scripts>`_ directory to execute the needed tests.
 You can use the same scripts locally to test without having to wait for the online CIs to pass if you want to quickly

docs/index.rst

@@ -1,12 +1,12 @@
 Welcome to F4PGA examples!
-==========================
+##########################
 
 This guide explains how to get started with F4PGA and build example designs from the :gh:`F4PGA Examples <chipsalliance/f4pga-examples>`
 GitHub repository.
 It currently focuses on the following FPGA families:
 
 - Artix-7 from Xilinx,
-- EOS S3 from QuickLogic.
+- EOS-S3 from QuickLogic.
 
 Follow this guide to:
 
@@ -15,27 +15,27 @@ Follow this guide to:
   example designs onto the devboard of your choice.
 - compile and run :doc:`your own designs<personal-designs>` using the F4PGA toolchain.
 - :doc:`customize the Makefile<customizing-makefiles>` for your own designs.
-- gain valuable information about :doc:`Understanding Toolchain Commands in F4PGA <understanding>`.
+
 
 About F4PGA
------------
+===========
 
-F4PGA is a fully open source toolchain for the development of FPGAs,
+F4PGA is a fully open source toolchain for the development of FPGAs, currently targeting chips from multiple vendors, e.g.:
-currently targeting chips from multiple vendors, e.g.:
 
-- Xilinx 7-Series
+- Xilinx's 7-Series.
-- Lattice iCE40
+- Lattice's ICE40 and ECP5.
-- Lattice ECP5 FPGAs
+- QuickLogic's EOS-S3.
-- QuickLogic EOS S3
+
+Gain valuable information about the flows and the tools in section :ref:`Design Flows <f4pga:Flows>` at
+:doc:`F4PGA Documentation <f4pga:index>`.
+
+
+Table of Contents
+=================
 
 .. toctree::
 
    getting
-   understanding
-
-.. toctree::
-   :caption: Example designs
-
    building-examples
    running-examples
 

docs/personal-designs.rst

@@ -1,6 +1,6 @@
 .. _Building-Custom-Designs:
 
-Building Custom Designs
+Building custom designs
 =======================
 
 This section describes how to compile and download your own designs to an FPGA using only

docs/project-f.rst

@@ -1,5 +1,5 @@
-Running Project F designs in F4PGA
+Running Project F designs
-==================================
+=========================
 
 .. warning::
    F4PGA does not currently support the MMCME2_BASE primitive--a key commponent in Project F's clock_gen_480p module

docs/understanding.rst

@@ -1,192 +0,0 @@
-.. _Understanding:
-
-Understanding the flow
-======================
-
-This section provides valuable information on how each of the commands used to compile and build
-designs in F4PGA work. It is especially helpful for debugging or for using methods
-other than a makefile to build your designs, such as a bash or python script.
-
-The following describes the commands for running each of the steps for a full design flow
-(synthesis, place and route, and generate bitstream) as well as giving a description of the most
-common flags for those commands. If you would like a more detailed break down of how the design
-flow for F4PGA works take a look at the
-`FPGA Design Flow page <https://f4pga.readthedocs.io/en/latest/toolchain-desc/design-flow.html>`_.
-
-.. note::
-
-    Files created by synthesis, implementation, and bitstream generation will be dumped into
-    the directory from which the command is run by default. To keep all of the files generated by
-    the toolchain separate from your design files, you might consider running the toolchain
-    commands in a separate directory from your design files.
-
-
-
-Synthesis
-----------
-
-To synthesize your designs run the ``symbiflow_synth`` command. The command has the following
-flags:
-
-.. table:: symbiflow_synth
-
-    +------+---------------------------------------------------------------+
-    | Flag |                            Argument                           |
-    +======+===============================================================+
-    | -t   | Defines the name for the top level module                     |
-    +------+---------------------------------------------------------------+
-    | -v   | A list of paths to verilog files for the design               |
-    +------+---------------------------------------------------------------+
-    | -d   | FPGA family (i.e. artix7 or zynq7)                            |
-    +------+---------------------------------------------------------------+
-    | -p   | The part number for the FPGA (i.e xc7a35tcsg324-1)            |
-    +------+---------------------------------------------------------------+
-    | -x   | Optional command: path to xdc files for design                |
-    +------+---------------------------------------------------------------+
-
-
-An example of how to run synthesis on a design containing two separate
-verilog HDL files is below. The design is built for a basys3 board which comes from the artix7
-family and uses the xc7a35tcpg236-1 chip.
-
-.. code-block:: bash
-
-    symbiflow_synth -t top -v example.v top_example.v -d artix7 -p xc7a35tcpg236-1 -x design_constraint.xdc
-
-Synthesis is carried out using the Yosys open source tool. ``symbiflow_synth`` generates
-an .eblif file, a few verilog netlists that describe the gate level design for your project, and a log
-file. For more information on Yosys and its relation to F4PGA go to the
-`F4PGA-Yosys page <https://f4pga.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_.
-
-.. note::
-    The build files generated by the toolchain (for example .eblif from synthesis, .net from
-    packing, .bit from generate bitstream) are named using the top module specified in
-    symbiflow_synth. For example if you specified ``switch_top`` as the top level module name
-    during synthesis using the ``-t`` flag, the build files generated by the toolchain would be
-    named switch_top.eblif, switch_top.net, etc.
-
-
-Place and Route
-----------------
-
-The three steps for implementing a design are internally handled by the open source VPR
-(Versatile Place and Route) tool. For more information go to
-`the F4PGA VPR page <https://f4pga.readthedocs.io/en/latest/vtr-verilog-to-routing/doc/src/vpr/index.html>`_.
-
-Pack
-+++++
-
-Packing is run by the ``symbiflow_pack`` command and generates several files containing
-a pin usage report, a timing report, a log file, and a netlist. The various flags for the
-pack command are as follows:
-
-.. table:: symbiflow_pack
-
-    +------+--------------------------------------------------------------------+
-    | Flag |                              Argument                              |
-    +======+====================================================================+
-    | -e   | Path to .eblif file generated by synthesis                         |
-    +------+--------------------------------------------------------------------+
-    | -d   | Fabric definition for the board (i.e. xc7a100t_test)               |
-    +------+--------------------------------------------------------------------+
-    | -s   | Optional: SDC file path                                            |
-    +------+--------------------------------------------------------------------+
-
-Note that the -d option for this step (defining the fabric definition) is different
-from the -d from synthesis (defining the FPGA family).
-
-The following example runs packing on the basys3 board:
-
-.. code-block:: bash
-
-    symbiflow_pack -e top.eblif -d xc7a35t_test
-
-Place
-++++++
-
-Placement generates several files describing the location of design elements
-as well as a log file. Placement is run using ``symbiflow_place`` which utilizes
-the following flags:
-
-.. table:: symbiflow_place
-
-    +------+----------------------------------------------------+
-    | Flag |                      Argument                      |
-    +======+====================================================+
-    | -e   | Path to .eblif file generated by synthesis         |
-    +------+----------------------------------------------------+
-    | -d   | Fabric definition (xc7a50t_test)                   |
-    +------+----------------------------------------------------+
-    | -p   | Optional: PCF file path                            |
-    +------+----------------------------------------------------+
-    | -n   | Path to the .net file generated by pack step       |
-    +------+----------------------------------------------------+
-    | -P   | The part number for the FPGA (i.e xc7a35tcsg324-1) |
-    +------+----------------------------------------------------+
-    | -s   | Optional: SDC file path                            |
-    +------+----------------------------------------------------+
-
-For the basys3:
-
-.. code-block:: bash
-
-    symbiflow_pack -e top.eblif -d xc7a35t_test -p design.pcf -n top.net -P xc7a35tcpg236-1 -s design.sdc
-
-
-Route
-++++++
-
-Routing produces several timing reports as well as a post routing netlist and log file.
-``symbiflow_route`` uses the -e, -d, and the optional -s flags. The arguments for these flags
-are the same as in the placement step (.eblif, fabric definition, and SDC file path respectively).
-The following is an example:
-
-.. code-block:: bash
-
-    symbiflow_route -e top.eblif -d xc7a35t_test -s design.sdc
-
-
-Generating Bitstream
-----------------------
-
-Generating the bitstream consists of two steps. First, run ``symbiflow_write_fasm`` to generate
-the .fasm file used to create the bitstream. ``symbiflow_write_fasm`` uses the -e and -d flags
-with the same arguments as the placing and routing steps (.eblif path, and fabric definition).
-Second, run ``symbiflow_write_bitstream`` which has the following flags:
-
-.. table:: symbiflow_write_bitstream
-
-    +------+-------------------------------------------------------+
-    | Flag |                        Argument                       |
-    +======+=======================================================+
-    | -d   | FPGA family (i.e. artix7 or zynq7)                    |
-    +------+-------------------------------------------------------+
-    | -f   | The path to the .fasm file generated in by write_fasm |
-    +------+-------------------------------------------------------+
-    | -p   | The FPGA part number (i.e xc7a35tcsg324-1)            |
-    +------+-------------------------------------------------------+
-    | -b   | Name of the file to write the bitstream to            |
-    +------+-------------------------------------------------------+
-
-Notice that the specification for the part number is a lowercase ``-p`` instead of a capital
-``-P`` as in the placement step. Also note that the ``-d`` in write_bitstream defines the FPGA
-family instead of the fabric as in the write_fasm step.
-
-.. warning::
-
-   If you change the name of the output for your bitstream to something other than top.bit then the
-   openFPGALoader command used in the examples would need to change too. For example if I used
-   ``-b my_module_top`` in symbiflow_write_bitstream then my openFPGALoader command would change to:
-
-   .. code-block:: bash
-
-      openFPGALoader -b $OFL_BOARD my_module_top.bit
-
-   Note that the only part of the command that changes is "<top module name>.bit;"
-
-The following example generates a bitstream file named example.bit for the basys3 board:
-
-.. code-block:: bash
-
-    symbiflow_write_fasm -e top.eblif -d xc7a50t_test
-    symbiflow_write_bitstream -d artix7 -f top.fasm -p xc7a35tcpg236-1 -b example.bit