Hardware
/
f4pga-examples
mirror of https://github.com/chipsalliance/f4pga-examples.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fixed a few grammar errors and made things a little clearer 

Signed-off-by: Joshua Fife <jpfife17@gmail.com>
This commit is contained in:
Joshua Fife 2021-07-05 16:37:40 -06:00
parent ce5b57240d
commit 23ef2d56a2
4 changed files with 37 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/customizing-makefiles.rst
View File

@ -1,26 +1,25 @@
Customizing the Makefiles Customizing the Makefiles
========================== ==========================
A key step in creating your own designs is understanding how to generate your own Makefiles to A powerful tool in creating your own designs is understanding how to generate your own Makefile to
properly compile and build designs with the symbiflow toolchain. This tutorial walks you through compile projects. This tutorial walks you through some of the key aspects of working with Makefiles
some of the key aspects of working with Makefiles and explains how you can create Makefiles for and explains how you can create Makefiles for your own designs.
your own designs.
If you would like to use methods other than a Makefile to build and compile your 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 (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 commands used by the Makefile to build and compile designs take a look at the
`Understanding Toolchain Commands <understanding-commands.html>`_ page. `Understanding Toolchain Commands <understanding-commands.html>`_ page.
Example Example
------- -------
Every design in symbiflow has its own Makefile. For example Every example design in Symbiflow has its own Makefile. For example
`counter test <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_, `counter test <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_,
`Linux Litex Demo <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/linux_litex_demo/Makefile>`_, `Linux Litex demo <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/linux_litex_demo/Makefile>`_,
and `PicoSoC Demo <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/picosoc_demo/Makefile>`_ and `PicoSoC demo <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/picosoc_demo/Makefile>`_
all have there own unique Makefiles for compiling and building respective designs. To understand 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 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 <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_ is based on the Makefile within `counter test <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_
and has been modified slightly for simplicity. Highlighted lines within the code below are of 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. 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 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 Adding HDL files to your design
-------------------------------- --------------------------------
:ref:`Line 3 <makefile-example>` in the Makefile shows how to define the name for your top level module. For example if :ref:`Line 3 <makefile-example>` 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 your top module was named ``module switches ( ...`` then you would simply change line 3 to
``TOP:=switches``. ``TOP := switches``.
.. warning:: .. warning::
@ -128,10 +127,9 @@ Makefile to ``SYSTEM_VERILOG`` to improve readability.
Setting the Board Type and Part Name Setting the Board Type and Part Name
------------------------------------- -------------------------------------
:ref:`Line 5 <makefile-example>` in the example Makefile defines the device fabric for the board being used in the project. :ref:`Line 5 <makefile-example>` in the example Makefile defines the device fabric
for the board being used in the project. Several different device fabrics are
Several different device fabrics are supported and a listing of the commands for each supported and a listing of the commands for each follow:
follow:
.. tabs:: .. tabs::
@ -181,7 +179,7 @@ follow:
family while zybo boards are from the zynq7 series. family while zybo boards are from the zynq7 series.
As shown on :ref:`line 9 <makefile-example>` of the example Makefile, you will also need to define the specific FPGA part As shown on :ref:`line 9 <makefile-example>` 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: depending on your hardware:
.. tabs:: .. tabs::
@ -232,7 +230,7 @@ depending on your hardware:
Constraint files Constraint files
---------------- ----------------
:ref:`Line 10 <makefile-example>` shows how you can specify what the constraint files are being used for your design. The :ref:`Line 10 <makefile-example>` 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: general syntax depends on whether you are using XDC files or a SDC+PCF pair:
.. tabs:: .. 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 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 (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 <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_: is from lines 9-39 of `the Makefile from counter test <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/counter_test/Makefile>`_:
@ -350,7 +348,7 @@ running ``TARGET="<board type>" make -C counter_test`` before building the count
This command sets the TARGET variable to the type of hardware you are using. 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 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 <makefile-example>`: designs, then you could just use something similar to :ref:`lines 5, 9 and 10 <makefile-example>` in our example:
.. code-block:: bash .. code-block:: bash
:name: device-partname-snippet :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}/<name of XDC file> XDC := ${current_dir}/<name of XDC file>
If you plan on using multiple types of hardware for your designs, then it might be better to just 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 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. will need to set the TARGET variable before running make on your design.

3
docs/master_makefile/Makefile
View File

@ -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))) mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
current_dir := $(patsubst %/,%,$(dir $(mkfile_path))) current_dir := $(patsubst %/,%,$(dir $(mkfile_path)))
TOP := top TOP := top

15
docs/personal-designs.rst
View File

@ -2,7 +2,7 @@ Building Custom Designs
======================== ========================
This section describes how to compile and download your own designs to an FPGA using only 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 Before building any examples, you will need to first install the toolchain. To do this, follow the
steps in `Getting Symbiflow <getting-symbiflow.html>`_. After you have downloaded the toolchain, steps in `Getting Symbiflow <getting-symbiflow.html>`_. After you have downloaded the toolchain,
@ -13,9 +13,9 @@ your conda environment, and activating your env.
Preparing Your Design 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 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. within it.
HDL Files HDL Files
@ -23,12 +23,12 @@ HDL Files
Symbiflow provides full support for Verilog. Some support for SystemVerilog HDL code is also 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 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 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 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 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 your own makefiles or commands, you can specify your top level module name using the -t flag in
symbiflow_synth. ``symbiflow_synth``.
Constraint File Constraint File
++++++++++++++++ ++++++++++++++++
@ -45,14 +45,11 @@ toolchain will automatically generate one to provide clock constraints to VTR.
Makefile Makefile
+++++++++ +++++++++
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 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 :download:`Makefile <master_makefile/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 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 constraint files, you can find instructions for how to modify the provided makefile or create
your own in `Understanding the Makefile in Symbiflow <Understanding-Makefile.html>`_. your own in the `Customizing Makefiles <customizing-makefiles.html>`_ page.
Building your personal projects Building your personal projects
------------------------------- -------------------------------

14
docs/understanding-commands.rst
View File

@ -13,7 +13,7 @@ flow for Symbiflow works take a look at the
.. note:: .. 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 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 the toolchain separate from your design files, you might consider running the toolchain
commands in a separate directory from your design files. 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 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 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 <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_. `Symbiflow-Yosys page <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_.
.. note:: .. note::
@ -90,7 +90,7 @@ pack command are as follows:
| -s | Optional: SDC file path | | -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). from the -d from synthesis (defining the FPGA family).
The following example runs packing on the basys3 board: The following example runs packing on the basys3 board:
@ -102,7 +102,9 @@ The following example runs packing on the basys3 board:
Place 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 .. table:: symbiflow_place
@ -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 ``-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. 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 .. code-block:: bash