diff --git a/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml index a7481fb..83f266a 100644 --- a/.github/workflows/Pipeline.yml +++ b/.github/workflows/Pipeline.yml @@ -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/ diff --git a/README.md b/README.md index c8c507b..7d45a49 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,23 @@ -# FOSS Flows For FPGA (F4PGA) project -

+ +

+ +# FOSS Flows For FPGA (F4PGA) project + +

'Automerge' workflow status

-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) diff --git a/docs/changes.yml b/docs/changes.yml index 244728d..236747d 100644 --- a/docs/changes.yml +++ b/docs/changes.yml @@ -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. diff --git a/docs/conf.py b/docs/conf.py index 4411150..945f0e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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', '') } diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 47f332f..db1961b 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -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 ➚ `__ (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 ➚ `__ (for developers) +.. _GettingStarted:Guidelines: - * `F4PGA Architectures Visualizer ➚ `__ +Guidelines +========== - * `Project X-Ray ➚ `__ +This is the main documentation, which gathers info about the :ref:`Python CLI tools and APIs ` and the +:ref:`Desing Flows ` supported by F4PGA, along with a :ref:`Glossary`, references to specifications, plugins and +:ref:`publications `. - * `X-Ray Quickstart ➚ `__ +Since F4PGA is meant for users with varying backgrounds and expertise, three paths are provided to walk into the ecosystem. - * `Project Trellis ➚ `__ +**Newcomers** are invited to go through `Examples ➚ `__, which provides +step-by-step guidelines to install the tools through `Conda ➚ `__, 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 ➚ ` +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 `__ +in :gh:`hdl/packages` shows how to use the ``*/conda/f4pga/*`` containers from :gh:`hdl/containers` +(see `workflow runs `__ 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 ➚ `__) +should head to `Architecture Definitions ➚ `__. +The effort to document the details of each device/family are distributed on multiple projects: + +* `Project X-Ray ➚ `__ + + * `X-Ray Quickstart ➚ `__ + +* `Project Trellis ➚ `__ + +* :gh:`Project 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 ➚ `__, +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 ` +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 `__) + based on ``*/conda/f4pga/*`` containers. .. _GettingStarted:LoadingBitstreams: diff --git a/docs/glossary.rst b/docs/glossary.rst index b5f749d..7d2c4b8 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1,3 +1,5 @@ +.. _Glossary: + Glossary ######## diff --git a/docs/index.rst b/docs/index.rst index 37e697a..4ef3e12 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 ➚ `__, which is a Workgroup under the `CHIPS Alliance ➚ `__, 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 ➚ `): + + * :gh:`F4PGA Python CLI ➚ ` + * :gh:`F4PGA Architecture Definitions ➚ ` + * :gh:`F4PGA Examples ➚ ` + * :gh:`F4PGA Yosys 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 ➚ ` + * :gh:`FPGA Interchange Python utilities ➚ ` + * :gh:`FPGA Interchange Test suite ➚ ` + +* The :gh:`FPGA tool performance framework ➚ ` 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 ➚ ` + * :gh:`F4PGA database visualizer ➚ ` + +* Other utilities (FPGA assembly format, documentation and other): + + * :gh:`F4PGA Assembly (FASM) ➚ ` + * :gh:`Xilinx bitstream generation library ➚ ` + * :gh:`Verilog-to-routing XML utilities ➚ ` + * :gh:`SDF format utilities ➚ ` + * :gh:`F4PGA tools data manager ➚ ` + * :gh:`F4PGA Sphinx Theme ➚ ` + * :gh:`F4PGA Sphinx HDL diagrams ➚ ` + * :gh:`F4PGA 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) ➚ + FPGA Interchange schema ➚ .. toctree:: diff --git a/.github/scripts/activate.sh b/scripts/activate.sh similarity index 100% rename from .github/scripts/activate.sh rename to scripts/activate.sh diff --git a/.github/scripts/prepare_environment.sh b/scripts/prepare_environment.sh similarity index 100% rename from .github/scripts/prepare_environment.sh rename to scripts/prepare_environment.sh