yosys/docs/source/CHAPTER_Approach.rst

.. _chapter:approach:

Approach
========

Yosys is a tool for synthesising (behavioural) Verilog HDL code to target
architecture netlists. Yosys aims at a wide range of application domains and
thus must be flexible and easy to adapt to new tasks. This chapter covers the
general approach followed in the effort to implement this tool.

Data- and control-flow
----------------------

The data- and control-flow of a typical synthesis tool is very similar to the
data- and control-flow of a typical compiler: different subsystems are called in
a predetermined order, each consuming the data generated by the last subsystem
and generating the data for the next subsystem (see :numref:`Fig. %s
<fig:approach_flow>`).

.. figure:: ../images/approach_flow.*
	:class: width-helper
	:name: fig:approach_flow

	General data- and control-flow of a synthesis tool

The first subsystem to be called is usually called a frontend. It does not
process the data generated by another subsystem but instead reads the user
input—in the case of a HDL synthesis tool, the behavioural HDL code.

The subsystems that consume data from previous subsystems and produce data for
the next subsystems (usually in the same or a similar format) are called passes.

The last subsystem that is executed transforms the data generated by the last
pass into a suitable output format and writes it to a disk file. This subsystem
is usually called the backend.

In Yosys all frontends, passes and backends are directly available as commands
in the synthesis script. Thus the user can easily create a custom synthesis flow
just by calling passes in the right order in a synthesis script.

Internal formats in Yosys
-------------------------

Yosys uses two different internal formats. The first is used to store an
abstract syntax tree (AST) of a Verilog input file. This format is simply called
AST and is generated by the Verilog Frontend. This data structure is consumed by
a subsystem called AST Frontend [1]_. This AST Frontend then generates a design
in Yosys' main internal format, the
Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does
that by first performing a number of simplifications within the AST
representation and then generating RTLIL from the simplified AST data structure.

The RTLIL representation is used by all passes as input and outputs. This has
the following advantages over using different representational formats between
different passes:

-  The passes can be rearranged in a different order and passes can be removed
   or inserted.

-  Passes can simply pass-thru the parts of the design they don't change without
   the need to convert between formats. In fact Yosys passes output the same
   data structure they received as input and performs all changes in place.

-  All passes use the same interface, thus reducing the effort required to
   understand a pass when reading the Yosys source code, e.g. when adding
   additional features.

The RTLIL representation is basically a netlist representation with the
following additional features:

-  An internal cell library with fixed-function cells to represent RTL datapath
   and register cells as well as logical gate-level cells (single-bit gates and
   registers).

-  Support for multi-bit values that can use individual bits from wires as well
   as constant bits to represent coarse-grain netlists.

-  Support for basic behavioural constructs (if-then-else structures and
   multi-case switches with a sensitivity list for updating the outputs).

-  Support for multi-port memories.

The use of RTLIL also has the disadvantage of having a very powerful format
between all passes, even when doing gate-level synthesis where the more advanced
features are not needed. In order to reduce complexity for passes that operate
on a low-level representation, these passes check the features used in the input
RTLIL and fail to run when unsupported high-level constructs are used. In such
cases a pass that transforms the higher-level constructs to lower-level
constructs must be called from the synthesis script first.

.. _sec:typusecase:

Typical use case
----------------

The following example script may be used in a synthesis flow to convert the
behavioural Verilog code from the input file design.v to a gate-level netlist
synth.v using the cell library described by the Liberty file :

.. code:: yoscrypt
   :number-lines:

   # read input file to internal representation
   read_verilog design.v

   # convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
   proc

   # perform some simple optimizations
   opt

   # convert high-level memory constructs to d-type flip-flops and multiplexers
   memory

   # perform some simple optimizations
   opt

   # convert design to (logical) gate-level netlists
   techmap

   # perform some simple optimizations
   opt

   # map internal register types to the ones from the cell library
   dfflibmap -liberty cells.lib

   # use ABC to map remaining logic to cells from the cell library
   abc -liberty cells.lib

   # cleanup
   opt

   # write results to output file
   write_verilog synth.v

A detailed description of the commands available in Yosys can be found in
:ref:`cmd_ref`.

.. [1]
   In Yosys the term pass is only used to refer to commands that operate on the
   RTLIL data structure.