vhpidirect: add 'quickstart/package'

.github/workflows/test.yml

@@ -20,6 +20,7 @@ jobs:
             vhpidirect/quickstart/random,
             vhpidirect/quickstart/math,
             vhpidirect/quickstart/customc,
+            vhpidirect/quickstart/package,
             vhpidirect/wrapping/basic,
             vhpidirect/wrapping/time,
             vhpidirect/linking/bind,
@@ -45,6 +46,7 @@ jobs:
             vhpidirect/quickstart/random,
             vhpidirect/quickstart/math,
             vhpidirect/quickstart/customc,
+            vhpidirect/quickstart/package,
             vhpidirect/wrapping/basic,
             vhpidirect/wrapping/time,
             #vhpidirect/linking/bind,  ! needs investigation, output of list-link seems to have wrong path format

doc/vhpidirect/examples/quickstart.rst

@@ -44,3 +44,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. This also makes it very easy to reuse the VHPIDIRECT declarations in different projects.
+
+In this example 2 different entities use a C defined ``c_printInt(val: integer)`` subprogram to print two different numbers. Subprogram declaration requirements are detailed under the :ref:`COSIM:VHPIDIRECT:Declarations` section.

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;