Reorganize, update README, add refs, and add vpi/quickstart

.github/workflows/test.yml

@@ -20,17 +20,18 @@ jobs:
             vhpidirect/quickstart/random,
             vhpidirect/quickstart/math,
             vhpidirect/quickstart/customc,
+            vhpidirect/quickstart/wrapping/basic,
+            vhpidirect/quickstart/wrapping/time,
+            vhpidirect/quickstart/linking/bind,
             vhpidirect/quickstart/package,
             vhpidirect/quickstart/sharedvar,
-            vhpidirect/wrapping/basic,
-            vhpidirect/wrapping/time,
-            vhpidirect/linking/bind,
             vhpidirect/shared/shlib,
             vhpidirect/shared/dlopen,
             vhpidirect/shared/shghdl,
             vhpidirect/arrays/intvector,
             vhpidirect/arrays/logicvector,
             vhpidirect/arrays/matrices,
+            vpi/quickstart,
           ]
     runs-on: ubuntu-latest
     env:
@@ -67,17 +68,18 @@ jobs:
             vhpidirect/quickstart/random,
             vhpidirect/quickstart/math,
             vhpidirect/quickstart/customc,
+            vhpidirect/quickstart/wrapping/basic,
+            vhpidirect/quickstart/wrapping/time,
+            #vhpidirect/quickstart/linking/bind,  ! needs investigation, output of list-link seems to have wrong path format
             vhpidirect/quickstart/package,
             vhpidirect/quickstart/sharedvar,
-            vhpidirect/wrapping/basic,
-            vhpidirect/wrapping/time,
-            #vhpidirect/linking/bind,  ! needs investigation, output of list-link seems to have wrong path format
             vhpidirect/shared/shlib,
-            #vhpidirect/shared/dlopen, ! dlfcn.h is not available on win
-            #vhpidirect/shared/shghdl, ! dlfcn.h is not available on win
+            #vhpidirect/shared/dlopen,  ! dlfcn.h is not available on win
+            #vhpidirect/shared/shghdl,  ! dlfcn.h is not available on win
             vhpidirect/arrays/intvector,
             vhpidirect/arrays/logicvector,
             vhpidirect/arrays/matrices,
+            vpi/quickstart,
           ]
     runs-on: windows-latest
     env:

.gitignore

@@ -3,3 +3,8 @@
 *.lst
 *.o
 *.so
+*.vpi
+ent*
+tb*
+!*.vhd
+!*.vhdl

README.md

@@ -13,4 +13,10 @@
 
 # Co-simulation with GHDL
 
-This repository contains documentation and code examples about different procedures to interface VHDL with foreign languages and tools through GHDL.
+This repository contains **documentation** with code **examples** about different procedures to interface VHDL with foreign languages and tools through GHDL.
+
+Subdirs in [vhpidirect](./vhpidirect) and [vpi](./vpi) contain groups of examples to illustrate specific sets of features. Run the
+`run.sh` script in each subdir in order to build and execute the group of examples. In some cases, there are further subdirs with
+additional examples. Explanations are available in the [docs](https://ghdl.github.io/ghdl-cosim).
+
+*This repository was created recently and multiple existing examples are not published yet. Find on-going work in issue [#1](https://github.com/ghdl/ghdl-cosim/issues/1) and in [open Pull Requests](https://github.com/ghdl/ghdl-cosim/pulls)*.

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/arrays.rst

@@ -43,10 +43,10 @@ This example shows how to hardcode both the length and the initial content of an
 VHDL, the pointer is passed and the content is read and modified from VHDL.
 
 If the integer array must be created or filled at runtime by some more advanced process, it is possible to execute the GHDL
-simulation within a custom ``main()`` entrypoint (see :ref:`COSIM:VHPIDIRECT:Examples:wrapping:basic`). This use case is
-included in the example too. By using ``main.c`` instead of ``caux.c``, the content of the array is written programatically
-in C, before calling ``ghdl_main``. Note that the content of the array is read from C both before and after executing the
-simulation.
+simulation within a custom ``main()`` entrypoint (see :ref:`COSIM:VHPIDIRECT:Examples:quickstart:wrapping:basic`). This use
+case is included in the example too. By using ``main.c`` instead of ``caux.c``, the content of the array is written
+programatically in C, before calling ``ghdl_main``. Note that the content of the array is read from C both before and after
+executing the simulation.
 
 .. NOTE::
   There is no explicit example about how to have the size defined in C, but have the allocation/deallocation performed
@@ -77,8 +77,8 @@ not need neither ``[c_]allocIntArr`` nor ``[c_]freePointer``.
 
 .. _COSIM:VHPIDIRECT:Examples:arrays:logicvectors:
 
-:cosimtree:`logicvector <vhpidirect/arrays/logicvector>`
-**************************************************************
+:cosimtree:`Vector of std_logic <vhpidirect/arrays/logicvector>`
+****************************************************************
 
 Commonly signals in VHDL are of a logic type or a vector thereof (``std_logic`` and ``std_logic_vector``), coming from IEEE's ``std_logic_1164`` package.
 These types can hold values other than high and low (``1`` and ``0``) and are enumerated as:
@@ -130,7 +130,7 @@ For illustrative purposes, the two vectors are populated with logic values in di
   The integer values that are given to ``char`` variables in C which are intended to be read as VHDL logic values, must be limited to [0, 8]. This ensures that they represent one of the 9 enumerated logic values.
 .. _COSIM:VHPIDIRECT:Examples:arrays:matrices:
 
-:cosimtree:`matrices <vhpidirect/arrays/matrices>`
+:cosimtree:`Matrices <vhpidirect/arrays/matrices>`
 **************************************************
 
 Constrained multidimensional arrays of doubles/reals

doc/vhpidirect/examples/index.rst

@@ -6,8 +6,6 @@ Examples
 .. toctree::
 
    quickstart
-   wrapping
-   linking
    shared
    arrays
    other

doc/vhpidirect/examples/quickstart.rst

@@ -6,12 +6,14 @@ Quick Start
 
 .. _COSIM:VHPIDIRECT:Examples:quickstart:random:
 
-:cosimtree:`random <vhpidirect/quickstart/random>`
-**************************************************
+:cosimtree:`'rand' from stdlib <vhpidirect/quickstart/random>`
+**************************************************************
 
-By default, GHDL includes the standard C library in the generated simulation models. Hence, resources from ``stdlib`` can be used without any modification to the build procedure.
+By default, GHDL includes the standard C library in the generated simulation models. Hence, resources from ``stdlib``
+can be used without any modification to the build procedure.
 
-This example shows how to import and use ``rand`` to generate and print 10 integer numbers. The VHDL code is equivalent to the following C snippet. However, note that this C source is NOT required, because ``stdlib`` is already built in.
+This example shows how to import and use ``rand`` to generate and print 10 integer numbers. The VHDL code is equivalent
+to the following C snippet. However, note that this C source is NOT required, because ``stdlib`` is already built in.
 
 .. code-block:: C
 
@@ -27,8 +29,8 @@ This example shows how to import and use ``rand`` to generate and print 10 integ
 
 .. _COSIM:VHPIDIRECT:Examples:quickstart:math:
 
-:cosimtree:`math <vhpidirect/quickstart/math>`
-**********************************************
+:cosimtree:`'sin' from libmath <vhpidirect/quickstart/math>`
+************************************************************
 
 By the same token, it is possible to include functions from system library by just providing the corresponding linker
 flag.
@@ -38,8 +40,8 @@ no additional C sources are required, because the ``math`` library is already co
 
 .. _COSIM:VHPIDIRECT:Examples:quickstart:customc:
 
-:cosimtree:`customc <vhpidirect/quickstart/customc>`
-****************************************************
+:cosimtree:`custom C <vhpidirect/quickstart/customc>`
+*****************************************************
 
 When the required functionality is not available in pre-built libraries, custom C sources and/or objects can be added
 to the elaboration and/or linking.
@@ -52,6 +54,70 @@ for further details.
 Since either C sources or pre-compiled ``.o`` objects can be added, in C/C++ projects of moderate complexity, it might
 be desirable to merge all the C sources in a single object before elaborating the design.
 
+.. _COSIM:VHPIDIRECT:Examples:wrapping:
+
+Wrapping ghdl_main
+******************
+
+.. _COSIM:VHPIDIRECT:Examples:quickstart:wrapping:basic:
+
+:cosimtree:`basic <vhpidirect/quickstart/wrapping/basic>`
+---------------------------------------------------------
+
+Instead of using GHDL's own entrypoint to the execution, it is possible to wrap it by providing a custom ``main``
+function. Upon existence of ``main``, execution of the simulation is triggered by calling ``ghdl_main``.
+
+This is the most basic example of such usage. ``ghdl_main`` is declared as ``extern`` in C, and arguments ``argc`` and
+``argv`` are passed without modification. However, this sets the ground for custom prepocessing and postprocessing in a
+foreign language.
+
+Other options are to just pass empty arguments (``ghdl_main(0, NULL)``) or to customize them:
+
+.. code-block:: C
+
+  char* args[] = {NULL, "--wave=wave.ghw"};
+  ghdl_main(2, args);
+
+See :ref:`COSIM:VHPIDIRECT:Wrapping` for further details about the constraints of ``argv``.
+
+:cosimtree:`time <vhpidirect/quickstart/wrapping/time>`
+-------------------------------------------------------
+
+Although most of the provided examples are written in C, VHPIDIRECT can be used with any language that supports a
+C-alike compile and link model.
+
+This example shows how to time the execution of a simulation from either C or Ada. In both cases, function ``clock`` is
+used to get the time before and after calling ``ghdl_main``. Regarding the build procedure, it is to be noted that C
+sources are elaborated with :option:`-e`, because GHDL allows to pass parameters (in this case, additional C sources)
+to the compiler and/or linker. However, since it is not possible to do so with Ada, ``gnatmake``, :option:`--bind` and
+:option:`--list-link` are used instead. See :ref:`COSIM:VHPIDIRECT:Linking` for further info about custom linking setups.
+
+.. HINT::
+  Compared to the previous example, the declaration of ``ghdl_main`` includes three arguments in this example:
+  ``int argc, void** argv, void** envp``. This is done for illustration purposes only, as it has no real effect on the
+  exercise.
+
+.. _COSIM:VHPIDIRECT:Examples:quickstart:linking:
+
+Linking
+*******
+
+:cosimtree:`bind <vhpidirect/quickstart/linking/bind>`
+------------------------------------------------------
+
+Although GHDL's elaborate command can compile and link C sources, it is sometimes preferred or required to call a
+compiler explicitly with custom arguments. This is useful, e.g., when a simulation is to be embedded in the build of an
+existing C/C++ application.
+
+This example is equivalent to :ref:`COSIM:VHPIDIRECT:Examples:quickstart:wrapping:basic`, but it shows how to use
+:option:`--bind` and :option:`--list-link` instead of :option:`-e`. See :ref:`COSIM:VHPIDIRECT:Linking` for further
+details.
+
+.. HINT::
+  Objects generated by :option:`--bind` are created in the working directory. See :ref:`gccllvm-only-programs` and
+  :ghdlsharp:`781`.
+
+
 .. _COSIM:VHPIDIRECT:Examples:quickstart:package:
 
 :cosimtree:`package <vhpidirect/quickstart/package>`
@@ -71,8 +137,8 @@ numbers. Subprogram declaration requirements are detailed under the :ref:`COSIM:
 While sharing variables through packages in VHDL 1993 is flexible, in VHDL 2008 protected types need to be used.
 However, GHDL allows to relax some rules of the LRM through :option:`-frelaxed`.
 
-This example shows multiple alternatives to share variables through packages, depending on the target version of the standard.
-Three different binaries are built from the same entity, using:
+This example shows multiple alternatives to share variables through packages, depending on the target version of the
+standard. Three different binaries are built from the same entity, using:
 
   * A VHDL 1993 package with ``--std=93``.
 

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,