docs: move 'understanding' from f4pga-examples as 'f4pga/Deprecated' (#603)

docs/f4pga/Deprecated.rst

@@ -0,0 +1,194 @@
+.. _Understanding:
+
+Understanding the (deprecated) flow
+###################################
+
+.. IMPORTANT::
+  This section describes the usage of the now deprecated ``symbiflow_*`` entrypoints/wrappers.
+  It is provided for backwards compatibility, so that users of the *old* flow can keep using it.
+  However, it is recommended for new users to use the approach explained in :ref:`pyF4PGA`.
+
+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 :ref:`Design Flows section <Flows>`.
+
+.. 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 :ref:`Flows:F4PGA:Yosys`.
+
+.. 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 `VPR ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>`__.
+
+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

docs/f4pga/index.rst

@@ -1,3 +1,5 @@
+.. _pyF4PGA:
+
 Overview
 ########
 

docs/flows/f4pga.rst

@@ -8,6 +8,8 @@ In the F4PGA toolchain synthesis is made with the use of Yosys, that is able to
 convert HDL to netlist description.
 The result of these steps is written to a file in ``.eblif`` format.
 
+.. _Flows:F4PGA:Yosys:
+
 Yosys
 =====
 

docs/flows/index.rst

@@ -1,3 +1,5 @@
+.. _Flows:
+
 Introduction
 ============
 

docs/index.rst

@@ -27,6 +27,7 @@ The project aims to design tools that are highly extendable and multiplatform.
   f4pga/Usage
   f4pga/modules/index
   f4pga/DevNotes
+  f4pga/Deprecated
 
 
 .. toctree::