From ba507faf3f64ac55f5582b5bd64054c3d014f327 Mon Sep 17 00:00:00 2001 From: umarcor Date: Sun, 3 May 2020 00:30:48 +0200 Subject: [PATCH 1/5] vhpidirect: move 'wrapping' and 'linking' into 'quickstart' --- .github/workflows/test.yml | 12 +-- doc/vhpidirect/examples/arrays.rst | 14 +-- doc/vhpidirect/examples/index.rst | 2 - doc/vhpidirect/examples/linking.rst | 15 ---- doc/vhpidirect/examples/quickstart.rst | 86 ++++++++++++++++--- doc/vhpidirect/examples/wrapping.rst | 33 ------- .../{ => quickstart}/linking/bind/main.c | 0 .../{ => quickstart}/linking/bind/run.sh | 0 .../{ => quickstart}/linking/bind/tb.vhd | 0 .../{ => quickstart}/wrapping/basic/main.c | 0 .../{ => quickstart}/wrapping/basic/run.sh | 0 .../{ => quickstart}/wrapping/basic/tb.vhd | 0 .../{ => quickstart}/wrapping/time/main.c | 0 .../{ => quickstart}/wrapping/time/run.sh | 0 .../wrapping/time/showtime.adb | 0 .../{ => quickstart}/wrapping/time/tb.vhd | 0 16 files changed, 89 insertions(+), 73 deletions(-) delete mode 100644 doc/vhpidirect/examples/linking.rst delete mode 100644 doc/vhpidirect/examples/wrapping.rst rename vhpidirect/{ => quickstart}/linking/bind/main.c (100%) rename vhpidirect/{ => quickstart}/linking/bind/run.sh (100%) rename vhpidirect/{ => quickstart}/linking/bind/tb.vhd (100%) rename vhpidirect/{ => quickstart}/wrapping/basic/main.c (100%) rename vhpidirect/{ => quickstart}/wrapping/basic/run.sh (100%) rename vhpidirect/{ => quickstart}/wrapping/basic/tb.vhd (100%) rename vhpidirect/{ => quickstart}/wrapping/time/main.c (100%) rename vhpidirect/{ => quickstart}/wrapping/time/run.sh (100%) rename vhpidirect/{ => quickstart}/wrapping/time/showtime.adb (100%) rename vhpidirect/{ => quickstart}/wrapping/time/tb.vhd (100%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ee356561..744106ad 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -20,11 +20,11 @@ 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, @@ -67,11 +67,11 @@ 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 diff --git a/doc/vhpidirect/examples/arrays.rst b/doc/vhpidirect/examples/arrays.rst index de4cef81..89084df0 100644 --- a/doc/vhpidirect/examples/arrays.rst +++ b/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 ` -************************************************************** +:cosimtree:`Vector of std_logic ` +**************************************************************** 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 ` +:cosimtree:`Matrices ` ************************************************** Constrained multidimensional arrays of doubles/reals diff --git a/doc/vhpidirect/examples/index.rst b/doc/vhpidirect/examples/index.rst index 4c6d349b..2edaac05 100644 --- a/doc/vhpidirect/examples/index.rst +++ b/doc/vhpidirect/examples/index.rst @@ -6,8 +6,6 @@ Examples .. toctree:: quickstart - wrapping - linking shared arrays other diff --git a/doc/vhpidirect/examples/linking.rst b/doc/vhpidirect/examples/linking.rst deleted file mode 100644 index 1bda5221..00000000 --- a/doc/vhpidirect/examples/linking.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. program:: ghdl -.. _COSIM:VHPIDIRECT:Examples:linking: - -Linking -####### - -:cosimtree:`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: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`. diff --git a/doc/vhpidirect/examples/quickstart.rst b/doc/vhpidirect/examples/quickstart.rst index ce7acc80..216de3f9 100644 --- a/doc/vhpidirect/examples/quickstart.rst +++ b/doc/vhpidirect/examples/quickstart.rst @@ -6,12 +6,14 @@ Quick Start .. _COSIM:VHPIDIRECT:Examples:quickstart:random: -:cosimtree:`random ` -************************************************** +:cosimtree:`'rand' from stdlib ` +************************************************************** -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 ` -********************************************** +:cosimtree:`'sin' from libmath ` +************************************************************ 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 ` -**************************************************** +:cosimtree:`custom C ` +***************************************************** 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 ` +--------------------------------------------------------- + +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 ` +------------------------------------------------------- + +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 ` +------------------------------------------------------ + +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 ` @@ -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``. diff --git a/doc/vhpidirect/examples/wrapping.rst b/doc/vhpidirect/examples/wrapping.rst deleted file mode 100644 index 43e3087c..00000000 --- a/doc/vhpidirect/examples/wrapping.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. program:: ghdl -.. _COSIM:VHPIDIRECT:Examples:wrapping: - -Wrapping -######## - -.. _COSIM:VHPIDIRECT:Examples:wrapping:basic: - -:cosimtree:`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 ` -******************************************** - -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. diff --git a/vhpidirect/linking/bind/main.c b/vhpidirect/quickstart/linking/bind/main.c similarity index 100% rename from vhpidirect/linking/bind/main.c rename to vhpidirect/quickstart/linking/bind/main.c diff --git a/vhpidirect/linking/bind/run.sh b/vhpidirect/quickstart/linking/bind/run.sh similarity index 100% rename from vhpidirect/linking/bind/run.sh rename to vhpidirect/quickstart/linking/bind/run.sh diff --git a/vhpidirect/linking/bind/tb.vhd b/vhpidirect/quickstart/linking/bind/tb.vhd similarity index 100% rename from vhpidirect/linking/bind/tb.vhd rename to vhpidirect/quickstart/linking/bind/tb.vhd diff --git a/vhpidirect/wrapping/basic/main.c b/vhpidirect/quickstart/wrapping/basic/main.c similarity index 100% rename from vhpidirect/wrapping/basic/main.c rename to vhpidirect/quickstart/wrapping/basic/main.c diff --git a/vhpidirect/wrapping/basic/run.sh b/vhpidirect/quickstart/wrapping/basic/run.sh similarity index 100% rename from vhpidirect/wrapping/basic/run.sh rename to vhpidirect/quickstart/wrapping/basic/run.sh diff --git a/vhpidirect/wrapping/basic/tb.vhd b/vhpidirect/quickstart/wrapping/basic/tb.vhd similarity index 100% rename from vhpidirect/wrapping/basic/tb.vhd rename to vhpidirect/quickstart/wrapping/basic/tb.vhd diff --git a/vhpidirect/wrapping/time/main.c b/vhpidirect/quickstart/wrapping/time/main.c similarity index 100% rename from vhpidirect/wrapping/time/main.c rename to vhpidirect/quickstart/wrapping/time/main.c diff --git a/vhpidirect/wrapping/time/run.sh b/vhpidirect/quickstart/wrapping/time/run.sh similarity index 100% rename from vhpidirect/wrapping/time/run.sh rename to vhpidirect/quickstart/wrapping/time/run.sh diff --git a/vhpidirect/wrapping/time/showtime.adb b/vhpidirect/quickstart/wrapping/time/showtime.adb similarity index 100% rename from vhpidirect/wrapping/time/showtime.adb rename to vhpidirect/quickstart/wrapping/time/showtime.adb diff --git a/vhpidirect/wrapping/time/tb.vhd b/vhpidirect/quickstart/wrapping/time/tb.vhd similarity index 100% rename from vhpidirect/wrapping/time/tb.vhd rename to vhpidirect/quickstart/wrapping/time/tb.vhd From a7bbd9ed5773f5c716d1e6d3f85d493d60137cb6 Mon Sep 17 00:00:00 2001 From: umarcor Date: Sat, 2 May 2020 13:23:49 +0200 Subject: [PATCH 2/5] doc: add vhpidirect/index, vpi/index and vhpi/index --- doc/index.rst | 46 +++++++++++++++--------------- doc/vhpi/index.rst | 17 +++++++++++ doc/vhpidirect/examples/shared.rst | 4 +-- doc/vhpidirect/index.rst | 22 ++++++++++++++ doc/vpi/index.rst | 19 ++++++++++++ 5 files changed, 83 insertions(+), 25 deletions(-) create mode 100644 doc/vhpi/index.rst create mode 100644 doc/vhpidirect/index.rst create mode 100644 doc/vpi/index.rst diff --git a/doc/index.rst b/doc/index.rst index ac061800..231d06dc 100644 --- a/doc/index.rst +++ b/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 `_ (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 `_ (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 `_). +As of today, generation of C++/SystemC models à la `Verilator `_ is not +supported. However, a *vhdlator*/*ghdlator* might be available in the future. + +:ref:`VHPIDIRECT ` is easier to use than :ref:`VPI `/:ref:`VHPI ` +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 diff --git a/doc/vhpi/index.rst b/doc/vhpi/index.rst new file mode 100644 index 00000000..7dadeffa --- /dev/null +++ b/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 `_. +In the 2009, the programming interface was published as part of `1076-2008 - IEEE Standard VHDL Language Reference Manual `_. +The latest version was published in 2019: `1076-2019 - IEEE Standard for VHDL Language Reference Manual `_. + +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 `_ and `github.com/andrepool/fli `_. diff --git a/doc/vhpidirect/examples/shared.rst b/doc/vhpidirect/examples/shared.rst index 2c5914b8..67e24f36 100644 --- a/doc/vhpidirect/examples/shared.rst +++ b/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, diff --git a/doc/vhpidirect/index.rst b/doc/vhpidirect/index.rst new file mode 100644 index 00000000..ec67f59e --- /dev/null +++ b/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. diff --git a/doc/vpi/index.rst b/doc/vpi/index.rst new file mode 100644 index 00000000..3a7e337d --- /dev/null +++ b/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 `_. +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`. From 00b6b1e0b0b070863b2d729ddea1a440df07ab4f Mon Sep 17 00:00:00 2001 From: umarcor Date: Sat, 2 May 2020 13:59:43 +0200 Subject: [PATCH 3/5] vpi: add 'quickstart' --- .github/workflows/test.yml | 6 +++-- doc/vpi/examples/index.rst | 18 ++++++++++++++- doc/vpi/examples/quickstart.rst | 17 ++++++++++++++ vpi/ent.vhd | 26 +++++++++++++++++++++ vpi/quickstart/run.sh | 25 ++++++++++++++++++++ vpi/quickstart/vpi_hello.c | 22 ++++++++++++++++++ vpi/tb.vhd | 41 +++++++++++++++++++++++++++++++++ 7 files changed, 152 insertions(+), 3 deletions(-) create mode 100644 doc/vpi/examples/quickstart.rst create mode 100644 vpi/ent.vhd create mode 100755 vpi/quickstart/run.sh create mode 100644 vpi/quickstart/vpi_hello.c create mode 100644 vpi/tb.vhd diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 744106ad..8b415fe7 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -31,6 +31,7 @@ jobs: vhpidirect/arrays/intvector, vhpidirect/arrays/logicvector, vhpidirect/arrays/matrices, + vpi/quickstart, ] runs-on: ubuntu-latest env: @@ -73,11 +74,12 @@ jobs: vhpidirect/quickstart/package, vhpidirect/quickstart/sharedvar, 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: diff --git a/doc/vpi/examples/index.rst b/doc/vpi/examples/index.rst index df8af1ba..c4b4abbd 100644 --- a/doc/vpi/examples/index.rst +++ b/doc/vpi/examples/index.rst @@ -1,4 +1,20 @@ +.. program:: ghdl +.. _COSIM:VPI:Examples: + Examples ######## -TBC +A very brief description of how to use VPI is that ``vpi_user.h`` provides dozens of functions to scan/navigate the hierarchy +of the elaborated hardware design, and it allows to set callbacks for specific events/signals. + +.. NOTE:: + Since VHDL sources are agnostic to the usage of VPI modules, most of the examples in this section reuse the same VHDL + sources. Readers should focus on the differences between the provided C files. + +.. ATTENTION:: + On Windows, the directory containing ``libghdlvpi.dll`` needs to be added to the ``PATH``. This can be achieved with + :option:`--vpi-library-dir`, :option:`--vpi-library-dir-unix` or ``$(cd $(dirname $(which ghdl))/../lib; pwd)``. + +.. toctree:: + + quickstart diff --git a/doc/vpi/examples/quickstart.rst b/doc/vpi/examples/quickstart.rst new file mode 100644 index 00000000..d65ee146 --- /dev/null +++ b/doc/vpi/examples/quickstart.rst @@ -0,0 +1,17 @@ +.. program:: ghdl +.. _COSIM:VPI:Examples:quickstart: + +Quick Start +########### + +.. _COSIM:VPI:Examples:quickstart:hello: + +:cosimtree:`hello ` +*********************************************** + +This is the most minimal example, where a single callback is registered at the beginning of the simulation. The callback just +prints ``Hello!``. Then, the simulation is executed as usual. + +VPI allows to register callbacks at multiple events and to optionally delay their execution after the event is triggered. +The list of available callback reasons is defined in :ghdlsrc:`vpi_user.h `. The structure type that is used +and required to register a callback, ``s_cb_data``, is also defined in the same header file. diff --git a/vpi/ent.vhd b/vpi/ent.vhd new file mode 100644 index 00000000..185af825 --- /dev/null +++ b/vpi/ent.vhd @@ -0,0 +1,26 @@ +library ieee; +use ieee.std_logic_1164.all; +use ieee.numeric_std.all; + +entity ent is + generic ( + G_WIDTH : natural := 4 + ); + port ( + A : in std_logic_vector(G_WIDTH-1 downto 0); + B : in std_logic_vector(G_WIDTH-1 downto 0); + C : in std_logic; + Q : out std_logic_vector(G_WIDTH downto 0) + ); +end entity; + +architecture arch of ent is + + signal c_in : unsigned(0 downto 0); + +begin + + c_in <= to_unsigned(1,1) when C='1' else to_unsigned(0,1); + Q <= std_logic_vector(unsigned('0' & A) + unsigned(B) + c_in); + +end architecture; diff --git a/vpi/quickstart/run.sh b/vpi/quickstart/run.sh new file mode 100755 index 00000000..e3485a46 --- /dev/null +++ b/vpi/quickstart/run.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env sh + +set -e + +cd $(dirname "$0") + +echo "> Analyze ent.vhd and tb.vhd" +ghdl -a ../ent.vhd ../tb.vhd + +echo "> Elaborate tb" +ghdl -e -o tb tb + +echo "> Compile vpi_hello.c" +ghdl --vpi-compile gcc -c vpi_hello.c -o vpi.o + +echo "> Link vpi.o" +ghdl --vpi-link gcc vpi.o -o vpi.vpi + +if [ "$OS" = "Windows_NT" ]; then + # Need to put the directory containing libghdlvpi.dll in the path. + PATH=$PATH:`ghdl --vpi-library-dir-unix` +fi + +echo "> Execute tb" +./tb --vpi=./vpi.vpi diff --git a/vpi/quickstart/vpi_hello.c b/vpi/quickstart/vpi_hello.c new file mode 100644 index 00000000..20a61553 --- /dev/null +++ b/vpi/quickstart/vpi_hello.c @@ -0,0 +1,22 @@ +#include +#include + +PLI_INT32 cb_hello(){ + printf("Hello!\n"); + return 0; +} + +void entry_point_cb() { + s_cb_data cb; + + cb.reason = cbStartOfSimulation; + cb.cb_rtn = &cb_hello; + cb.user_data = NULL; + + if (vpi_register_cb(&cb) == NULL) { + vpi_printf ("cannot register cbStartOfSimulation call back\n"); + } +} + +// List of entry points called when the plugin is loaded +void (*vlog_startup_routines[]) () = {entry_point_cb, 0}; diff --git a/vpi/tb.vhd b/vpi/tb.vhd new file mode 100644 index 00000000..68b14a13 --- /dev/null +++ b/vpi/tb.vhd @@ -0,0 +1,41 @@ +library ieee; +use ieee.std_logic_1164.all; +use ieee.numeric_std.all; + +entity tb is + generic ( + G_WIDTH : natural := 4; + G_INST : natural := 4 + ); +end tb; + +architecture arch of tb is + + signal a, b : std_logic_vector(G_INST*G_WIDTH-1 downto 0); + signal c : std_logic_vector(G_INST downto 0); + +begin + + i_ent: for x in 0 to G_INST-1 generate + signal q: std_logic_vector(G_WIDTH downto 0); + begin + w_ent: entity work.ent + port map ( + A => a((x+1)*G_WIDTH-1 downto x*G_WIDTH), + B => b((x+1)*G_WIDTH-1 downto x*G_WIDTH), + C => c(x), + Q => q + ); + c(x+1) <= q(q'left); + end generate; + + process + begin + a <= std_logic_vector(to_unsigned(2, a'length)); + b <= std_logic_vector(to_unsigned(13, b'length)); + c(0) <= '0'; + wait for 10 ns; + wait; + end process; + +end architecture; From 4836b52073e4d08ed372b85e15806e0a058870bf Mon Sep 17 00:00:00 2001 From: umarcor Date: Sun, 3 May 2020 00:38:16 +0200 Subject: [PATCH 4/5] update .gitignore --- .gitignore | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.gitignore b/.gitignore index 476f7820..ec86efdd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,8 @@ *.lst *.o *.so +*.vpi +ent* +tb* +!*.vhd +!*.vhdl From 215e4e7253315658b58f0dc3285f55da31db727b Mon Sep 17 00:00:00 2001 From: umarcor Date: Sat, 2 May 2020 13:59:57 +0200 Subject: [PATCH 5/5] update README.md --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 509197d9..faaa28c1 100644 --- a/README.md +++ b/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. \ No newline at end of file +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)*.