doc: split 'Interfacing to other languages' to ghdl/ghdl-cosim (#1216)

* doc: move co-simulation content to ghdl/ghdl-cosim

* doc: fix option ref syntax

* doc: move examples to ghdl/ghdl-cosim

6 files changed, 5 insertions, 397 deletions

diff --git a/doc/conf.py b/doc/conf.py
index e28ce3e16..3764a2995 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -142,6 +142,7 @@ texinfo_documents = [
 
 intersphinx_mapping = {
    'python': ('https://docs.python.org/3.6/', None),
+   'cosim': ('https://ghdl.github.io/ghdl-cosim', None),
    'poc': ('https://poc-library.readthedocs.io/en/release', None)
 }
 
diff --git a/doc/examples/README.rst b/doc/examples/README.rst
deleted file mode 100644
index 921bcf2a3..000000000
--- a/doc/examples/README.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _USING:Examples:
-
-Examples
-########
-
-This sections contains advanced examples using specific features of the language, the tool,
-or interaction with third-party projects. It is suggested for users who are new to either
-`GHDL` or `VHDL` to read :ref:`USING:QuickStart` first.
-
-.. toctree::
-
-   ../examples/VHPIDIRECT
diff --git a/doc/examples/VHPIDIRECT.rst b/doc/examples/VHPIDIRECT.rst
deleted file mode 100644
index f8eddf911..000000000
--- a/doc/examples/VHPIDIRECT.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _Examples:VHPIDIRECT:
-
-Data exchange through VHPIDIRECT
-################################
-
-VUnit
-=====
-
-`VUnit <https://github.com/VUnit/vunit>`_ is an open source unit testing framework for VHDL/SystemVerilog. Sharing memory buffers between foreign C or Python applications and VHDL testbenches is supported through GHDL's VHPIDIRECT features. Buffers are accessed from VHDL as either strings, arrays of bytes or arrays of 32 bit integers. See VUnit example `external buffer <https://github.com/VUnit/vunit/tree/master/examples/vhdl/external_buffer>`_ for details about the API.
-
-ghdlex and netpp
-================
-
-`netpp (network property protocol) <https://section5.ch/index.php/netpp/>`_ is a communication library allowing to expose variables or other properties of an application to the network as abstract 'Properties'. Its basic philosophy is that a device always knows its capabilities. netpp capable devices can be explored by command line, Python scripts or GUI applications. Properties of a device - be it virtual or real - are typically described by a static description in an XML device description language, but they can also be constructed on the fly.
-
-`ghdlex <https://github.com/hackfin/ghdlex>`_ is a set of C extensions to facilitate data exchange between a GHDL simulation and external applications. VHPIDIRECT mechanisms are used to wrap GHDL data types into structures usable from a C library. `ghdlex` uses the `netpp <https://section5.ch/index.php/netpp/>`_ library to expose virtual entities (such as pins or RAM) to the network. It also demonstrates simple data I/O through unix pipes. A few VHDL example entities are provided, such as a virtual console, FIFOs, RAM.
-
-The author of `netpp` and `ghdlex` is also working on `MaSoCist <https://github.com/hackfin/MaSoCist>`_, a linux'ish build system for System on Chip designs, based on GHDL. It allows to handle more complex setup, e.g. how a RISC-V architecture (for example) is regress-tested using a virtual debug interface.
diff --git a/doc/index.rst b/doc/index.rst
index c675383be..61c5f79ac 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -104,7 +104,6 @@
    using/Foreign
    using/ImplementationOfVHDL
    using/ImplementationOfVITAL
-   examples/README
 
 .. raw:: latex
 
diff --git a/doc/using/Foreign.rst b/doc/using/Foreign.rst
index cdbeeace3..98a3aa1c9 100644
--- a/doc/using/Foreign.rst
+++ b/doc/using/Foreign.rst
@@ -2,369 +2,7 @@
 
 .. _USING:Foreign:
 
-Interfacing to other languages
-##############################
-
-.. index:: interfacing
-
-.. index:: other languages
-
-.. index:: foreign
-
-.. index:: VHPI
-
-.. index:: VHPIDIRECT
-
-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.
-
-.. 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`).
-
-.. 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
-====================
-
-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.
-
-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:
-
-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.
-
-.. 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 ``-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:
-
-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");
-
-.. 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`.
-
-
-.. _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 :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`.
-
-::
-
-  $ 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 :option:`--bind` and :option:`--list-link`.
-
-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:
-
-.. 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, in Python:
-
-.. 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.
-
-.. 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
-==================
-
-.. 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
+Co-simulation
+#############
 
+See :ref:`COSIM`.
diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst
index c236152e6..23924fd94 100644
--- a/doc/using/Synthesis.rst
+++ b/doc/using/Synthesis.rst
@@ -58,7 +58,7 @@ Artifacts generated by Yosys can be used in multiple open source and vendor tool
 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``)
+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.