Various VPI examples

.gitignore

@@ -3,3 +3,6 @@
 *.lst
 *.o
 *.so
+*.vpi
+ent
+tb

doc/vpi/examples/index.rst

@@ -1,4 +1,5 @@
 Examples
 ########
 
-TBC
+See :cosimtree:`VPI examples <vpi>` directory 
+

vpi/README.md

@@ -0,0 +1,14 @@
+## VPI examples
+
+The directory contains some VPI usage examples:
+
+1. [helloworld](./helloworld/) minimal VPI code example that runs a simulation, prints a message and exits. 
+2. [access](./access/) signal read/write example on an adder component using `vpi_put_value` and `vpi_get_value`.
+3. [list](./list/) example on signal hierarchy iteration using `vpi_iterate`and `vpi_scan`.
+4. [timestep](./timestep/) shows how to run a simulation for an arbitrary number of timesteps. 
+
+to run a test, just go in the directory and execute 
+```bash
+sh run.sh
+```
+

vpi/access/ent.vhd

@@ -0,0 +1,24 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+-- ent is a 4 bit adder
+
+entity ent is
+    port(nibble1, nibble2 : in unsigned(3 downto 0); 
+         sum       : out unsigned(3 downto 0); 
+         carry_out : out std_logic);
+
+end entity ent;
+
+architecture behavioral of ent is
+
+    signal temp : unsigned(4 downto 0); 
+
+begin 
+
+    temp <= ("0" & nibble1) + nibble2; 
+    sum       <= temp(3 downto 0); 
+    carry_out <= temp(4);
+
+end architecture behavioral;

vpi/access/run.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd "$(dirname $0)"
+
+echo "Analyze ent.vhd and tb.vhd"
+ghdl -a ent.vhd tb.vhd
+
+echo "Elaborate tb"
+ghdl -e tb
+
+echo "Compile vpi.c"
+ghdl --vpi-compile gcc -c vpi.c -I./../common/ -o vpi.o
+
+echo "Link vpi.o"
+ghdl --vpi-link gcc vpi.o -o vpi.vpi
+
+echo "Execute tb"
+ghdl -r tb --vpi=./vpi.vpi

vpi/access/tb.vhd

@@ -0,0 +1,39 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+entity tb is
+end tb;
+
+architecture behavioral of tb is
+    component ent
+        port(nibble1, nibble2 : in unsigned(3 downto 0); 
+             sum       : out unsigned(3 downto 0); 
+             carry_out : out std_logic);
+
+    end component ent;
+
+    for ent_0: ent use entity work.ent;
+
+        signal nibble1, nibble2, sum : unsigned(3 downto 0);
+        signal carry_out : std_logic;
+
+    begin
+
+        ent_0: ent port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum,
+                             carry_out => carry_out);
+
+        process
+
+        begin
+
+            wait for 10 ns;
+            wait;
+
+        end process;
+
+end architecture behavioral;
+
+

vpi/access/vpi.c

@@ -0,0 +1,47 @@
+#include <vpi_user.h>
+#include <stdio.h>
+#include "common_vpi.h"
+
+PLI_INT32 start_cb(p_cb_data data){
+    (void) data;
+    s_vpi_value val;
+
+    printf("Start of simulation \n");
+
+    val.format = vpiBinStrVal;
+    val.value.str = "0101";
+    printf("set %s in tb.nibble1 \n", val.value.str);
+    vpiHandle nibble1 = vpi_handle_by_name("tb.nibble1", NULL);
+    vpi_put_value(nibble1, &val, NULL, vpiNoDelay);
+
+    val.value.str = "0011";
+    printf("set %s in tb.nibble2 \n", val.value.str);
+    vpiHandle nibble2 = vpi_handle_by_name("tb.nibble2", NULL);
+    vpi_put_value(nibble2, &val, NULL, vpiNoDelay);
+
+    return 0;
+}
+
+PLI_INT32 end_cb(p_cb_data data){
+    (void) data;
+    s_vpi_value val;
+
+    val.format = vpiBinStrVal;
+    vpiHandle sum = vpi_handle_by_name("tb.sum", NULL);
+    vpi_get_value(sum, &val);
+    printf("get %s from tb.sum \n", val.value.str);
+
+    printf("End of simulation \n");
+
+    return 0;
+}
+
+void entry_point_cb() {
+    register_cb(start_cb, cbStartOfSimulation, -1);
+    register_cb(end_cb, cbEndOfSimulation, -1);
+}
+
+void (*vlog_startup_routines[]) () = {
+    entry_point_cb,
+    0
+};

vpi/common/common_vpi.h

@@ -0,0 +1,27 @@
+#pragma once
+#include <inttypes.h>
+#include <vpi_user.h>
+
+void register_cb(PLI_INT32(*f)(p_cb_data),
+                 PLI_INT32 reason,
+                 int64_t cycles){
+
+    s_cb_data cbData;
+    s_vpi_time simuTime;
+    if (cycles < 0){
+        cbData.time = NULL;
+    } else {
+        cbData.time = &simuTime;
+        simuTime.type = vpiSimTime;
+        simuTime.high = (PLI_INT32) (cycles >> 32);
+        simuTime.low = (PLI_INT32) (cycles & 0xFFFFFFFF);
+    }
+
+    cbData.reason = reason;
+    cbData.cb_rtn = f;
+    cbData.user_data = 0;
+    cbData.value = 0;
+
+    vpi_register_cb(&cbData);
+}
+

vpi/helloworld/ent.vhd

@@ -0,0 +1,24 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+-- ent is a 4 bit adder
+
+entity ent is
+    port(nibble1, nibble2 : in unsigned(3 downto 0); 
+         sum       : out unsigned(3 downto 0); 
+         carry_out : out std_logic);
+
+end entity ent;
+
+architecture behavioral of ent is
+
+    signal temp : unsigned(4 downto 0); 
+
+begin 
+
+    temp <= ("0" & nibble1) + nibble2; 
+    sum       <= temp(3 downto 0); 
+    carry_out <= temp(4);
+
+end architecture behavioral;

vpi/helloworld/run.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd "$(dirname $0)"
+
+echo "Analyze ent.vhd"
+ghdl -a ent.vhd
+
+echo "Elaborate tb"
+ghdl -e ent
+
+echo "Compile vpi.c"
+ghdl --vpi-compile gcc -c vpi.c -I./../common/ -o vpi.o
+
+echo "Link vpi.o"
+ghdl --vpi-link gcc vpi.o -o vpi.vpi
+
+echo "Execute ent"
+ghdl -r ent --vpi=./vpi.vpi

vpi/helloworld/vpi.c

@@ -0,0 +1,34 @@
+#include <vpi_user.h>
+#include <stdio.h>
+#include "common_vpi.h"
+
+PLI_INT32 start_cb(p_cb_data data){
+    (void) data;
+    printf("Start of simulation \n");
+    return 0;
+}
+
+PLI_INT32 delay_ro_cb(p_cb_data data){
+    (void) data;
+    printf("Hello world! \n");
+    vpi_control(vpiFinish, 0);
+    return 0;
+}
+
+PLI_INT32 end_cb(p_cb_data data){
+    (void) data;
+    printf("End of simulation \n");
+    return 0;
+}
+
+
+void entry_point_cb() {
+    register_cb(start_cb, cbStartOfSimulation, -1);
+    register_cb(end_cb, cbEndOfSimulation, -1);
+    register_cb(delay_ro_cb, cbAfterDelay, 0);
+}
+
+void (*vlog_startup_routines[]) () = {
+    entry_point_cb,
+    0
+};

vpi/list/ent.vhd

@@ -0,0 +1,24 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+-- ent is a 4 bit adder
+
+entity ent is
+    port(nibble1, nibble2 : in unsigned(3 downto 0); 
+         sum       : out unsigned(3 downto 0); 
+         carry_out : out std_logic);
+
+end entity ent;
+
+architecture behavioral of ent is
+
+    signal temp : unsigned(4 downto 0); 
+
+begin 
+
+    temp <= ("0" & nibble1) + nibble2; 
+    sum       <= temp(3 downto 0); 
+    carry_out <= temp(4);
+
+end architecture behavioral;

vpi/list/run.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd "$(dirname $0)"
+
+echo "Analyze ent.vhd and tb.vhd"
+ghdl -a ent.vhd tb.vhd
+
+echo "Elaborate tb"
+ghdl -e tb
+
+echo "Compile vpi.c"
+ghdl --vpi-compile gcc -c vpi.c -I./../common/ -o vpi.o
+
+echo "Link vpi.o"
+ghdl --vpi-link gcc vpi.o -o vpi.vpi
+
+echo "Execute tb"
+ghdl -r tb --vpi=./vpi.vpi

vpi/list/tb.vhd

@@ -0,0 +1,39 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+entity tb is
+end tb;
+
+architecture behavioral of tb is
+    component ent
+        port(nibble1, nibble2 : in unsigned(3 downto 0); 
+             sum       : out unsigned(3 downto 0); 
+             carry_out : out std_logic);
+
+    end component ent;
+
+    for ent_0: ent use entity work.ent;
+
+        signal nibble1, nibble2, sum : unsigned(3 downto 0);
+        signal carry_out : std_logic;
+
+    begin
+
+        ent_0: ent port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum,
+                             carry_out => carry_out);
+
+        process
+
+        begin
+
+            wait for 10 ns;
+            wait;
+
+        end process;
+
+end architecture behavioral;
+
+