diff options
| -rw-r--r-- | doc/about.rst | 3 | ||||
| -rw-r--r-- | doc/contribute.rst | 7 | ||||
| -rw-r--r-- | doc/index.rst | 6 | ||||
| -rw-r--r-- | doc/licenses.rst | 7 | ||||
| -rw-r--r-- | doc/references/CommandReference.rst | 15 | ||||
| -rw-r--r-- | doc/references/ImplementationOfVHDL.rst | 272 | ||||
| -rw-r--r-- | doc/shields.json | 2 | ||||
| -rw-r--r-- | doc/using/Foreign.rst | 339 | ||||
| -rw-r--r-- | doc/using/InvokingGHDL.rst | 6 | ||||
| -rw-r--r-- | doc/using/Simulation.rst | 19 |
10 files changed, 393 insertions, 283 deletions
diff --git a/doc/about.rst b/doc/about.rst index e1018767a..6558b77d8 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -41,6 +41,9 @@ GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee. 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 supported yet, there is some experimental code. On the one hand, subcommand ``--synth`` is a proof-of-concept to generate a netlist (RTL) with GHDL. For now, it is a dump of an internal structure, so it is not very useful, except for debugging. In the future, it might be an EDIF or VHDL file. On the other hand, `ghdlsynth <https://github.com/tgingold/ghdlsynth-beta>`_ is a complementary repository that allows GHDL to be loaded by `yosys <http://www.clifford.at/yosys/>`_ as a module, which can be used to generate bitstreams for some FPGA devices. + .. _INTRO:WHO: Who uses GHDL? diff --git a/doc/contribute.rst b/doc/contribute.rst index ee8bbf0de..16165e839 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -1,4 +1,9 @@ -.. include:: shields.inc +.. only:: html + + .. exec:: + from helpers import createShields + createShields('shields') + .. _INTRO:Contributing: Contributing diff --git a/doc/index.rst b/doc/index.rst index c29deabda..2df9c2c9f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -21,6 +21,9 @@ LRM) is a plus. News **** + 03.03.2019 - GHDL v0.36 was released. + ========================================= + 23.02.2019 - GHDL v0.36-rc1 was released. ========================================= @@ -50,6 +53,8 @@ LRM) is a plus. .. only:: latex + .. rubric:: 03.03.2019 - GHDL v0.36 was released. + .. rubric:: 23.02.2019 - GHDL v0.36-rc1 was released. .. rubric:: 29.11.2018 - GHDL 20181129 was released. @@ -87,6 +92,7 @@ LRM) is a plus. using/QuickStartGuide using/InvokingGHDL using/Simulation + using/Foreign .. raw:: latex diff --git a/doc/licenses.rst b/doc/licenses.rst index e9aa93836..00c5620de 100644 --- a/doc/licenses.rst +++ b/doc/licenses.rst @@ -1,4 +1,3 @@ -.. include:: shields.inc .. _INTRO:Copyrights: Copyrights | Licenses @@ -68,6 +67,12 @@ Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix RTD them van Rantwijk, Joris Debian packaging ========================= ============================================================ +.. only:: html + + .. exec:: + from helpers import createShields + createShields('shields') + Only those who made substantial contributions are shown in the table above, but many others contributed with minor patches. You can find a list at |SHIELD:contributors| With apologies to anyone who ought to be either on this table or in the GitHub contributor list, but isn't. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either the late gna! website or `sourceforge.net/p/ghdl-updates/tickets <https://sourceforge.net/p/ghdl-updates/tickets/>`_. diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index de6ff5415..2b53e51f3 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -116,6 +116,8 @@ Lines [``--lines``] Display on the standard output lines of files preceded by line number. +.. _gccllvm-only-programs: + GCC/LLVM only commands ====================== @@ -128,6 +130,9 @@ Bind [``--bind``] Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. +.. HINT:: + Currently, the objects generated by ``--bind`` are created in the working directory. This behaviour is different from other object files generated with ``-a``, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path. + .. index:: cmd GCC/LLVM linking Link [``--link``] @@ -144,7 +149,13 @@ List link [``--list-link``] .. option:: --list-link <primary_unit [secondary_unit]> -This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable. This command is intended to add object files in a link of a foreign program. +This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path. + +.. HINT:: + One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX` is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done: + + * Filter the output of ``--list-link`` with e.g. ``sed``. + * Provide an additional non-anonymous version script: ``-Wl,-Wl,--version-script=file.ver``. Options ======= @@ -175,6 +186,8 @@ Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a p Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. +.. _passing-options-to-other-programs: + Passing options to other programs ================================= diff --git a/doc/references/ImplementationOfVHDL.rst b/doc/references/ImplementationOfVHDL.rst index 90cedc825..55f4f5141 100644 --- a/doc/references/ImplementationOfVHDL.rst +++ b/doc/references/ImplementationOfVHDL.rst @@ -213,275 +213,3 @@ GHDL follows the VHDL LRM (the manual which defines VHDL) more strictly than other VHDL tools. You could try to relax the restrictions by using the :option:`--std=93c`, :option:`-fexplicit`, :option:`-frelaxed-rules` and :option:`--warn-no-vital-generic`. - -Interfacing to other languages -============================== - -.. index:: interfacing - -.. index:: other languages - -.. index:: foreign - -.. index:: VHPI - -.. index:: VHPIDIRECT - -Interfacing with foreign languages is possible only on GNU/Linux systems. - -You can define a subprogram in a foreign language (such as `C` or -`Ada`) and import it into a VHDL design. - -Foreign declarations --------------------- - -Only subprograms (functions or procedures) can be imported, using the foreign -attribute. In this example, the `sin` function is imported: - -.. code-block:: VHDL - - package math is - function sin (v : real) return real; - attribute foreign of sin : function is "VHPIDIRECT sin"; - end math; - - package body math is - function sin (v : real) return real is - begin - assert false severity failure; - end sin; - end math; - - -A subprogram is made foreign if the `foreign` attribute decorates -it. This attribute is declared in the 1993 revision of the -``std.standard`` package. Therefore, you cannot use this feature in -VHDL 1987. - -The decoration is achieved through an attribute specification. The -attribute specification must be in the same declarative part as the -subprogram and must be after it. This is a general rule for specifications. -The value of the specification must be a locally static string. - -Even when a subprogram is foreign, its body must be present. However, since -it won't be called, you can make it empty or simply put an assertion. - -The value of the attribute must start with ``VHPIDIRECT`` (an -upper-case keyword followed by one or more blanks). The linkage name of the -subprogram follows. - -.. _Restrictions_on_foreign_declarations: - -Restrictions on foreign declarations ------------------------------------- - -Any subprogram can be imported. GHDL puts no restrictions on foreign -subprograms. However, the representation of a type or of an interface in a -foreign language may be obscure. Most non-composite types are easily imported: - - -*integer types* - They are represented by a 32 bit word. This generally corresponds to - `int` for `C` or `Integer` for `Ada`. - -*physical types* - They are represented by a 64 bit word. This generally corresponds to the - `long long` for `C` or `Long_Long_Integer` for `Ada`. - -*floating point types* - They are represented by a 64 bit floating point word. This generally - corresponds to `double` for `C` or `Long_Float` for `Ada`. - -*enumeration types* - They are represented by an 8 bit word, or, if the number of literals is - greater than 256, by a 32 bit word. There is no corresponding C type, since arguments are - not promoted. - -Non-composite types are passed by value. For the `in` mode, this -corresponds to the `C` or `Ada` mechanism. The `out` and -`inout` interfaces of non-composite types are gathered in a record -and this record is passed by reference as the first argument to the -subprogram. As a consequence, you shouldn't use `in` and -`inout` modes in foreign subprograms, since they are not portable. - -Records are represented like a `C` structure and are passed by reference -to subprograms. - -Arrays with static bounds are represented like a `C` array, whose -length is the number of elements, and are passed by reference to subprograms. - -Unconstrained arrays are represented by a fat pointer. Do not use unconstrained -arrays in foreign subprograms. - -Accesses to an unconstrained array are fat pointers. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. - -Files are represented by a 32 bit word, which corresponds to an index -in a table. - -.. _Linking_with_foreign_object_files: - -Linking with foreign object files ---------------------------------- - -You may add additional files or options during the link using the -*-Wl,* of `GHDL`, as described in :ref:`Elaboration:command`. -For example:: - - ghdl -e -Wl,-lm math_tb - -will create the :file:`math_tb` executable with the :file:`lm` (mathematical) -library. - -Note the :file:`c` library is always linked with an executable. - -.. _Starting_a_simulation_from_a_foreign_program: - -Starting a simulation from a foreign program --------------------------------------------- - -You may run your design from an external program. You just have to call -the ``ghdl_main`` function which can be defined: - -in C: - -.. code-block:: C - - extern int ghdl_main (int argc, char **argv); - -in Ada: - -.. code-block:: Ada - - with System; - ... - function Ghdl_Main (Argc : Integer; Argv : System.Address) - return Integer; - pragma import (C, Ghdl_Main, "ghdl_main"); - - -This function must be called once, and returns 0 at the end of the simulation. -In case of failure, this function does not return. This has to be fixed. - -.. _Linking_with_Ada: - -Linking with Ada ----------------- - -As explained previously in :ref:`Starting_a_simulation_from_a_foreign_program`, -you can start a simulation from an `Ada` program. However the build -process is not trivial: you have to elaborate your `Ada` program and your -`VHDL` design. - -First, you have to analyze all your design files. In this example, we -suppose there is only one design file, :file:`design.vhdl`. - -:: - - $ ghdl -a design.vhdl - -Then, bind your design. In this example, we suppose the entity at the -design apex is ``design``. - -:: - - $ ghdl --bind design - -Finally, compile, bind your `Ada` program and link it with your `VHDL` -design:: - - $ gnatmake my_prog -largs `ghdl --list-link design` - - -Using GRT from Ada ------------------- - -.. warning:: - This topic is only for advanced users who know how to use `Ada` - and `GNAT`. This is provided only for reference; we have tested - this once before releasing `GHDL` 0.19, but this is not checked at - each release. - -The simulator kernel of `GHDL` named :dfn:`GRT` is written in -`Ada95` and contains a very light and slightly adapted version -of `VHPI`. Since it is an `Ada` implementation it is -called :dfn:`AVHPI`. Although being tough, you may interface to `AVHPI`. - -For using `AVHPI`, you need the sources of `GHDL` and to recompile -them (at least the `GRT` library). This library is usually compiled with -a `No_Run_Time` pragma, so that the user does not need to install the -`GNAT` runtime library. However, you certainly want to use the usual -runtime library and want to avoid this pragma. For this, reset the -`GRT_PRAGMA_FLAG` variable. - -:: - - $ make GRT_PRAGMA_FLAG= grt-all - - -Since `GRT` is a self-contained library, you don't want -`gnatlink` to fetch individual object files (furthermore this -doesn't always work due to tricks used in `GRT`). For this, -remove all the object files and make the :file:`.ali` files read-only. - -:: - - $ rm *.o - $ chmod -w *.ali - - -You may then install the sources files and the :file:`.ali` files. I have never -tested this step. - -You are now ready to use it. - -Here is an example, :file:`test_grt.adb` which displays the top -level design name. - -.. code-block:: Ada - - with System; use System; - with Grt.Avhpi; use Grt.Avhpi; - with Ada.Text_IO; use Ada.Text_IO; - with Ghdl_Main; - - procedure Test_Grt is - -- VHPI handle. - H : VhpiHandleT; - Status : Integer; - - -- Name. - Name : String (1 .. 64); - Name_Len : Integer; - begin - -- Elaborate and run the design. - Status := Ghdl_Main (0, Null_Address); - - -- Display the status of the simulation. - Put_Line ("Status is " & Integer'Image (Status)); - - -- Get the root instance. - Get_Root_Inst(H); - - -- Disp its name using vhpi API. - Vhpi_Get_Str (VhpiNameP, H, Name, Name_Len); - Put_Line ("Root instance name: " & Name (1 .. Name_Len)); - end Test_Grt; - - -First, analyze and bind your design:: - - $ ghdl -a counter.vhdl - $ ghdl --bind counter - - -Then build the whole:: - - $ gnatmake test_grt -aL`grt_ali_path` -aI`grt_src_path` -largs - `ghdl --list-link counter` - - -Finally, run your design:: - - $ ./test_grt - Status is 0 - Root instance name: counter diff --git a/doc/shields.json b/doc/shields.json index e0be16551..8224fe0f9 100644 --- a/doc/shields.json +++ b/doc/shields.json @@ -39,7 +39,7 @@ "src": "badge/new-feature--request-yellowgreen.svg?logo=github", "target": "gh:ghdl/ghdl/issues/new?template=feature_request.md", "alt": "Open new feature request at GitHub" }, - "lissues-open": { + "issues-open": { "src": "github/issues/ghdl/ghdl.svg?logo=github", "target": "gh:ghdl/ghdl/issues", "alt": "Open issues" }, diff --git a/doc/using/Foreign.rst b/doc/using/Foreign.rst new file mode 100644 index 000000000..7a50e4358 --- /dev/null +++ b/doc/using/Foreign.rst @@ -0,0 +1,339 @@ +.. FOREIGN: + +Interfacing to other languages +############################## + +.. index:: interfacing + +.. index:: other languages + +.. index:: foreign + +.. index:: VHPI + +.. index:: VHPIDIRECT + +Interfacing with foreign languages through VHPIDIRECT is possible any platform. +You can define a subprogram in a foreign language (such as `C` or +`Ada`) and import it into a VHDL design. + +.. HINT:: + VHPIDIRECT is the simplest way to call C code from VHDL. VHPI is a complex API to interface C and VHDL, which allows to + inspect the hierarchy, set callbacks and/or assign signals. GHDL does not support VHPI. For these kind of features, it is + suggested to use VPI instead (see :ref:`VPI_build_commands`). + +Foreign declarations +==================== + +Only subprograms (functions or procedures) can be imported, using the foreign +attribute. In this example, the `sin` function is imported: + +.. code-block:: VHDL + + package math is + function sin (v : real) return real; + attribute foreign of sin : function is "VHPIDIRECT sin"; + end math; + + package body math is + function sin (v : real) return real is + begin + assert false severity failure; + end sin; + end math; + + +A subprogram is made foreign if the `foreign` attribute decorates +it. This attribute is declared in the 1993 revision of the +``std.standard`` package. Therefore, you cannot use this feature in +VHDL 1987. + +The decoration is achieved through an attribute specification. The +attribute specification must be in the same declarative part as the +subprogram and must be after it. This is a general rule for specifications. +The value of the specification must be a locally static string. + +Even when a subprogram is foreign, its body must be present. However, since +it won't be called, you can make it empty or simply put an assertion. + +The value of the attribute must start with ``VHPIDIRECT`` (an +upper-case keyword followed by one or more blanks). The linkage name of the +subprogram follows. + +.. _Restrictions_on_foreign_declarations: + +Restrictions on foreign declarations +------------------------------------ + +Any subprogram can be imported. GHDL puts no restrictions on foreign +subprograms. However, the representation of a type or of an interface in a +foreign language may be obscure. Most non-composite types are easily imported: + + +*integer types* + They are represented by a 32 bit word. This generally corresponds to + `int` for `C` or `Integer` for `Ada`. + +*physical types* + They are represented by a 64 bit word. This generally corresponds to the + `long long` for `C` or `Long_Long_Integer` for `Ada`. + +*floating point types* + They are represented by a 64 bit floating point word. This generally + corresponds to `double` for `C` or `Long_Float` for `Ada`. + +*enumeration types* + They are represented by an 8 bit word, or, if the number of literals is + greater than 256, by a 32 bit word. There is no corresponding C type, since arguments are + not promoted. + +Non-composite types are passed by value. For the `in` mode, this +corresponds to the `C` or `Ada` mechanism. The `out` and +`inout` interfaces of non-composite types are gathered in a record +and this record is passed by reference as the first argument to the +subprogram. As a consequence, you shouldn't use `in` and +`inout` modes in foreign subprograms, since they are not portable. + +Records are represented like a `C` structure and are passed by reference +to subprograms. + +Arrays with static bounds are represented like a `C` array, whose +length is the number of elements, and are passed by reference to subprograms. + +Unconstrained arrays are represented by a fat pointer. Do not use unconstrained +arrays in foreign subprograms. + +Accesses to an unconstrained array are fat pointers. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. + +Files are represented by a 32 bit word, which corresponds to an index +in a table. + +.. _Linking_with_foreign_object_files: + +Linking foreign object files to GHDL +==================================== + +You may add additional files or options during the link of `GHDL` using +``-Wl,`` as described in :ref:`passing-options-to-other-programs`. +For example:: + + ghdl -e -Wl,-lm math_tb + +will create the :file:`math_tb` executable with the :file:`lm` (mathematical) +library. + +Note the :file:`c` library is always linked with an executable. + +.. _Starting_a_simulation_from_a_foreign_program: + +Wrapping and starting a GHDL simulation from a foreign program +================================================= + +You may run your design from an external program. You just have to call +the ``ghdl_main`` function which can be defined: + +in C: + +.. code-block:: C + + extern int ghdl_main (int argc, char **argv); + +in Ada: + +.. code-block:: Ada + + with System; + ... + function Ghdl_Main (Argc : Integer; Argv : System.Address) + return Integer; + pragma import (C, Ghdl_Main, "ghdl_main"); + + +This function must be called once, and returns 0 at the end of the simulation. + +.. _Linking_with_Ada: + +Linking GHDL to Ada/C +===================== + +As explained previously in :ref:`Starting_a_simulation_from_a_foreign_program`, +you can start a simulation from an `Ada` or `C` program. However the build +process is not trivial: you have to elaborate your program and your +`VHDL` design. + +.. HINT:: + If the foreign language is C, this procedure is equivalent to the one described in + :ref:`Linking_with_foreign_object_files`, which is easier. Thus, this procedure is + explained for didactic purposes. When suitable, we suggest to use ``-e`` instead + of ``--bind`` and ``--list-link``. + +First, you have to analyze all your design files. In this example, we +suppose there is only one design file, :file:`design.vhdl`. + +:: + + $ ghdl -a design.vhdl + +Then, bind your design. In this example, we suppose the entity at the +design apex is ``design``. + +:: + + $ ghdl --bind design + +Finally, compile/bind your program and link it with your `VHDL` +design:: + +in C: + +:: + + gcc my_prog.c -Wl,`ghdl --list-link design` + +in Ada: + +:: + + $ gnatmake my_prog -largs `ghdl --list-link design` + +See :ref:`gccllvm-only-programs` for further details about ``--bind`` and ``--list-link``. + +Dynamically loading foreign objects from GHDL +============================================= + +Instead of linking and building foreign objects along with GHDL, it is also possible to load foreign resources dinamically. +In order to do so, provide the path and name of the shared library where the resource is to be loaded from. For example: + +.. code-block:: VHDL + + attribute foreign of get_rand: function is "VHPIDIRECT ./getrand.so get_rand"; + +Dynamically loading GHDL +======================== + +In order to generate a position independent executable (PIE), be it an executable binary +or a shared library, GHDL must be built with config option ``--default-pic``. This will ensure +that all the libraries and sources analyzed by GHDL generate position independent code (PIC). +Furthermore, when the binary is built, argument ``-Wl,-pie`` needs to be provided. + +PIE binaries can be loaded and executed from any language that supports C-alike signatures and types +(C, C++, golang, Python, Rust, etc.). For example: + +.. code-block:: Python + + import ctypes + gbin = ctypes.CDLL(bin_path) + + args = ['-gGENA="value"', 'gGENB="value"'] + + xargs = (ctypes.POINTER(ctypes.c_char) * (len(args) + 1))() + for i, arg in enumerate(args): + xargs[i] = ctypes.create_string_buffer(arg.encode('utf-8')) + return args[0], xargs + + gbin.main(len(xargv)-1, xargv) + + import _ctypes + # On GNU/Linux + _ctypes.dlclose(gbin._handle) + # On Windows + #_ctypes.FreeLibrary(gbin._handle) + +This allows seamless co-simulation using concurrent/parallel execution features available in each language: +pthreads, goroutines/gochannels, multiprocessing/queues, etc. Moreover, it provides a mechanism to execute multiple +GHDL simulations in parallel. + +Using GRT from Ada +================== + +.. warning:: + This topic is only for advanced users who know how to use `Ada` + and `GNAT`. This is provided only for reference; we have tested + this once before releasing `GHDL` 0.19, but this is not checked at + each release. + +The simulator kernel of `GHDL` named :dfn:`GRT` is written in +`Ada95` and contains a very light and slightly adapted version +of `VHPI`. Since it is an `Ada` implementation it is +called :dfn:`AVHPI`. Although being tough, you may interface to `AVHPI`. + +For using `AVHPI`, you need the sources of `GHDL` and to recompile +them (at least the `GRT` library). This library is usually compiled with +a `No_Run_Time` pragma, so that the user does not need to install the +`GNAT` runtime library. However, you certainly want to use the usual +runtime library and want to avoid this pragma. For this, reset the +`GRT_PRAGMA_FLAG` variable. + +:: + + $ make GRT_PRAGMA_FLAG= grt-all + + +Since `GRT` is a self-contained library, you don't want +`gnatlink` to fetch individual object files (furthermore this +doesn't always work due to tricks used in `GRT`). For this, +remove all the object files and make the :file:`.ali` files read-only. + +:: + + $ rm *.o + $ chmod -w *.ali + + +You may then install the sources files and the :file:`.ali` files. I have never +tested this step. + +You are now ready to use it. + +Here is an example, :file:`test_grt.adb` which displays the top +level design name. + +.. code-block:: Ada + + with System; use System; + with Grt.Avhpi; use Grt.Avhpi; + with Ada.Text_IO; use Ada.Text_IO; + with Ghdl_Main; + + procedure Test_Grt is + -- VHPI handle. + H : VhpiHandleT; + Status : Integer; + + -- Name. + Name : String (1 .. 64); + Name_Len : Integer; + begin + -- Elaborate and run the design. + Status := Ghdl_Main (0, Null_Address); + + -- Display the status of the simulation. + Put_Line ("Status is " & Integer'Image (Status)); + + -- Get the root instance. + Get_Root_Inst(H); + + -- Disp its name using vhpi API. + Vhpi_Get_Str (VhpiNameP, H, Name, Name_Len); + Put_Line ("Root instance name: " & Name (1 .. Name_Len)); + end Test_Grt; + + +First, analyze and bind your design:: + + $ ghdl -a counter.vhdl + $ ghdl --bind counter + + +Then build the whole:: + + $ gnatmake test_grt -aL`grt_ali_path` -aI`grt_src_path` -largs + `ghdl --list-link counter` + + +Finally, run your design:: + + $ ./test_grt + Status is 0 + Root instance name: counter + diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index f5b39d3e4..41a347ba2 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -51,7 +51,7 @@ Elaboration [``-e``] .. option:: -e <[options...] primary_unit [secondary_unit]> -Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default configurations and the default binding indications according to the LRM rules. It also generates the list of object files required for the executable. Then, it links all these files with the runtime library. The actual elaboration is performed at runtime. +Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default configurations and the default binding indications according to the LRM rules. It also generates the list of object files required for the executable. Then, it links all these files with the runtime library. * The elaboration command, :option:`-e`, must be followed by a name of either: @@ -65,6 +65,9 @@ Name of the units must be a simple name, without any dot. You can select the nam * If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this can be skipped. + .. WARNING:: + This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation, ``ghdl --elab-run --no-run`` is required. + .. index:: cmd run @@ -510,6 +513,7 @@ Make a local copy of an existing library. This is very useful if you want to add ghdl --copy --work=ieee --ieee=synopsys ghdl -a --work=ieee numeric_unsigned.vhd +.. _VPI_build_commands: VPI build commands ================== diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index ba31c8d5c..012a15621 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -14,11 +14,10 @@ invoking a program. Contrary to most programming languages, there is no standard method in VHDL to obtain the arguments or to set the exit status. -In GHDL, it is impossible to pass parameters to your design. A later version -could do it through the generic interfaces of the top entity. - -However, the GHDL runtime behaviour can be modified with some options; for -example, it is possible to stop simulation after a certain time. +However, the GHDL runtime behaviour can be modified with some options. For +example, it is possible to pass parameters to your design through the generic +interfaces of the top entity. It is also possible to stop simulation after a +certain time. The exit status of the simulation is ``EXIT_SUCCESS`` (0) if the simulation completes, or ``EXIT_FAILURE`` (1) in case of error @@ -26,7 +25,15 @@ simulation completes, or ``EXIT_FAILURE`` (1) in case of error Here is the list of the most useful options. Some debugging options are also available, but not described here. The :option:`--help` option lists -all options available, including the debugging one. +all options available, including the debugging ones. + +.. option:: -gGENERIC=VALUE + + Set value `VALUE` to generic with name `GENERIC`. + + .. WARNING:: + This is currently a run option; but in the future it will be deprecated to + become an elaboration option only. .. option:: --assert-level<=LEVEL> |