687 lines
34 KiB
HTML
687 lines
34 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="./">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
||
<meta name="lang:clipboard.copy" content="Copy to clipboard">
|
||
<meta name="lang:clipboard.copied" content="Copied to clipboard">
|
||
<meta name="lang:search.language" content="en">
|
||
<meta name="lang:search.pipeline.stopwords" content="True">
|
||
<meta name="lang:search.pipeline.trimmer" content="True">
|
||
<meta name="lang:search.result.none" content="No matching documents">
|
||
<meta name="lang:search.result.one" content="1 matching document">
|
||
<meta name="lang:search.result.other" content="# matching documents">
|
||
<meta name="lang:search.tokenizer" content="[\s\-]+">
|
||
|
||
|
||
<link href="https://fonts.gstatic.com/" rel="preconnect" crossorigin>
|
||
<link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:300,400,400i,700&display=fallback" rel="stylesheet">
|
||
|
||
<style>
|
||
body,
|
||
input {
|
||
font-family: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif
|
||
}
|
||
|
||
code,
|
||
kbd,
|
||
pre {
|
||
font-family: "Roboto Mono", "Courier New", Courier, monospace
|
||
}
|
||
</style>
|
||
|
||
|
||
<link rel="stylesheet" href="_static/stylesheets/application.css"/>
|
||
<link rel="stylesheet" href="_static/stylesheets/application-palette.css"/>
|
||
<link rel="stylesheet" href="_static/stylesheets/application-fixes.css"/>
|
||
<link rel="stylesheet" href="_static/stylesheets/f4pga.css"/>
|
||
|
||
<link rel="stylesheet" href="_static/fonts/material-icons.css"/>
|
||
|
||
<meta name="theme-color" content="#3f51b5">
|
||
<script src="_static/javascripts/modernizr.js"></script>
|
||
|
||
|
||
|
||
<title>Getting started — F4PGA documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
|
||
<link rel="stylesheet" type="text/css" href="_static/material.css?v=79c92029" />
|
||
<script src="_static/documentation_options.js?v=5929fcd5"></script>
|
||
<script src="_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<link rel="icon" href="_static/favicon.svg"/>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="How it works" href="how.html" />
|
||
<link rel="prev" title="FOSS Flows For FPGA" href="index.html" />
|
||
|
||
|
||
|
||
</head>
|
||
<body dir=ltr
|
||
data-md-color-primary=indigo data-md-color-accent=blue>
|
||
|
||
<svg class="md-svg">
|
||
<defs data-children-count="0">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="416" height="448" viewBox="0 0 416 448" id="__github"><path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19T128 352t-18.125-8.5-10.75-19T96 304t3.125-20.5 10.75-19T128 256t18.125 8.5 10.75 19T160 304zm160 0q0 10-3.125 20.5t-10.75 19T288 352t-18.125-8.5-10.75-19T256 304t3.125-20.5 10.75-19T288 256t18.125 8.5 10.75 19T320 304zm40 0q0-30-17.25-51T296 232q-10.25 0-48.75 5.25Q229.5 240 208 240t-39.25-2.75Q130.75 232 120 232q-29.5 0-46.75 21T56 304q0 22 8 38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0 37.25-1.75t35-7.375 30.5-15 20.25-25.75T360 304zm56-44q0 51.75-15.25 82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5T212 416q-19.5 0-35.5-.75t-36.875-3.125-38.125-7.5-34.25-12.875T37 371.5t-21.5-28.75Q0 312 0 260q0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25 30.875Q171.5 96 212 96q37 0 70 8 26.25-20.5 46.75-30.25T376 64q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34 99.5z"/></svg>
|
||
|
||
</defs>
|
||
</svg>
|
||
|
||
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer">
|
||
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search">
|
||
<label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
|
||
<a href="#getting-started" tabindex="1" class="md-skip"> Skip to content </a>
|
||
<header class="md-header" data-md-component="header">
|
||
<nav class="md-header-nav md-grid">
|
||
<div class="md-flex navheader">
|
||
<div class="md-flex__cell md-flex__cell--shrink">
|
||
<a href="index.html" title="F4PGA documentation"
|
||
class="md-header-nav__button md-logo">
|
||
|
||
|
||
|
||
</a>
|
||
</div>
|
||
<div class="md-flex__cell md-flex__cell--shrink">
|
||
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
|
||
</div>
|
||
<div class="md-flex__cell md-flex__cell--stretch">
|
||
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
|
||
<span class="md-header-nav__topic">F4PGA documentation</span>
|
||
<span class="md-header-nav__topic"> Getting started </span>
|
||
</div>
|
||
</div>
|
||
<div class="md-flex__cell md-flex__cell--shrink">
|
||
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
|
||
<div class="md-search" data-md-component="search" role="dialog">
|
||
<label class="md-search__overlay" for="__search"></label>
|
||
<div class="md-search__inner" role="search">
|
||
<form class="md-search__form" action="search.html" method="GET" name="search">
|
||
<input type="text" class="md-search__input" name="q" placeholder="Search"
|
||
autocapitalize="off" autocomplete="off" spellcheck="false"
|
||
data-md-component="query" data-md-state="active">
|
||
<label class="md-icon md-search__icon" for="__search"></label>
|
||
<button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
|
||

|
||
</button>
|
||
</form>
|
||
<div class="md-search__output">
|
||
<div class="md-search__scrollwrap" data-md-scrollfix>
|
||
<div class="md-search-result" data-md-component="result">
|
||
<div class="md-search-result__meta">
|
||
Type to start searching
|
||
</div>
|
||
<ol class="md-search-result__list"></ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="md-flex__cell md-flex__cell--shrink">
|
||
<div class="md-header-nav__source">
|
||
<a href="https://github.com/chipsalliance/f4pga" title="Go to repository" class="md-source" data-md-source="github">
|
||
|
||
<div class="md-source__icon">
|
||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24" width="28" height="28">
|
||
<use xlink:href="#__github" width="24" height="24"></use>
|
||
</svg>
|
||
</div>
|
||
|
||
<div class="md-source__repository">
|
||
chipsalliance/f4pga
|
||
</div>
|
||
</a>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<script src="_static/javascripts/version_dropdown.js"></script>
|
||
<script>
|
||
var json_loc = ""versions.json"",
|
||
target_loc = "../",
|
||
text = "Versions";
|
||
$( document ).ready( add_version_dropdown(json_loc, target_loc, text));
|
||
</script>
|
||
|
||
|
||
</div>
|
||
</nav>
|
||
</header>
|
||
|
||
|
||
<div class="md-container">
|
||
|
||
|
||
|
||
<nav class="md-tabs" data-md-component="tabs">
|
||
<div class="md-tabs__inner md-grid">
|
||
<ul class="md-tabs__list" style="float:left">
|
||
<li class="md-tabs__item"><a href="index.html" class="md-tabs__link">F4PGA documentation</a></li>
|
||
</ul>
|
||
<ul class="md-tabs__list" id="chipsalliance-header" style="float:right">
|
||
|
||
<li class="md-tabs__item"><a href="https://chipsalliance.org" class="md-tabs__link">
|
||
<i class="md-icon">web</i> CHIPS Alliance Website</a></li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
<main class="md-main">
|
||
<div class="md-main__inner md-grid" data-md-component="container">
|
||
|
||
<div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
<nav class="md-nav md-nav--primary" data-md-level="0">
|
||
<label class="md-nav__title md-nav__title--site" for="__drawer">
|
||
<a href="index.html" title="F4PGA documentation" class="md-nav__button md-logo">
|
||
|
||
<img src="_static/" alt=" logo" width="48" height="48">
|
||
|
||
</a>
|
||
<a href="index.html"
|
||
title="F4PGA documentation">F4PGA documentation</a>
|
||
</label>
|
||
<div class="md-nav__source">
|
||
<a href="https://github.com/chipsalliance/f4pga" title="Go to repository" class="md-source" data-md-source="github">
|
||
|
||
<div class="md-source__icon">
|
||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24" width="28" height="28">
|
||
<use xlink:href="#__github" width="24" height="24"></use>
|
||
</svg>
|
||
</div>
|
||
|
||
<div class="md-source__repository">
|
||
chipsalliance/f4pga
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
|
||
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">About F4PGA</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="#" class="md-nav__link md-nav__link--active">
|
||
Getting started</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="how.html" class="md-nav__link">
|
||
How it works</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="status.html" class="md-nav__link">
|
||
Supported Architectures</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="community.html" class="md-nav__link">
|
||
Community</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">Python utils</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="f4pga/index.html" class="md-nav__link">
|
||
Overview</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="f4pga/Usage.html" class="md-nav__link">
|
||
Usage</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="f4pga/modules/index.html" class="md-nav__link">
|
||
Modules</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="f4pga/DevNotes.html" class="md-nav__link">
|
||
Developer’s notes</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="f4pga/Deprecated.html" class="md-nav__link">
|
||
Understanding the (deprecated) flow</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">Development</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="development/changes.html" class="md-nav__link">
|
||
Changes</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="development/building-docs.html" class="md-nav__link">
|
||
Building the documentation</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="development/venv.html" class="md-nav__link">
|
||
Packages in virtual environment</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">Design Flows</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="flows/index.html" class="md-nav__link">
|
||
Introduction</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="flows/synthesis.html" class="md-nav__link">
|
||
Synthesis</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="flows/pnr.html" class="md-nav__link">
|
||
Place & Route</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="flows/bitstream.html" class="md-nav__link">
|
||
Bitstream translation</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="flows/f4pga.html" class="md-nav__link">
|
||
In F4PGA</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">Specifications</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="https://fasm.readthedocs.io/en/latest/" class="md-nav__link">
|
||
FPGA Assembly (FASM) ➚</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="https://chipsalliance/fpga-interchange-schema" class="md-nav__link">
|
||
FPGA Interchange schema ➚</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<span class="md-nav__link caption"><span class="caption-text">Appendix</span></span>
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="glossary.html" class="md-nav__link">
|
||
Glossary</a>
|
||
|
||
|
||
|
||
</li>
|
||
<li class="md-nav__item">
|
||
|
||
<a href="references.html" class="md-nav__link">
|
||
References</a>
|
||
|
||
|
||
|
||
</li>
|
||
</ul>
|
||
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
<nav class="md-nav md-nav--secondary">
|
||
<label class="md-nav__title" for="__toc">Contents</label>
|
||
<ul class="md-nav__list" data-md-scrollfix="">
|
||
<li class="md-nav__item"><a href="#getting-started--page-root" class="md-nav__link">Getting started</a><nav class="md-nav">
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item"><a href="#guidelines" class="md-nav__link">Guidelines</a>
|
||
</li>
|
||
<li class="md-nav__item"><a href="#toolchain-installation" class="md-nav__link">Toolchain installation</a><nav class="md-nav">
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item"><a href="#conda-recommended" class="md-nav__link">Conda (Recommended)</a><nav class="md-nav">
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item"><a href="#bumping-overriding-specific-tools" class="md-nav__link">Bumping/overriding specific tools</a>
|
||
</li></ul>
|
||
</nav>
|
||
</li>
|
||
<li class="md-nav__item"><a href="#other" class="md-nav__link">Other</a><nav class="md-nav">
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item"><a href="#containers" class="md-nav__link">Containers</a>
|
||
</li></ul>
|
||
</nav>
|
||
</li></ul>
|
||
</nav>
|
||
</li>
|
||
<li class="md-nav__item"><a href="#loading-bitstreams" class="md-nav__link">Loading bitstreams</a><nav class="md-nav">
|
||
<ul class="md-nav__list">
|
||
<li class="md-nav__item"><a href="#installing-openfpgaloader" class="md-nav__link">Installing OpenFPGALoader</a>
|
||
</li>
|
||
<li class="md-nav__item"><a href="#usage" class="md-nav__link">Usage</a>
|
||
</li></ul>
|
||
</nav>
|
||
</li></ul>
|
||
</nav>
|
||
</li>
|
||
|
||
<li class="md-nav__item"><a class="md-nav__extra_link" href="_sources/getting-started.rst.txt">Show Source</a> </li>
|
||
|
||
<li id="searchbox" class="md-nav__item"></li>
|
||
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="md-content">
|
||
<article class="md-content__inner md-typeset" role="main">
|
||
|
||
<section id="getting-started">
|
||
<h1 id="getting-started--page-root">Getting started<a class="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 <a class="reference internal" href="#gettingstarted-guidelines"><span class="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 <a class="reference internal" href="#gettingstarted-toolchaininstallation"><span class="std std-ref">Toolchain installation</span></a> below.</p>
|
||
<section id="guidelines">
|
||
<span id="gettingstarted-guidelines"></span><h2 id="guidelines">Guidelines<a class="headerlink" href="#guidelines" title="Link to this heading">¶</a></h2>
|
||
<p>This is the main documentation, which gathers info about the <a class="reference internal" href="f4pga/index.html#pyf4pga"><span class="std std-ref">Python CLI tools and APIs</span></a> and the
|
||
<a class="reference internal" href="flows/index.html#flows"><span class="std std-ref">Design Flows</span></a> supported by F4PGA, along with a <a class="reference internal" href="glossary.html#glossary"><span class="std std-ref">Glossary</span></a>, references to specifications, plugins and
|
||
<a class="reference internal" href="references.html#references"><span class="std std-ref">publications</span></a>.</p>
|
||
<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 <a class="reference external" href="https://f4pga-examples.readthedocs.io">Examples ➚</a>, which provides
|
||
step-by-step guidelines to install the tools through <a class="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 <a class="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 <a class="extlink-ghsrc reference external" href="https://github.com/chipsalliance/f4pga/blob/main/scripts">scripts</a>, as well as the Continuous Integration
|
||
<a class="extlink-ghsrc reference external" href="https://github.com/chipsalliance/f4pga/blob/main/.github/workflows/Pipeline.yml">Pipeline</a>.
|
||
Moreover, workflow <a class="reference external" href="https://github.com/hdl/packages/blob/main/.github/workflows/containers-conda-f4pga.yml">containers-conda-f4pga.yml</a>
|
||
in <a class="extlink-gh reference external" href="https://github.com/hdl/packages">gh:hdl/packages</a> shows how to use the <code class="docutils literal notranslate"><span class="pre">*/conda/f4pga/*</span></code> containers from <a class="extlink-gh reference external" href="https://github.com/hdl/containers">gh:hdl/containers</a>
|
||
(see <a class="reference external" href="https://github.com/hdl/packages/actions/workflows/containers-conda-f4pga.yml">workflow runs</a> and
|
||
<a class="reference internal" href="#gettingstarted-toolchaininstallation-other-containers"><span class="std std-ref">Containers</span></a>).</p>
|
||
<p><strong>Advanced</strong> users and developers willing to support new devices and/or enhance the features of the supported families
|
||
(see <a class="reference external" href="https://chipsalliance.github.io/f4pga-database-visualizer/">F4PGA Architectures Visualizer ➚</a>)
|
||
should head to <a class="reference external" href="https://f4pga.readthedocs.io/projects/arch-defs">Architecture Definitions ➚</a>.
|
||
The effort to document the details of each device/family are distributed on multiple projects:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://f4pga.readthedocs.io/projects/prjxray/en/latest/">Project X-Ray ➚</a></p>
|
||
<ul>
|
||
<li><p><a class="reference external" href="https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide">X-Ray Quickstart ➚</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference external" href="https://prjtrellis.readthedocs.io/en/latest/">Project Trellis ➚</a></p></li>
|
||
<li><p><a class="extlink-gh reference external" href="https://github.com/f4pga/icestorm">Project Icestorm ➚</a></p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="toolchain-installation">
|
||
<span id="gettingstarted-toolchaininstallation"></span><h2 id="toolchain-installation">Toolchain installation<a class="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 <code class="docutils literal notranslate"><span class="pre">apt</span></code>, <code class="docutils literal notranslate"><span class="pre">dnf</span></code>,
|
||
<code class="docutils literal notranslate"><span class="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 <a class="reference external" href="https://conda.io">Conda ➚</a>,
|
||
or some other pre-packaged solution combining latest releases.</p>
|
||
<section id="conda-recommended">
|
||
<span id="gettingstarted-toolchaininstallation-conda"></span><h3 id="conda-recommended">Conda (Recommended)<a class="headerlink" href="#conda-recommended" title="Link to this heading">¶</a></h3>
|
||
<div class="admonition important">
|
||
<p class="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 <a class="reference internal" href="#gettingstarted-guidelines"><span class="std std-ref">Guidelines</span></a> above, multiple Conda environments are provided:</p>
|
||
<ul class="simple">
|
||
<li><p><strong>Newcomers</strong> will find environment and requirements files in <a class="extlink-gh reference external" href="https://github.com/chipsalliance/f4pga-examples">gh:chipsalliance/f4pga-examples</a>, which are to be used
|
||
as explained in <a class="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 <a class="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>
|
||
<ul class="simple">
|
||
<li><p>Setting environment variables <code class="docutils literal notranslate"><span class="pre">F4PGA_INSTALL_DIR</span></code> and <code class="docutils literal notranslate"><span class="pre">F4PGA_FAM</span></code> (and optionally <code class="docutils literal notranslate"><span class="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>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Architecture Definition packages are built and released in <a class="extlink-gh reference external" href="https://github.com/SymbiFlow/f4pga-arch-defs">gh:SymbiFlow/f4pga-arch-defs</a>.
|
||
In this repository and in <a class="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 <a class="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>
|
||
<section id="bumping-overriding-specific-tools">
|
||
<span id="gettingstarted-toolchaininstallation-conda-bumping"></span><h4 id="bumping-overriding-specific-tools">Bumping/overriding specific tools<a class="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 <a class="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 <code class="docutils literal notranslate"><span class="pre">GCS</span></code> in a successful run of workflow <a class="extlink-gh reference external" href="https://github.com/SymbiFlow/f4pga-arch-defs/actions/workflows/Automerge.yml">Automerge</a>
|
||
on branch <code class="docutils literal notranslate"><span class="pre">main</span></code> of <a class="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 <a class="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>
|
||
<section id="other">
|
||
<span id="gettingstarted-toolchaininstallation-other"></span><h3 id="other">Other<a class="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.
|
||
<a class="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>
|
||
<section id="containers">
|
||
<span id="gettingstarted-toolchaininstallation-other-containers"></span><h4 id="containers">Containers<a class="headerlink" href="#containers" title="Link to this heading">¶</a></h4>
|
||
<p>Ready-to-use docker/podman containers are maintained in <a class="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 <a class="extlink-gh reference external" href="https://github.com/chipsalliance/f4pga-examples">gh:chipsalliance/f4pga-examples</a>.
|
||
See <a class="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>
|
||
<div class="admonition hint">
|
||
<p class="admonition-title">Hint</p>
|
||
<p><a class="extlink-ghsharp reference external" href="https://github.com/chipsalliance/f4pga/issues/574">#574</a> is work in progress to provide an F4PGA Action
|
||
(see <a class="reference external" href="https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions">Understanding GitHub Actions</a>)
|
||
based on <code class="docutils literal notranslate"><span class="pre">*/conda/f4pga/*</span></code> containers.</p>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="loading-bitstreams">
|
||
<span id="gettingstarted-loadingbitstreams"></span><h2 id="loading-bitstreams">Loading bitstreams<a class="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 <a class="reference external" href="https://hdl.github.io/constraints/ProgDebug.html#progdebug" title="(in FPGA Board Constraints vlatest)"><span class="xref std std-ref">hdl/constraints: Programming and debugging</span></a>.
|
||
The tools used in the F4PGA Toolchain are e.g. <code class="docutils literal notranslate"><span class="pre">OpenOCD</span></code>, <code class="docutils literal notranslate"><span class="pre">tinyfpgab</span></code> or <code class="docutils literal notranslate"><span class="pre">tinyprog</span></code>.
|
||
Moreover, <a class="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>
|
||
<section id="installing-openfpgaloader">
|
||
<h3 id="installing-openfpgaloader">Installing OpenFPGALoader<a class="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 <a class="reference external" href="https://anaconda.org/litex-hub/openfpgaloader">conda</a>
|
||
or packages in tool <a class="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
|
||
<a class="extlink-gh reference external" href="https://github.com/trabucayre/openFPGALoader/blob/master/INSTALL.md">readme</a>.</p>
|
||
</section>
|
||
<section id="usage">
|
||
<h3 id="usage">Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>
|
||
<p>For programming the FPGA, use one of these commands:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>openFPGALoader<span class="w"> </span>-b<span class="w"> </span><board><span class="w"> </span><bitstream><span class="w"> </span><span class="c1"># (e.g. arty)</span>
|
||
openFPGALoader<span class="w"> </span>-c<span class="w"> </span><cable><span class="w"> </span><bitstream><span class="w"> </span><span class="c1"># (e.g. digilent)</span>
|
||
openFPGALoader<span class="w"> </span>-d<span class="w"> </span><device><span class="w"> </span><bitstream><span class="w"> </span><span class="c1"># (e.g. /dev/ttyUSB0)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can also list the supported boards, cables and FPGAs:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>openFPGALoader<span class="w"> </span>--list-boards
|
||
openFPGALoader<span class="w"> </span>--list-cables
|
||
openFPGALoader<span class="w"> </span>--list-fpga
|
||
</pre></div>
|
||
</div>
|
||
<p>If you encounter any issues, please refer to <a class="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>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</article>
|
||
</div>
|
||
</div>
|
||
</main>
|
||
</div>
|
||
<footer class="md-footer">
|
||
<div class="md-footer-nav">
|
||
<nav class="md-footer-nav__inner md-grid">
|
||
|
||
<a href="index.html" title="FOSS Flows For FPGA"
|
||
class="md-flex md-footer-nav__link md-footer-nav__link--prev"
|
||
rel="prev">
|
||
<div class="md-flex__cell md-flex__cell--shrink">
|
||
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
|
||
</div>
|
||
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
|
||
<span class="md-flex__ellipsis">
|
||
<span
|
||
class="md-footer-nav__direction"> Previous </span> FOSS Flows For FPGA </span>
|
||
</div>
|
||
</a>
|
||
|
||
|
||
<a href="how.html" title="How it works"
|
||
class="md-flex md-footer-nav__link md-footer-nav__link--next"
|
||
rel="next">
|
||
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"><span
|
||
class="md-flex__ellipsis"> <span
|
||
class="md-footer-nav__direction"> Next </span> How it works </span>
|
||
</div>
|
||
<div class="md-flex__cell md-flex__cell--shrink"><i
|
||
class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
|
||
</div>
|
||
|
||
</a>
|
||
|
||
</nav>
|
||
</div>
|
||
<div class="md-footer-meta md-typeset">
|
||
<div class="md-footer-meta__inner md-grid">
|
||
<div class="md-footer-social">
|
||
|
||
<div class="md-footer-social__link">
|
||
<a href="https://chipsalliance.org/" target="_blank">CHIPS Alliance</a>
|
||
</div>
|
||
</ul>
|
||
<div class="md-footer-social__link">
|
||
<a href="https://github.com/chipsalliance/f4pga" target="_blank">GitHub</a>
|
||
</div>
|
||
</div>
|
||
<div class="md-footer-copyright">
|
||
<div class="md-footer-copyright__highlight">
|
||
© Copyright F4PGA Authors, 2019 - 2022.
|
||
|
||
</div>
|
||
Created using
|
||
<a href="http://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
|
||
and
|
||
<a href="https://github.com/f4pga/sphinx_f4pga_theme">Material for
|
||
Sphinx</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
<script src="_static/javascripts/application.js"></script>
|
||
<script src="_static/javascripts/f4pga.js"></script>
|
||
<script>app.initialize({version: "1.0.4", url: {base: ".."}})</script>
|
||
</body>
|
||
</html> |