Skip to content

Commit

Permalink
update 835a405
Browse files Browse the repository at this point in the history
  • Loading branch information
GitHub Actions authored and GitHub Actions committed Jul 25, 2023
0 parents commit ee9378e
Show file tree
Hide file tree
Showing 138 changed files with 31,992 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 3a9ef3d141e453497a9073aadc74952b
tags: 645f666f9bcd5a90fca523b33c5a78b7
Empty file added .nojekyll
Empty file.
3 changes: 3 additions & 0 deletions _images/EDA.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/flow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions _images/hero.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions _images/parts.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/step.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/tool.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
542 changes: 542 additions & 0 deletions _images/toolchain-flow.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
72 changes: 72 additions & 0 deletions _sources/community.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
.. _Community:

Community
#########

`FOSS Flows For FPGA (F4PGA) <https://f4pga.org>`__ project is a `Workgroup <https://chipsalliance.org/workgroups/>`__
under the `CHIPS Alliance <https://chipsalliance.com/>`__.
The F4PGA Workgroup consists of members from different backgrounds, including FPGA vendors
(`Xilinx <https://www.xilinx.com/>`__
and `QuickLogic <https://www.quicklogic.com/>`__),
industrial users
(`Google <https://www.google.com/>`__
and `Antmicro <https://antmicro.com/>`__)
and academia
(`University of Toronto <https://www.utoronto.ca/>`__),
who collaborate to build a more open source and software-driven FPGA ecosystem (IP, tools and workflows) to drive the
adoption of FPGAs in existing and new use cases, and eliminate barriers of entry.

Communication
=============

* `Twitter [@f4pga] <https://twitter.com/f4pga>`__

* `Slack [chipsalliance.slack.com] <https://chipsalliance.slack.com/>`__

.. TIP::
To register to CHIPS Alliance Slack workspace, use the following `Slack Invite <https://slack-invite.chipsalliance.org/>`__.

* `IRC [irc.libera.chat/#F4PGA] <https://kiwiirc.com/nextclient/#irc://irc.libera.chat/#F4PGA>`__

* `Mailing list [lists.chipsalliance.org/g/f4pga-wg] <https://lists.chipsalliance.org/g/f4pga-wg>`__

Sources
=======

* :gh:`github.com/chipsalliance <chipsalliance/?q=f4pga>`

* :gh:`github.com/F4PGA <F4PGA>`

.. _Contributing:

Contributing
============

Are you interested in helping this project move forward?
F4PGA is a collaborative project and we welcome your contributions.
The code is available on GitHub, while the HTML documentation is available on Read The Docs.
There are multiple areas and technologies we need help with - reach out to us, we're sure we will find something for you.

* Do you know **Python**?
Almost all scripts are written in Python!

* Do you know **C++**?
VPR & nextpnr & libraries written in C++!

* Do you know **TCL**?
All the EDA tools use TCL!

* Do you know **(System) Verilog**, **VHDL**, **Chisel**, **Migen** and/or **Amaranth**?
Simulation and models are written in Hardware Description Languages (HDLs)!

* Do you know **XML**?
Most file formats are XML!

* Do you know English?
Documentation is written in English!

* Do you know **Docker** and/or **Podman**?
Help make it easier to set up F4PGA!

* Do you have time?
We will find you a task!
15 changes: 15 additions & 0 deletions _sources/development/building-docs.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
Building the documentation
##########################

Activate the virtual environment and install dependencies::

make env
make enter

Build the whole documentation::

make html

For more options see::

make help
4 changes: 4 additions & 0 deletions _sources/development/changes.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Changes
#######

.. include:: changes.inc
10 changes: 10 additions & 0 deletions _sources/development/venv.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Packages in virtual environment
###############################

To install packages in conda environment you can use both
``conda`` and ``pip``.

Note that ``pip`` is installed in the conda environment which uses ``python3``,
and is related to ``pip3`` **inside** the virtual environment,
whereas invocation of ``pip3`` directly uses your **system** ``pip3`` instance,
typically located in ``/usr/bin/pip3``
194 changes: 194 additions & 0 deletions _sources/f4pga/Deprecated.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
.. _Understanding:

Understanding the (deprecated) flow
###################################

.. IMPORTANT::
This section describes the usage of the now deprecated ``symbiflow_*`` entrypoints/wrappers.
It is provided for backwards compatibility, so that users of the *old* flow can keep using it.
However, it is recommended for new users to use the approach explained in :ref:`pyF4PGA`.

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 :ref:`Design Flows section <Flows>`.

.. 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 :ref:`Flows:F4PGA:Yosys`.

.. 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 `VPR ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>`__.

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

0 comments on commit ee9378e

Please sign in to comment.