315 lines
11 KiB
ReStructuredText
315 lines
11 KiB
ReStructuredText
.. -*- Mode: rst -*-
|
|
|
|
|
|
1. Introduction
|
|
===============
|
|
|
|
The goal of the DesignFlow Python tool is to provide a replacement for
|
|
Makefiles, especially the complex system that has been developped for
|
|
alliance-check-toolkit. It is build upon |DoIt| (DoIt_).
|
|
|
|
|
|
1.1 Task vs. Rules
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Both as a tribute to |Makefile|, to avoid ambiguties with |DoIt| and to remember
|
|
that they are task *generators*, the classes defined to create tasks for the design
|
|
flow are called ``rules``.
|
|
|
|
|
|
|
|
1.2 A Warning About Determinism
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There is a very important execution difference from a |Makefile|. In a
|
|
|Makefile| each rule command is executed in a a separated process, so
|
|
information is effectively passed through files which are written then read
|
|
from disk. But in |DoIt| we are running inside *one* |Python| process, so while
|
|
using Coriolis and the |Hurricane| database, all informations stays *in
|
|
memory*. Files are driven, but *not re-read* as the database will use the datas
|
|
already present in memory.
|
|
|
|
This is not whitout consequences about determism. Let's look at two different
|
|
scenarii.
|
|
|
|
1. We run straight from the RTL to the layout, using the rule/task sequence: ::
|
|
|
|
Yosys => design.blif => blif2vst => design.vst => PnR => design.gds
|
|
|
|
In this case, while ``design.vst`` is written on disk, the ``PnR`` stage
|
|
will not re-read the ``vst`` file and directly access the data in memory.
|
|
|
|
2. Run in two separated steps, first we create the ``vst`` file: ::
|
|
|
|
Yosys => design.blif => blif2vst => design.vst
|
|
|
|
Then, we perform the ``PnR``: ::
|
|
|
|
design.vst => PnR => design.gds
|
|
|
|
In this case, as the |DoIt| processess has been restarted between the two
|
|
tasks, the ``PnR`` stage *will* read the ``vst`` file.
|
|
|
|
The determism in |Coriolis| is ensured through the unique identifiers of the
|
|
objects, attributed in creation order. So between thoses two scenarii, the
|
|
identifiers will change and so the algorithm results. The differences should
|
|
be minor as the identifiers are used as a *last ditch* test to sort between
|
|
two objects which cost functions are exactly equal, nevertheless, it will
|
|
occur.
|
|
|
|
.. note:: |Coriolis| is deterministic, meaning that each scenario will always
|
|
give the same result. The difference is truly *between* scenarii.
|
|
|
|
|
|
2. Using The Design Flow
|
|
========================
|
|
|
|
|
|
2.1 Locating the Various Parts
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
One of the most tricky part of setting up the design flow is to locate where
|
|
the various components are. The script needs to be able to find:
|
|
|
|
1. Coriolis, binaries & libraries. This depends widely of your kind of
|
|
installation and system. The helper script ``crlenv.py`` supplied
|
|
both in |alliance-check-toolkit| and |Coriolis| may help you there.
|
|
It looks in all the standard locations (that it is aware of) to try
|
|
to find it.
|
|
|
|
.. note:: Usually, |Alliance| is installed in the same tree as
|
|
|Coriolis|, so it's setup can be deduced from it.
|
|
|
|
2. The configurations files for the technology to be used. Here again,
|
|
the ``designflow.technos`` module provides you with a set of
|
|
pre-defined configurations for open sources technologie shipped
|
|
with |Coriolis|. For unsupported ones, you may write your own,
|
|
it should perform the whole initialization of the |Coriolis| and
|
|
|Hurricane| database.
|
|
|
|
3. Optionnaly the |alliance-check-toolkit|.
|
|
|
|
|
|
2.2 Basic Example of |dodo| File
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This example can be found in |alliance-check-toolkit|, under ``benchs/arlet6502/sky130_c4m``.
|
|
|
|
Here
|
|
|
|
.. code:: Python
|
|
|
|
from designflow.technos import setupSky130_c4m
|
|
|
|
setupSky130_c4m( checkToolkit='../../..'
|
|
, pdkMasterTop='../../../pdkmaster/C4M.Sky130' )
|
|
|
|
DOIT_CONFIG = { 'verbosity' : 2 }
|
|
|
|
from designflow.pnr import PnR
|
|
from designflow.yosys import Yosys
|
|
from designflow.blif2vst import Blif2Vst
|
|
from designflow.alias import Alias
|
|
from designflow.clean import Clean
|
|
PnR.textMode = True
|
|
|
|
from doDesign import scriptMain
|
|
|
|
ruleYosys = Yosys .mkRule( 'yosys', 'Arlet6502.v' )
|
|
ruleB2V = Blif2Vst.mkRule( 'b2v' , [ 'arlet6502.vst'
|
|
, 'Arlet6502.spi' ]
|
|
, [ruleYosys]
|
|
, flags=0 )
|
|
rulePnR = PnR .mkRule( 'pnr' , [ 'arlet6502_cts_r.gds'
|
|
, 'arlet6502_cts_r.spi'
|
|
, 'arlet6502_cts_r.vst' ]
|
|
, [ruleB2V]
|
|
, scriptMain )
|
|
ruleCgt = PnR .mkRule( 'cgt' )
|
|
ruleGds = Alias .mkRule( 'gds', [rulePnR] )
|
|
ruleClean = Clean .mkRule()
|
|
|
|
|
|
You can run it with:
|
|
|
|
.. code:: bash
|
|
|
|
ego@home:sky130_c4m> ../../../bin/crlenv.py -- doit list
|
|
b2v Run <blif2vst arlet6502 depends=[Arlet6502.blif]>.
|
|
cgt Run plain CGT (no loaded design)
|
|
clean_flow Clean all generated (targets) files.
|
|
gds Run <Alias "gds" for "pnr">.
|
|
pnr Run <pnr arlet6502_cts_r.gds depends=[arlet6502.vst,Arlet6502.spi]>.
|
|
yosys Run <yosys Arlet6502.v top=Arlet6502 blackboxes=[] flattens=[]>.
|
|
ego@home:sky130_c4m> ../../../bin/crlenv.py -- doit pnr
|
|
ego@home:sky130_c4m> ../../../bin/crlenv.py -- doit clean_flow
|
|
|
|
|
|
Let's have a detailed look on the various parts of the script.
|
|
|
|
A. **Choosing the technology** Here, we load the predefined configuration for
|
|
SkyWater 130nm. We also have to give the location of the
|
|
|alliance-check-toolkit|, it may be relative or absolute.
|
|
|
|
If you want to use another one, it up to you to configure |Coriolis| at
|
|
this point by any means you see fit.
|
|
|
|
.. code:: Python
|
|
|
|
from designflow.technos import setupSky130_c4m
|
|
|
|
setupSky130_c4m( checkToolkit='../../..'
|
|
, pdkMasterTop='../../../pdkmaster/C4M.Sky130' )
|
|
|
|
|
|
B. **Loading the various task/rule generators that we will use**, from the
|
|
``designflow`` namespace. The rules are named from the tool they
|
|
encapsulate.
|
|
|
|
.. code:: Python
|
|
|
|
from designflow.pnr import PnR
|
|
from designflow.yosys import Yosys
|
|
from designflow.blif2vst import Blif2Vst
|
|
from designflow.alias import Alias
|
|
from designflow.clean import Clean
|
|
PnR.textMode = True
|
|
|
|
|
|
C. **Creating the rule set.** Each rule generator as a static method ``mkRule()``
|
|
to create a new task. The three first parameters are always:
|
|
|
|
1. The name of the task (the ``basename`` for |DoIt|).
|
|
|
|
2. A target or list of targets, must be files or ``pathlib.Path`` objects.
|
|
|
|
3. A dependency or list of dependencies, they can be files, ``pathlib.Path``
|
|
objects, or other tasks. We can see that the ``Blif2Vst`` rule uses
|
|
directly the ``Yosys`` one (the input file will be the *first* target
|
|
of the ``Yosys`` rule).
|
|
|
|
4. Any extra parameters. A set of flag for ``Blif2Vst``. The ``PnR`` rule takes
|
|
an optional callable argument, *any* callable. In this case we import the
|
|
``scriptMain()`` function from ``doDesign()``.
|
|
|
|
There are two more special rules:
|
|
|
|
* ``Alias``, to rename a rule. It this case ``gds`` is defined as an alias to
|
|
``PnR`` (because it generate the |gds| file).
|
|
|
|
* ``Clean`` to create a rule that will remove all the generated targets.
|
|
|
|
.. note:: The clean rule is named ``clean_flow`` because |DoIt| already have
|
|
a ``clean`` arguments which would shadow it.
|
|
|
|
|
|
.. code:: Python
|
|
|
|
PnR.textMode = True
|
|
|
|
from doDesign import scriptMain
|
|
|
|
ruleYosys = Yosys .mkRule( 'yosys', 'Arlet6502.v' )
|
|
ruleB2V = Blif2Vst.mkRule( 'b2v' , [ 'arlet6502.vst'
|
|
, 'Arlet6502.spi' ]
|
|
, [ruleYosys]
|
|
, flags=0 )
|
|
rulePnR = PnR .mkRule( 'pnr' , [ 'arlet6502_cts_r.gds'
|
|
, 'arlet6502_cts_r.spi'
|
|
, 'arlet6502_cts_r.vst' ]
|
|
, [ruleB2V]
|
|
, scriptMain )
|
|
ruleCgt = PnR .mkRule( 'cgt' )
|
|
ruleGds = Alias .mkRule( 'gds', [rulePnR] )
|
|
ruleClean = Clean .mkRule()
|
|
|
|
|
|
3. Rules's Catalog
|
|
==================
|
|
|
|
3.1 Alliance Legacy Tools
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Support for the |Alliance| legacy tools. They are run through sub-processes.
|
|
For more detailed documentation about those tools, refer to their |man| pages.
|
|
|
|
#. ``Asimut``, |VHDL| simulator.
|
|
|
|
#. ``Boog``, logical synthesys. Map a |VHDL| behavioral description to a standard
|
|
cell library (works with ``boom`` & ``loon``).
|
|
|
|
#. ``Boom``, behavioral description optimizer (works with ``boog`` & ``loon``).
|
|
|
|
#. ``Cougar``, symbolic layout extractor.
|
|
|
|
#. ``Dreal``, real layout (|GDS|, |CIF|) editor.
|
|
|
|
#. ``Druc``, symbolic layout |DRC|.
|
|
|
|
#. ``Flatph``, flatten a layout, fully or in part.
|
|
|
|
#. ``Genpat``, pattern generator (for use with ``Asimut``).
|
|
|
|
#. ``Graal``, symbolic layout editor.
|
|
|
|
#. ``Loon``, netlist optimizer for surface and/or delay (works with ``boom`` & ``boog``).
|
|
|
|
#. ``Lvx``, netlist comparator (*Layout* *Versus* *Extracted*).
|
|
|
|
#. ``S2R``, symbolic to real translator (to |GDS| or |CIF|).
|
|
|
|
#. ``Vasy``, Alliance |VHDL| subset translator towards standard |VHDL| or |Verilog|.
|
|
|
|
|
|
3.2 Current Tools
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
#. ``Blif2Vst``, translate a |blif| netlist (|Yosys| output) into the |Alliance|
|
|
netlist format |vst|. This is a |Python| script calling |Coriolis| directly
|
|
integrated inside the task.
|
|
|
|
#. ``PnR``, maybe a bit of a misnomer. This is a caller to function that the user have
|
|
to write to perform the P&R as he sees fit for it's particular design.
|
|
|
|
#. ``Yosys``, call the |Yosys| logical synthesyser. Provide an off the shelf subset
|
|
of functionalities to perform classic use cases.
|
|
|
|
|
|
3.3 Utility Rules
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
#. ``Alias``, create a name alias for a rule.
|
|
|
|
#. ``Clean``, remove all the generated targets of all the rules. The name of the
|
|
rule is ``clean_flow` to not interfer with the |DoIt| clean arguments.
|
|
Files not part of any rules targets can be added to be removeds. Then,
|
|
to actually remove them, add the ``--extras`` flag to the command line.
|
|
|
|
.. code:: bash
|
|
|
|
ego@home:sky130_c4m> ../../../bin/crlenv.py -- doit clean_flow --extras
|
|
|
|
|
|
#. ``Copy``, copy a file into the current directory.
|
|
|
|
|
|
3.4 Rule Sets
|
|
~~~~~~~~~~~~~
|
|
|
|
For commonly used sequences of rules, some predefined sets are defined.
|
|
|
|
#. ``alliancesynth``, to apply the logical |Alliance| logical synthesis
|
|
set of tools. From |VHDL| to optimized |vst|. The set is as follow: ::
|
|
|
|
x.vbe => boom => x_boom.vbe => boog => x_boog.vst => loon => x.vst
|
|
|
|
An additional rule using ``vasy`` is triggered if the input format
|
|
is standard |VHDL|.
|
|
|
|
#. ``pnrcheck``, complete flow from |Verilog| to symbolic layout, with
|
|
|DRC| and |LVX| checks. Uses |Yosys| for synthesis.
|
|
|
|
#. ``routecheck``, perform the routing, the |DRC| and |LVX| check on an
|
|
already placed design. Use symbolic layout.
|
|
|