Google Git
Sign in
foss-fpga-tools / symbiflow-docs / refs/heads/gh-pages / . / f4pga / modules / index.html
blob: 103e5fa3b58622cd4eb9e662dbcc5a3cb3ce7165 [file] [log] [blame]
<!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>Modules &#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="fasm" href="fasm.html" />
<link rel="prev" title="Usage" href="../Usage.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/modules/index" 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"> Modules </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="#" class="md-nav__link md-nav__link--active">
Modules</a>
</li>
<li class="md-nav__item">
<a href="../DevNotes.html" class="md-nav__link">
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-modules-index--page-root" class="md-nav__link">Modules</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#interface" class="md-nav__link">Interface</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#configuration-interface" class="md-nav__link">Configuration interface:</a>
</li>
<li class="md-nav__item"><a href="#platform-level-configuration" class="md-nav__link">Platform-level configuration</a>
</li>
<li class="md-nav__item"><a href="#project-level-configuration" class="md-nav__link">Project-level configuration</a>
</li>
<li class="md-nav__item"><a href="#internal-environmental-variables" class="md-nav__link">Internal environmental variables</a>
</li>
<li class="md-nav__item"><a href="#module-class" class="md-nav__link"><code class="docutils literal notranslate"><span class="pre">Module</span></code> class</a>
</li>
<li class="md-nav__item"><a href="#module-s-execution-modes" class="md-nav__link">Module’s execution modes</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#mapping-mode" class="md-nav__link"><em>mapping</em> mode</a>
</li>
<li class="md-nav__item"><a href="#exec-mode" class="md-nav__link"><em>exec</em> mode</a>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a href="#module-initialization-instantiation" class="md-nav__link">Module initialization/instantiation</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#qualifiers-decorators" class="md-nav__link">Qualifiers/decorators</a>
</li></ul>
</nav>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a href="#common-modules" class="md-nav__link">Common modules</a>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a class="md-nav__extra_link" href="../../_sources/f4pga/modules/index.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="modules">
<h1 id="f4pga-modules-index--page-root">Modules<a class="headerlink" href="#f4pga-modules-index--page-root" title="Link to this heading"></a></h1>
<section id="interface">
<h2 id="interface">Interface<a class="headerlink" href="#interface" title="Link to this heading"></a></h2>
<p>This document contains all the information needed to configure modules for
your <em><strong>f4pga</strong></em> project as well as some info about the API used to write
modules.</p>
<section id="configuration-interface">
<h3 id="configuration-interface">Configuration interface:<a class="headerlink" href="#configuration-interface" title="Link to this heading"></a></h3>
<p>Modules are configured through an internal API by <em><strong>f4pga</strong></em>.
The basic requirement for a module script is to expose a class with <code class="docutils literal notranslate"><span class="pre">Module</span></code>
interface.</p>
<p><em><strong>f4pga</strong></em> reads its configuration from two different sources:
<strong>platform’s flow definition</strong>, which is a file that usually comes bundled with f4pga
and <strong>project’s flow configuration</strong>, which is a set of configuration options provided by the user
through a JSON file or CLI interface.</p>
<p>Those sources contain snippets of <em>module configurations</em>.</p>
<p>A <em>module configuration</em> is a structure with the following fields:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">takes</span></code> - a dictionary that contains keys which are names of the dependencies used by the module.
The values are paths to those dependencies.
They can be either singular strings or lists of strings.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">produces</span></code> - a dictionary that contains keys which are names of the dependencies produced by the module.
The values are requested filenames for the files generated by the module.
They can be either singular strings or lists of strings.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> - a dictionary that contains other values used to configure the module.
The keys are value’s names and the values can have any type.</p></li>
</ul>
</section>
<section id="platform-level-configuration">
<h3 id="platform-level-configuration">Platform-level configuration<a class="headerlink" href="#platform-level-configuration" title="Link to this heading"></a></h3>
<p>In case of <strong>platform’s flow definition</strong>, a <code class="docutils literal notranslate"><span class="pre">values</span></code> dictionary can be defined
globally and the values defined there will be passed to every module’s config.</p>
<p>Those values can be overridden per-module through <code class="docutils literal notranslate"><span class="pre">module_options</span></code> dictionary.</p>
<p>Parameters used during module’s construction can also be defined in <code class="docutils literal notranslate"><span class="pre">module_options</span></code>
as <code class="docutils literal notranslate"><span class="pre">params</span></code> (those are not a part of <em>module configuration</em>, instead they are used
during the actual construction of a module instance, before it declares any of its
input/outputs etc.. This is typically used to achieve some parametrization over module’s
I/O).</p>
<p>Defining dictionaries for <code class="docutils literal notranslate"><span class="pre">takes</span></code> and <code class="docutils literal notranslate"><span class="pre">produces</span></code> is currently disallowed within
<strong>platform’s flow definition</strong>.</p>
<p>For examples of <strong>platform’s flow definition</strong> described here, please have a look at
<code class="docutils literal notranslate"><span class="pre">f4pga/platforms/</span></code> directory. It contains <strong>platform flow definitions</strong> that come bundled
with f4pga.</p>
</section>
<section id="project-level-configuration">
<h3 id="project-level-configuration">Project-level configuration<a class="headerlink" href="#project-level-configuration" title="Link to this heading"></a></h3>
<p>This section describes <strong>project’s flow configuration</strong>.</p>
<p>Similarly to <strong>platform’s flow definition</strong>, <code class="docutils literal notranslate"><span class="pre">values</span></code> dict can be provided.
The values provided there will overwrite the values from
<strong>platform’s flow definition</strong> in case of a collision.</p>
<p>Unlike <strong>platform’s flow definition</strong>, <strong>project’s flow configuration</strong> may contain
<code class="docutils literal notranslate"><span class="pre">dependencies</span></code> dict. This dictionary would be used to map symbolic dependency
names to actual paths. Most dependencies can have their paths resolved implicitly
without the need to provide explicit paths, which is a mechanism that is described
in a later section of this document. However some dependencies must be provided
explicitly, eg. paths to project’s Verilog source files. It should be noted that
depending on the flow definition and the dependency in question, the path does not
necessarily have to point to an already existing file. If the dependency is a
product of a module within the flow, the path assigned to it will be used
by the module to build that dependency. This is also used to in case of <em>on-demand</em>
dependencies, which won’t be produced unless the user explicitly provides a path
for them.</p>
<p><strong>project’s flow configuration</strong> cannot specify <code class="docutils literal notranslate"><span class="pre">params</span></code> for modules and does not
use <code class="docutils literal notranslate"><span class="pre">module_options</span></code> dictionary. Neither it can instantiate any extra stages.</p>
<p>Any entry with a couple <em>exceptions*</em> is treated as a platform name.
Enabling support for a given platform within a <strong>project’s flow configuration</strong> file
requires having an entry for that platform.
Each of those entries may contain <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>, <code class="docutils literal notranslate"><span class="pre">values</span></code> fields which will
overload the <code class="docutils literal notranslate"><span class="pre">dependecies</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code> defined in a global scope of
<strong>project’s flow configuration</strong>. Any other field under those platform entries
is treated as a <em>stage-specific-configuration</em>. The key is a name of a stage within
a flow for the specified platform and the values are dicts which may contain
<code class="docutils literal notranslate"><span class="pre">dependencies</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code> fields that overload <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code>
respectively, locally for the stage. Additionally a <code class="docutils literal notranslate"><span class="pre">default_target</span></code> field can be
provided to specify a default target to built when the user does not specify it through
a CLI interface.</p>
<p>The aforementioned <em>*exceptions</em> are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">dependencies</span></code> - dependencies shared by all platforms.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> - values shared by all platforms</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">default_platform</span></code> - default platform to chose in case it doesn’t get specified
by the user</p></li>
</ul>
<p>Those apply only to flow configuration file.</p>
</section>
<section id="internal-environmental-variables">
<h3 id="internal-environmental-variables">Internal environmental variables<a class="headerlink" href="#internal-environmental-variables" title="Link to this heading"></a></h3>
<p>It’s very useful to be able to refer to some data within
<strong>platform’s flow definition</strong> and <strong>project’s flow configuration</strong> to
either avoid redundant definitions or to store and access results of certain operations.
<em><strong>f4pga</strong></em> allows doing that by using a special syntax for accessing internal
environmental variables.</p>
<p>The syntax is <code class="docutils literal notranslate"><span class="pre">${variable_name}</span></code>. Any string value within
<strong>platform’s flow definition</strong> and <strong>project’s flow configuration</strong> that contains
such patterns will have them replaced with the values of the variables referenced
if those values are strings. Eg.:</p>
<p>With the following values defined:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w"> </span><span class="nt">"a_value"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1234"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"another_value"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a_value: ${a_value}"</span>
<span class="p">}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">another_value</span></code> will resolve to:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="s2">"a_value: 1234"</span>
</pre></div>
</div>
<p>If the value is a list however, the result would be a list with all entries being
the original string with the reference to a variable replaced by following
items of the original list. Eg.:</p>
<p>With the following values defined</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w"> </span><span class="nt">"list_of_values"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"a"</span><span class="p">,</span><span class="w"> </span><span class="s2">"b"</span><span class="p">,</span><span class="w"> </span><span class="s2">"c"</span><span class="p">],</span>
<span class="w"> </span><span class="nt">"some_string"</span><span class="p">:</span><span class="w"> </span><span class="s2">"item: ${list_of_values}"</span>
<span class="p">}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">some_string</span></code> will resolve to</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"item: a"</span><span class="p">,</span><span class="w"> </span><span class="s2">"item: b"</span><span class="p">,</span><span class="w"> </span><span class="s2">"item: c"</span><span class="p">]</span>
</pre></div>
</div>
<p>Be careful when using this kind of resolution, as it’s computational and memory
complexity grows exponentially in regards to the number of list variables being
referenced, which is a rather obvious fact, but it’s still worth mentioning.</p>
<p>The variables that can be referenced within a definition/configuration fall into 3
categories:</p>
<ul class="simple">
<li><p><strong>value references</strong> - anything declared as a <code class="docutils literal notranslate"><span class="pre">value</span></code> can be accessed by it’s
name</p></li>
<li><p><strong>dependency references</strong> - any dependency path can be referenced using the name
of the dependency prefaced with a ‘:’ prefix. Eg.: <code class="docutils literal notranslate"><span class="pre">${:eblif}</span></code> will resolve
to the path of <code class="docutils literal notranslate"><span class="pre">eblif</span></code> dependency. Make sure that the dependency can be
actually resolved when you are using this kind of reference. For example
you can’t use the a reference to <code class="docutils literal notranslate"><span class="pre">eblif</span></code> dependency in a module which does not
rely on it. An exception is the producer module which can in fact reference it’s
own outputs but these references cannot be used during the <em>mapping</em> stage
(more on that later).</p></li>
<li><p><strong>built-in references</strong> - there are a couple of built-in variables which are very
handy:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">shareDir</span></code> - path to f4pga’s <em>share</em> directory.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">binDir</span></code> - path to f4pga’s <em>bin</em> directory.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">prjxray_db</span></code> - Project X-Ray database path.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python3</span></code> - path to Python 3 interpreter.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">noisyWarnings</span></code> - (this one should probably get removed)</p></li>
</ul>
</li>
</ul>
</section>
<section id="module-class">
<h3 id="module-class"><code class="docutils literal notranslate"><span class="pre">Module</span></code> class<a class="headerlink" href="#module-class" title="Link to this heading"></a></h3>
<p>Each module is represented as a class derived from <code class="docutils literal notranslate"><span class="pre">Module</span></code> class.</p>
<p>The class should implement the following methods:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">execute(self,</span> <span class="pre">ctx:</span> <span class="pre">ModuleContext)</span></code> - executes the module in <em>exec</em> mode</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">map_io(self,</span> <span class="pre">ctx:</span> <span class="pre">ModuleContext)</span> <span class="pre">-&gt;</span> <span class="pre">'dict[str,</span> <span class="pre">]'</span></code> - executes the module in
<em>mapping</em> mode</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__init__(self,</span> <span class="pre">params:</span> <span class="pre">'dict[str,</span> <span class="pre">]')</span></code> - initializer. The <code class="docutils literal notranslate"><span class="pre">params</span></code>
is a dict with optional parameter for the module.</p></li>
</ul>
<p>Each module script should expose the class by defining it’s name/type alias as
<code class="docutils literal notranslate"><span class="pre">ModuleClass</span></code>. f4pga tries to access a <code class="docutils literal notranslate"><span class="pre">ModuleClass</span></code> attribute within a package
when instantiating a module.</p>
</section>
<section id="module-s-execution-modes">
<h3 id="module-s-execution-modes">Module’s execution modes<a class="headerlink" href="#module-s-execution-modes" title="Link to this heading"></a></h3>
<p>A module has essentially two execution modes:</p>
<ul class="simple">
<li><p><em>mapping</em> mode</p></li>
<li><p><em>exec</em> mode</p></li>
</ul>
<section id="mapping-mode">
<h4 id="mapping-mode"><em>mapping</em> mode<a class="headerlink" href="#mapping-mode" title="Link to this heading"></a></h4>
<p>In <em>mapping</em> mode the module is provided with an incomplete configuration which
includes:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">takes</span></code> namespace: this maps names of input dependencies to the paths of these
dependencies</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> namespace: this maps names of variables to the values of those
variables.</p></li>
</ul>
<p>The module has to provide a dictionary that will provide every output dependency
that’s not <em>on-demand</em> a default path. This is basically a promise that when
executed in <em>exec</em> mode, the module will produce files for this paths.
Typically such paths would be derived from a path of one of it’s input dependencies.
This mechanism allows the user to avoid specifying an explicit path for each
intermediate target.</p>
<p>It should be noted that variables referring to the output dependencies
can’t be accessed at this stage for the obvious reason as their values are yet
to be evaluated.</p>
</section>
<section id="exec-mode">
<h4 id="exec-mode"><em>exec</em> mode<a class="headerlink" href="#exec-mode" title="Link to this heading"></a></h4>
<p>In <em>exec</em> mode the module does the actual work.</p>
<p>The configuration passed into this mode is full and it includes:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">takes</span></code> namespace: this maps names of input dependencies to the paths of these
dependencies</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> namespace: this maps names of variables to the values of those
variables.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">produces</span></code> namespace: this maps names of output dependencies to explicit paths.
This should not be used directly really, but it’s useful for
<code class="docutils literal notranslate"><span class="pre">ModuleContext.is_output_explicit</span></code> method.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">outputs</span></code> namespace: this maps names of output dependencies to their paths.</p></li>
</ul>
<p>When the module finishes executing in <em>exec</em> mode, all of the dependencies
described in <code class="docutils literal notranslate"><span class="pre">outputs</span></code> should be present.</p>
</section>
</section>
<section id="module-initialization-instantiation">
<h3 id="module-initialization-instantiation">Module initialization/instantiation<a class="headerlink" href="#module-initialization-instantiation" title="Link to this heading"></a></h3>
<p>In the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method of module’s class, the following fields should be
set:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">takes</span></code> - a list of symbolic dependency names for dependencies used by the module</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">produces</span></code> - a list of symbolic dependencies names for dependencies produced
by the module.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> - a list of names given to the variables used withing the module</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">prod_meta</span></code> - A dictionary which maps product names to descriptions of these
products. Those entries are optional and can be skipped.</p></li>
</ul>
<section id="qualifiers-decorators">
<h4 id="qualifiers-decorators">Qualifiers/decorators<a class="headerlink" href="#qualifiers-decorators" title="Link to this heading"></a></h4>
<p>By default the presence of all the dependencies and values is mandatory
(In case of <code class="docutils literal notranslate"><span class="pre">produces</span></code> that means that the module always has to produce the listed
dependencies). This can be changed by “decorating” a name in one of the following
ways:</p>
<ul class="simple">
<li><p>‘<code class="docutils literal notranslate"><span class="pre">?</span></code>’ <em>suffix</em></p>
<ul>
<li><p>In <code class="docutils literal notranslate"><span class="pre">takes</span></code> - the dependency is not necessary for the module to execute</p></li>
<li><p>In <code class="docutils literal notranslate"><span class="pre">produces</span></code> - the dependency may be produced, but it is not guaranteed.</p></li>
<li><p>In <code class="docutils literal notranslate"><span class="pre">values</span></code> the value is not required for the module to execute.
Referring to it through <code class="docutils literal notranslate"><span class="pre">ModuleContext.values.value_name</span></code> won’t raise an
exception if the value is not present, instead <code class="docutils literal notranslate"><span class="pre">None</span></code> will be returned.</p></li>
</ul>
</li>
<li><p>‘<code class="docutils literal notranslate"><span class="pre">!</span></code>’ <em>suffix</em></p>
<ul>
<li><p>In <code class="docutils literal notranslate"><span class="pre">produces</span></code> - the dependency is going to be produced only if the user
provides an explicit path for it.</p></li>
</ul>
</li>
</ul>
<p>Currently it’s impossible to combine both ‘<code class="docutils literal notranslate"><span class="pre">!</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">?</span></code>’ together. This limitation
does not have any reason behind it other than the way the qualifier system
is implemented at the moment. It might be removed in the future.</p>
</section>
</section>
</section>
<section id="common-modules">
<h2 id="common-modules">Common modules<a class="headerlink" href="#common-modules" title="Link to this heading"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="fasm.html">fasm</a><ul>
<li class="toctree-l2"><a class="reference internal" href="fasm.html#values">Values</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="generic_script_wrapper.html">generic_script_wrapper</a><ul>
<li class="toctree-l2"><a class="reference internal" href="generic_script_wrapper.html#parameters">Parameters</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="io_rename.html">io_rename</a><ul>
<li class="toctree-l2"><a class="reference internal" href="io_rename.html#parameters">Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="io_rename.html#values">Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="io_rename.html#extra-notes">Extra notes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mkdirs.html">mkdirs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="mkdirs.html#parameters">Parameters</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pack.html">pack</a></li>
<li class="toctree-l1"><a class="reference internal" href="place.html">place</a></li>
<li class="toctree-l1"><a class="reference internal" href="place_constraints.html">place_constraints</a></li>
<li class="toctree-l1"><a class="reference internal" href="route.html">route</a></li>
<li class="toctree-l1"><a class="reference internal" href="synth.html">synth</a><ul>
<li class="toctree-l2"><a class="reference internal" href="synth.html#parameters">Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="synth.html#values">Values</a></li>
</ul>
</li>
</ul>
</div>
</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="../Usage.html" title="Usage"
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> Usage </span>
</div>
</a>
<a href="fasm.html" title="fasm"
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> fasm </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>