doc: update tips/hints related to VHPIDIRECT (#1202)

3 files changed, 57 insertions, 36 deletions

diff --git a/doc/using/Foreign.rst b/doc/using/Foreign.rst
index 57ffc2ce3..cdbeeace3 100644
--- a/doc/using/Foreign.rst
+++ b/doc/using/Foreign.rst
@@ -15,7 +15,7 @@ Interfacing to other languages
 
 .. index:: VHPIDIRECT
 
-Interfacing with foreign languages through VHPIDIRECT is possible any platform.
+Interfacing with foreign languages through VHPIDIRECT is possible on any platform.
 You can define a subprogram in a foreign language (such as `C` or
 `Ada`) and import it into a VHDL design.
 
@@ -24,6 +24,10 @@ You can define a subprogram in a foreign language (such as `C` or
    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`).
 
+.. ATTENTION::
+  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. See :ref:`INTRO:Copyrights`.
+
+
 Foreign declarations
 ====================
 
@@ -62,7 +66,7 @@ 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.
 
-The object file with the source code for the foreign subprogram must then be 
+The object file with the source code for the foreign subprogram must then be
 linked to GHDL, expanded upon in :ref:`Starting_a_simulation_from_a_foreign_program`.
 
 .. _Restrictions_on_foreign_declarations:
@@ -131,9 +135,9 @@ Note the :file:`c` library is always linked with an executable.
 
 .. HINT::
   The process for personal code is the same, provided the code is compiled to an object file.
-  Analysis must be made of the HDL files, then elaboration with `-Wl,personal.o toplevelEntityName` as arguments. 
-  Additional object files are flagged separate `-Wl,*` arguments. The elaboration step will compile the executable with the custom resources.
-  Further reading (particularly about the backend restrictions) is at :ref:`Elaboration:command` and :ref:`Run:command`.
+  Analysis must be made of the HDL files, then elaboration with ``-e -Wl,personal.o [options...] primary_unit [secondary_unit]`` as arguments.
+  Additional object files are flagged separate ``-Wl,*`` arguments. The elaboration step will compile the executable with the custom resources.
+  Further reading (particularly about the backend particularities) is at :ref:`Elaboration:command` and :ref:`Run:command`.
 
 .. _Starting_a_simulation_from_a_foreign_program:
 
@@ -149,9 +153,6 @@ in C:
 
   extern int ghdl_main (int argc, char **argv);
 
-.. TIP::
-  Don't forget to list the object file of this entry point as per :ref:`Linking_with_foreign_object_files`.
-
 in Ada:
 
 .. code-block:: Ada
@@ -162,8 +163,17 @@ in Ada:
     return Integer;
   pragma import (C, Ghdl_Main, "ghdl_main");
 
+.. TIP::
+  Don't forget to list the object file(s) of this entry point and other foreign sources, as per :ref:`Linking_with_foreign_object_files`.
+
+.. ATTENTION::
+  This function must be called once, since reseting/restarting the simulation runtime is not supported yet (see :ghdlsharp:`1184`).
+
+.. HINT::
+  Immitating the run time flags, such as ``-gDEPTH=12`` from :option:`-gGENERIC`, requires the ``argv`` to have the executable's path at index 0, effectively shifting all other indicies along by 1. This can be taken from the 0 index of the ``argv`` passed to ``main()``, or (not suggested, despite a lack of consequences) left empty/null.
+
+  Since ``ghdl_main`` is the entrypoint to the design (GRT runtime), the supported CLI options are the ones shown in :ref:`USING:Simulation`. Options for analysis/elaboration are not required and will NOT work. See :option:`-r`.
 
-This function must be called once, and returns 0 at the end of the simulation.
 
 .. _Linking_with_Ada:
 
@@ -178,8 +188,8 @@ process is not trivial: you have to elaborate your program and your
 .. 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``.
+   explained for didactic purposes. When suitable, we suggest to use :option:`-e`, instead
+   of :option:`--bind` and :option:`--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`.
@@ -210,10 +220,10 @@ in Ada:
 
   $ gnatmake my_prog -largs `ghdl --list-link design`
 
-See :ref:`gccllvm-only-programs` for further details about ``--bind`` and ``--list-link``.
+See :ref:`gccllvm-only-programs` for further details about :option:`--bind` and :option:`--list-link`.
 
-Dynamically loading foreign objects from GHDL
-=============================================
+Dynamically loading foreign objects from within GHDL
+====================================================
 
 Instead of linking and building foreign objects along with GHDL, it is also possible to load foreign resources dynamically.
 In order to do so, provide the path and name of the shared library where the resource is to be loaded from. For example:
@@ -257,6 +267,13 @@ This allows seamless co-simulation using concurrent/parallel execution features
 pthreads, goroutines/gochannels, multiprocessing/queues, etc. Moreover, it provides a mechanism to execute multiple
 GHDL simulations in parallel.
 
+.. TIP::
+    As explained in :ref:`Starting_a_simulation_from_a_foreign_program`, ``ghdl_main`` must be called once, since reseting/restarting the simulation runtime is not supported yet (see :ghdlsharp:`1184`). When it is loaded dynamically, this means that the binary file/library needs to be unloaded from memory and loaded again.
+
+.. ATTENTION::
+    By default, GHDL uses ``grt.ver`` to limit which symbols are exposed in the generated binary, and ``ghdl_main`` is not included. Hence, the version script needs to be removed, or a complementary script needs to be provided. Otherwise, it will not be possible to find the function easily. See :option:`--list-link` for further info.
+
+
 Using GRT from Ada
 ==================
 
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index 613fdaf05..e393892c2 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -80,7 +80,7 @@ files required for the executable. Then, it links all these files with the runti
   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.
+     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. See :option:`--no-run`.
 
 
 .. index:: cmd run
@@ -92,9 +92,9 @@ Run [``-r``]
 
 .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
 
-Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration:command>`.
+Runs/simulates a design. Two sets of options are accepted, both of them being separated by ``primary_unit [secondary_unit]``. For the first set, ``options...``, arguments are the same as for the :ref:`elaboration command <Elaboration:command>`. For the second set, ``simulation_options...``, arguments are defined in :ref:`USING:Simulation`.
 
-* GGC/LLVM: simply, the filename of the executable is determined and it is executed. Options are ignored. You may also directly execute the program. The executable must be in the current directory.
+* GGC/LLVM: the filename of the executable is determined and it is executed. Elaboration options are ignored. You may also directly execute the program. The executable must be in the current directory.
 * mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during analysis.
 
 This command exists for three reasons:
@@ -103,8 +103,6 @@ This command exists for three reasons:
 * It is coherent with the :option:`-a` and :option:`-e` commands.
 * It works with mcode implementation, where the executable code is generated in memory.
 
-See section :ref:`USING:Simulation`, for details on options.
-
 
 .. index:: cmd elaborate and run
 
@@ -113,9 +111,9 @@ See section :ref:`USING:Simulation`, for details on options.
 Elaborate and run [``--elab-run``]
 ----------------------------------
 
-.. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]>
+.. option:: --elab-run <[options...] primary_unit [secondary_unit] [simulation_options...]>
 
-Acts like the elaboration command (see :option:`-e`) followed by the run command (see :option:`-r`).
+Acts like the elaboration command followed by the run command. Note that this command accepts two sets of options. See :option:`-e`, :option:`-r` and :ref:`USING:Simulation`.
 
 
 .. index:: cmd checking syntax
diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst
index 74fd5c89d..e97212375 100644
--- a/doc/using/Simulation.rst
+++ b/doc/using/Simulation.rst
@@ -1,30 +1,34 @@
 .. program:: ghdl
 .. _USING:Simulation:
 
-Simulation and runtime
-######################
+Simulation (runtime)
+####################
 
 .. _simulation_options:
 
 Simulation options
 ==================
 
-In most system environments, it is possible to pass options while
+In most system environments, it is possible to pass CLI options while
 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.
+However, the GHDL runtime behaviour can be modified with some options:
 
-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
-(assertion failure, overflow or any constraint error).
+- 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 (assertion
+  failure, overflow or any constraint error).
 
 Here is the list of the most useful options. For further info, see :ref:`DEV:Debugging`.
 
+.. HINT::
+   Note that these arguments are represented as ``simulation_options...`` in this documentation.
+   For analysis/elaboration options, see :ref:`USING:Invoking`.
+
+
 .. option:: -gGENERIC=VALUE
 
   Set value `VALUE` to generic with name `GENERIC`.
@@ -129,6 +133,12 @@ Here is the list of the most useful options. For further info, see :ref:`DEV:Deb
 
   Display a short description of the options accepted by the runtime library.
 
+.. option:: --no-run
+
+  Stop the simulation before the first cycle. This option actually elaborates the design, so it will catch any bound error in port maps. See also :option:`-e`.
+
+  This may be used with :option:`--disp-tree` to display the tree without simulating the whole design.
+
 .. _export_waves:
 
 Export waveforms
@@ -264,10 +274,6 @@ Export hierarchy and references
     If `KIND` is not specified, the hierarchy is displayed with the
     ``port`` mode.
 
-.. option:: --no-run
-
-  Stop the simulation before the first cycle. This may be used with :option:`--disp-tree` to display the tree without simulating the whole design. This option actually elaborates the design, so it will catch any bound error in port maps.
-
 .. option:: --xref-html [options] files...
 
   To easily navigate through your sources, you may generate cross-references. This command generates an html file for