diff --git a/README.rst b/README.rst index f4765d5..190f119 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,10 @@ SymbiFlow examples ================== +Please refer to the `project documentation `_ +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. + .. image:: https://github.com/symbiflow/symbiflow-examples/workflows/doc-test/badge.svg?branch=master :target: https://github.com/SymbiFlow/symbiflow-examples/actions @@ -23,10 +27,8 @@ The repository includes: * `docs/ <./docs>`_ - Guide on how to get started with SymbiFlow and build provided examples * `.github/ <./.github>`_ - Directory with CI configuration and scripts -Please refer to the `project documentation `_ -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 `_. +The examples provided by this repository are automatically built by extracting +necessary code snippets with `tuttest `_. Building those docs ------------------- diff --git a/docs/Understanding-Makefile.rst b/docs/customizing-makefiles.rst similarity index 71% rename from docs/Understanding-Makefile.rst rename to docs/customizing-makefiles.rst index 55a1883..4c82f0e 100644 --- a/docs/Understanding-Makefile.rst +++ b/docs/customizing-makefiles.rst @@ -1,11 +1,24 @@ Customizing the Makefiles from Symbiflow-examples For Your Own Designs ======================================================================= -A key step in creating your own designs is understanding how to generate your own Makefiles to properly compile and build designs with the symbiflow toolchain. This tutorial walks you through some of the key aspects of working with Makefiles and explains how you can create Makefiles for your own designs. +A key step in creating your own designs is understanding how to generate your own Makefiles to +properly compile and build designs with the symbiflow toolchain. This tutorial walks you through +some of the key aspects of working with Makefiles and explains how you can create Makefiles for +your own designs. Example ------- -Every design in symbiflow has its own makefile. For example `Counter-test `_, `Linux Litex Demo `_, and `Picosoc Demo `_ all have there own unique Makefiles for compiling and building respective designs. To understand how to set up a Makefile in symbiflow, lets take a look at a simple Makefile. The following code is based off of the Makefile within `Counter-test `_ and has been modified slightly for simplicity. Highlighted lines within the code below are of particular interest and will change depending on your specific design elements and hardware. Lines that are not highlighted do not change from design to design and can be copy and pasted into your own Makefile. +Every design in symbiflow has its own makefile. For example +`Counter-test `_, +`Linux Litex Demo `_, +and `Picosoc Demo `_ +all have there own unique Makefiles for compiling and building respective designs. To understand +how to set up a Makefile in symbiflow, lets take a look at a simple Makefile. The following code +is based off of the Makefile within `Counter-test `_ +and has been modified slightly for simplicity. Highlighted lines within the code below are of +particular interest and will change depending on your specific design elements and hardware. +Lines that are not highlighted do not change from design to design and can be copy and pasted +into your own Makefile. .. code-block:: bash :name: makefile-example @@ -56,7 +69,9 @@ Every design in symbiflow has its own makefile. For example `Counter-test :=${current_dir}/``. You can also add multiple HDL files to a design using the following syntax: +Line 4 in the Makefile shows how to add HDL files to the design. The general syntax is: +``:=${current_dir}/``. You can also add multiple HDL files to a +design using the following syntax: .. code-block:: bash :name: multi-file-example @@ -70,7 +85,9 @@ Line 4 in the Makefile shows how to add HDL files to the design. The general syn ${current_dir}/ \ ... -You could also use wildcards to collect all HDL file types of a specific extension and add them to your design. For example, if you wanted to add all verilog files within the current directory to your design, you could replace line 4 in the Makefile with: +You could also use wildcards to collect all HDL file types of a specific extension and add them +to your design. For example, if you wanted to add all verilog files within the current directory +to your design, you could replace line 4 in the Makefile with: .. code-block:: bash :name: wildcard-example @@ -78,15 +95,20 @@ You could also use wildcards to collect all HDL file types of a specific extensi VERILOG := ${current_dir}/*.v -To include SystemVerilog HDL in your designs simply change the ``.v`` extension in the examples above to a ``.sv``. You might also want to change the ``VERILOG`` bash variables throughout the Makefile to ``SYSTEM_VERILOG`` to improve readability. +To include SystemVerilog HDL in your designs simply change the ``.v`` extension in the examples +above to a ``.sv``. You might also want to change the ``VERILOG`` bash variables throughout the +Makefile to ``SYSTEM_VERILOG`` to improve readability. .. note:: - As of this writing symbiflow only supports Verilog and SystemVerilog HDL by default. + As of this writing symbiflow only offers full support for Verilog by default. + SystemVerilog can also be run through the toolchain but more complicated commands are not fully + supported. Setting the Board Type and Part Name ------------------------------------- -Line 5 in the example Makefile defines the board type for the project. The use of the term DEVICE may be confusing, but it does refer to a board type as you can see from the context below. +Line 5 in the example Makefile defines the board type for the project. The use of the term DEVICE +may be confusing, but it does refer to a board type as you can see from the context below. Several different board types are supported and a listing of the commands for each board type follow: @@ -135,7 +157,9 @@ Several different board types are supported and a listing of the commands for ea DEVICE:= xc7a200t_test -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: +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:: @@ -185,7 +209,8 @@ As shown on line 9 of the example makefile you will also need to define the spec Constraint files ---------------- -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: +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:: @@ -202,7 +227,9 @@ Line 10 shows how you can specify what the constraint files are being used for y PCF := ${current_dir}/ SDC := ${current_dir}/ -Note that the lines 22, 25, 28, and 31 (.eblif, net, place, and route) will also need to change depending on if you use an XDC file or some combination of SDC, PCF and XDC files. The following snippets show the differences and the areas that will need to change: +Note that the lines 22, 25, 28, and 31 (.eblif, net, place, and route) will also need to change +depending on if you use an XDC file or some combination of SDC, PCF and XDC files. The following +snippets show the differences and the areas that will need to change: .. tabs:: @@ -263,7 +290,9 @@ Lines 33-37 (running ``symbiflow_write_fasm`` and ``symbiflow_write_bitstream``) A Note on the example designs use of ifeq/else ifeq blocks ------------------------------------------------------------- -If you look at many of the Makefiles from the example designs within symbiflow (i.e. counter-test, Picosoc, etc.), you will find an ifeq else ifeq block. The following snippet is from lines 9-39 of `the Makefile from Counter-test `_: +If you look at many of the Makefiles from the example designs within symbiflow +(i.e. counter-test, Picosoc, etc.), you will find an ifeq else ifeq block. The following snippet +is from lines 9-39 of `the Makefile from Counter-test `_: .. code-block:: bash @@ -301,9 +330,16 @@ If you look at many of the Makefiles from the example designs within symbiflow ( BOARD_BUILDDIR := ${BUILDDIR}/basys3 endif -This snippet of code is an if else block used to set the specific PARTNAME and DEVICE parameters for different types of hardware. Since each FPGA has a unique pin configuration, the block also defines a constraint file specific to the hardware being used (i.e. ``basys3.xdc``, ``nexys_video.xdc``). The code block determines what type of hardware is being used based upon a TARGET variable which is assumed to be defined before running make. For example, you may recall running ``TARGET="" make -C counter_test`` before building the counter-test example. This command sets the TARGET variable to the type of hardware you are using. +This snippet of code is an if else block used to set the specific PARTNAME and DEVICE parameters +for different types of hardware. Since each FPGA has a unique pin configuration, the block also +defines a constraint file specific to the hardware being used (i.e. ``basys3.xdc``, +``nexys_video.xdc``). The code block determines what type of hardware is being used based upon a +TARGET variable which is assumed to be defined before running make. For example, you may recall +running ``TARGET="" make -C counter_test`` before building the counter-test example. +This command sets the TARGET variable to the type of hardware you are using. -The if else block is completely optional. If you are only using one type of hardware for your designs then you could just use something similar to lines 5, 9 and 10 in our example: +The if else block is completely optional. If you are only using one type of hardware for your +designs then you could just use something similar to lines 5, 9 and 10 in our example: .. code-block:: bash :name: device-partname-snippet @@ -313,4 +349,7 @@ The if else block is completely optional. If you are only using one type of hard PARTNAME:= xc7a35tcpg236-1 XDC:=${current_dir}/ -If you plan on using multiple types of hardware for your designs, then it might be better to just copy the if else blocks from one of the symbiflow-examples. Note that you may need to change the names for the XDC or PCF+SDC parameters to match the names you have used. Also remember that you will need to set the TARGET variable before running make on your design. +If you plan on using multiple types of hardware for your designs, then it might be better to just +copy the if else blocks from one of the symbiflow-examples. Note that you may need to change the +names for the XDC or PCF+SDC parameters to match the names you have used. Also remember that you +will need to set the TARGET variable before running make on your design. diff --git a/docs/index.rst b/docs/index.rst index 06a4562..6f19b14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ Follow this guide to: - :doc:`build ` and :doc:`upload ` example designs onto the devboard of your choice. - compile and run :doc:`your own designs` using the Symbiflow toolchain. -- :doc:`customize the Makefile` for your own designs. +- :doc:`customize the Makefile` for your own designs. About SymbiFlow @@ -36,4 +36,4 @@ currently targeting chips from multiple vendors, e.g.: building-examples running-examples personal-designs - Understanding-Makefile + customizing-makefiles diff --git a/docs/personal-designs.rst b/docs/personal-designs.rst index 60907d8..32ec823 100644 --- a/docs/personal-designs.rst +++ b/docs/personal-designs.rst @@ -1,12 +1,14 @@ -Compiling and Running Your Own Designs Using the Symbiflow-examples Toolchain -============================================================================== +Building Custom Designs +======================== -This section describes how to compile and download your own designs to an FPGA using only the symbiflow-examples tool chain. +This section describes how to compile and download your own designs to an FPGA using only +the symbiflow-examples tool chain. Setup Prior to Running the Toolchain -------------------------------------- -Before building any examples, you will need to first install the toolchain. To do this, follow the steps in `Getting Symbiflow `_. -After you have downloaded the toolchain, set the installation directory to match what you set it to earlier, for example: +Before building any examples, you will need to first install the toolchain. To do this, follow the +steps in `Getting Symbiflow `_. 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 @@ -49,35 +51,54 @@ Finally, activate your Conda environment: .. note:: - 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. + 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 ---------------------- -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. The location of the directory does not mater as long as the three design files are all within it. +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. The location of the directory does not mater as long as the three design files are all +within it. 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, 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!`` +Symbiflow provides full support for Verilog. Some support for SystemVerilog HDL code is also +provided, although more complicated designs written in SystemVerilog may not build properly under +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!`` Constraint File ++++++++++++++++ -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. +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 `Understanding the Makefile in Symbiflow `_ page. +To learn about how Makefiles in symbiflow work, see +`Understanding the Makefile in Symbiflow `_ page. -If you have used verilog as your HDL and an XDC as your constraint, you can add this :download:`Makefile ` to your design directory instead of building your own. If you have used a different HDL than verilog or have used a combination of PCF+SDC constraint files, you can find instructions for how to modify the provided makefile or create your own in `Understanding the Makefile in Symbiflow `_. +If you have used verilog as your HDL and an XDC as your constraint, you can add this +:download:`Makefile ` to your design directory instead of building your +own. If you have used a different HDL than verilog or have used a combination of PCF+SDC +constraint files, you can find instructions for how to modify the provided makefile or create +your own in `Understanding the Makefile in Symbiflow `_. Building your personal projects ------------------------------- -Before you begin building your design, navigate to the directory where you have stored your personal 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 @@ -125,7 +146,8 @@ If your design builds without error, the bitstream can be found in the following cd build/ -Once you navigate to the directory containing the bitstream, use the following commands on the **Arty and Basys3** to upload the design to your board: +Once you navigate to the directory containing the bitstream, use the following commands on the +**Arty and Basys3** to upload the design to your board: .. code-block:: bash @@ -133,8 +155,11 @@ 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: + 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: .. code-block:: bash :name: bash-functions