Revised draft for Personal Designs

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

README.rst

@@ -24,7 +24,7 @@ The repository includes:
 * `.github/ <./.github>`_ - Directory with CI configuration and scripts
 
 Please refer to the `project documentation <https://symbiflow-examples.readthedocs.io>`_
-for a proper guide on how to run these examples. The examples provided by this
+for a proper guide on how to run these examples as well as instructions on how to build and compile your own HDL designs using the symbiflow toolchain. The examples provided by this
 repository are automatically built by extracting necessary code snippets with
 `tuttest <https://github.com/antmicro/tuttest>`_.
 

docs/Understanding-Makefile.rst

@@ -1,14 +1,14 @@
-Understanding the Makefile in Symbiflow
+Customizing the Makefiles from Symbiflow-examples For Your Own Designs
-==========================================
+=======================================================================
-A key steep in creating your own designs is understanding how to use the Makefiles in symbiflow. This tutorial walks you through some of the key aspects of working with the Makefiles in symbiflow to allow for better debugging. 
+A key step in creating your own designs is understanding how to use the Makefiles in symbiflow. This tutorial walks you through some of the key aspects of working with the Makefiles in symbiflow to allow for better debugging. 
 
 Example 
 -------
-To understand how the Makfiles within symbiflow are setup, lets take a look at a more simple Makefile that will run the symbiflow counter test on the basys3 board. Highlighted lines within the code below are of particular interest and will change depending on your design and hardware.
+To understand how the Makefiles within Symbiflow are setup, lets take a look at a simple Makefile in symbiflow-examples that will run the symbiflow counter test on the basys3 board. Highlighted lines within the code below are of particular interest and will change depending on your design and hardware.
 
 .. code-block:: bash
    :name: makefile-example
-   :emphasize-lines: 4, 5, 9, 10
+   :emphasize-lines: 4, 5, 9, 10, 22, 25, 28, 31
    :linenos:
 
    mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
@@ -52,7 +52,6 @@ To understand how the Makfiles within symbiflow are setup, lets take a look at a
    clean:
       rm -rf ${BUILDDIR}
 
-Lets go over the highlighted lines one by one and discuss their purpose. 
 
 Adding HDL files to your design
 ----------------------------------
@@ -84,9 +83,9 @@ To include SystemVerilog in your design simply change the ``*.v`` above to a ``*
 
    As of this writing symbiflow only supports Verilog and SystemVerilog HDL by default.
 
-Setting the device properties
+Setting the Board Type and Part Name
-------------------------------
+-------------------------------------
-Line 5 in the example sets the device type for the project. Several different board types are supported and a listing of the commands for each board type follows:
+Line 5 in the example defines the device architecture for the project. Several different board types are supported and a listing of the commands for each board type follow:
 
 .. tabs::
 
@@ -133,7 +132,7 @@ Line 5 in the example sets the device type for the project. Several different bo
          DEVICE:= xc7a200t_test
 
 
-As shown on line 9 of the example makefile you will also need to define the part your FPGA uses. To do this you need to add the following line of code to your makefile depending on your hardware:
+As shown on line 9 of the example makefile you will also need to define the specific FPGA part your board uses. To do this you need to add the following line of code to your makefile depending on your hardware:
 
 .. tabs::
 
@@ -183,7 +182,7 @@ As shown on line 9 of the example makefile you will also need to define the part
 Constraint files
 ----------------
 
-Line 10 shows how you can specify what the constraint files are being used for your design. The general syntax depends on wether you are using XDC files or a SDC+PCF pair:
+Line 10 shows how you can specify what the constraint files are being used for your design. The general syntax depends on whether you are using XDC files or a SDC+PCF pair:
 
 .. tabs::
 
@@ -256,4 +255,4 @@ Note that the lines 22, 25, 28, and 31 (.eblif, net, place, and route) will also
          ${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 from design to design.

docs/personal-designs.rst

@@ -1,12 +1,12 @@
-Using Symbiflow to upload your own designs
+Compiling and Running Your Own Designs Using the Symbiflow Toolchain 
-===========================================
+=====================================================================
 
-This section describes how to upload you're own designs to an FPGA from start to finish using only open source tools.
+This section describes how to compile and download your own designs to an FPGA using only the symbiflow tool chain.
 
-Preparing your environment
+Setup Prior to Running the Toolchain
-----------------------------
+--------------------------------------
-Before building any example, set the installation directory to match what you
+Before building any examples, you will need to first install the toolchain. To do this, follow the steps in `Getting Symbiflow <getting-symbiflow.html>`_.
-set it to earlier, for example:
+After you have downloaded the toolchain, set the installation directory to match what you set it to earlier, for example:
 
 .. code-block:: bash
    :name: export-install-dir
@@ -31,7 +31,7 @@ Select your FPGA family:
 
          FPGA_FAM="eos-s3"
 
-Next, prepare the environment:
+Next, set the path and source for your conda environment:
 
 .. code-block:: bash
    :name: conda-prep-env
@@ -39,7 +39,7 @@ Next, prepare the environment:
    export PATH="$INSTALL_DIR/$FPGA_FAM/install/bin:$PATH";
    source "$INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh"
 
-Finally, enter your working Conda environment:
+Finally, activate your Conda environment:
 
 .. code-block:: bash
    :name: conda-act-env
@@ -49,40 +49,42 @@ Finally, enter your working Conda environment:
 
 .. note::
 
-   You will need to run the commands for preparing your conda environment each time you open a new terminal. You will also need to activate the Conda environment for your hardware before you attempt to build your designs. It might be a good idea to add the above commands to your ``.bashrc`` either as functions or aliases to save yourself some repetitive typing. 
+   You will need to run the commands for setting the path and source of your conda environment each time you open a new terminal. You will also need to activate the Conda environment for your hardware before you attempt to build your designs. It might be a good idea to add the above commands to your ``.bashrc`` either as default commands that run each time you open a new terminal or aliases to save yourself some repetitive typing. 
 
 
-Preparing Your Design
+Preparing Your Design 
 ----------------------
-Building a design in symbiflow requires three simple parts, the HDL files for your design, a constraints file, and a Makefile. For simplicity, all three of these design parts should be moved to a single directory.
+Building a design in symbiflow requires three parts, the HDL files for your design, a constraints file, and a Makefile. For simplicity, all three of these design files should be moved to a single directory in the location of your choosing.
 
-HDL files
+HDL Files
 ++++++++++
-Symbiflow provides support for both Verilog and SystemVerilog HDL code. 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, your top level module should be declared as ``module top (...``. Failure to do so will result in an error during the build process stating something to the effect of ``ERROR: Module 'top' not found!``
+Symbiflow provides support for both Verilog and SystemVerilog HDL code. 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 during the build process stating something similar to ``ERROR: Module 'top' not found!``
 
 
 
-Constraint file
+Constraint File
 ++++++++++++++++
-The Symbiflow tool chain supports both .XDC and .PCF+.SDC formats for constraint files. Use whichever method you prefer and add your constraint file(s) to the design directory.
+The Symbiflow tool chain supports both .XDC and .PCF+.SDC formats for constraints. Use whichever method you prefer and add your constraint file(s) to your design directory.
 
 
 Makefile
 +++++++++
-To learn about how Makefiles in symbiflow work, see the `Understanding the Makefile in Symbiflow <Understanding-Makefile.html>`_ page.
+To learn about how Makefiles in symbiflow work, see `Understanding the Makefile in Symbiflow <Understanding-Makefile.html>`_ page.
 
 If you have used verilog as your HDL and an XDC as your constraint, you can add this :download:`Makefile <master_makefile/Makefile>` to your design directory instead of building your own.
 
 
 Building your personal projects 
 -------------------------------
-Before you begin building your design, navigate to the directory where you have stored your Makefile, HDL, and constraint files:
+
+Before you begin building your design, navigate to the directory where you have stored your personal Makefile, HDL, and constraint files:
 
 .. code-block:: bash
    :name: your-directory
 
    cd <path to your directory>
 
+
 Then, depending on your board type run: 
 
 .. tabs::
@@ -132,7 +134,7 @@ Once you navigate to the directory containing the bitstream, use the following c
 
 .. tip::
     Many of the commands needed to build a project are run multiple times with little to no variation. You might consider adding a few aliases or even a few bash functions to your .bashrc file to save yourself some typing or repeated copy/paste. 
-    For example, instead of using the somewhat cumbersome command used to upload the bitstream to Xilinx 7 series FPGA every time, you could just add the following lines to your bashrc file:
+    For example, instead of using the somewhat cumbersome command used to upload the bitstream to Xilinx 7 series FPGA every time, you could just add the following lines to your .bashrc file:
     
     .. code-block:: bash
        :name: bash-functions