mirror of
https://github.com/chipsalliance/f4pga-examples.git
synced 2025-01-03 03:43:38 -05:00
docs: 'understanding' moved to f4pga
Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral
parent
11986eaca5
commit
6cdae4ab93
6 changed files with 21 additions and 213 deletions
|
|
@ -6,7 +6,7 @@ This tutorial walks you through how to do that.
|
|||
|
||||
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 F4PGA commands used by the common Makefile to build and
|
||||
compile designs take a look at the :ref:`Understanding` page.
|
||||
compile designs take a look at the :doc:`F4PGA Documentation <f4pga:index>` page.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Running "CI" locally
|
||||
####################
|
||||
Running CI locally
|
||||
##################
|
||||
|
||||
The CI uses a bunch of scripts in the `.github/scripts/ <./.github/scripts>`_ directory to execute the needed tests.
|
||||
You can use the same scripts locally to test without having to wait for the online CIs to pass if you want to quickly
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
Welcome to F4PGA examples!
|
||||
==========================
|
||||
##########################
|
||||
|
||||
This guide explains how to get started with F4PGA and build example designs from the :gh:`F4PGA Examples <chipsalliance/f4pga-examples>`
|
||||
GitHub repository.
|
||||
It currently focuses on the following FPGA families:
|
||||
|
||||
- Artix-7 from Xilinx,
|
||||
- EOS S3 from QuickLogic.
|
||||
- EOS-S3 from QuickLogic.
|
||||
|
||||
Follow this guide to:
|
||||
|
||||
|
|
@ -15,27 +15,27 @@ Follow this guide to:
|
|||
example designs onto the devboard of your choice.
|
||||
- compile and run :doc:`your own designs<personal-designs>` using the F4PGA toolchain.
|
||||
- :doc:`customize the Makefile<customizing-makefiles>` for your own designs.
|
||||
- gain valuable information about :doc:`Understanding Toolchain Commands in F4PGA <understanding>`.
|
||||
|
||||
|
||||
About F4PGA
|
||||
-----------
|
||||
===========
|
||||
|
||||
F4PGA is a fully open source toolchain for the development of FPGAs,
|
||||
currently targeting chips from multiple vendors, e.g.:
|
||||
F4PGA is a fully open source toolchain for the development of FPGAs, currently targeting chips from multiple vendors, e.g.:
|
||||
|
||||
- Xilinx 7-Series
|
||||
- Lattice iCE40
|
||||
- Lattice ECP5 FPGAs
|
||||
- QuickLogic EOS S3
|
||||
- Xilinx's 7-Series.
|
||||
- Lattice's ICE40 and ECP5.
|
||||
- QuickLogic's EOS-S3.
|
||||
|
||||
Gain valuable information about the flows and the tools in section :ref:`Design Flows <f4pga:Flows>` at
|
||||
:doc:`F4PGA Documentation <f4pga:index>`.
|
||||
|
||||
|
||||
Table of Contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
|
||||
getting
|
||||
understanding
|
||||
|
||||
.. toctree::
|
||||
:caption: Example designs
|
||||
|
||||
building-examples
|
||||
running-examples
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
.. _Building-Custom-Designs:
|
||||
|
||||
Building Custom Designs
|
||||
Building custom designs
|
||||
=======================
|
||||
|
||||
This section describes how to compile and download your own designs to an FPGA using only
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Running Project F designs in F4PGA
|
||||
==================================
|
||||
Running Project F designs
|
||||
=========================
|
||||
|
||||
.. warning::
|
||||
F4PGA does not currently support the MMCME2_BASE primitive--a key commponent in Project F's clock_gen_480p module
|
||||
|
|
|
|||
|
|
@ -1,192 +0,0 @@
|
|||
.. _Understanding:
|
||||
|
||||
Understanding the flow
|
||||
======================
|
||||
|
||||
This section provides valuable information on how each of the commands used to compile and build
|
||||
designs in F4PGA work. It is especially helpful for debugging or for using methods
|
||||
other than a makefile to build your designs, such as a bash or python script.
|
||||
|
||||
The following describes the commands for running each of the steps for a full design flow
|
||||
(synthesis, place and route, and generate bitstream) as well as giving a description of the most
|
||||
common flags for those commands. If you would like a more detailed break down of how the design
|
||||
flow for F4PGA works take a look at the
|
||||
`FPGA Design Flow page <https://f4pga.readthedocs.io/en/latest/toolchain-desc/design-flow.html>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Synthesis
|
||||
----------
|
||||
|
||||
To synthesize your designs run the ``symbiflow_synth`` command. The command has the following
|
||||
flags:
|
||||
|
||||
.. table:: symbiflow_synth
|
||||
|
||||
+------+---------------------------------------------------------------+
|
||||
| Flag | Argument |
|
||||
+======+===============================================================+
|
||||
| -t | Defines the name for the top level module |
|
||||
+------+---------------------------------------------------------------+
|
||||
| -v | A list of paths to verilog files for the design |
|
||||
+------+---------------------------------------------------------------+
|
||||
| -d | FPGA family (i.e. artix7 or zynq7) |
|
||||
+------+---------------------------------------------------------------+
|
||||
| -p | The part number for the FPGA (i.e xc7a35tcsg324-1) |
|
||||
+------+---------------------------------------------------------------+
|
||||
| -x | Optional command: path to xdc files for design |
|
||||
+------+---------------------------------------------------------------+
|
||||
|
||||
|
||||
An example of how to run synthesis on a design containing two separate
|
||||
verilog HDL files is below. The design is built for a basys3 board which comes from the artix7
|
||||
family and uses the xc7a35tcpg236-1 chip.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symbiflow_synth -t top -v example.v top_example.v -d artix7 -p xc7a35tcpg236-1 -x design_constraint.xdc
|
||||
|
||||
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 F4PGA go to the
|
||||
`F4PGA-Yosys page <https://f4pga.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_.
|
||||
|
||||
.. note::
|
||||
The build files generated by the toolchain (for example .eblif from synthesis, .net from
|
||||
packing, .bit from generate bitstream) are named using the top module specified in
|
||||
symbiflow_synth. For example if you specified ``switch_top`` as the top level module name
|
||||
during synthesis using the ``-t`` flag, the build files generated by the toolchain would be
|
||||
named switch_top.eblif, switch_top.net, etc.
|
||||
|
||||
|
||||
Place and Route
|
||||
----------------
|
||||
|
||||
The three steps for implementing a design are internally handled by the open source VPR
|
||||
(Versatile Place and Route) tool. For more information go to
|
||||
`the F4PGA VPR page <https://f4pga.readthedocs.io/en/latest/vtr-verilog-to-routing/doc/src/vpr/index.html>`_.
|
||||
|
||||
Pack
|
||||
+++++
|
||||
|
||||
Packing is run by the ``symbiflow_pack`` command and generates several files containing
|
||||
a pin usage report, a timing report, a log file, and a netlist. The various flags for the
|
||||
pack command are as follows:
|
||||
|
||||
.. table:: symbiflow_pack
|
||||
|
||||
+------+--------------------------------------------------------------------+
|
||||
| Flag | Argument |
|
||||
+======+====================================================================+
|
||||
| -e | Path to .eblif file generated by synthesis |
|
||||
+------+--------------------------------------------------------------------+
|
||||
| -d | Fabric definition for the board (i.e. xc7a100t_test) |
|
||||
+------+--------------------------------------------------------------------+
|
||||
| -s | Optional: SDC file path |
|
||||
+------+--------------------------------------------------------------------+
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symbiflow_pack -e top.eblif -d xc7a35t_test
|
||||
|
||||
Place
|
||||
++++++
|
||||
|
||||
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
|
||||
|
||||
+------+----------------------------------------------------+
|
||||
| Flag | Argument |
|
||||
+======+====================================================+
|
||||
| -e | Path to .eblif file generated by synthesis |
|
||||
+------+----------------------------------------------------+
|
||||
| -d | Fabric definition (xc7a50t_test) |
|
||||
+------+----------------------------------------------------+
|
||||
| -p | Optional: PCF file path |
|
||||
+------+----------------------------------------------------+
|
||||
| -n | Path to the .net file generated by pack step |
|
||||
+------+----------------------------------------------------+
|
||||
| -P | The part number for the FPGA (i.e xc7a35tcsg324-1) |
|
||||
+------+----------------------------------------------------+
|
||||
| -s | Optional: SDC file path |
|
||||
+------+----------------------------------------------------+
|
||||
|
||||
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
|
||||
++++++
|
||||
|
||||
Routing produces several timing reports as well as a post routing netlist and log file.
|
||||
``symbiflow_route`` uses the -e, -d, and the optional -s flags. The arguments for these flags
|
||||
are the same as in the placement step (.eblif, fabric definition, and SDC file path respectively).
|
||||
The following is an example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symbiflow_route -e top.eblif -d xc7a35t_test -s design.sdc
|
||||
|
||||
|
||||
Generating Bitstream
|
||||
----------------------
|
||||
|
||||
Generating the bitstream consists of two steps. First, run ``symbiflow_write_fasm`` to generate
|
||||
the .fasm file used to create the bitstream. ``symbiflow_write_fasm`` uses the -e and -d flags
|
||||
with the same arguments as the placing and routing steps (.eblif path, and fabric definition).
|
||||
Second, run ``symbiflow_write_bitstream`` which has the following flags:
|
||||
|
||||
.. table:: symbiflow_write_bitstream
|
||||
|
||||
+------+-------------------------------------------------------+
|
||||
| Flag | Argument |
|
||||
+======+=======================================================+
|
||||
| -d | FPGA family (i.e. artix7 or zynq7) |
|
||||
+------+-------------------------------------------------------+
|
||||
| -f | The path to the .fasm file generated in by write_fasm |
|
||||
+------+-------------------------------------------------------+
|
||||
| -p | The FPGA part number (i.e xc7a35tcsg324-1) |
|
||||
+------+-------------------------------------------------------+
|
||||
| -b | Name of the file to write the bitstream to |
|
||||
+------+-------------------------------------------------------+
|
||||
|
||||
Notice that the specification for the part number is a lowercase ``-p`` instead of a capital
|
||||
``-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.
|
||||
|
||||
.. warning::
|
||||
|
||||
If you change the name of the output for your bitstream to something other than top.bit then the
|
||||
openFPGALoader command used in the examples would need to change too. For example if I used
|
||||
``-b my_module_top`` in symbiflow_write_bitstream then my openFPGALoader command would change to:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openFPGALoader -b $OFL_BOARD my_module_top.bit
|
||||
|
||||
Note that the only part of the command that changes is "<top module name>.bit;"
|
||||
|
||||
The following example generates a bitstream file named example.bit for the basys3 board:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symbiflow_write_fasm -e top.eblif -d xc7a50t_test
|
||||
symbiflow_write_bitstream -d artix7 -f top.fasm -p xc7a35tcpg236-1 -b example.bit
|
||||
Loading…
Reference in a new issue