path: root/doc/using/Synthesis.rst

.. 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``]
***********************

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.

Moreover, 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.

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

.. option:: --synth <[options...] [library.]top_unit [arch]>

  Elaborates for synthesis the design whose top unit is indicated by ``[library.]top_unit [arch]``.

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

.. option:: --synth <[options...] file... -e [top_unit [arch]]>

  Analyses and elaborates for synthesis the files present on the command line only.
  Elaboration starts from the top unit indicated by ``[top_unit [arch]]``.
  If no top unit is specified, GHDL will try guessing it and a note will be printed.

  .. IMPORTANT::
    Files can be provided in any order, but ``-e`` must be provided after them.
    That is, ``--synth <[options...] files...>`` is NOT supported.
    This is because we want to unambiguously tell files and the unit specification apart.
    We don't want to rely on parsing the items and guessing whether we are dealing with files or a top unit name.
    In corner cases, a filename might exist which matches the name of a primary unit: ``ghdl synth name``.

.. _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.

.. 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()``.

.. 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 [library.]top_unit [arch]

.. option:: --out=<vhdl|raw-vhdl|verilog|dot|none|raw|dump>

  * **vhdl** *(default)*: equivalent to ``raw-vhdl``, but the original top-level unit is preserved unmodified, so the
    synthesized design can be simulated with the same testbench.

  * **raw-vhdl**: all statements are converted to a simple VHDL 1993
    netlist, for allowing instantiation in other synthesis tools
    without modern VHDL support.

  * **verilog**: generate a verilog netlist.

  * **dot**: generate a graphviz dot diagram of the netlist AST.

  * **none**: perform the synthesis, but do not generate any output; useful for frequent checks.

  * **raw**: print the internal representation of the design, for debugging purposes.

  * **dump**: similar to ``raw``, with even more internal details for debugging.

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

  Any unit from library NAME is a black box.

  Example::

    $ ghdl --synth --std=08 --vendor-library=vendorlib [library.]top_unit [arch]

Assertions, PSL and formal verification
=======================================

.. option:: --no-formal

  Neither synthesize assert nor PSL.

  Example::

    $ ghdl --synth --std=08 --no-formal [library.]top_unit [arch]

.. 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 [library.]top_unit [arch]

.. 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 [library.]top_unit [arch]

  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 [library.]top_unit [arch]

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

.. _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 `ghdl/ghdl-yosys-plugin: 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 top_unit [arch]; write_verilog filename.v'

To EDIF
-------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_edif filename.edif'

To SMT
------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_smt2 filename.smt2'

To BTOR2
--------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_btor filename.btor'

To FIRRTL
---------

.. code-block:: shell

    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; 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.