Added explanation of symbiflow commands

Signed-off-by: Joshua Fife <jpfife17@gmail.com>

docs/customizing-makefiles.rst

@@ -285,7 +285,12 @@ snippets show the differences and the areas that will need to change:
          ${BOARD_BUILDDIR}/${TOP}.route: ${BOARD_BUILDDIR}/${TOP}.place
             cd ${BOARD_BUILDDIR} && symbiflow_route -e ${TOP}.eblif -d ${DEVICE} -s ${SDC} 2>&1 > /dev/null
 
-Lines 33-37 (running ``symbiflow_write_fasm`` and ``symbiflow_write_bitstream``) typically do not change from design to design.
+Lines 33-37 (running ``symbiflow_write_fasm`` and ``symbiflow_write_bitstream``) typically do 
+not change within the makefile from design to design. 
+
+If you would like to learn more about these commands or if you are using methods other than a 
+makefile to build and compile your designs (such as python or bash scripts) take a look at 
+`Understanding Toolchain Commands <understanding-commands.html>`_.
 
 A Note on the example designs use of ifeq/else ifeq blocks
 -------------------------------------------------------------

docs/index.rst

@@ -15,6 +15,7 @@ Follow this guide to:
   example designs onto the devboard of your choice.
 - compile and run :doc:`your own designs<personal-designs>` using the Symbiflow toolchain.
 - :doc:`customize the Makefile<customizing-makefiles>` for your own designs.
+- gain valuable information about `Understanding Toolchain Commands in Symbiflow <understanding-commands.html>`_
 
 
 About SymbiFlow
@@ -37,3 +38,4 @@ currently targeting chips from multiple vendors, e.g.:
    running-examples
    personal-designs
    customizing-makefiles
+   understanding-commands

docs/personal-designs.rst

@@ -72,7 +72,9 @@ provided, although more complicated designs written in SystemVerilog may not bui
 Yosys. Use whichever method you prefer and add your design files to the directory of choice. 
 If you are using the provided Makefiles to build your design, the top level module in your HDL 
 code should be declared as ``module top (...``. Failure to do so will result in an error from 
-symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!``
+symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!`` If you are using 
+your own makefiles or commands you can specify your top level module name using the -t flag in 
+symbiflow_synth. 
 
 
 

docs/understanding-commands.rst

@@ -0,0 +1,163 @@
+Understanding Toolchain Commands
+=================================
+
+This section provides valuable information on how each of the commands used to compile and build 
+designs in Symbiflow work. It is especially helpful for debugging or if you are 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 Symbiflow works take a look at the 
+`FPGA Design Flow page <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/design-flow.html>`_.
+
+.. note::
+
+    Files created by the synthesis, implementation, and bitstream generation will be dumped into 
+    the directory from which the command is run. 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:
+
+
++------+------------------------------------------------------+
+| Flag |                       Argument                       |
++======+======================================================+
+| -t   | Defines the name for the top level module            |
++------+------------------------------------------------------+
+| -v   | A list of verilog/systemVerilog 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 bellow. 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 file1.v file2.v -d artix7 -p xc7a35tcpg236-1 -x design_constraint.xdc
+
+The symbiflow_synth command synthesizes your design using the Yosys open source tool and generates 
+an .eblif file (the name of the file is the name for your top level module as defined by the -t 
+option), some verilog files that describe the gate level design for your project, and a log
+file. For more information on Yosys and its relation to symbiflow follow 
+`this link <https://symbiflow.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 during synthesis using the ``-t``
+    flag, the build files generated by the toolchain would be named switch_top.eblif, switch_top.net, 
+    etc.
+
+
+Implementation/Place and Route
+-------------------------------
+
+The steps for implementing a design are internally handled by the open source VPR 
+(Versatile Place and Route) tool. For more information go to 
+`the Symbiflow VPR page <https://symbiflow.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:
+
++------+--------------------------------------------------------------------+
+| Flag |                              Argument                              |
++======+====================================================================+
+| -e   | Path to .eblif file generated by synthesis                         |
++------+--------------------------------------------------------------------+
+| -d   | Fabric specification for the board (i.e. xc7a100t_test)            |
++------+--------------------------------------------------------------------+
+| -s   | Optional: SDC file path                                            |
++------+--------------------------------------------------------------------+
+
+Note that the -d option from the pack step (defining the fabric specification) 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 is run using ``symbiflow_place`` which utilizes the following flags:
+
++------+----------------------------------------------------+
+| Flag |                      Argument                      |
++======+====================================================+
+| -e   | Path to .eblif file generated by synthesis         |
++------+----------------------------------------------------+
+| -d   | Fabric specification (xc7a50t_tes)                 |
++------+----------------------------------------------------+
+| -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 with the same use cases as in 
+placement. 
+
+Generating Bitstream
+----------------------
+
+Generating the bitstream consists of two steps. First, ``symbiflow_write_fasm`` is run to 
+generate the .fasm file. ``symbiflow_write_fasm`` uses the -e and -d flags with the same use
+cases as in placing and routing. Second, ``symbiflow_write_bitstream`` is run. The 
+``symbiflow_write_bitstream`` command has the following flags:
+
++------+-------------------------------------------------------+
+| Flag |                        Argument                       |
++======+=======================================================+
+| -d   | FPGA family (i.e. artix7 or zynq7)                    |
++------+-------------------------------------------------------+
+| -f   | The name of 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. ``-d`` in bitstream also defines the FPGA family instead of the fabric as
+in write_fasm step.
+
+The following example generates a bitstream file named example.bit:
+
+.. 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