diff --git a/docs/customizing-makefiles.rst b/docs/customizing-makefiles.rst index 50e868b..5e4acdf 100644 --- a/docs/customizing-makefiles.rst +++ b/docs/customizing-makefiles.rst @@ -1,26 +1,25 @@ Customizing the Makefiles ========================== -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 powerful tool in creating your own designs is understanding how to generate your own Makefile to +compile projects. 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. 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 symbiflow -commands used by the Makefile to build and compile designs take a look at +(such as python or bash scripts) or if you would like to learn more about the various Symbiflow +commands used by the Makefile to build and compile designs take a look at the `Understanding Toolchain Commands `_ page. Example ------- -Every design in symbiflow has its own Makefile. For example +Every example design in Symbiflow has its own Makefile. For example `counter test `_, -`Linux Litex Demo `_, -and `PicoSoC Demo `_ +`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 on the Makefile within the `counter test `_ +is based on 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 @@ -76,9 +75,9 @@ into your own Makefile. Adding HDL files to your design -------------------------------- -:ref:`Line 3 ` in the Makefile shows how to define the name for your top level module. For example if -your top level module was named ``module switches ( ...`` then you would simply change line 3 to -``TOP:=switches``. +:ref:`Line 3 ` in the Makefile shows how to define the name for your top level module. For example, if +your top module was named ``module switches ( ...`` then you would simply change line 3 to +``TOP := switches``. .. warning:: @@ -128,10 +127,9 @@ Makefile to ``SYSTEM_VERILOG`` to improve readability. Setting the Board Type and Part Name ------------------------------------- -:ref:`Line 5 ` in the example Makefile defines the device fabric for the board being used in the project. - -Several different device fabrics are supported and a listing of the commands for each -follow: +:ref:`Line 5 ` in the example Makefile defines the device fabric +for the board being used in the project. Several different device fabrics are +supported and a listing of the commands for each follow: .. tabs:: @@ -181,7 +179,7 @@ follow: family while zybo boards are from the zynq7 series. As shown on :ref:`line 9 ` of the example Makefile, you will also need to define the specific FPGA part -number for your chip. To do this you need to add the following line of code to your Makefile +number for your chip. To do this, you need to add the following line of code to your Makefile depending on your hardware: .. tabs:: @@ -232,7 +230,7 @@ depending on your hardware: Constraint files ---------------- -:ref:`Line 10 ` shows how you can specify what the constraint files are being used for your design. The +:ref:`Line 10 ` shows how you can specify what 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:: @@ -300,7 +298,7 @@ not change within the Makefile from design to design. 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 +If you look at 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 `_: @@ -350,7 +348,7 @@ running ``TARGET="" make -C counter_test`` before building the count 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 :ref:`lines 5, 9 and 10 in our example `: +designs, then you could just use something similar to :ref:`lines 5, 9 and 10 ` in our example: .. code-block:: bash :name: device-partname-snippet @@ -361,6 +359,6 @@ designs then you could just use something similar to :ref:`lines 5, 9 and 10 in 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 +copy the if else block 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/master_makefile/Makefile b/docs/master_makefile/Makefile index e299828..12ffd7d 100644 --- a/docs/master_makefile/Makefile +++ b/docs/master_makefile/Makefile @@ -1,4 +1,5 @@ -# This is the master Makefile for all projects +# This Makefile can be add to your design to compile projects using Verilog as an HDL, +# and an XDC as a constraint. You can also make changes to this file to build more specialized designs. mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST))) current_dir := $(patsubst %/,%,$(dir $(mkfile_path))) TOP := top diff --git a/docs/personal-designs.rst b/docs/personal-designs.rst index e7c55a6..767436c 100644 --- a/docs/personal-designs.rst +++ b/docs/personal-designs.rst @@ -2,7 +2,7 @@ Building Custom Designs ======================== This section describes how to compile and download your own designs to an FPGA using only -the symbiflow toolchain. +the Symbiflow 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, @@ -13,9 +13,9 @@ your conda environment, and activating your env. Preparing Your Design ---------------------- -Building a design in symbiflow requires three parts, the HDL files for your design, a constraints +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 +directory. The location of the directory does not mater as long as the three design elements are all within it. HDL Files @@ -23,12 +23,12 @@ HDL Files 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. +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!`` If you are using your own makefiles or commands, you can specify your top level module name using the -t flag in -symbiflow_synth. +``symbiflow_synth``. Constraint File ++++++++++++++++ @@ -45,14 +45,11 @@ toolchain will automatically generate one to provide clock constraints to VTR. Makefile +++++++++ -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 `_. +your own in the `Customizing Makefiles `_ page. Building your personal projects ------------------------------- diff --git a/docs/understanding-commands.rst b/docs/understanding-commands.rst index dc17d1e..b0d7bf4 100644 --- a/docs/understanding-commands.rst +++ b/docs/understanding-commands.rst @@ -13,7 +13,7 @@ flow for Symbiflow works take a look at the .. note:: - Files created by the synthesis, implementation, and bitstream generation will be dumped into + 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. @@ -51,9 +51,9 @@ family and uses the xc7a35tcpg236-1 chip. symbiflow_synth -t top -v example.v top_example.v -d artix7 -p xc7a35tcpg236-1 -x design_constraint.xdc -The symbiflow_synth command synthesizes your design using the Yosys open source tool. Synthesis generates +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 symbiflow go to the +file. For more information on Yosys and its relation to Symbiflow go to the `Symbiflow-Yosys page `_. .. note:: @@ -90,7 +90,7 @@ pack command are as follows: | -s | Optional: SDC file path | +------+--------------------------------------------------------------------+ -Note that the -d option from the pack step (defining the fabric specification) is different +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: @@ -102,7 +102,9 @@ The following example runs packing on the basys3 board: Place ++++++ -Placement is run using ``symbiflow_place`` which utilizes the following flags: +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 @@ -127,7 +129,7 @@ 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 ++++++ @@ -168,7 +170,7 @@ Notice that the specification for the part number is a lowercase ``-p`` instead ``-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. -The following example generates a bitstream file for the basys3 named example.bit: +The following example generates a bitstream file named example.bit for the basys3 board: .. code-block:: bash