Add packageless intvector examples (#5 a + c)

.github/workflows/test.yml

@@ -24,11 +24,13 @@ jobs:
             vhpidirect/quickstart/wrapping/time,
             vhpidirect/quickstart/linking/bind,
             vhpidirect/quickstart/package,
+            vhpidirect/arrays/intvectorgeneric,
             vhpidirect/quickstart/sharedvar,
             vhpidirect/shared/shlib,
             vhpidirect/shared/dlopen,
             vhpidirect/shared/shghdl,
             vhpidirect/arrays/intvector,
+            vhpidirect/arrays/intvector/maindefined,
             vhpidirect/arrays/logicvector,
             vhpidirect/arrays/matrices,
             vhpidirect/arrays/matrices/framebuffer,
@@ -73,11 +75,13 @@ jobs:
             vhpidirect/quickstart/wrapping/time,
             #vhpidirect/quickstart/linking/bind,  ! needs investigation, output of list-link seems to have wrong path format
             vhpidirect/quickstart/package,
+            vhpidirect/arrays/intvectorgeneric,
             vhpidirect/quickstart/sharedvar,
             vhpidirect/shared/shlib,
-            #vhpidirect/shared/dlopen,  ! dlfcn.h is not available on win
-            #vhpidirect/shared/shghdl,  ! dlfcn.h is not available on win
+            #vhpidirect/shared/dlopen, ! dlfcn.h is not available on win
+            #vhpidirect/shared/shghdl, ! dlfcn.h is not available on win
             vhpidirect/arrays/intvector,
+            vhpidirect/arrays/intvector/maindefined,
             vhpidirect/arrays/logicvector,
             vhpidirect/arrays/matrices,
             #vhpidirect/arrays/matrices/framebuffer, ! needs ImageMagick's 'convert'

.gitignore

@@ -8,3 +8,6 @@ ent*
 tb*
 !*.vhd
 !*.vhdl
+doc/_build/*
+.vunit_hash
+vhpidirect/arrays/matrices/vunit_axis_vcs/vunit_out/*

doc/vhpidirect/examples/arrays.rst

@@ -52,6 +52,26 @@ executing the simulation.
   There is no explicit example about how to have the size defined in C, but have the allocation/deallocation performed
   in VHDL. However, implementing such a solution is a matter of combining these examples with the VHDL-sized ones below.
 
+
+.. _COSIM:VHPIDIRECT:Examples:arrays:intvector:maindefined:
+
+:cosimtree:`Sized in C: First defined in main() <vhpidirect/arrays/intvector/maindefined>`
+==========================================================================================================
+
+If the integer array must be created or filled by some more advanced process before VHDL can request the array's pointer, it is
+possible to execute the GHDL simulation within a custom ``int main()`` entrypoint (see :ref:`COSIM:VHPIDIRECT:Examples:wrapping:basic`).
+In this example the custom entrypoint prompts the user for the size of the array and then handles the variables appropriately before
+going on to execute the GHDL simulation.
+
+:cosimtree:`Sized in VHDL <vhpidirect/arrays/intvectorgeneric>`
+===============================================================================
+
+Interface generics are the generics of the toplevel VHDL entity, and their values can be set via GHDL's runtime option :option:`-g` (see :ref:`simulation_options`). In this example an interface generic is used as an argument for the call of the VHPIDIRECT subprogram ``c_intArr_ptr(arraySize: integer)``. This subprogram is linked to the foreign C function ``getIntArr_ptr(int arraySize)`` which uses the argument to allocate an ``int*`` enough space to contain ``arraySize`` integers, populating each index thereafter. The subprogram returns the array's pointer and each index is printed out in VHDL.
+
+.. NOTE::
+	The C function is actually extended to handle a second call. If the ``int*`` has been used before its memory is freed, and if the new arraySize is greater than 0, the pointer is allocated enough memory again. In this way, a VHDL subprogram call of ``c_intArr_ptr(0);`` frees the previously allocated memory.
+
+
 .. _COSIM:VHPIDIRECT:Examples:arrays:intvector:vhdlsized:
 
 :cosimtree:`Sized in VHDL <vhpidirect/arrays/intvector/vhdlsized>`

vhpidirect/arrays/intvector/caux.c

@@ -0,0 +1,11 @@
+#define SIZE_ARRAY (sizeof(intArray)/sizeof(int))
+
+int intArray[] = {11, 22, 33, 44, 55, 66};
+
+int getIntArrSize(){
+    return SIZE_ARRAY;
+}
+
+int* getIntArr_ptr(){
+    return intArray;
+}

vhpidirect/arrays/intvector/maindefined/caux.c

@@ -0,0 +1,9 @@
+#include "caux.h"
+
+int getIntArrSize(){
+	return arraySize;
+}
+
+int* getIntArr_ptr(){
+	return intArray;
+}

vhpidirect/arrays/intvector/maindefined/caux.h

@@ -0,0 +1,5 @@
+int arraySize;
+int* intArray;
+
+int getIntArrSize();
+int* getIntArr_ptr();

vhpidirect/arrays/intvector/maindefined/main.c

@@ -0,0 +1,26 @@
+#include <stdio.h>
+#include <malloc.h>
+
+#include "caux.h"
+
+extern int ghdl_main(char argc, char* argv[]);
+
+int main(char argc, char* argv[]){
+	char strIn[3];
+
+	printf("Enter the length of the integer array [1-99]: ");
+	fgets(strIn, 3, stdin);
+	printf("\n");
+	sscanf(strIn, "%d", &arraySize);
+
+	intArray = malloc(arraySize*sizeof(int));
+	for(int i = 0; i < arraySize; i++){
+		intArray[i] = 11*(i+1);
+	}
+
+	printf("GHDL Simulation Begin\n*****************************************\n");
+	int ghdlReturn = ghdl_main(argc, argv);
+	printf("*****************************************\nGHDL Simulation End\n");
+
+	free(intArray);
+}

vhpidirect/arrays/intvector/maindefined/run.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd $(dirname "$0")
+
+echo "Build main.o (with caux.h) [GCC]"
+gcc -c main.c
+
+echo "Analyze tb.vhd [GHDL]"
+ghdl -a tb.vhd
+
+echo "Build tb (with caux.c) [GHDL]"
+ghdl -e -Wl,main.o -Wl,caux.c tb
+
+echo "Execute tb"
+./tb

vhpidirect/arrays/intvector/maindefined/tb.vhd

@@ -0,0 +1,36 @@
+entity tb is
+end entity tb;
+
+architecture RTL of tb is
+
+begin
+
+	process
+		function c_intArrSize return integer is-- represented C-side with int
+		begin
+			assert false report "c_intArrSize VHPI" severity failure;
+		end;
+		attribute foreign of c_intArrSize : function is "VHPIDIRECT getIntArrSize"; -- getIntArrSize is the C-side function name
+
+		type int_arr is array(0 to c_intArrSize-1) of integer;
+		type int_arr_ptr is access int_arr; -- represented C-side with int*
+
+		function c_intArr_ptr return int_arr_ptr is
+		begin
+			assert false report "c_intArr_ptr VHPI" severity failure;
+		end;
+		attribute foreign of c_intArr_ptr : function is "VHPIDIRECT getIntArr_ptr";
+
+		variable c_intArr : int_arr_ptr := c_intArr_ptr;
+
+	begin
+		report "Array length: " & integer'image(c_intArr.all'length);
+
+		for i in 0 to c_intArr.all'right loop
+			report "c_intArr[" & integer'image(i) &"] = " &  integer'image(c_intArr.all(i));
+		end loop;
+
+		wait;
+	end process;
+
+end architecture RTL;

vhpidirect/arrays/intvector/tb.vhd

@@ -0,0 +1,37 @@
+entity tb is
+end entity tb;
+
+architecture RTL of tb is
+
+begin
+
+	process
+		function c_intArrSize return integer is-- represented C-side with int
+		begin
+			assert false report "c_intArrSize VHPI" severity failure;
+		end;
+		attribute foreign of c_intArrSize : function is "VHPIDIRECT getIntArrSize"; -- getIntArrSize is the C-side function name
+
+		type int_arr is array(0 to c_intArrSize-1) of integer;
+		type int_arr_ptr is access int_arr; -- represented C-side with int*
+
+		function c_intArr_ptr return int_arr_ptr is
+		begin
+			assert false report "c_intArr_ptr VHPI" severity failure;
+		end;
+		attribute foreign of c_intArr_ptr : function is "VHPIDIRECT getIntArr_ptr";
+
+		variable c_intArr : int_arr_ptr := c_intArr_ptr;
+
+	begin
+		report "Array length: " & integer'image(c_intArr.all'length);
+
+		for i in 0 to c_intArr.all'right loop
+			report "c_intArr[" & integer'image(i) &"] = " &  integer'image(c_intArr.all(i)) & ". Set to: " & integer'image(-2*c_intArr.all(i));
+			c_intArr.all(i) := -2*c_intArr.all(i);
+		end loop;
+
+		wait;
+	end process;
+
+end architecture RTL;

vhpidirect/arrays/intvectorgeneric/caux.c

@@ -0,0 +1,17 @@
+#include <malloc.h>
+#include <stddef.h>
+
+int* intArray;
+int* getIntArr_ptr(int arraySize){//function acts like a constructor so initialise the variable
+    if(intArray != NULL){
+        free(intArray);
+    }
+    if(arraySize > 0){
+        intArray = malloc(arraySize*sizeof(int));
+        for (int i = 0; i < arraySize; i++)
+        {
+            intArray[i] = 11*(i+1);
+        }
+    }
+    return intArray;
+}

vhpidirect/arrays/intvectorgeneric/run.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd $(dirname "$0")
+
+echo "Analyze tb.vhd"
+ghdl -a tb.vhd
+
+echo "Build tb (with caux.c) [GHDL]"
+ghdl -e -Wl,caux.c tb
+
+echo "Execute tb (-gg_array_size=2)"
+./tb -gg_array_size=2
+
+echo "Execute tb (-gg_array_size=6)"
+./tb -gg_array_size=6

vhpidirect/arrays/intvectorgeneric/tb.vhd

@@ -0,0 +1,31 @@
+entity tb is
+	generic(
+		g_array_size : integer := 1
+	);
+end entity tb;
+
+architecture RTL of tb is
+begin
+	process
+		type int_arr is array(0 to g_array_size-1) of integer;
+		type int_arr_ptr is access int_arr; -- represented C-side with int*
+
+		impure function c_intArr_ptr(arraySize: integer) return int_arr_ptr is
+		begin
+			assert false report "c_intArr_ptr VHPI" severity failure;
+		end;
+		attribute foreign of c_intArr_ptr : function is "VHPIDIRECT getIntArr_ptr";
+
+		variable c_intArr : int_arr_ptr := c_intArr_ptr(g_array_size);
+	begin
+		report "ArraySize Interface Generic: " & integer'image(g_array_size);
+
+		for i in 0 to g_array_size-1 loop
+			report "c_intArr[" & integer'image(i) & "] = " &  integer'image(c_intArr(i));
+		end loop;
+
+		c_intArr := c_intArr_ptr(0);
+		wait;
+	end process;
+
+end architecture RTL;