diff options
-rw-r--r-- | doc/_static/icons/.gitempty | 0 | ||||
-rw-r--r-- | doc/_static/images/.gitempty | 0 | ||||
-rw-r--r-- | doc/about.rst | 19 | ||||
-rw-r--r-- | doc/contribute.rst | 9 | ||||
-rw-r--r-- | doc/development/Documentation.rst | 2 | ||||
-rw-r--r-- | doc/development/GSOC.rst | 2 | ||||
-rw-r--r-- | doc/development/Synthesis.rst | 8 | ||||
-rw-r--r-- | doc/getting/index.rst | 7 | ||||
-rw-r--r-- | doc/index.rst | 4 | ||||
-rw-r--r-- | doc/internals/Frontend.rst | 8 | ||||
-rw-r--r-- | doc/internals/Overview.rst | 19 | ||||
-rw-r--r-- | doc/internals/img/internals.png | bin | 0 -> 80333 bytes | |||
-rw-r--r-- | doc/licenses.rst | 18 | ||||
-rw-r--r-- | doc/using/CommandReference.rst | 4 | ||||
-rw-r--r-- | doc/using/InvokingGHDL.rst | 29 | ||||
-rw-r--r-- | doc/using/Simulation.rst | 14 | ||||
-rw-r--r-- | doc/using/Synthesis.rst | 67 |
17 files changed, 134 insertions, 76 deletions
diff --git a/doc/_static/icons/.gitempty b/doc/_static/icons/.gitempty deleted file mode 100644 index e69de29bb..000000000 --- a/doc/_static/icons/.gitempty +++ /dev/null diff --git a/doc/_static/images/.gitempty b/doc/_static/images/.gitempty deleted file mode 100644 index e69de29bb..000000000 --- a/doc/_static/images/.gitempty +++ /dev/null diff --git a/doc/about.rst b/doc/about.rst index 32915a05f..3e8ea0dd9 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -20,31 +20,28 @@ However, VHDL was not designed as a general purpose language but as an `HDL`. As Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same meaning. At the same time, like a design written in another `HDL`, a set of VHDL sources can be transformed with a :dfn:`synthesis tool` into a netlist, that is, a detailed gate-level implementation. -The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). +The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Five revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_ and `2019 <https://ieeexplore.ieee.org/document/8938196>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). .. _INTRO:GHDL: What is GHDL? ============= -`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler and simulator that can execute (nearly) any VHDL program. GHDL is *not* a synthesis tool: you cannot create a netlist with GHDL (yet). +`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design. + +.. NOTE:: + For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist. Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator. See :ref:`USING:Synthesis` for further details regarding synthesis. Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an intermediary language such as `C` or `C++`. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language. -GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade| , both on x86 and on x86_64. +GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one named *mcode*) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, etc. -The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. +The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. -GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, the latest, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported. +GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported. Several third party projects are supported: `VUnit <https://vunit.github.io/>`_, `OSVVM <http://osvvm.org/>`_, `cocotb <https://github.com/potentialventures/cocotb>`_ (through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_), ... - -.. HINT:: - - Although synthesis is not available yet, there is some experimental support. See :ref:`DEV:Synthesis` for further info. - - .. _INTRO:WHO: Who uses GHDL? diff --git a/doc/contribute.rst b/doc/contribute.rst index 8b7710190..aeb2b4290 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -1,3 +1,5 @@ +.. program:: ghdl + .. only:: html .. exec:: @@ -38,9 +40,12 @@ Reporting bugs .. TIP:: * If the compiler crashes, this is a bug. Reliable tools never crash. * If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid input, this may be a bug. - * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. However, since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. + * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. Since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. * If a compiler message is not clear enough, please tell us. The error messages can be improved, but we do not have enough experience with them. +.. TIP:: + It is suggested to test synthesis features with :option:`--synth`, before processing the design with :ref:`Synth:plugin`. + Please, report issues of this kind through |SHIELD:bug-report|, as this allows us to categorize issues into groups and to assign developers to them. You can track the issue’s state and see how it’s getting solved. @@ -63,7 +68,7 @@ to assign developers to them. You can track the issue’s state and see how it†* Anything else that you think would be helpful. .. NOTE:: - If you don't know the LRM, be aware that an issue claimed as a bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL is not a solid argument. Some of them are supported by GHDL (see :ref:`IEEE_library_pitfalls`), but any such enhancement will have very low priority. + If you don't know the LRM, be aware that an issue claimed as a bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL variants is not a solid argument. Some of them are supported by GHDL (see :ref:`IEEE_library_pitfalls`), but any such enhancement will have very low priority. .. _requesting_enhancements: diff --git a/doc/development/Documentation.rst b/doc/development/Documentation.rst index 2ae76ff5e..364986542 100644 --- a/doc/development/Documentation.rst +++ b/doc/development/Documentation.rst @@ -3,7 +3,7 @@ Documentation ############# -* Development/Synthesis. Synthesis, ghdlsynth-beta, formal verification, etc. Copy the 'Usage' section from ghdlsynth's README (https://github.com/1138-4EB/ghdlsynth-beta#usage). +* Using/Synthesis: formal verification, etc. * Development/libghdl. How to interact with GHDL through ``libghdl`` and/or ``libghdl-py``. * Development/Related Projects. Brief discussion about similarities/differences with other open source projects such as rust_hdl or pyVHDLParser. * Usage/Docker. Probably copy/convert :file:`README.md` and :file:`USE_CASES.md` in ghdl/docker :ghdlsharp:`166`. diff --git a/doc/development/GSOC.rst b/doc/development/GSOC.rst index 813a2aa64..723afb832 100644 --- a/doc/development/GSOC.rst +++ b/doc/development/GSOC.rst @@ -8,7 +8,7 @@ This page contains ideas for enhancing GHDL that can fit internship programs, su VHDL frontend for Yosys ======================= -`Yosys <https://github.com/YosysHQ/yosys>`_ is an open-source synthesis tool with built-in Verilog support and partial SystemVerilog support. `ghdlsynth-beta <https://github.com/tgingold/ghdlsynth-beta>`_ is an experimental plugin for Yosys that allows to use GHDL (precisely, `libghdl <https://github.com/ghdl/ghdl#project-structure>`_) as a frontend for Yosys. Although functional, :ref:`DEV:Synthesis` is work in progress: multiple features are not supported yet, and others need to be tested for bugs. +`Yosys <https://github.com/YosysHQ/yosys>`_ is an open-source synthesis tool with built-in Verilog support and partial SystemVerilog support. :ref:`Synth:plugin` is an experimental plugin for Yosys that allows to use GHDL. Although functional, :ref:`USING:Synthesis` is work in progress: multiple features are not supported yet, and others need to be tested for bugs. .. NOTE:: * `FOSSI GSOC 2019 | VHDL front-end for Yosys <https://fossi-foundation.org/gsoc19-ideas.html#vhdl-front-end--for-yosys>`_ diff --git a/doc/development/Synthesis.rst b/doc/development/Synthesis.rst deleted file mode 100644 index bcd23ff70..000000000 --- a/doc/development/Synthesis.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _DEV:Synthesis: - -Synthesis -######### - -There is an experimental command (``--synth``) to generate RTL netlists (the format, VHDL or EDIF, is yet to be defined) from synthesisable code. For command ``--synth`` to be available, GHDL must be configured/built with option ``--enable-synth`` (GCC 8.1>= required, due to some new GNAT features which are only available in recent releases). Since this is a proof-of-concept, the output is mostly a dump of an internal structure for now. Therefore, it is not very useful, except for debugging. - -Moreover, `ghdlsynth <https://github.com/tgingold/ghdlsynth-beta>`_ is a complementary repository that lets GHDL to be loaded by `yosys <http://www.clifford.at/yosys/>`_ as a frontend plugin module, in order to generate bitstreams for some FPGA devices. diff --git a/doc/getting/index.rst b/doc/getting/index.rst index f64e44caf..591c4d95e 100644 --- a/doc/getting/index.rst +++ b/doc/getting/index.rst @@ -10,13 +10,18 @@ GHDL can be downloaded as a `zip-file <https://github.com/ghdl/ghdl/archive/mast offers HTTPS and SSH as transfer protocols. See the :ref:`RELEASE:Sources` page for further details. -.. IMPORTANT :: +.. IMPORTANT:: Since GHDL is written in `Ada`, independently of the code generator you use, the a compiler is required. Most GNU/Linux package managers provide a package named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`, can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits). Then, untar and run the doinstall script. +.. ATTENTION:: + Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which + are not available in previous releases. Users with older versions (who don't need synthesis) + can configure GHDL with option ``--no-synth``. + .. rubric :: Available back-ends GHDL currently supports three different back-ends (code generators): diff --git a/doc/index.rst b/doc/index.rst index 4a24216f5..c675383be 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -99,8 +99,9 @@ examples/quick_start/README using/InvokingGHDL using/Simulation - using/Foreign + using/Synthesis using/CommandReference + using/Foreign using/ImplementationOfVHDL using/ImplementationOfVITAL examples/README @@ -113,7 +114,6 @@ :caption: Development :hidden: - development/Synthesis development/Debugging development/CodingStyle development/Roadmap diff --git a/doc/internals/Frontend.rst b/doc/internals/Frontend.rst index 6d5e1da5c..fd5abd4e6 100644 --- a/doc/internals/Frontend.rst +++ b/doc/internals/Frontend.rst @@ -3,7 +3,13 @@ Front-end ######### -Input files (or source files) are read by `files_map.ad[sb]`. Only regular files can be read, because they are read entirely before being scanned. This simplifies the scanner, but this also allows to have a unique index for each character in any file. Therefore the source location is a simple 32-bit integer whose type is `Location_Type`. From the location, `files_map` can deduce the source file (type is `Source_File_Entry`) and then the offset in the source file. There is a line table for each source file in order to speed-up the conversion from file offset to line number and column number. +Input files (or source files) are read by `files_map.ad[sb]`. Only regular files can be +read, because they are read entirely before being scanned. This simplifies the scanner, +but this also allows to have a unique index for each character in any file. +Therefore the source location is a simple 32-bit integer whose type is `Location_Type`. +From the location, `files_map` can deduce the source file (type is `Source_File_Entry`) +and then the offset in the source file. There is a line table for each source file in +order to speed-up the conversion from file offset to line number and column number. The scanner (file :file:`vhdl-scanner.ad[sb]`) reads the source files and creates token from them. The tokens are defined in file :file:`vhdl-tokens.ads`. Tokens are scanned diff --git a/doc/internals/Overview.rst b/doc/internals/Overview.rst index 3be8772b4..fd29f5832 100644 --- a/doc/internals/Overview.rst +++ b/doc/internals/Overview.rst @@ -3,16 +3,23 @@ Overview ######## -`GHDL` is architectured like a traditionnal compiler. It has: +.. image:: img/internals.png + :width: 350px + :align: center -* a driver (sources in :file:`src/ghdldrv`) to call the programs (compiler, assembler, linker) if needed. +`GHDL` is architectured like a traditionnal compiler. It has: -* a library (sources in :file:`src/grt`) to help execution at run-time. +* a driver (sources in :ghdlsrc:`src/ghdldrv <ghdldrv>`) to call the programs (compiler, assembler, linker) if needed. -* a front-end (sources in :file:`src/vhdl`) to parse and analyse VHDL. +* a runtime library named GRT (sources in :ghdlsrc:`src/grt <grt>`) to help execution at run-time. This ensures that execution is cycle-accurate. -* a back-end (in fact many, sources are in :file:`src/ortho`) to generate code. +* a front-end (sources in :ghdlsrc:`src/vhdl <vhdl>`) to parse and analyse VHDL. See :ref:`INT:Frontend` and :ref:`INT:AST`. -The architecture is modular. For example, it is possible to use the front-end in the `libghdl` library for the language server or to do synthesis (sources in :file:`src/synth`) instead of code generation. +* multiple back-ends to generate either code or netlists. + + * Three for :ref:`simulation <USING:Simulation>` (sources are in :ghdlsrc:`src/ortho <ortho>`): mcode, LLVM and GCC. See :ref:`BUILD`. + * Two for :ref:`synthesis <USING:Synthesis>` (sources in :ghdlsrc:`src/synth <synth>`): :ref:`--synth <Synth:command>` and :ref:`Synth:plugin`. + +The architecture is modular. For example, the front-end in the ``libghdl`` library is used for the language server. The main work is performed by the front-end, which is documented in the next chapter. diff --git a/doc/internals/img/internals.png b/doc/internals/img/internals.png Binary files differnew file mode 100644 index 000000000..cc6714287 --- /dev/null +++ b/doc/internals/img/internals.png diff --git a/doc/licenses.rst b/doc/licenses.rst index d979d7cc1..aa2a65087 100644 --- a/doc/licenses.rst +++ b/doc/licenses.rst @@ -3,24 +3,24 @@ Copyrights | Licenses ##################### -- The GHDL front-end package :samp:`std.textio`, and the runtime library :samp:`grt` are given under :ref:`LIC:GPLv2`. +- The GHDL front-end package ``std.textio``, and the runtime library ``GRT`` are given under :ref:`LIC:GPLv2`. - The documentation is given under :ref:`LIC:CC-BY-SA`. .. WARNING:: - As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without the VHDL sources. To my mind, this is not a real restriction, since it is pointless to distribute VHDL executable. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. + As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without allowing access to the VHDL sources. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. - The following packages are copyrighted by third parties (see corresponding sources for more information): - - These from library :samp:`ieee` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`_ : + - These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`_ : - - :samp:`numeric_bit` and :samp:`numeric_std`: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 <http://ieeexplore.ieee.org/document/592543/>`_ ] - - :samp:`std_logic_1164`, :samp:`Math_Real` and :samp:`Math_Complex` - - :samp:`VITAL_Primitives`, :samp:`VITAL_Timing` and :samp:`VITAL_Memory` [see also `IEEE 1076.4 <http://ieeexplore.ieee.org/document/954750/>`_ ] + - ``numeric_bit`` and ``numeric_std``: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 <http://ieeexplore.ieee.org/document/592543/>`_ ] + - ``std_logic_1164``, ``Math_Real`` and ``Math_Complex`` + - ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` [see also `IEEE 1076.4 <http://ieeexplore.ieee.org/document/954750/>`_ ] - The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice. - - :samp:`synopsys` directory: :samp:`std_logic_arith`, :samp:`std_logic_signed`, :samp:`std_logic_unsigned` and :samp:`std_logic_textio` are copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`_ - - :samp:`mentor` directory: :samp:`std_logic_arith` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_ + - ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`_ + - ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_ .. _LIC:GPLv2: @@ -63,7 +63,7 @@ Jensen, Adam FreeBSD builds Koch, Markus vendor pre-compile script for Lattice (GNU/Linux) Koontz, David Mac OSX builds, LRM compliance work, bugfix analyses Lehmann, Patrick Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. -Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix RTD theme +Martinez-Corral, Unai Docker, CI, Docs van Rantwijk, Joris Debian packaging ========================= ============================================================ diff --git a/doc/using/CommandReference.rst b/doc/using/CommandReference.rst index 17ae4bc40..f66335d2c 100644 --- a/doc/using/CommandReference.rst +++ b/doc/using/CommandReference.rst @@ -1,8 +1,8 @@ .. program:: ghdl .. _REF:Command: -Command Reference -################# +Additional Command Reference +############################ .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index e393892c2..1857fccfc 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -227,35 +227,6 @@ Theses rules can then be integrated in another Makefile. .. _GHDL:options: -Synthesis command -================= - -GHDL supports synthesis, but only as a front-end: it generates a -generic netlist that is not optimized. - -.. index:: synthesis command - -.. _Synth:command: - -Synthesis [``--synth``] ------------------------ - -.. option:: --synth <[options] [unit]> - -.. option:: --synth <[options] files -e [unit]> - -The first command elaborates for synthesis the design whose top unit -is indicated by ``unit``. All the units must have been analyzed. The -second form analyze only the files present on the command line and -then elaborate them starting from the top ``unit``. A generic netlist -is then displayed using a very simple vhdl subset. - -The command line is the same as the ``ghdl`` command added to -Yosys by the ghdl plugin except ``--synth`` is not present. With this -plugin, it is possible to optimize and map to a target the netlist. - -This command is useful for checking that a design could be synthesized. - Options ======= diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index e97212375..64e4f36c6 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -37,9 +37,17 @@ Here is the list of the most useful options. For further info, see :ref:`DEV:Deb $ ghdl -r --std=08 my_unit -gDEPTH=12 - .. WARNING:: - This is currently a run option; but in the future it will be deprecated to - become an elaboration option only. + .. NOTE:: + This is currently a run option; but in the (not near) future it might be deprecated to + become an elaboration option only. As a result, now you can generate a single binary and + execute it multiple times with different arguments. That might not be possible in the future. + + As explained in :option:`-e`, performing a complete elaboration in terms of the LRM requires + to get rid of the compile and link model. This is mostly because delaying certain elaboration + steps to the runtime prevents elaboration-time optimisions. + + .. HINT:: + Currently, GHDL has limited support for generic types in the CLI. It is suggested to use strings or integers. Nonetheless, project `JSON-for-VHDL <https://github.com/Paebbels/JSON-for-VHDL>`_ allows to encode a set of parameters as stringified JSON, and it provides VHDL functions to read specific values from it. It is valid for synthesis. .. option:: --assert-level=<LEVEL> diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst new file mode 100644 index 000000000..c236152e6 --- /dev/null +++ b/doc/using/Synthesis.rst @@ -0,0 +1,67 @@ +.. 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. + +.. NOTE:: + 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`). + +.. 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. + +.. _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. |