1.. program:: ghdl
2.. _USING:Synthesis:
3
4Synthesis
5#########
6
7.. WARNING::
8  This is experimental and work in progress! If you find crashes or unsupported features, please :ref:`report them <reporting_bugs>`!
9
10Since ``v0.37``, GHDL features a built-in (experimental) synthesis kernel with two backends: ``synth`` and ``yosys-plugin``.
11Currently, synthesis is supported as a front-end of other synthesis and technology mapping tools.
12Hence, the netlists generated by GHDL are not optimised.
13
14.. index:: synthesis command
15
16.. _Synth:command:
17
18Synthesis [``--synth``]
19***********************
20
21.. HINT::
22  This command is useful for checking that a design can be synthesized, before actually running a complete synthesis
23  tool. In fact, because this is expected to be much faster, it can be used as a frequent check.
24
25.. TIP::
26  Since GHDL's front-end supports multiple versions of the standard, but the synthesised netlists are generated using
27  a subset of VHDL 1993, GHDL's synthesis features can be used as a preprocessor with tools that do support older
28  versions of the standard, but which don't provide the most recent features.
29
30.. option:: --synth <[options] primary_unit [secondary_unit]>
31
32Elaborates for synthesis the design whose top unit is indicated by ``primary_unit [secondary_unit]``.
33
34.. ATTENTION::
35  All the units must have been analyzed; that is, the artifacts of previously executed :option:`-a` calls must exist.
36
37.. option:: --synth <[options] files... -e primary_unit [secondary_unit]>
38
39Analyses and elaborates for synthesis the files present on the command line only.
40Elaboration starts from the top unit indicated by ``primary_unit [secondary_unit]``.
41
42Currently, the output is a generic netlist using a (very simple) subset of VHDL 1993.
43See :ghdlsharp:`1174` for on-going discussion about other output formats.
44
45.. TIP::
46  Files can be provided in any order.
47
48.. _synthesis_options:
49
50Synthesis options
51*****************
52
53.. HINT::
54  Multiple pragmas are supported for preventing blocks of code from being synthesized:
55
56  ``-- pragma|synopsys|synthesis (synthesis|translate)( |_)(on|off)``
57
58  For example:
59
60  * ``-- pragma translate off``
61  * ``-- synthesis translate_on``
62  * ``-- synopsys synthesis_off``
63
64Due to GHDL's modular architecture (see :ref:`INT:Overview`), the synthesis kernel shares the VHDL parsing front-end with the
65simulation back-ends. Hence, available options for synthesis are the same as for analysis and/or simulation elaboration
66(see :ref:`GHDL:options`). In addition to those options, there are some synthesis specific options.
67
68.. option:: -gNAME=VALUE
69
70  Override top unit generic `NAME` with value `VALUE`. Similar to the run-time option :option:`-gGENERIC`.
71
72  Example::
73
74    $ ghdl --synth --std=08 -gDEPTH=12 my_unit
75
76.. option:: --vendor-library=NAME
77
78  Any unit from library NAME is a black box.
79
80  Example::
81
82    $ ghdl --synth --std=08 --vendor-library=vendorlib my_unit
83
84.. option:: --no-formal
85
86  Neither synthesize assert nor PSL.
87
88  Example::
89
90    $ ghdl --synth --std=08 --no-formal my_unit
91
92.. option:: --no-assert-cover
93
94  Disable automatic cover PSL assertion activation. If this option isn't used, GHDL generates
95  `cover` directives for each `assert` directive (with an implication operator) automatically during synthesis.
96
97  Example::
98
99    $ ghdl --synth --std=08 --no-assert-cover my_unit
100
101.. option:: --assert-assumes
102
103  Treat all PSL asserts like PSL assumes. If this option is used, GHDL generates an `assume` directive
104  for each `assert` directive during synthesis. This is similar to the `-assert-assumes`
105  option of Yosys' `read_verilog <http://www.clifford.at/yosys/cmd_read_verilog.html>`_ command.
106
107  Example::
108
109    $ ghdl --synth --std=08 --assert-assumes my_unit
110
111  As all PSL asserts are treated like PSL assumes, no `cover` directives are automatically generated for them,
112  regardless of using the :option:`--no-assert-cover` or not.
113
114
115.. option:: --assume-asserts
116
117  Treat all PSL assumes like PSL asserts. If this option is used, GHDL generates an `assert` directive
118  for each `assume` directive during synthesis. This is similar to the `-assume-asserts`
119  option of Yosys' `read_verilog <http://www.clifford.at/yosys/cmd_read_verilog.html>`_ command.
120
121  Example::
122
123    $ ghdl --synth --std=08 --assume-asserts my_unit
124
125  `cover` directives are automatically generated for the resulting asserts (with an implication operator)
126  if :option:`--no-assert-cover` isn't used.
127
128.. TIP::
129  Furthermore there are lot of debug options available. Beware: these debug options should only used
130  for debugging purposes as they aren't guaranteed to be stable during development of GHDL's synthesis feature.
131  You can find them in the file :ghdlsrc:`ghdlsynth.adb <ghdldrv/ghdlsynth.adb>` in the procedure ``Decode_Option()``.
132
133.. _Synth:plugin:
134
135Yosys plugin
136************
137
138`ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_ is a module to use GHDL as a VHDL front-end for `Yosys
139Open Synthesis Suite <http://www.clifford.at/yosys/>`_, a framework for optimised synthesis and technology mapping.
140Artifacts generated by Yosys can be used in multiple open source and vendor tools to achieve P&R, formal verification,
141etc. A relevant feature of combining GHDL and Yosys is that mixed-language (VHDL-Verilog) synthesis with open source
142tools is possible.
143
144The command line syntax for this plugin is the same as for :option:`--synth`, except that the command name (``--synth``)
145is neither required nor supported. Instead, ``yosys``, ``yosys -m ghdl`` or ``yosys -m path/to/ghdl.so`` need to be used,
146depending of how is the plugin built. See `README <https://github.com/ghdl/ghdl-yosys-plugin>`_ for building and installation
147guidelines.
148
149.. HINT::
150  ghdl-yosys-plugin is a thin layer that converts the internal representation of :option:`--synth` to Yosys' C API. Hence,
151  it is suggested to check the designs with :option:`--synth` before running synthesis with Yosys.
152
153Convert (V)HDL to other formats
154===============================
155
156Yosys provides ``write_*`` commands for generating output netlists in different formats. Therefore, VHDL and/or Verilog
157sources can be converted to EDIF, SMT, BTOR2, etc.
158
159.. HINT:: For a comprehensive list of supported output formats (AIGER, BLIF, ILANG, JSON...), check out the
160  `Yosys documentation <http://www.clifford.at/yosys/documentation.html>`_.
161
162To Verilog
163----------
164
165.. code-block:: shell
166
167    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_verilog filename.v'
168
169To EDIF
170-------
171
172.. code-block:: shell
173
174    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_edif filename.edif'
175
176To SMT
177------
178
179.. code-block:: shell
180
181    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_smt2 filename.smt2'
182
183To BTOR2
184--------
185
186.. code-block:: shell
187
188    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_btor filename.btor'
189
190To FIRRTL
191---------
192
193.. code-block:: shell
194
195    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_firrtl filename.firrtl'
196
197To VHDL
198-------
199
200There is work in progress in `ghdl/ghdl-yosys-plugin#122 <https://github.com/ghdl/ghdl-yosys-plugin/pull/122>`_ for adding
201a ``write_vhdl`` command to Yosys. That is the complement of what ghdl-yosys-plugin provides.
202