vhpidirect: add 'wrapping/exitcb'

[umarcor]

The purpose of this PR is to document how to execute code after calling ghdl_main, that is, how to set an exit callback. Ref ghdl/ghdl#894.

EDIT: This can also be reproduced using C only by changing https://github.com/ghdl/ghdl-cosim/blob/master/vhpidirect/shared/shghdl/tb.vhd#L7 from severity note to failure.

However, currently, this is mostly a reproducer for the Aborted (core dumped) issue reported in ghdl/ghdl#803. In this example:

• All the tests are repeated with std 93 and std 08.
• A main function calls a function named wrapper, which calls ghdl_main.
• In wrapper, an exit handler is set.
• Tests are executed with two different main functions. In one of them, a signal handler is set, in order to catch SIGABRT.
• Tests are built as binaries and as shared libraries. Shared libraries are dynamically loaded and executed from a Python script.

Up to eleven different output items are expected:

1. PY COSIM ENTER
2. PY RUN ENTER
3. Hello wrapper!
4. tb.vhd:15:5:@0ms:(report failure): Hello wrapping/exitcb [fail]!
   ./tb08_fail:error: report failed
   in process .tb(fail).P0
   ./tb08_fail:error: simulation failed
5. SIGABRT caught 6!
6. Aborted (core dumped)
7. Bye wrapper <0>!
8. This is the exit handler.
9. 1
10. PY RUN EXIT
11. PY COSIM EXIT

These are the results:

	1	2	3	4	5	6	7	8	9	10	11
93/08 pass	-	-	x	x	-		x	x	0	-	-
93/08 pass so (py)	x	x	x	x	-		x	x	-	x	x
93/08 fail	-	-	x	x	-			x	1	-	-
93/08 fail so (py)	x	x	x	x	-	x
93/08 pass sigabrt	-	-	x	x			x	x	0	-	-
93/08 pass sigabrt so (py)	x	x	x	x			x	x	-	x	x
93/08 fail sigabrt	-	-	x	x				x	1	-	-
93/08 fail sigabrt so (py)	x	x	x	x	x	x
08 pass sigabrt VUnit	x	x	x	x			x	x	-	x	x
93 pass->fail sigabrt VUnit	x	x	x	x	x	x

Conclusions:

• When tests pass, whatever code after ghdl_main or in caller functions is properly executed (columns 7-11).
• When a test fails:
  • If a binary was used, code after ghdl_main is NOT executed (column 7), but it is possible to work around it with an exit handler (column 8), and code in caller functions is preserved (column 9-11). I would expect column 7 to be executed too.
  • If a shared library was used, an Aborted or Aborted (core dumpled) is produced. Nothing is executed after it (columns 7-11).
    • If a signal handler is used, it is possible to execute some code on abortion (column 5).

For completeness, VUnit uses a report of severity failure as the standard procedure to force a VHDL 1993 simulation to end; as reporting failing/passing tests is handled independently of the exit code. In the current status, it is not possible to use VUnit along with GHDL to produce and execute shared libraries. All VHDL 1993 tests and any failing VHDL 2008 tests will produce an abortion, forcing any surrounding Python code to exit inmediately.

All these tests are executed in CI. See test / vunit (vhpidirect/wrapping/exitcb, ./run.sh) and test / vunit (vhpidirect/wrapping/exitcb/py, ./vunit_run.sh) below.

[umarcor]

After ghdl/ghdl@0978b48, all C only examples do work now. I split Python and VUnit examples, and marked them as xfail. Those work on MSYS2, but fail on Linux (consistently, but differently on the containers or on the host).

The failure when using the upstream MSYS2 package is expected, since the patch was not uploaded yet.