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
==========================
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 <understanding-commands.html>`_ 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 <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>`_,
and `PicoSoC Demo <https://github.com/SymbiFlow/symbiflow-examples/blob/master/xc7/picosoc_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>`_
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 <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
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 <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
``TOP:=switches``.
:ref:`Line 3 <makefile-example>` 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 <makefile-example>` 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 <makefile-example>` 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 <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:
.. tabs::
@ -232,7 +230,7 @@ depending on your hardware:
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:
.. 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 <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.
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
: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>
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.

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)))
current_dir := $(patsubst %/,%,$(dir $(mkfile_path)))
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
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 <getting-symbiflow.html>`_. 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 <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. 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 <Understanding-Makefile.html>`_.
your own in the `Customizing Makefiles <customizing-makefiles.html>`_ page.
Building your personal projects
-------------------------------

16
docs/understanding-commands.rst
View File

@ -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 <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_.
.. 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