doc: add vhpidirect/index, vpi/index and vhpi/index

Author: umarcor

doc/index.rst

@@ -27,21 +27,32 @@ who are new to either `GHDL` or `VHDL` to first read the :ref:`USING:QuickStart`
 Three main approaches are used to co-simulate (co-execute) VHDL sources along with software applications written in a
 language other than VHDL (typically C/C++/SystemC):
 
-* Verilog Procedural Interface (VPI), also known as Program Language Interface (PLI) 2.0.
+* `Verilog Procedural Interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_ (VPI), also known as
+  Program Language Interface (PLI) 2.0.
 
-* VHDL Procedural Interface (VHPI), or specific implementations, such as Foreign Language Interface (FLI).
+* `VHDL Programming Interface <https://ieeexplore.ieee.org/document/4299594>`_ (VHPI), or specific implementations,
+  such as Foreign Language Interface (FLI).
 
 * Generation of C/C++ models/sources through a transpiler.
 
 VPI and VHPI are complex APIs which allow to inspect the hierarchy, set callbacks and/or assign signals. Because
 provided features are similar, GHDL supports VPI only. Furthermore, as an easier to use alternative, GHDL features a
-custom coexecution procedure named VHPIDIRECT, similar to SystemVerilog's Direct Programming Interface (DPI).
-As of today, generation of C++/SystemC models à la Verilator is not supported. However, a *vhdlator*/*ghdlator* might
-be available in the future.
+custom coexecution procedure named VHPIDIRECT, similar to SystemVerilog's DPI (`Direct Programming Interface <https://en.wikipedia.org/wiki/SystemVerilog_DPI>`_).
+As of today, generation of C++/SystemC models à la `Verilator <https://www.veripool.org/wiki/verilator>`_ is not
+supported. However, a *vhdlator*/*ghdlator* might be available in the future.
+
+:ref:`VHPIDIRECT <COSIM:VHPIDIRECT:Intro>` is easier to use than :ref:`VPI <COSIM:VPI:Intro>`/:ref:`VHPI <COSIM:VHPI:Intro>`
+because, as the name suggests, it is a direct interface. However, on the one hand VHPIDIRECT requires modification of
+VHDL sources, which might not be possible or desirable in certain contexts. On the other hand, VPI/VHPI allow use cases
+which are not yet possible with VHPIDIRECT, such as controlling execution time steps. It is suggested to read the quick
+start examples of both interfacing mechanisms, in order to get a feel of the differences.
+
 
 .. toctree::
    :caption: VHPIDIRECT
+   :hidden:
 
+   vhpidirect/index
    vhpidirect/declarations
    vhpidirect/wrapping
    vhpidirect/linking
@@ -50,28 +61,17 @@ be available in the future.
    vhpidirect/examples/index
    vhpidirect/mistakes
 
-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.
-
-.. NOTE::
-  GHDL supports different backends, and not all of them generate binary artifacts. Precisely, ``mcode`` is an in-memory
-  backend. Hence, the examples need to be built/executed with either LLVM or GCC backends. A few of them, the ones that
-  do not require linking object files, can be used with mcode.
-
-.. 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`.
-
-.. TIP::
-  See :ghdlsharp:`1053` for on-going work with regard to VHPIDIRECT.
 
 .. toctree::
    :caption: VPI
+   :hidden:
 
+   vpi/index
    vpi/examples/index
 
-See :ref:`VPI_build_commands`.
 
-TBC
+.. toctree::
+   :caption: VPHI
+   :hidden:
+
+   vhpi/index

doc/vhpi/index.rst

@@ -0,0 +1,17 @@
+.. program:: ghdl
+
+.. _COSIM:VHPI:Intro:
+
+Introduction
+============
+
+.. ATTENTION::
+  Since VPI and VHPI provide very similar features, and because VPI is already supported in GHDL, VHPI is not available (yet).
+  Hence, the information in this section is provided for completeness only.
+
+VHDL Programming Interface (VHPI) was introduced in 2007, as an ammendment to IEEE Std 1076-2002: `1076c-2007 - IEEE Standard VHDL Language Reference Manual - Procedural Language Application Interface <https://ieeexplore.ieee.org/document/4299594>`_.
+In the 2009, the programming interface was published as part of `1076-2008 - IEEE Standard VHDL Language Reference Manual <https://ieeexplore.ieee.org/document/4772740>`_.
+The latest version was published in 2019: `1076-2019 - IEEE Standard for VHDL Language Reference Manual <https://ieeexplore.ieee.org/document/8938196>`_.
+
+Some vendors support C programming interfaces similar to VHPI. For example, Mentor Graphics' ModelSim/QuestaSim supports a
+Foreign Language Interface (FLI) that provides functions to have procedural access to information within the simulator, ``vsim``. These allow to traverse the hierarchy, get/set values and control a simulation run. See `Using ModelSim Foreign Language Interface for c – VHDL CoSimulation and for Simulator Control on Linux x86 Platform <https://opencores.org/usercontent/doc/1380917197>`_ and `github.com/andrepool/fli <https://github.com/andrepool/fli>`_.

doc/vhpidirect/examples/shared.rst

@@ -1,8 +1,8 @@
 .. program:: ghdl
 .. _COSIM:VHPIDIRECT:Examples:shared:
 
-Shared
-######
+Shared libs and dynamic loading
+###############################
 
 .. IMPORTANT::
   As explained in :ref:`COSIM:VHPIDIRECT:Dynamic:loading_a_simulation`, in order to load binaries/libraries dynamically,

doc/vhpidirect/index.rst

@@ -0,0 +1,22 @@
+.. program:: ghdl
+
+.. _COSIM:VHPIDIRECT:Intro:
+
+Introduction
+============
+
+Interfacing with foreign languages through VHPIDIRECT is possible on any platform. You can reuse or define a subprogram
+in a foreign language (such as `C` or `Ada`) and import it into a VHDL design.
+
+.. NOTE::
+  GHDL supports different backends, and not all of them generate binary artifacts. Precisely, ``mcode`` is an in-memory
+  backend. Hence, the examples need to be built/executed with either LLVM or GCC backends. A few of them, the ones that
+  do not require linking object files, can be used with mcode.
+
+.. 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`.
+
+.. TIP::
+  See :ghdlsharp:`1053` for on-going work with regard to VHPIDIRECT.

doc/vpi/index.rst

@@ -0,0 +1,19 @@
+.. program:: ghdl
+.. _COSIM:VPI:Intro:
+
+Introduction
+============
+
+Verilog Procedural Interface (VPI) is part of the IEEE Std 1364: `1364-2005 - IEEE Standard for Verilog Hardware Description Language <https://ieeexplore.ieee.org/document/1620780>`_.
+It allows Verilog code to invoke C functions, and C functions to invoke Verilog system tasks. VPI is sometimes referred to
+as PLI 2, because it replaced the deprecated Program Language Interface (PLI).
+
+VPI provides advanced features, at the cost of having to learn the API. Since this is the user and reference manual for GHDL,
+an introduction to VPI is not included. Thus, the reader should have at least a basic knowledge of the interface. A good knowledge of the reference manual.
+
+Unlike VHPIDIRECT, which allows and requires the user to define a custom API between VHDL and C, VPI is itself a pre-defined
+API. Hence, all VPI modules need to include a standard header file, ``vpi_user.h``. At the same time, VPI modules need to be
+built as shared libraries, and they are dynamically loaded at runtime. This is similar to example :ref:`COSIM:VHPIDIRECT:Examples:shared:shlib`.
+However, when using VPI, VHDL sources are agnostic to the existence of C sources.
+
+Information about GHDL's commands related to VPI is available at :ref:`VPI_build_commands` and :option:`--vpi`.