docs: update (#588)

This commit is contained in:
Unai Martinez-Corral 2022-08-11 16:12:12 +02:00 committed by GitHub
commit 60204c0760
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 199 additions and 70 deletions

View File

@ -107,11 +107,11 @@ jobs:
uses: actions/checkout@v3
- name: 🔧 Prepare environment
run: ./.github/scripts/prepare_environment.sh
run: ./scripts/prepare_environment.sh
- name: 🐍 Install f4pga (pip)
run: |
. ./.github/scripts/activate.sh
. ./scripts/activate.sh
cd f4pga
pip install .
cd ..
@ -124,7 +124,7 @@ jobs:
- name: 🚧 [F4PGA] Test f4pga build
if: matrix.flow == 'F4PGA'
run: |
. ./.github/scripts/activate.sh
. ./scripts/activate.sh
cd f4pga-examples/${{ matrix.fam }}
f4pga -vv build --flow ../../.github/${{ matrix.fam }}_test.json
@ -141,7 +141,7 @@ jobs:
- name: 🚧 [SymbiFlow] Test make example
if: matrix.flow == 'SymbiFlow'
run: |
. ./.github/scripts/activate.sh
. ./scripts/activate.sh
cd f4pga-examples/${{ matrix.fam }}
export F4PGA_USE_DEPRECATED=true
case '${{ matrix.fam }}' in
@ -179,18 +179,18 @@ jobs:
uses: actions/checkout@v3
- name: 🔧 Prepare environment
run: ./.github/scripts/prepare_environment.sh
run: ./scripts/prepare_environment.sh
- name: 🐍 Install f4pga (pip)
run: |
. ./.github/scripts/activate.sh
. ./scripts/activate.sh
cd f4pga
pip install .
cd ..
- name: 🚦 Test Python wrappers
run: |
. ./.github/scripts/activate.sh
. ./scripts/activate.sh
pip3 install -r ./test/requirements.txt
pytest --verbose --capture=no -rA --color=yes test/

View File

@ -1,58 +1,23 @@
# FOSS Flows For FPGA (F4PGA) project
<p align="center">
<a title="Website" href="https://f4pga.org"><img src="https://img.shields.io/website?longCache=true&style=flat-square&label=f4pga.org&up_color=10cfc9&url=https%3A%2F%2Ff4pga.org%2Findex.html&labelColor=fff"></a><!--
-->
<a title="Documentation" href="https://f4pga.readthedocs.io"><img src="https://img.shields.io/website?longCache=true&style=flat-square&label=Documentation&up_color=1226aa&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff"></a><!--
-->
<a title="Community" href="https://f4pga.readthedocs.io/en/latest/community.html#communication"><img src="https://img.shields.io/badge/Chat-IRC%20%7C%20Slack-white?longCache=true&style=flat-square&logo=Slack&logoColor=fff"></a><!--
-->
</p>
# FOSS Flows For FPGA (F4PGA) project
<p align="center">
<a title="'Automerge' workflow status" href="https://github.com/chipsalliance/f4pga/actions/workflows/Doc.yml"><img alt="'Automerge' workflow status" src="https://img.shields.io/github/workflow/status/chipsalliance/f4pga/Automerge/main?longCache=true&style=flat-square&label=Tests&logo=Github%20Actions&logoColor=fff"></a><!--
-->
</p>
This is the top-level repository for the [F4PGA](https://f4pga.org/) project, which is a Workgroup under the [CHIPS Alliance](https://chipsalliance.org).
The elements of the project include (but are not limited to):
* The F4PGA open source FPGA toolchains for programming FPGAs (formerly known as [SymbiFlow](https://github.com/SymbiFlow)).
This includes:
* [![Documentation](https://img.shields.io/website?longCache=true&style=flat-square&label=Documentation&up_color=1226aa&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga.readthedocs.io)
* F4PGA Architecture Definitions [![Arch-Defs (for Developers)](https://img.shields.io/website?longCache=true&style=flat-square&label=For%20Developers&up_color=231f20&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fprojects%2Farch-defs%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga.readthedocs.io/projects/arch-defs)
* F4PGA Examples [![Examples (for Users)](https://img.shields.io/website?longCache=true&style=flat-square&label=For%20Users&up_color=231f20&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga-examples.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga-examples.readthedocs.io)
* [F4PGA Yosys plugins](https://github.com/chipsalliance/yosys-f4pga-plugins)
* The FPGA interchange format (an interchange format defined by CHIPS Alliance to enable interoperability between
different FPGA tools) adopted by the F4PGA toolchain:
* [FPGA Interchange schema](https://github.com/chipsalliance/fpga-interchange-schema)
* [FPGA Interchange Python utilities](https://github.com/chipsalliance/python-fpga-interchange)
* [FPGA Interchange Test suite](https://github.com/SymbiFlow/fpga-interchange-tests)
* The [FPGA tool performance framework](https://github.com/chipsalliance/fpga-tool-perf) framework for benchmarking
designs against various FPGA tools, and vice versa, over time.
* FPGA Database visualisation tools for visual exploration of FPGA bitstream and databases:
* [F4PGA bitstream viewer](https://github.com/SymbiFlow/f4pga-bitstream-viewer)
* [F4PGA database visualizer](https://github.com/chipsalliance/f4pga-database-visualizer)
* Other utilities (FPGA assembly format, documentation and other):
* [F4PGA Assembly (FASM)](https://github.com/chipsalliance/fasm)
* [Xilinx bitstream generation library](https://github.com/SymbiFlow/f4pga-xc-fasm)
* [Verilog-to-routing XML utilities](https://github.com/SymbiFlow/vtr-xml-utils)
* [SDF format utilities](https://github.com/chipsalliance/python-sdf-timing)
* [F4PGA tools data manager](https://github.com/SymbiFlow/symbiflow-tools-data-manager)
* [F4PGA Sphinx Theme](https://github.com/SymbiFlow/sphinx_symbiflow_theme)
* [F4PGA Sphinx HDL diagrams](https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams)
* [F4PGA Sphinx Verilog domain](https://github.com/SymbiFlow/sphinx-verilog-domain)
## F4PGA Workgroup
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/), [Antmicro](https://antmicro.com/))
and academia
([University of Toronto](https://www.utoronto.ca/)),
This is the top-level repository for the [F4PGA](https://f4pga.org/) project, which is a Workgroup under the [CHIPS Alliance](https://chipsalliance.org); consisting of members from different backgrounds, including FPGA vendors, industrial users and academia (see [Documentation > Community](https://f4pga.readthedocs.io/en/latest/community.html));
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.
* [Documentation > Getting started](https://f4pga.readthedocs.io) (for everyone)
* [F4PGA Examples](https://f4pga-examples.readthedocs.io) (for users)
* [F4PGA Architecture Definitions](https://f4pga.readthedocs.io/projects/arch-defs) (for developers)

View File

@ -37,7 +37,7 @@
- symbiflow-ql-eos-s3_wlcsp-*-tar-xz
description: |
* Tarballs from f4pga-arch-defs now include usable environment and requirements files which allow bootstraping
minimal Conda environments.
minimal Conda environments.
* The default F4PGA_SHARE_DIR path does not include subdir 'install' by default.

View File

@ -171,8 +171,11 @@ man_pages = [
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"examples": ("https://f4pga-examples.readthedocs.io/en/latest/", None),
"arch-defs": ("https://f4pga.readthedocs.io/projects/arch-defs/en/latest/", None),
"conda-eda": ("https://hdl.github.io/conda-eda/", None),
"constraints": ("https://hdl.github.io/constraints/", None),
"containers": ("https://hdl.github.io/containers/", None),
"fasm": ("https://fasm.readthedocs.io/en/latest/", None),
"interchange": ("https://fpga-interchange-schema.readthedocs.io/", None),
"openfpgaloader": ("https://trabucayre.github.io/openFPGALoader/", None),
@ -189,5 +192,5 @@ extlinks = {
'ghsharp': ('https://github.com/chipsalliance/f4pga/issues/%s', '#'),
'ghissue': ('https://github.com/chipsalliance/f4pga/issues/%s', 'issue #'),
'ghpull': ('https://github.com/chipsalliance/f4pga/pull/%s', 'pull request #'),
'ghsrc': ('https://github.com/chipsalliance/f4pga/blob/master/%s', '')
'ghsrc': ('https://github.com/chipsalliance/f4pga/blob/main/%s', '')
}

View File

@ -1,23 +1,142 @@
Getting started
###############
To begin using F4PGA, you might want to take a look at the tutorials below, which make for a good starting point.
They will guide you through the process of using the toolchain, explaining how to generate and load a bitstream into
your FPGA.
To begin using F4PGA, you might want to take a look at the :ref:`GettingStarted:Guidelines` below, which make for a good
starting point.
They will guide you through the process of installing and using the flows, explaining how to generate and load a
bitstream into your FPGA.
* `Examples ➚ <https://f4pga-examples.readthedocs.io>`__ (for users)
F4PGA flows are composed of multiple tools, scripts and CLI utilities.
Fortunately, various alternatives exist for setting up the whole ecosystem without going through the daunting task of
installing pieces one-by-one.
See :ref:`GettingStarted:ToolchainInstallation` below.
* `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>`__ (for developers)
.. _GettingStarted:Guidelines:
* `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__
Guidelines
==========
* `Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>`__
This is the main documentation, which gathers info about the :ref:`Python CLI tools and APIs <pyF4PGA>` and the
:ref:`Desing Flows <Flows>` supported by F4PGA, along with a :ref:`Glossary`, references to specifications, plugins and
:ref:`publications <References>`.
* `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
Since F4PGA is meant for users with varying backgrounds and expertise, three paths are provided to walk into the ecosystem.
* `Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>`__
**Newcomers** are invited to go through `Examples ➚ <https://f4pga-examples.readthedocs.io>`__, which provides
step-by-step guidelines to install the tools through `Conda ➚ <https://conda.io>`__, generate a bitstream from one of the
provided designs and load the bitstream into a development board.
See :ref:`examples:CustomizingMakefiles` for adapting the build plumbing to your own desings.
* :gh:`Project Icestorm ➚ <f4pga/icestorm>`
For **Intermediate** users and contributors, who are already familiar with installing the tools and building bitstreams,
it is recommended to read the shell scripts in subdir :ghsrc:`scripts`, as well as the Continuous Integration
:ghsrc:`Pipeline <.github/workflows/Pipeline.yml>`.
Moreover, workflow `containers-conda-f4pga.yml <https://github.com/hdl/packages/blob/main/.github/workflows/containers-conda-f4pga.yml>`__
in :gh:`hdl/packages` shows how to use the ``*/conda/f4pga/*`` containers from :gh:`hdl/containers`
(see `workflow runs <https://github.com/hdl/packages/actions/workflows/containers-conda-f4pga.yml>`__ and
:ref:`GettingStarted:ToolchainInstallation:Other:Containers`).
**Advanced** users and developers willing to support new devices and/or enhance the features of the supported families
(see `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__)
should head to `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs>`__.
The effort to document the details of each device/family are distributed on multiple projects:
* `Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>`__
* `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
* `Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>`__
* :gh:`Project Icestorm ➚ <f4pga/icestorm>`
.. _GettingStarted:ToolchainInstallation:
Toolchain installation
======================
F4PGA flows require multiple radpidly moving tools, assets and scripts, which makes it difficult for system packagers to
catch up.
Although some of the tools used in F4PGA (such as yosys, nextpnr or vpr) are available already through ``apt``, ``dnf``,
``pacman``, etc. they typically use pinned versions which are not the latest.
Therefore, the recommended installation procedure to follow the guidelines in F4PGA is repositories is using `Conda ➚ <https://conda.io>`__,
or some other pre-packaged solution combining latest releases.
.. _GettingStarted:ToolchainInstallation:Conda:
Conda (Recommended)
-------------------
.. IMPORTANT::
Dure to size constraints, Architecture Definition packages cannot be distributed through Conda.
Hence, installing a functional F4PGA system is a two step process: bootstraping the conda environment and getting the
tarballs (or vice versa).
In the future, getting and managing the tarballs might be handled by F4PGA.
In coherence with the :ref:`GettingStarted:Guidelines` above, multiple Conda environments are provided:
* **Newcomers** will find environment and requirements files in :gh:`chipsalliance/f4pga-examples`, which are to be used
as explained in :ref:`examples:Getting`.
* **Intermediate** users and contributors can use the minimal environment and requirements files included in the
Architecture Definition packages, as is done in the CI of this repository.
* **Advanced** users and developers will get all the dependencies by bootstraping the environment in :gh:`SymbiFlow/f4pga-arch-defs`.
Summarizing, the installation procedure implies:
* Setting environment variables ``F4PGA_INSTALL_DIR`` and ``F4PGA_FAM`` (and optionally ``F4PGA_SHARE_DIR``), so that
CLI utilities can find tools and assets.
* Downloading and extracting the Architecture Definition tarballs.
* Getting the environment and requirements files, by cloning f4pga-examples or f4pga-arch-defs, or by using the ones
included in the tarballs.
* Bootstraping the Conda environment and optionally installing additional tools.
.. NOTE::
Architecture Definition packages are built and released in :gh:`SymbiFlow/f4pga-arch-defs`.
In this repository and in :gh:`chipsalliance/f4pga-examples`, pinned versions of the packages are used.
However, tracking the *latest* release is also supported.
See :ref:`arch-defs:Packages`.
.. _GettingStarted:ToolchainInstallation:Conda:Bumping:
Bumping/overriding specific tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Find guidelines to tweak the Conda environment and to override specific tools at :ref:`conda-eda:Usage:Bumping`.
In order to bump the Architecture Definition packages to an specific version, check the TIMESTAMP and the commit hash in
the job named ``GCS`` in a successful run of workflow :gh:`Automerge <SymbiFlow/f4pga-arch-defs/actions/workflows/Automerge.yml>`
on branch ``main`` of :gh:`SymbiFlow/f4pga-arch-defs`.
Alternatively, use the latest as explained in :ref:`arch-defs:Packages`.
.. _GettingStarted:ToolchainInstallation:Other:
Other
-----
Apart from Conda, multiple other solutions exist for setting up all the tools required in F4PGA.
:gh:`hdl/packages` *is an index for several projects providing great prepackaged/prebuilt and easy-to-set-up
bleeding-edge packages/environments of electronic design automation (EDA) tools/projects*.
.. _GettingStarted:ToolchainInstallation:Other:Containers:
Containers
~~~~~~~~~~
Ready-to-use docker/podman containers are maintained in :gh:`hdl/containers` and made available through
`gcr.io/hdl-containers` or `ghcr.io/hdl/containers`.
Some of those include Conda, the Architecture Definitions and the f4pga Python package, so they are ready to use along
with the examples in :gh:`chipsalliance/f4pga-examples`.
See :ref:`containers:tools-and-images:f4pga`.
.. HINT::
:ghsharp:`574` is work in progress to provide an F4PGA Action
(see `Understanding GitHub Actions <https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions>`__)
based on ``*/conda/f4pga/*`` containers.
.. _GettingStarted:LoadingBitstreams:

View File

@ -1,3 +1,5 @@
.. _Glossary:
Glossary
########

View File

@ -1,22 +1,61 @@
FOSS Flows For FPGA
###################
F4PGA is an Open Source solution for Hardware Description Language (HDL) to Bitstream FPGA synthesis, currently
targeting Xilinx 7-Series, Lattice iCE40 and Lattice ECP5 FPGAs.
`F4PGA ➚ <https://f4pga.org/>`__, which is a Workgroup under the `CHIPS Alliance ➚ <https://chipsalliance.org>`__, is an
Open Source solution for Hardware Description Language (HDL) to Bitstream FPGA synthesis, currently targeting
Xilinx's 7-Series, QuickLogic's EOS-S3, and Lattice' iCE40 and ECP5 devices.
Think of it as the GCC of FPGAs.
The project aims to design tools that are highly extendable and multiplatform.
.. image:: _static/images/hero.svg
:align: center
The elements of the project include (but are not limited to):
* The F4PGA open source FPGA toolchains for programming FPGAs (formerly known as :gh:`SymbiFlow ➚ <https://github.com/SymbiFlow>`):
* :gh:`F4PGA Python CLI ➚ <chipsalliance/f4pga/tree/main/f4pga>`
* :gh:`F4PGA Architecture Definitions ➚ <SymbiFlow/f4pga-arch-defs>`
* :gh:`F4PGA Examples ➚ <chipsalliance/f4pga-examples>`
* :gh:`F4PGA Yosys plugins ➚ <chipsalliance/yosys-f4pga-plugins>`
* The FPGA interchange format (an interchange format defined by CHIPS Alliance to enable interoperability between
different FPGA tools) adopted by the F4PGA toolchain:
* :gh:`FPGA Interchange schema ➚ <chipsalliance/fpga-interchange-schema>`
* :gh:`FPGA Interchange Python utilities ➚ <chipsalliance/python-fpga-interchange>`
* :gh:`FPGA Interchange Test suite ➚ <SymbiFlow/fpga-interchange-tests>`
* The :gh:`FPGA tool performance framework ➚ <chipsalliance/fpga-tool-perf>` framework for benchmarking
designs against various FPGA tools, and vice versa, over time.
* FPGA visualisation tools for visual exploration of FPGA bitstream and databases:
* :gh:`F4PGA bitstream viewer ➚ <SymbiFlow/f4pga-bitstream-viewer>`
* :gh:`F4PGA database visualizer ➚ <chipsalliance/f4pga-database-visualizer>`
* Other utilities (FPGA assembly format, documentation and other):
* :gh:`F4PGA Assembly (FASM) ➚ <chipsalliance/fasm>`
* :gh:`Xilinx bitstream generation library ➚ <SymbiFlow/f4pga-xc-fasm>`
* :gh:`Verilog-to-routing XML utilities ➚ <SymbiFlow/vtr-xml-utils>`
* :gh:`SDF format utilities ➚ <chipsalliance/python-sdf-timing>`
* :gh:`F4PGA tools data manager ➚ <SymbiFlow/symbiflow-tools-data-manager>`
* :gh:`F4PGA Sphinx Theme ➚ <SymbiFlow/sphinx_symbiflow_theme>`
* :gh:`F4PGA Sphinx HDL diagrams ➚ <SymbiFlow/sphinxcontrib-hdl-diagrams>`
* :gh:`F4PGA Sphinx Verilog domain ➚ <SymbiFlow/sphinx-verilog-domain>`
Table of Contents
=================
.. toctree::
:caption: About F4PGA
community
getting-started
how
status
getting-started
community
.. toctree::
@ -52,6 +91,7 @@ The project aims to design tools that are highly extendable and multiplatform.
:caption: Specifications
FPGA Assembly (FASM) ➚ <https://fasm.readthedocs.io/en/latest/>
FPGA Interchange schema ➚ <https://chipsalliance/fpga-interchange-schema>
.. toctree::