<h1id="getting-started--page-root">Getting started<aclass="headerlink"href="#getting-started--page-root"title="Link to this heading">¶</a></h1>
<p>To begin using F4PGA, you might want to take a look at the <aclass="reference internal"href="#gettingstarted-guidelines"><spanclass="std std-ref">Guidelines</span></a> 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.</p>
<p>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 <aclass="reference internal"href="#gettingstarted-toolchaininstallation"><spanclass="std std-ref">Toolchain installation</span></a> below.</p>
<sectionid="guidelines">
<spanid="gettingstarted-guidelines"></span><h2id="guidelines">Guidelines<aclass="headerlink"href="#guidelines"title="Link to this heading">¶</a></h2>
<p>This is the main documentation, which gathers info about the <aclass="reference internal"href="f4pga/index.html#pyf4pga"><spanclass="std std-ref">Python CLI tools and APIs</span></a> and the
<aclass="reference internal"href="flows/index.html#flows"><spanclass="std std-ref">Design Flows</span></a> supported by F4PGA, along with a <aclass="reference internal"href="glossary.html#glossary"><spanclass="std std-ref">Glossary</span></a>, references to specifications, plugins and
<p>Since F4PGA is meant for users with varying backgrounds and expertise, three paths are provided to walk into the ecosystem.</p>
<p><strong>Newcomers</strong> are invited to go through <aclass="reference external"href="https://f4pga-examples.readthedocs.io">Examples ➚</a>, which provides
step-by-step guidelines to install the tools through <aclass="reference external"href="https://conda.io">Conda ➚</a>, generate a bitstream from one of the
provided designs and load the bitstream into a development board.
See <aclass="reference external"href="https://f4pga-examples.readthedocs.io/en/latest/customizing-makefiles.html#customizingmakefiles"title="(in F4PGA examples)"><span>Customizing the Makefiles</span></a> for adapting the build plumbing to your own desings.</p>
<p>For <strong>Intermediate</strong> users and contributors, who are already familiar with installing the tools and building bitstreams,
it is recommended to read the shell scripts in subdir <aclass="extlink-ghsrc reference external"href="https://github.com/chipsalliance/f4pga/blob/main/scripts">scripts</a>, as well as the Continuous Integration
in <aclass="extlink-gh reference external"href="https://github.com/hdl/packages">gh:hdl/packages</a> shows how to use the <codeclass="docutils literal notranslate"><spanclass="pre">*/conda/f4pga/*</span></code> containers from <aclass="extlink-gh reference external"href="https://github.com/hdl/containers">gh:hdl/containers</a>
(see <aclass="reference external"href="https://github.com/hdl/packages/actions/workflows/containers-conda-f4pga.yml">workflow runs</a> and
<spanid="gettingstarted-toolchaininstallation"></span><h2id="toolchain-installation">Toolchain installation<aclass="headerlink"href="#toolchain-installation"title="Link to this heading">¶</a></h2>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">apt</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">dnf</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">pacman</span></code>, 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 <aclass="reference external"href="https://conda.io">Conda ➚</a>,
or some other pre-packaged solution combining latest releases.</p>
<sectionid="conda-recommended">
<spanid="gettingstarted-toolchaininstallation-conda"></span><h3id="conda-recommended">Conda (Recommended)<aclass="headerlink"href="#conda-recommended"title="Link to this heading">¶</a></h3>
<divclass="admonition important">
<pclass="admonition-title">Important</p>
<p>Due 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.</p>
</div>
<p>In coherence with the <aclass="reference internal"href="#gettingstarted-guidelines"><spanclass="std std-ref">Guidelines</span></a> above, multiple Conda environments are provided:</p>
<ulclass="simple">
<li><p><strong>Newcomers</strong> will find environment and requirements files in <aclass="extlink-gh reference external"href="https://github.com/chipsalliance/f4pga-examples">gh:chipsalliance/f4pga-examples</a>, which are to be used
as explained in <aclass="reference external"href="https://f4pga-examples.readthedocs.io/en/latest/getting.html#getting"title="(in F4PGA examples)"><span>Getting F4PGA</span></a>.</p></li>
<li><p><strong>Intermediate</strong> 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.</p></li>
<li><p><strong>Advanced</strong> users and developers will get all the dependencies by bootstraping the environment in <aclass="extlink-gh reference external"href="https://github.com/SymbiFlow/f4pga-arch-defs">gh:SymbiFlow/f4pga-arch-defs</a>.</p></li>
</ul>
<p>Summarizing, the installation procedure implies:</p>
<ulclass="simple">
<li><p>Setting environment variables <codeclass="docutils literal notranslate"><spanclass="pre">F4PGA_INSTALL_DIR</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">F4PGA_FAM</span></code> (and optionally <codeclass="docutils literal notranslate"><spanclass="pre">F4PGA_SHARE_DIR</span></code>), so that
CLI utilities can find tools and assets.</p></li>
<li><p>Downloading and extracting the Architecture Definition tarballs.</p></li>
<li><p>Getting the environment and requirements files, by cloning f4pga-examples or f4pga-arch-defs, or by using the ones
included in the tarballs.</p></li>
<li><p>Bootstraping the Conda environment and optionally installing additional tools.</p></li>
</ul>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Architecture Definition packages are built and released in <aclass="extlink-gh reference external"href="https://github.com/SymbiFlow/f4pga-arch-defs">gh:SymbiFlow/f4pga-arch-defs</a>.
In this repository and in <aclass="extlink-gh reference external"href="https://github.com/chipsalliance/f4pga-examples">gh:chipsalliance/f4pga-examples</a>, pinned versions of the packages are used.
However, tracking the <em>latest</em> release is also supported.
See <aclass="reference external"href="https://f4pga.readthedocs.io/projects/arch-defs/en/latest/packages.html#packages"title="(in F4PGA Architecture Definitions vlatest)"><span>Pre-built architecture files</span></a>.</p>
</div>
<sectionid="bumping-overriding-specific-tools">
<spanid="gettingstarted-toolchaininstallation-conda-bumping"></span><h4id="bumping-overriding-specific-tools">Bumping/overriding specific tools<aclass="headerlink"href="#bumping-overriding-specific-tools"title="Link to this heading">¶</a></h4>
<p>Find guidelines to tweak the Conda environment and to override specific tools at <aclass="reference external"href="https://hdl.github.io/conda-eda/Usage.html#usage-bumping"title="(in Conda recipes for FPGA EDA tools vlatest)"><span>Bumping/overriding specific tools</span></a>.</p>
<p>In order to bump the Architecture Definition packages to an specific version, check the TIMESTAMP and the commit hash in
the job named <codeclass="docutils literal notranslate"><spanclass="pre">GCS</span></code> in a successful run of workflow <aclass="extlink-gh reference external"href="https://github.com/SymbiFlow/f4pga-arch-defs/actions/workflows/Automerge.yml">Automerge</a>
on branch <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> of <aclass="extlink-gh reference external"href="https://github.com/SymbiFlow/f4pga-arch-defs">gh:SymbiFlow/f4pga-arch-defs</a>.
Alternatively, use the latest as explained in <aclass="reference external"href="https://f4pga.readthedocs.io/projects/arch-defs/en/latest/packages.html#packages"title="(in F4PGA Architecture Definitions vlatest)"><span>Pre-built architecture files</span></a>.</p>
</section>
</section>
<sectionid="other">
<spanid="gettingstarted-toolchaininstallation-other"></span><h3id="other">Other<aclass="headerlink"href="#other"title="Link to this heading">¶</a></h3>
<p>Apart from Conda, multiple other solutions exist for setting up all the tools required in F4PGA.
<aclass="extlink-gh reference external"href="https://github.com/hdl/packages">gh:hdl/packages</a><em>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</em>.</p>
<sectionid="containers">
<spanid="gettingstarted-toolchaininstallation-other-containers"></span><h4id="containers">Containers<aclass="headerlink"href="#containers"title="Link to this heading">¶</a></h4>
<p>Ready-to-use docker/podman containers are maintained in <aclass="extlink-gh reference external"href="https://github.com/hdl/containers">gh:hdl/containers</a> and made available through
<cite>gcr.io/hdl-containers</cite> or <cite>ghcr.io/hdl/containers</cite>.
Some of those include Conda, the Architecture Definitions and the f4pga Python package, so they are ready to use along
with the examples in <aclass="extlink-gh reference external"href="https://github.com/chipsalliance/f4pga-examples">gh:chipsalliance/f4pga-examples</a>.
See <aclass="reference external"href="https://hdl.github.io/containers/ToolsAndImages.html#tools-and-images-f4pga"title="(in HDL Containers: Building and deploying container images for open source Electronic Design Automation vlatest)"><span>F4PGA (Conda)</span></a>.</p>
<divclass="admonition hint">
<pclass="admonition-title">Hint</p>
<p><aclass="extlink-ghsharp reference external"href="https://github.com/chipsalliance/f4pga/issues/574">#574</a> is work in progress to provide an F4PGA Action
(see <aclass="reference external"href="https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions">Understanding GitHub Actions</a>)
based on <codeclass="docutils literal notranslate"><spanclass="pre">*/conda/f4pga/*</span></code> containers.</p>
</div>
</section>
</section>
</section>
<sectionid="loading-bitstreams">
<spanid="gettingstarted-loadingbitstreams"></span><h2id="loading-bitstreams">Loading bitstreams<aclass="headerlink"href="#loading-bitstreams"title="Link to this heading">¶</a></h2>
<p>For every board, the loading process may vary and different tools may be required.
Typically, each tool supports a specific target family or the lines of products of a vendor.
Some of the most known are listed in <aclass="reference external"href="https://hdl.github.io/constraints/ProgDebug.html#progdebug"title="(in FPGA Board Constraints vlatest)"><spanclass="xref std std-ref">hdl/constraints: Programming and debugging</span></a>.
The tools used in the F4PGA Toolchain are e.g. <codeclass="docutils literal notranslate"><spanclass="pre">OpenOCD</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">tinyfpgab</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">tinyprog</span></code>.
Moreover, <aclass="extlink-gh reference external"href="https://github.com/trabucayre/openFPGALoader">OpenFPGALoader</a> is a universal utility for programming FPGA devices, which is
becoming an alternative to the fragmentation in bitstream loading tools.
OpenFPGALoader supports many different boards with FPGAs based on the architectures including xc7, ECP5, iCE40 and many
more.
It can utilize a variety of the programming adapters based on JTAG, DAP interface, ORBTrace, DFU and FTDI chips.</p>
<sectionid="installing-openfpgaloader">
<h3id="installing-openfpgaloader">Installing OpenFPGALoader<aclass="headerlink"href="#installing-openfpgaloader"title="Link to this heading">¶</a></h3>
<p>OpenFPGALoader is available in several packaging solutions.
It can be installed with distribution specific package managers on Arch Linux and Fedora.
There are also prebuilt packages available in <aclass="reference external"href="https://anaconda.org/litex-hub/openfpgaloader">conda</a>
or packages in tool <aclass="extlink-gh reference external"href="https://github.com/trabucayre/openFPGALoader/releases">repository</a>.
OpenFPGALoader can also be built from sources.
For installation guidelines using both prebuilt packages and building from source, please refer to instructions in
<p>If you encounter any issues, please refer to <aclass="reference external"href="https://trabucayre.github.io/openFPGALoader/index.html"title="(in openFPGALoader: universal utility for programming FPGA vlatest)"><span>openFPGALoader: universal utility for programming FPGA</span></a>.</p>
