Google Git
Sign in
foss-fpga-tools / symbiflow-docs / refs/heads/gh-pages / . / f4pga / DevNotes.html
blob: cef6e09a3e31afdea6773e3a209f43b83264cdd8 [file] [log] [blame] [edit]
<!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>Developer’s notes &#8212; F4PGA documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<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="Understanding the (deprecated) flow" href="Deprecated.html" />
<link rel="prev" title="synth" href="modules/synth.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="#f4pga/DevNotes" 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">
&nbsp;
</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"> Developer’s notes </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">
&#xE5CD;
</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="../getting-started.html" class="md-nav__link">
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="index.html" class="md-nav__link">
Overview</a>
</li>
<li class="md-nav__item">
<a href="Usage.html" class="md-nav__link">
Usage</a>
</li>
<li class="md-nav__item">
<a href="modules/index.html" class="md-nav__link">
Modules</a>
</li>
<li class="md-nav__item">
<a href="#" class="md-nav__link md-nav__link--active">
Developer’s notes</a>
</li>
<li class="md-nav__item">
<a href="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="#f4pga-devnotes--page-root" class="md-nav__link">Developer’s notes</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#last-update-2022-05-06" class="md-nav__link">Last update: 2022-05-06</a>
</li>
<li class="md-nav__item"><a href="#project-s-structure" class="md-nav__link">Project’s structure</a>
</li>
<li class="md-nav__item"><a href="#different-subsystems-and-where-to-find-them" class="md-nav__link">Different subsystems and where to find them?</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#building-and-dependency-resolution" class="md-nav__link">Building and dependency resolution</a>
</li>
<li class="md-nav__item"><a href="#modification-tracking" class="md-nav__link">Modification tracking</a>
</li>
<li class="md-nav__item"><a href="#internal-environmental-variable-system" class="md-nav__link">Internal environmental variable system</a>
</li>
<li class="md-nav__item"><a href="#installation" class="md-nav__link">Installation</a>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a href="#todo" class="md-nav__link">TODO:</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#out-of-the-current-scope" class="md-nav__link">Out of the current scope</a>
</li></ul>
</nav>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a class="md-nav__extra_link" href="../_sources/f4pga/DevNotes.md.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="developer-s-notes">
<h1 id="f4pga-devnotes--page-root">Developer’s notes<a class="headerlink" href="#f4pga-devnotes--page-root" title="Link to this heading"></a></h1>
<section id="last-update-2022-05-06">
<h2 id="last-update-2022-05-06">Last update: 2022-05-06<a class="headerlink" href="#last-update-2022-05-06" title="Link to this heading"></a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>These notes are provided as-is and they shouldn’t be treated as a full-blown accurate
documentation, but rather as a helpful resource for those who want to get involved with
development of <em>f4pga</em>. These are not updated regularly.</p>
<p>For more detailed, up-to-date information about the code, refer to the pydoc documentation.</p>
</div>
</section>
<section id="project-s-structure">
<h2 id="project-s-structure">Project’s structure<a class="headerlink" href="#project-s-structure" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> contains the logic and entry point of the build system</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">argparser.py</span></code> contains boring code for CLI interface</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cache.py</span></code> contains code needed for tracking modifications in the project.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">common.py</span></code> contains code shared by the main utility and the modules</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">flow_config.py</span></code> contains code for reading and accessing flow definitions and configurations</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">module_inspector.py</span></code> contains utilities for inspecting I/O of modules</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">module_runner.py</span></code> contains code required to load modules at run-time</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">module.py</span></code> contains definitions required for writing and using f4pga modules</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">part_db.json</span></code> contains mappings from part names to platform names</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">setup.py</span></code> contains a package installation script</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stage.py</span></code> contains classes relevant to stage representation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">modules</span></code> contains loadable modules</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">platforms</span></code> contains platform flow definitions</p></li>
</ul>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Through the codebase <em>f4pga</em> (tool) might be often referenced as <em>sfbuild</em>.
Similarly, <em>F4PGA</em> (toolchain) might get called <em>Symbiflow</em>.
This is due to the project being written back when <em>F4PGA</em> was called <em>Symbiflow</em>.</p>
</div>
</section>
<section id="different-subsystems-and-where-to-find-them">
<h2 id="different-subsystems-and-where-to-find-them">Different subsystems and where to find them?<a class="headerlink" href="#different-subsystems-and-where-to-find-them" title="Link to this heading"></a></h2>
<section id="building-and-dependency-resolution">
<h3 id="building-and-dependency-resolution">Building and dependency resolution<a class="headerlink" href="#building-and-dependency-resolution" title="Link to this heading"></a></h3>
<p>All the code regarding dependency resolution is located in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file.
Take a look at the <code class="docutils literal notranslate"><span class="pre">Flow</span></code> class.</p>
<p>Most of the work is done in <code class="docutils literal notranslate"><span class="pre">Flow._resolve_dependencies</span></code> method. Basically it
performs a <em>DFS</em> with <em>stages</em> (instances of <em>f4pga modules</em>) as its nodes
which are linked using symbolic names of dependencies on inputs and outputs.
It queries the modules for information regarding i/o (most importantly the paths
on which they are going to produce outputs), checks whether
their inputs are going to be satisfied, checks if dependencies were modified, etc.</p>
<p>The actual building is done using <code class="docutils literal notranslate"><span class="pre">Flow._build_dep</span></code> procedure. It uses a similar
<em>DFS</em> approach to invoke modules and check their inputs and outputs.</p>
</section>
<section id="modification-tracking">
<h3 id="modification-tracking">Modification tracking<a class="headerlink" href="#modification-tracking" title="Link to this heading"></a></h3>
<p>Modification tracking is done by taking, comparing and keeping track of <code class="docutils literal notranslate"><span class="pre">adler32</span></code>
hashes of all dependencies. Each dependency has a set of hashes associated with it.
The reason for having multiple hashes is that a dependency may have multiple
“<em>consumers</em>”, ie. <em>stages</em> which take it as input. Each hash is associated with
particular consumer. This is necessary, because the system tries to avoid rebuilds
when possible and status of each file (modified/unmodified) may differ in regards
to individual stages.</p>
<p>Keeping track of status of each file is done using <code class="docutils literal notranslate"><span class="pre">F4Cache</span></code> class, which is
defined in <code class="docutils literal notranslate"><span class="pre">cache.py</span></code> file. <code class="docutils literal notranslate"><span class="pre">F4Cache</span></code> is used mostly inside <code class="docutils literal notranslate"><span class="pre">Flow</span></code>’s methods.</p>
</section>
<section id="internal-environmental-variable-system">
<h3 id="internal-environmental-variable-system">Internal environmental variable system<a class="headerlink" href="#internal-environmental-variable-system" title="Link to this heading"></a></h3>
<p><em>f4pga</em> exposes some data to the user as well as reads some using internal
environmental variables. These can be referenced by users in
<em>platform flow definitions</em> and <em>project flow configurations</em> using the
<code class="docutils literal notranslate"><span class="pre">${variable_name}</span></code> syntax when defining values. They can also be read inside
<em>f4pga modules</em> by accessing the <code class="docutils literal notranslate"><span class="pre">ctx.values</span></code> namespace.</p>
<p>The core of its system is the <code class="docutils literal notranslate"><span class="pre">ResolutionEnvironemt</span></code> class which can be found
inside the <code class="docutils literal notranslate"><span class="pre">common</span></code> module.</p>
</section>
<section id="installation">
<h3 id="installation">Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h3>
<p>Check <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code>.</p>
</section>
</section>
<section id="todo">
<h2 id="todo">TODO:<a class="headerlink" href="#todo" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Define a clear specification for entries in <em>platform flow definitions</em> and
<em>platform flow configurations</em>. Which environmental variables can be accessed
where, and when?</p></li>
<li><p>Force “<em>on-demand</em>” outputs if they are required by another stage.
This may require redesigning the “on-demand” feature, which currently works
by producing a dependency if and only if the user explicitly provides the
path. Otherwise the path is unknown.</p></li>
<li><p>Make commenting style consistent</p></li>
<li><p>Document writing flow definitions</p></li>
<li><p>Extend the metadata system for modules, perhaps make it easier to use.</p></li>
<li><p>Add missing metadata for module targets.</p></li>
<li><p>(<em>suggestion</em>) Generate platform definitions using CMake.</p></li>
</ul>
<section id="out-of-the-current-scope">
<h3 id="out-of-the-current-scope">Out of the current scope<a class="headerlink" href="#out-of-the-current-scope" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Change interfaces of some internal python scripts. This could lead to possibly
merging some modules for XC7 and Quicklogic into one common module.</p></li>
</ul>
</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="modules/synth.html" title="synth"
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> synth </span>
</div>
</a>
<a href="Deprecated.html" title="Understanding the (deprecated) flow"
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> Understanding the (deprecated) flow </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">
&#169; 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>