yosys/docs/source/getting_started/example_synth.rst

Synthesis starter
-----------------

.. 
   Typical phases of a synthesis flow are as follows:

   - Reading and elaborating the design
   - Higher-level synthesis and optimization

   - Converting ``always``-blocks to logic and registers
   - Perform coarse-grain optimizations (resource sharing, const folding, ...)
   - Handling of memories and other coarse-grain blocks
   - Extracting and optimizing finite state machines

   - Convert remaining logic to bit-level logic functions
   - Perform optimizations on bit-level logic functions
   - Map bit-level logic gates and registers to cell library
   - Write results to output file

A simple counter
~~~~~~~~~~~~~~~~

.. role:: yoscrypt(code)
   :language: yoscrypt

.. TODO:: move current example synth as mapping to cell libraries

   replace with a walk through of synth_ice40

This section covers an `example project`_ available in
``docs/source/code_examples/intro/``.  The project contains a simple ASIC
synthesis script (``counter.ys``), a digital design written in Verilog
(``counter.v``), and a simple CMOS cell library (``mycells.lib``).

.. _example project: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/intro

First, let's quickly look at the design:

.. literalinclude:: /code_examples/intro/counter.v
   :language: Verilog
   :caption: ``docs/source/code_examples/intro/counter.v``
   :linenos:
   :name: counter-v

This is a simple counter with reset and enable.  If the reset signal, ``rst``,
is high then the counter will reset to 0.  Otherwise, if the enable signal,
``en``, is high then the ``count`` register will increment by 1 each rising edge
of the clock, ``clk``.  

Loading the design
~~~~~~~~~~~~~~~~~~

Let's load the design into Yosys.  From the command line, we can call ``yosys
counter.v``.  This will open an interactive Yosys shell session and immediately
parse the code from ``counter.v`` and convert it into an Abstract Syntax Tree
(AST).  If you are interested in how this happens, there is more information in
the document, :doc:`/yosys_internals/flow/verilog_frontend`.  For now, suffice
it to say that we do this to simplify further processing of the design.  You
should see something like the following:

.. code:: console

   $ yosys counter.v

   -- Parsing `counter.v' using frontend ` -vlog2k' --

   1. Executing Verilog-2005 frontend: counter.v
   Parsing Verilog input from `counter.v' to AST representation.
   Storing AST representation for module `$abstract\counter'.
   Successfully finished Verilog frontend.

Now that we are in the interactive shell, we can call Yosys commands directly.
Let's run :yoscrypt:`hierarchy -check -top counter`.  This command declares that
the top level module is ``counter``, and that we want to expand it and any other
modules it may use.  Any other modules which were loaded are then discarded,
stopping the following commands from trying to work on them.  By passing the
``-check`` option there we are also telling the :cmd:ref:`hierarchy` command
that if the design includes any non-blackbox modules without an implementation
it should return an error.

.. TODO:: more on why :cmd:ref:`hierarchy` is important

.. note::

   :cmd:ref:`hierarchy` should always be the first command after the design has
   been read.

.. use doscon for a console-like display that supports the `yosys> [command]` format.

.. code:: doscon

   yosys> hierarchy -check -top counter

   2. Executing HIERARCHY pass (managing design hierarchy).

   3. Executing AST frontend in derive mode using pre-parsed AST for module `\counter'.
   Generating RTLIL representation for module `\counter'.

   3.1. Analyzing design hierarchy..
   Top module:  \counter

   3.2. Analyzing design hierarchy..
   Top module:  \counter
   Removing unused module `$abstract\counter'.
   Removed 1 unused modules.

Our circuit now looks like this:

.. figure:: /_images/code_examples/intro/counter_00.*
   :class: width-helper
   :name: counter-hierarchy

   ``counter`` module after :cmd:ref:`hierarchy`

.. seealso:: Advanced usage docs for :doc:`/using_yosys/more_scripting/load_design`

Elaboration
~~~~~~~~~~~

Notice that block that says "PROC" in :ref:`counter-hierarchy`?  Simple
operations like ``count + 2'd1`` can be extracted from our ``always @`` block in
:ref:`counter-v`.  This gives us the ``$add`` cell we see.  But control logic,
like the ``if .. else``; and memory elements, like the ``count <='2d0``; are not
so straightforward. To handle these, let us now introduce a new command:
:doc:`/cmd/proc`.

:cmd:ref:`proc` is a macro command; running a series of other commands which
work to convert the behavioral logic of processes into multiplexers and
registers.  We go into more detail on :cmd:ref:`proc` later in
:doc:`/using_yosys/synthesis/proc`, but for now let's see what happens when we
run it.

.. figure:: /_images/code_examples/intro/counter_proc.*
   :class: width-helper

   ``counter`` module after :cmd:ref:`proc`

The ``if`` statements are now modeled with ``$mux`` cells, and the memory
consists of a ``$dff`` cell.  That's getting a bit messy now, so let's chuck in
a call to :cmd:ref:`opt`.

.. figure:: /_images/code_examples/intro/counter_01.*
   :class: width-helper

   ``counter`` module after :cmd:ref:`opt`

Much better.  We can now see that the ``$dff`` and ``$mux`` cells have been
replaced with a single ``$sdffe``, using the built-in enable and reset ports
instead.

.. TODO:: a bit more on :cmd:ref:`opt` here

At this stage of a synthesis flow there are a few other commands we could run.
First off is :cmd:ref:`flatten`.  If we had any modules within our ``counter``,
this would replace them with their implementation.  Flattening the design like
this can allow for optimizations between modules which would otherwise be
missed.  Next is :doc:`/cmd/check`.

Depending on the target architecture, we might also run commands such as
:cmd:ref:`tribuf` with the ``-logic`` option and :cmd:ref:`deminout`.  These
remove tristate and inout constructs respectively, replacing them with logic
suitable for mapping to an FPGA.

.. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/proc`

The coarse-grain representation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At this stage, the design is in coarse-grain representation.  It still looks
recognizable, and cells are word-level operators with parametrizable width.
There isn't much else we can do for our ``counter`` example, but this is the
stage of synthesis where we do things like const propagation, expression
rewriting, and trimming unused parts of wires.

This is also where we convert our FSMs and hard blocks like DSPs or memories.
Such elements have to be inferred from patterns in the design and there are
special passes for each.  Detection of these patterns can also be affected by
optimizations and other transformations done previously.

.. TODO:: talk more about DSPs (and their associated commands)

Some of the commands we might use here are:

- :doc:`/cmd/fsm`,
- :doc:`/cmd/memory`,
- :doc:`/cmd/wreduce`,
- :doc:`/cmd/peepopt`,
- :doc:`/cmd/pmuxtree`,
- :doc:`/cmd/alumacc`, and
- :doc:`/cmd/share`.

.. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/fsm`, and 
   :doc:`/using_yosys/synthesis/memory`

Logic gate mapping
~~~~~~~~~~~~~~~~~~

.. TODO:: example_synth mapping to gates

:yoscrypt:`techmap` - Map coarse-grain RTL cells (adders, etc.) to fine-grain
logic gates (AND, OR, NOT, etc.).

When :cmd:ref:`techmap` is used without a map file, it uses a built-in map file
to map all RTL cell types to a generic library of built-in logic gates and
registers.

The built-in logic gate types are: ``$_NOT_``, ``$_AND_``, ``$_OR_``,
``$_XOR_``, and ``$_MUX_``.

See :doc:`/yosys_internals/formats/cell_library` for more about the internal
cells used.

.. figure:: /_images/code_examples/intro/counter_02.*
   :class: width-helper

   ``counter`` after :cmd:ref:`techmap`

Mapping to hardware
~~~~~~~~~~~~~~~~~~~

.. TODO:: example_synth mapping to hardware

:ref:`cmos_lib`

#. :yoscrypt:`dfflibmap -liberty mycells.lib` - Map registers to available
   hardware flip-flops.
#. :yoscrypt:`abc -liberty mycells.lib` - Map logic to available hardware gates.

.. figure:: /_images/code_examples/intro/counter_03.*
   :class: width-helper

   ``counter`` after hardware cell mapping

:cmd:ref:`dfflibmap`
    This command maps the internal register cell types to the register types
    described in a liberty file.

:cmd:ref:`hilomap`
    Some architectures require special driver cells for driving a constant hi or
    lo value. This command replaces simple constants with instances of such
    driver cells.

:cmd:ref:`iopadmap`
    Top-level input/outputs must usually be implemented using special I/O-pad
    cells. This command inserts such cells to the design.

:cmd:ref:`dfflegalize`
    Specify a set of supported FF cells/cell groups and convert all FFs to them.

.. seealso:: Advanced usage docs for :doc:`/yosys_internals/techmap`

.. _cmos_lib:

The CMOS cell library
^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: /code_examples/intro/mycells.lib
   :language: Liberty
   :caption: ``docs/source/code_examples/intro/mycells.lib``

The script file
~~~~~~~~~~~~~~~

#. :yoscrypt:`read_verilog -defer counter.v`
#. :yoscrypt:`clean` - Clean up the design (just the last step of
   :cmd:ref:`opt`).
#. :yoscrypt:`write_verilog synth.v` - Write final synthesis result to output
   file.

.. literalinclude:: /code_examples/intro/counter.ys
   :language: yoscrypt
   :caption: ``docs/source/code_examples/intro/counter.ys``

.. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/synth`