docs/getting-started: update
Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral
parent
5208674f58
commit
7bb83ffeb3
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue