From 7bb83ffeb3eb7420aa86ef0ee60a12c862d16abd Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 9 Aug 2022 16:49:49 +0200 Subject: [PATCH] docs/getting-started: update Signed-off-by: Unai Martinez-Corral --- docs/getting-started.rst | 139 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 129 insertions(+), 10 deletions(-) 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: