vhpidirect: add 'wrapping/exitcb'

.github/workflows/doc.yml

@@ -1,15 +1,28 @@
 name: 'doc'
-on: [push, pull_request]
+
+on:
+  push:
+  pull_request:
+
 jobs:
-  linux:
+
+
+  btd:
+    name: '📓 Docs'
     if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: buildthedocs/btd@v0
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '📓 BuildTheDocs (BTD)'
+      uses: buildthedocs/btd@v0
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
-    - uses: actions/upload-artifact@master
+
+    - name: '📤 Upload artifact: HTML'
+      uses: actions/upload-artifact@master
       with:
         name: doc
         path: doc/_build/html

.github/workflows/test.yml

@@ -11,77 +11,169 @@ env:
 
 jobs:
 
+
   xyce-docker:
+    name: '🛳️ ghdl/cosim:xyce'
     runs-on: ubuntu-latest
     env:
       DOCKER_BUILDKIT: 1
     steps:
-    - uses: actions/checkout@v2
-    - run: docker run --rm -v $(pwd):/src -w /src -e CI ghdl/cosim:xyce python3 -m pytest -v -s -ra test.py::TestExamples::test_vhpidirect_vffi_xyce --color=yes
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '🚧 Run tests'
+      run: docker run --rm -v $(pwd):/src -w /src -e CI ghdl/cosim:xyce python3 -m pytest -v -s -ra test.py::TestExamples::test_vhpidirect_vffi_xyce --color=yes
+
 
   lin-docker:
+    name: '🛳️ ghdl/cosim:matplotlib'
     runs-on: ubuntu-latest
     env:
       DOCKER_BUILDKIT: 1
     steps:
-    - uses: actions/checkout@v2
-    - run: docker run --rm -v $(pwd):/src -w /src -e CI ghdl/cosim:matplotlib python3 -m pytest -v -s -ra test.py --color=yes
 
-  win-stable:
-    runs-on: windows-latest
-    steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
-      with:
-        python-version: 3.8
-    - env:
-        WINDOWS_RELEASE: 0.37-mingw64-llvm
-      shell: bash
-      run: |
-        curl -fsSL -o ghdl.zip https://github.com/ghdl/ghdl/releases/download/v0.37/ghdl-${WINDOWS_RELEASE}.zip
-        7z x ghdl.zip "-o../ghdl-tmp" -y
-        mv ../ghdl-tmp/GHDL/${WINDOWS_RELEASE}/ ../ghdl
-        rm -rf ../ghdl-tmp ghdl.zip
-        export PATH=$PATH:$(pwd)/../ghdl/bin
-        python -m pip install pytest vunit_hdl matplotlib numpy --progress-bar off
-        python -m pytest -v -s -ra test.py --color=yes
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '🚧 Run tests'
+      run: docker run --rm -v $(pwd):/src -w /src -e CI ghdl/cosim:matplotlib python3 -m pytest -v -s -ra test.py --color=yes
+
 
   lin-setup:
+    name: '🐧Ubuntu · nightly LLVM'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: ghdl/setup-ghdl-ci@master
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '⚙️ Setup GHDL (LLVM)'
+      uses: ghdl/setup-ghdl-ci@master
       with:
         backend: llvm
-    - uses: actions/setup-python@v2
+
+    - name: '🐍 Setup Python'
+      uses: actions/setup-python@v2
       with:
         python-version: 3.8
-    - name: Install dependencies
+
+    - name: '⚙️ Install dependencies'
       run: |
         ghdl --version
         sudo apt update -qq
         sudo apt install -y imagemagick libssl-dev
         python -m pip install --progress-bar off pytest vunit_hdl matplotlib numpy
-    - run: python -m pytest -v -s -ra test.py --color=yes
+
+    - name: '🚧 Run tests'
+      run: python -m pytest -v -s -ra test.py --color=yes
+
 
   win-setup:
+    name: '🟪 MSYS2 · nightly LLVM'
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '🟪 Setup MSYS2'
+      uses: msys2/setup-msys2@v2
+      with:
+        msystem: MINGW64
+        update: true
+        install: >
+          mingw-w64-x86_64-python-pip
+          mingw-w64-x86_64-python-numpy
+          mingw-w64-x86_64-python-matplotlib
+          mingw-w64-x86_64-openssl
+          mingw-w64-x86_64-dlfcn
+
+    - name: '⚙️ Setup GHDL (LLVM)'
+      uses: ghdl/setup-ghdl-ci@master
+      with:
+        backend: llvm
+
+    - name: '🐍 Install dependencies'
+      run: python -m pip install --progress-bar off pytest vunit_hdl
+
+    - name: '🚧 Run tests'
+      run: python -m pytest -v -s -ra test.py --color=yes
+
+
+  win-msys:
+    name: '🟪 MSYS2 · pacman LLVM'
     runs-on: windows-latest
     defaults:
       run:
         shell: msys2 {0}
     steps:
-    - uses: msys2/setup-msys2@v2
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '🟪 Setup MSYS2'
+      uses: msys2/setup-msys2@v2
       with:
         msystem: MINGW64
         update: true
         install: >
+          mingw-w64-x86_64-ghdl-llvm
           mingw-w64-x86_64-python-pip
           mingw-w64-x86_64-python-numpy
           mingw-w64-x86_64-python-matplotlib
           mingw-w64-x86_64-openssl
-    - uses: actions/checkout@v2
-    - uses: ghdl/setup-ghdl-ci@master
+          mingw-w64-x86_64-dlfcn
+
+    - name: '🐍 Install dependencies'
+      run: python -m pip install --progress-bar off pytest vunit_hdl
+
+    - name: '🚧 Run tests'
+      run: python -m pytest -v -s -ra test.py --color=yes
+
+#--
+
+  lin-setup-vffi-demo:
+    name: '🐧Ubuntu · nightly LLVM · VFFI'
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '⚙️ Setup GHDL (LLVM)'
+      uses: ghdl/setup-ghdl-ci@master
       with:
         backend: llvm
-    - run: python -m pip install --progress-bar off pytest vunit_hdl
-    - run: python -m pytest -v -s -ra test.py --color=yes
+
+    - name: '🚧 Run tests'
+      run: ./vhpidirect/vffi_user/demo/run.sh
+
+
+  win-setup-vffi-demo:
+    name: '🟪 MSYS2 · nightly LLVM · VFFI'
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+
+    - name: '🧰 Checkout'
+      uses: actions/checkout@v2
+
+    - name: '🟪 Setup MSYS2'
+      uses: msys2/setup-msys2@v2
+      with:
+        msystem: MINGW64
+        update: true
+
+    - name: '⚙️ Setup GHDL (LLVM)'
+      uses: ghdl/setup-ghdl-ci@master
+      with:
+        backend: llvm
+
+    - name: '🚧 Run tests'
+      run: ./vhpidirect/vffi_user/demo/run.sh

doc/vhpidirect/examples/quickstart.rst

@@ -98,6 +98,20 @@ to the compiler and/or linker. However, since it is not possible to do so with A
   ``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:wrapping:exitcb:
+
+:cosimtree:`exitcb <vhpidirect/quickstart/wrapping/exitcb>`
+-----------------------------------------------------------
+
+When wrapped in a foreign language, calls to ``ghdl_main`` should return an exit code and allow the regular execution of the
+wrapper, so that users can handle simulation results in there. However, bugs might result in failures that exit immediately
+through an abortion signal. This example shows how to register an exit handler and a signal handler, to allow executing
+custom code regardless of crashes in the simulation.
+
+In VHDL 1993, simulation termination statements and exit codes that simulators should produce were undefined. Therefore, it was
+common practice to termine the simulations through reports of severity ``failure``. When wrapping GHDL, such strategies
+might result in undesired exit procedures. Using VHDL 2008 is suggested.
+
 .. _COSIM:VHPIDIRECT:Examples:quickstart:linking:
 
 Linking

doc/vhpidirect/examples/shared.rst

@@ -8,6 +8,16 @@ Shared libs and dynamic loading
   As explained in :ref:`COSIM:VHPIDIRECT:Dynamic:loading_a_simulation`, in order to load binaries/libraries dynamically,
   those need to be built as position independent code/executables (PIC/PIE).
 
+This set of examples is an introduction from scratch for users who are familiar with C, but who have never built or loaded
+shared libraries (``*.so``, ``*.dll`` or ``*.dyn``):
+
+* :ref:`COSIM:VHPIDIRECT:Examples:shared:shlib`: write C code and compile it as a shared library.
+* :ref:`COSIM:VHPIDIRECT:Examples:shared:dlopen`: write two shared libraries in C, and write a main C program for loading and executing both of them.
+* :ref:`COSIM:VHPIDIRECT:Examples:shared:shghdl`: build a simulation as a shared library, and write a main C program for loading and executing it.
+* :ref:`COSIM:VHPIDIRECT:Examples:shared:py`: build a simulation as a shared library, and write a Python script for loading and executing it.
+* :ref:`COSIM:VHPIDIRECT:Examples:shared:pycb`: build a simulation as a shared library, and write a Python script for loading it and replacing callbacks
+  through ``ctypes`` before executing the simulation.
+
 .. _COSIM:VHPIDIRECT:Examples:shared:shlib:
 
 :cosimtree:`shlib <vhpidirect/shared/shlib>`
@@ -62,23 +72,36 @@ symbols in the shared libraries.
   :ref:`COSIM:VHPIDIRECT:Dynamic:generating_shared_libraries`. In this example, this case is also tested. However, this
   is not suggested at all, since it won't work on all platforms.
 
-.. WARNING::
-  Currently, failing simulations that are dynamically loaded do produce an *Abortion*. This forces any C or Python
-  wrapper/caller to exit inmediately, without running any post-check. See :ghdlsharp:`803` and :cosimsharp:`15` for
-  further details.
-
 .. _COSIM:VHPIDIRECT:Examples:shared:py:
 
-py
-**
+:cosimtree:`py <vhpidirect/shared/py>`
+**************************************
 
 `Python <https://www.python.org/>`_'s :py:mod:`ctypes` module is a built-in "*foreign function library for Python*", which
 "*provides C compatible data types, and allows calling functions in DLLs or shared libraries*". Thus, it is posible to
 reproduce :ref:`COSIM:VHPIDIRECT:Examples:shared:shghdl` by loading and executing the simulation from Python, instead of
-C. In fact, this is the foundation of `VUnit/cosim <https://github.com/VUnit/cosim>`_.
+C.
+
+This example uses the testbench and C sources from :ref:`COSIM:VHPIDIRECT:Examples:quickstart:wrapping:exitcb`, but the simulation
+is built as a shared library and loaded dynamically from Python. A helper Python module is used for providing OS agnostic
+utilities (see :cosimtree:`pyaux.py <vhpidirect/shared/py/pyaux.py>`).
 
-Nonethless, this example has not been added yet because of :cosimsharp:`15`. As soon as GHDL is fixed so that both successful
-and failing simulations exit cleanly, a minimal Python example will be added here.
+.. WARNING::
+  On some Linux environments, failing simulations that are dynamically loaded from Python do produce an *Abortion*. This
+  forces the wrapper/caller to exit inmediately, without running any post-check. See :ghdlsharp:`803` and :cosimsharp:`15` for
+  further details.
+
+:cosimtree:`py/vunit <vhpidirect/shared/py/vunit>`
+==================================================
+
+This is equivalent to the previous example (:ref:`COSIM:VHPIDIRECT:Examples:shared:py`). Instead of calling GHDL's CLI explicitly,
+VUnit's Python aided plumbing is used. This allows including any of VUnit's VHDL features into the simulation models, which
+are then to be loaded dynamically from Python. In fact, this is the foundation of `VUnit/cosim <https://github.com/VUnit/cosim>`_.
+
+.. WARNING::
+  On some Linux environments, using VHDL 2008 works but VHDL 1993 does not return cleanly in case of failure. An *Abortion* is
+  produced, which prevents the regular after-simulation execution of VUnit. See :ghdlsharp:`803` and :cosimsharp:`15` for
+  further details.
 
 .. _COSIM:VHPIDIRECT:Examples:shared:pycb: