.. program:: ghdl
.. _USING:Synthesis:

Synthesis
#########

.. WARNING::
  This is experimental and work in progress! If you find crashes or unsupported features, please :ref:`report them <reporting_bugs>`!

Since ``v0.37``, GHDL features a built-in (experimental) synthesis kernel with two backends: ``synth`` and ``yosys-plugin``.
Currently, synthesis is supported as a front-end of other synthesis and technology mapping tools.
Hence, the netlists generated by GHDL are not optimised.

.. index:: synthesis command

.. _Synth:command:

Synthesis [``--synth``]
***********************

.. HINT::
  This command is useful for checking that a design can be synthesized, before actually running a complete synthesis
  tool. In fact, because this is expected to be much faster, it can be used as a frequent check.

.. TIP::
  Since GHDL's front-end supports multiple versions of the standard, but the synthesised netlists are generated using
  a subset of VHDL 1993, GHDL's synthesis features can be used as a preprocessor with tools that do support older
  versions of the standard, but which don't provide the most recent features.

.. option:: --synth <[options] primary_unit [secondary_unit]>

Elaborates for synthesis the design whose top unit is indicated by ``primary_unit [secondary_unit]``.

.. ATTENTION::
  All the units must have been analyzed; that is, the artifacts of previously executed :option:`-a` calls must exist.

.. option:: --synth <[options] files... -e primary_unit [secondary_unit]>

Analyses and elaborates for synthesis the files present on the command line only.
Elaboration starts from the top unit indicated by ``primary_unit [secondary_unit]``.

Currently, the output is a generic netlist using a (very simple) subset of VHDL 1993.
See :ghdlsharp:`1174` for on-going discussion about other output formats.

.. TIP::
  Files can be provided in any order.

.. _synthesis_options:

Synthesis options
*****************

.. HINT::
  Multiple pragmas are supported for preventing blocks of code from being synthesized:

  ``-- pragma|synopsys|synthesis (synthesis|translate)( |_)(on|off)``

  For example:

  * ``-- pragma translate off``
  * ``-- synthesis translate_on``
  * ``-- synopsys synthesis_off``

Due to GHDL's modular architecture (see :ref:`INT:Overview`), the synthesis kernel shares the VHDL parsing front-end with the
simulation back-ends. Hence, available options for synthesis are the same as for analysis and/or simulation elaboration
(see :ref:`GHDL:options`). In addition to those options, there are some synthesis specific options.

.. option:: -gNAME=VALUE

  Override top unit generic `NAME` with value `VALUE`. Similar to the run-time option :option:`-gGENERIC`.

  Example::

    $ ghdl --synth --std=08 -gDEPTH=12 my_unit

.. option:: --vendor-library=NAME

  Any unit from library NAME is a black box.

  Example::

    $ ghdl --synth --std=08 --vendor-library=vendorlib my_unit

.. option:: --no-formal

  Neither synthesize assert nor PSL.

  Example::

    $ ghdl --synth --std=08 --no-formal my_unit

.. option:: --no-assert-cover

  Disable automatic cover PSL assertion activation. If this option isn't used, GHDL generates
  `cover` directives for each `assert` directive (with an implication operator) automatically during synthesis.

  Example::

    $ ghdl --synth --std=08 --no-assert-cover my_unit

.. option:: --assert-assumes

  Treat all PSL asserts like PSL assumes. If this option is used, GHDL generates an `assume` directive
  for each `assert` directive during synthesis. This is similar to the `-assert-assumes`
  option of Yosys' `read_verilog <http://www.clifford.at/yosys/cmd_read_verilog.html>`_ command.

  Example::

    $ ghdl --synth --std=08 --assert-assumes my_unit

  As all PSL asserts are treated like PSL assumes, no `cover` directives are automatically generated for them,
  regardless of using the :option:`--no-assert-cover` or not.


.. option:: --assume-asserts

  Treat all PSL assumes like PSL asserts. If this option is used, GHDL generates an `assert` directive
  for each `assume` directive during synthesis. This is similar to the `-assume-asserts`
  option of Yosys' `read_verilog <http://www.clifford.at/yosys/cmd_read_verilog.html>`_ command.

  Example::

    $ ghdl --synth --std=08 --assume-asserts my_unit

  `cover` directives are automatically generated for the resulting asserts (with an implication operator)
  if :option:`--no-assert-cover` isn't used.

.. TIP::
  Furthermore there are lot of debug options available. Beware: these debug options should only used
  for debugging purposes as they aren't guaranteed to be stable during development of GHDL's synthesis feature.
  You can find them in the file :ghdlsrc:`ghdlsynth.adb <ghdldrv/ghdlsynth.adb>` in the procedure ``Decode_Option()``.

.. _Synth:plugin:

Yosys plugin
************

`ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_ is a module to use GHDL as a VHDL front-end for `Yosys
Open Synthesis Suite <http://www.clifford.at/yosys/>`_, a framework for optimised synthesis and technology mapping.
Artifacts generated by Yosys can be used in multiple open source and vendor tools to achieve P&R, formal verification,
etc. A relevant feature of combining GHDL and Yosys is that mixed-language (VHDL-Verilog) synthesis with open source
tools is possible.

The command line syntax for this plugin is the same as for :option:`--synth`, except that the command name (``--synth``)
is neither required nor supported. Instead, ``yosys``, ``yosys -m ghdl`` or ``yosys -m path/to/ghdl.so`` need to be used,
depending of how is the plugin built. See `README <https://github.com/ghdl/ghdl-yosys-plugin>`_ for building and installation
guidelines.

.. HINT::
  ghdl-yosys-plugin is a thin layer that converts the internal representation of :option:`--synth` to Yosys' C API. Hence,
  it is suggested to check the designs with :option:`--synth` before running synthesis with Yosys.

Convert (V)HDL to other formats
===============================

Yosys provides ``write_*`` commands for generating output netlists in different formats. Therefore, VHDL and/or Verilog
sources can be converted to EDIF, SMT, BTOR2, etc.

.. HINT:: For a comprehensive list of supported output formats (AIGER, BLIF, ILANG, JSON...), check out the
  `Yosys documentation <http://www.clifford.at/yosys/documentation.html>`_.

To Verilog
----------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_verilog filename.v'

To EDIF
-------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_edif filename.edif'

To SMT
------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_smt2 filename.smt2'

To BTOR2
--------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_btor filename.btor'

To FIRRTL
---------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_firrtl filename.firrtl'

To VHDL
-------

There is work in progress in `ghdl/ghdl-yosys-plugin#122 <https://github.com/ghdl/ghdl-yosys-plugin/pull/122>`_ for adding
a ``write_vhdl`` command to Yosys. That is the complement of what ghdl-yosys-plugin provides.
