From 2bea592952b8a9f9860bb646ddf72d26eac4ad29 Mon Sep 17 00:00:00 2001 From: umarcor <38422348+umarcor@users.noreply.github.com> Date: Fri, 10 Apr 2020 07:48:47 +0200 Subject: update doc (synth, overview, generics, etc.) (#1205) * doc: extend info about setting generics through the CLI * doc: rename 'Command Reference' to 'Additional Command Reference' * doc: use '``' instead of ':samp:' * doc: update info about synthesis * doc: add references to sources in internals/Overview * doc: add diagram to internals/Overview --- doc/using/CommandReference.rst | 4 +-- doc/using/InvokingGHDL.rst | 29 ------------------ doc/using/Simulation.rst | 14 +++++++-- doc/using/Synthesis.rst | 67 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 80 insertions(+), 34 deletions(-) create mode 100644 doc/using/Synthesis.rst (limited to 'doc/using') 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 `_ 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= 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 `! + +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 `_ is a module to use GHDL as a VHDL front-end for `Yosys +Open Synthesis Suite `_, 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 `_ 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. -- cgit v1.2.3