From 8444c4d233aade37c218ef778bd1105dca693f48 Mon Sep 17 00:00:00 2001 From: umarcor Date: Thu, 22 Apr 2021 16:14:27 +0200 Subject: doc/synth: clarify that we need '-e' for resolving the ambiguity between a unit name and a filename --- doc/using/Synthesis.rst | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst index fccfad9c6..c1a954e31 100644 --- a/doc/using/Synthesis.rst +++ b/doc/using/Synthesis.rst @@ -8,7 +8,8 @@ Synthesis 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``. +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. @@ -31,18 +32,23 @@ See :option:`--out` and :ghdlsharp:`1174` for on-going discussion about other ou .. option:: --synth <[options] [library.]top_unit [arch]> -Elaborates for synthesis the design whose top unit is indicated by ``[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. + .. 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 top_unit [arch]> +.. option:: --synth <[options] files... -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]``. + 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. -.. TIP:: - Files can be provided in any order. + .. 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: @@ -164,13 +170,15 @@ etc. A relevant feature of combining GHDL and Yosys is that mixed-language (VHDL 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 +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 `_ 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. + 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 =============================== -- cgit v1.2.3