vhpidirect: add 'quickstart/package'

.github/workflows/test.yml

@@ -21,6 +21,7 @@ jobs:
             quickstart/random,
             quickstart/math,
             quickstart/customc,
+            quickstart/package,
             wrapping/basic,
             wrapping/time,
             linking/bind,

doc/vhpidirect/examples/quickstart.rst

@@ -42,3 +42,10 @@ When the required functionality is not available in pre-built libraries, custom
 This example shows how to bind custom C functions in VHDL as either procedures or functions. Four cases are included: ``custom_procedure``, ``custom_procedure_withargs``, ``custom_function`` and ``custom_function_withargs``. In all cases, the parameters are defined as integers, in order to keep it simple. See :ref:`COSIM:VHPIDIRECT:Declarations` 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.
+
+:cosimtree:`package <vhpidirect/quickstart/package>`
+****************************************************
+
+If the auxillary VHPIDIRECT subprograms need to be accessed in more than one entity, it is possible to package the subprograms.
+
+In this example 2 different entities use a C defined ``c_printInt(val: integer)`` subprogram to print two different numbers. The subprogram attribute is declared as foreign in the ``pkg`` package and a dummy body for it is defined in the ``pkg`` package body. The dummy body contains an explicit assert that will highlight any failures to call the VHPIDIRECT C function.

vhpidirect/quickstart/package/caux.c

@@ -0,0 +1,4 @@
+#include<stdio.h>
+void printInt(int var){
+	printf("C-side print of int: %d\n", var);
+}

vhpidirect/quickstart/package/ent.vhd

@@ -0,0 +1,24 @@
+use work.pkg.all;
+
+entity ent is
+end ent;
+
+architecture rtl_A of ent is
+begin
+	process
+	begin
+		report "Entity1 calling c_print(1)." severity note;
+		c_printInt(1);
+		wait;
+	end process;
+end rtl_A;
+
+architecture rtl_B of ent is
+begin
+	process
+	begin
+		report "Entity2 calling c_print(2)." severity note;
+		c_printInt(2);
+		wait;
+	end process;
+end rtl_B;

vhpidirect/quickstart/package/pkg.vhd

@@ -0,0 +1,11 @@
+package pkg is
+	procedure c_printInt(val: integer);
+	attribute foreign of c_printInt : procedure is "VHPIDIRECT printInt";
+end package pkg;
+
+package body pkg is
+	procedure c_printInt(val: integer) is
+	begin
+		assert false report "c_printInt VHPI" severity failure;
+	end;
+end package body pkg;

vhpidirect/quickstart/package/run.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd $(dirname "$0")
+
+echo "Analyze pkg.vhd ent.vhd tb.vhd"
+ghdl -a pkg.vhd ent.vhd tb.vhd
+
+echo "Build tb with caux.c"
+ghdl -e -Wl,caux.c tb
+
+echo "Execute tb"
+./tb

vhpidirect/quickstart/package/tb.vhd

@@ -0,0 +1,15 @@
+entity tb is
+end tb;
+
+architecture arch of tb is
+begin
+
+	entA : entity work.ent(rtl_A);
+	entB : entity work.ent(rtl_B);
+
+	process
+	begin
+		report "Testbench." severity note;
+		wait;
+	end process;
+end;