update 74c2e51

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f2296f28fd7fc2c9803172c92da3cf4b
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/License.rst.txt

@@ -0,0 +1,178 @@
+.. _SRCLICENSE:
+
+.. Note::
+  This is a local copy of the `Apache License Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`__.
+
+.. Attention::
+  This **Apache License, 2.0** applies to all **source and configuration files of project**, **except documentation**.
+
+Apache License 2.0
+##################
+
+Version 2.0, January 2004
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+
+1. Definitions
+==============
+
+**"License"** shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1
+through 9 of this document.
+
+**"Licensor"** shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+**"Legal Entity"** shall mean the union of the acting entity and all other entities that control, are controlled by, or
+are under common control with that entity.
+For the purposes of this definition, **"control"** means (i) the power, direct or indirect, to cause the direction or
+management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+**"You"** (or **"Your"**) shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+**"Source"** form shall mean the preferred form for making modifications, including but not limited to software source
+code, documentation source, and configuration files.
+
+**"Object"** form shall mean any form resulting from mechanical transformation or translation of a Source form,
+including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+**"Work"** shall mean the work of authorship, whether in Source or Object form, made available under the License, as
+indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix
+below).
+
+**"Derivative Works"** shall mean any work, whether in Source or Object form, that is based on (or derived from) the
+Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship.
+For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link
+(or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+**"Contribution"** shall mean any work of authorship, including the original version of the Work and any modifications
+or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the
+Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+For the purposes of this definition, **"submitted"** means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of
+discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in
+writing by the copyright owner as **"Not a Contribution."**
+
+**"Contributor"** shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been
+received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License
+=============================
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object
+form.
+
+3. Grant of Patent License
+==========================
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent
+claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of
+their Contribution(s) with the Work to which such Contribution(s) was submitted.
+If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging
+that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement,
+then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation
+is filed.
+
+4. Redistribution
+=================
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You meet the following conditions:
+
+* You must give any other recipients of the Work or Derivative Works a copy of this License; and
+* You must cause any modified files to carry prominent notices stating that You changed the files; and
+* You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and
+  attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the
+  Derivative Works; and
+* If the Work includes a **"NOTICE"** text file as part of its distribution, then any Derivative Works that You
+  distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those
+  notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a
+  NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided
+  along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such
+  third-party notices normally appear.
+  The contents of the NOTICE file are for informational purposes only and do not modify the License.
+  You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to
+  the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the
+  License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and
+conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this
+License.
+
+5. Submission of Contributions
+==============================
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks
+=============
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the
+Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the
+content of the NOTICE file.
+
+7. Disclaimer of Warranty
+=========================
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including,
+without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE.
+You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability
+==========================
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required
+by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to use the Work (including but not limited
+to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages
+or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability
+=============================================
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of
+support, warranty, indemnity, or other liability obligations and/or rights consistent with this License.
+However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on
+behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any
+liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or
+additional liability.
+
+Appendix: How to apply the Apache License to your work
+======================================================
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets
+"[]" replaced with your own identifying information.
+(Don't include the brackets!)
+The text should be enclosed in the appropriate comment syntax for the file format.
+We also recommend that a file or class name and description of purpose be included on the same "printed page" as the
+copyright notice for easier identification within third-party archives.
+
+.. code-block:: none
+
+  Copyright [yyyy] [name of copyright owner]
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

_sources/ci.rst.txt

@@ -0,0 +1,33 @@
+.. program:: ghdl
+.. _COSIM:CI:
+
+Continuous Integration
+######################
+
+Since the main purpose of this repository is to provide reproducible and documented examples for users to learn, all of
+them are tested periodically in a `Continuous Integration (CI) <https://en.wikipedia.org/wiki/Continuous_integration>`_
+service. Currently, `GitHub Actions <https://github.com/features/actions>`_ is used and four different jobs/environments
+are tested:
+
+* GNU/Linux:
+
+    * Docker image ``ghdl/vunit:llvm`` from `ghdl/docker <https://github.com/ghdl/docker>`_.
+    * Latest *nightly* release installed through Action `ghdl/setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`_ on
+      Ubuntu.
+
+* Windows:
+
+    * Latest stable release for MINGW64 with LLVM backend.
+    * Latest *nightly* release installed through Action `ghdl/setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`_ on
+      MINGW64.
+
+    .. NOTE::
+       MSYS2 is set up with Action `msys2/setup-msys2 <https://github.com/msys2/setup-msys2>`_.
+
+The entrypoints of the examples are shell scripts (``run.sh``), makefiles (see :cosimsharp:`24`), or Python scripts
+(``run.py``). To handle all of them with a common interface, `pytest <https://pytest.org>`_ is used. Hence the full test suite
+is defined in :cosimtree:`test.py <test.py>`. Details about which examples are not supported on specific platforms can
+be found there.
+
+Past runs can be inspected at `ghdl/ghdl-cosim/actions <https://github.com/ghdl/ghdl-cosim/actions?query=workflow%3Atest>`_.
+It can be useful for users to know what to expect before executing the examples themselves.

_sources/index.rst.txt

@@ -0,0 +1,123 @@
+.. program:: ghdl
+
+.. _COSIM:
+
+Co-simulation with GHDL
+#######################
+
+.. index:: interfacing
+
+.. index:: other languages
+
+.. index:: foreign
+
+.. index:: VPI
+
+.. index:: VHPI
+
+.. index:: VHPIDIRECT
+
+.. index:: SystemC
+
+
+.. image:: _static/logo.png
+   :width: 500 px
+   :align: center
+   :target: https://github.com/ghdl/ghdl-cosim
+
+.. raw:: html
+
+    <br>
+
+    <p style="text-align: center;">
+      <a title="GitHub Repository" href="https://github.com/ghdl/ghdl-cosim"><img src="https://img.shields.io/badge/-ghdl/ghdl--cosim-323131.svg?longCache=true&style=flat-square&logo=github"></a><!--
+      -->
+      <a title="Source Code License" href="License.html"><img src="https://img.shields.io/badge/Code-Apache--2.0-green?longCache=true&style=flat-square&logo=Apache"></a><!--
+      -->
+      <a title="Documentation License" href="Doc-License.html"><img src="https://img.shields.io/badge/Doc-CC--BY%204.0-bf7600?longCache=true&style=flat-square&logo=CreativeCommons"></a><!--
+      -->
+      <a title="GHDL documentation" href="http://ghdl.github.io/ghdl"><img src="https://img.shields.io/website.svg?label=ghdl.github.io/ghdl&longCache=true&style=flat-square&url=http%3A%2F%2Fghdl.github.io%2Fghdl%2Findex.html&logo=GitHub&logoColor=fff"></a><!--
+      -->
+      <a title="Join the chat at https://gitter.im/ghdl1/Lobby" href="https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://img.shields.io/badge/Chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef"></a><!--
+      -->
+    </p>
+
+    <hr>
+
+This repository contains **documentation** and **working examples** about how to co-simulate VHDL and other languages through
+GHDL's foreign interfaces. Since specific features of the language and the tool are used, it is suggested for users
+who are new to either `GHDL` or `VHDL` to first read the :ref:`USING:QuickStart` in the main documentation
+(`ghdl.github.io/ghdl <https://ghdl.github.io/ghdl>`_).
+
+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 <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_ (VPI), also known as
+  Program Language Interface (PLI) 2.0.
+
+* `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 but VPI was published years before VHPI, GHDL supports VPI only. Furthermore, as an
+easier to use alternative, GHDL features a custom coexecution interface 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.
+
+.. ATTENTION:: In fact, VHPIDIRECT is defined as part of VHPI in VHDL 2008 LRM. However, GHDL's implementation is not
+  compliant with the standard. This is probably because VHPIDIRECT was implemented in GHDL based on some draft,
+  before VHDL 2008 was official. Nevertheless, the VASG is currently discussing the addition of a Foreign Function
+  Interface (FFI) or Direct Programming Interface (DPI) to the next revision of the standard. See `[LCS-202x] VHDL DPI/FFI based on GHDL’s implementation of VHPIDIRECT <https://umarcor.github.io/ghdl-cosim/vhdl202x/index.html>`_
+  (`PDF <https://github.com/umarcor/ghdl-cosim/blob/gh-pages/vhdl202x/vhdl202x-lcs-dpi.pdf>`_).
+
+: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 for the differences.
+
+
+.. toctree::
+   :hidden:
+
+   ci
+
+
+.. toctree::
+   :caption: VHPIDIRECT
+   :hidden:
+
+   vhpidirect/index
+   vhpidirect/declarations
+   vhpidirect/wrapping
+   vhpidirect/linking
+   vhpidirect/dynamic
+   vhpidirect/grt
+   vhpidirect/examples/index
+   vhpidirect/notebook/index
+
+
+.. toctree::
+   :caption: VPI
+   :hidden:
+
+   vpi/index
+   vpi/examples/index
+
+
+.. toctree::
+   :caption: VPHI
+   :hidden:
+
+   vhpi/index
+
+
+.. toctree::
+   :caption: Appendix
+   :hidden:
+
+   License
+   Doc-License

_sources/vhpi/index.rst.txt

@@ -0,0 +1,20 @@
+.. 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 functions allow traversing the hierarchy, getting/setting values and controlling 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>`_.