Various VPI examples

.github/workflows/test.yml

@@ -31,6 +31,12 @@ jobs:
             vhpidirect/arrays/intvector,
             vhpidirect/arrays/logicvector,
             vhpidirect/arrays/matrices,
+            vpi/quickstart/helloworld,
+            vpi/quickstart/begin_end,
+            vpi/quickstart/access,
+            vpi/quickstart/access_port,
+            vpi/quickstart/timestep,
+            vpi/list
           ]
     runs-on: ubuntu-latest
     env:
@@ -77,7 +83,13 @@ jobs:
             #vhpidirect/shared/shghdl, ! dlfcn.h is not available on win
             vhpidirect/arrays/intvector,
             vhpidirect/arrays/logicvector,
-            vhpidirect/arrays/matrices,
+            vhpidirect/arrays/matrices
+            #vpi/quickstart/helloworld,   ! VPI plugins needs their folder to be added to PATH   
+            #vpi/quickstart/begin_end,    ! VPI plugins needs their folder to be added to PATH 
+            #vpi/quickstart/access,       ! VPI plugins needs their folder to be added to PATH 
+            #vpi/quickstart/access_port,  ! VPI plugins needs their folder to be added to PATH      
+            #vpi/quickstart/timestep,     ! VPI plugins needs their folder to be added to PATH 
+            #vpi/list                     ! VPI plugins needs their folder to be added to PATH 
           ]
     runs-on: windows-latest
     env:

.gitignore

@@ -3,3 +3,9 @@
 *.lst
 *.o
 *.so
+*.vpi
+ent*
+tb*
+!*.vhd
+!*.vhdl
+doc/_build/*

doc/vpi/examples/index.rst

@@ -1,4 +1,7 @@
 Examples
 ########
 
-TBC
+.. toctree::
+
+   quickstart
+   list

doc/vpi/examples/list.rst

@@ -0,0 +1,5 @@
+List
+####
+
+:cosimtree:`list <vpi/list>`
+****************************

doc/vpi/examples/quickstart.rst

@@ -0,0 +1,23 @@
+Quickstart
+##########
+
+:cosimtree:`helloworld <vpi/quickstart/helloworld>`
+***************************************************
+
+:cosimtree:`begin_end <vpi/quickstart/begin_end>`
+*************************************************
+
+:cosimtree:`access <vpi/quickstart/access>`
+*******************************************
+
+:cosimtree:`access_port <vpi/quickstart/access_port>`
+*****************************************************
+
+:cosimtree:`timestep <vpi/quickstart/timestep>`
+***********************************************
+
+
+
+
+
+

vpi/README.md

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

vpi/common_vpi.h

@@ -0,0 +1,31 @@
+#pragma once
+#include <inttypes.h>
+#include <vpi_user.h>
+
+/*
+ * register_cb is a wrapper function around vpi_register_cb
+ * to simplify the the callback registering process
+ */
+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/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,22 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd "$(dirname $0)"
+
+PATH=$PATH:$(pwd)
+
+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./../ -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,50 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+entity tb is
+end tb;
+
+architecture behavioral of tb is
+
+        signal nibble1, nibble2 : unsigned(3 downto 0);
+        signal sum_0, sum_1, sum_2, sum_3 : unsigned(3 downto 0);
+        signal carry_out_0, carry_out_1, carry_out_2, carry_out_3: std_logic;
+
+    begin
+
+        ent_0: entity work.ent 
+                    port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum_0,
+                             carry_out => carry_out_0);
+
+        ent_1: entity work.ent 
+                    port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum_1,
+                             carry_out => carry_out_1);
+
+        ent_2: entity work.ent 
+                    port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum_2,
+                             carry_out => carry_out_2);
+
+        ent_3: entity work.ent 
+                    port map (nibble1 => nibble1,
+                             nibble2 => nibble2,
+                             sum => sum_3,
+                             carry_out => carry_out_3);
+        process
+
+        begin
+
+            wait for 10 ns;
+            wait;
+
+        end process;
+
+end architecture behavioral;
+
+

vpi/list/vpi.c

@@ -0,0 +1,61 @@
+#include <vpi_user.h>
+#include <stdio.h>
+#include "common_vpi.h"
+
+void print_net_in_module(vpiHandle module_handle) {
+    char* module_name = vpi_get_str(vpiName, module_handle);
+    vpiHandle net_handle;
+
+    printf(" Signals of %s: \n", module_name);
+    vpiHandle net_iterator = vpi_iterate(vpiNet,module_handle);
+    if(net_iterator){
+        while(net_handle = vpi_scan(net_iterator)){
+            char* net_full_name = vpi_get_str(vpiFullName, net_handle);
+            printf("  %s \n", net_full_name);
+            vpi_free_object(net_handle);
+        }
+    } 
+}
+
+void print_signals(){
+
+    vpiHandle top_mod_iterator;
+    vpiHandle top_mod_handle;
+
+    top_mod_iterator = vpi_iterate(vpiModule,NULL);
+
+    top_mod_handle = vpi_scan(top_mod_iterator);
+    while(top_mod_handle) {
+        print_net_in_module(top_mod_handle);
+        vpiHandle module_iterator = vpi_iterate(vpiModule,top_mod_handle);
+        if (module_iterator){
+            vpiHandle module_handle;
+            module_handle = vpi_scan(module_iterator);
+            while (module_handle) {
+                print_net_in_module(module_handle);
+                vpi_free_object(module_handle);
+                module_handle = vpi_scan(module_iterator);
+            }
+        }
+        vpi_free_object(top_mod_handle);
+        top_mod_handle = vpi_scan(top_mod_iterator);
+    }
+}
+
+PLI_INT32 start_cb(p_cb_data data){
+    (void) data;
+
+    printf("List of simulation signals: \n");
+    print_signals();
+
+    return 0;
+}
+
+void entry_point_cb() {
+    register_cb(start_cb, cbStartOfSimulation, -1);
+}
+
+void (*vlog_startup_routines[]) () = {
+    entry_point_cb,
+    0
+};

vpi/quickstart/access/run.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd "$(dirname $0)"
+
+PATH=$PATH:$(pwd)
+
+echo "Analyze tb.vhd"
+ghdl -a tb.vhd
+
+echo "Elaborate tb"
+ghdl -e tb
+
+echo "Compile vpi.c"
+ghdl --vpi-compile gcc -c vpi.c -I./../../ -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/quickstart/access/tb.vhd

@@ -0,0 +1,27 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+entity tb is
+end tb;
+
+architecture behavioral of tb is
+
+        signal nibble1, nibble2, sum : unsigned(3 downto 0);
+
+    begin
+
+        process
+
+        begin
+
+            wait for 10 ns;
+            wait;
+
+        end process;
+
+        sum <= nibble1 + nibble2;
+
+end architecture behavioral;
+
+

vpi/quickstart/access/vpi.c

@@ -0,0 +1,53 @@
+#include <vpi_user.h>
+#include <stdio.h>
+#include "common_vpi.h"
+
+PLI_INT32 start_cb(p_cb_data data){
+    (void) data;
+
+    // VPI value structure
+    s_vpi_value val;
+
+    // type of data format that is passed to the runtime.
+    val.format = vpiBinStrVal;
+    val.value.str = "0101";
+    printf("set %s in tb.nibble1 \n", val.value.str);
+
+    //vpi_handle_by_name returns an arbitrary port/signal in the
+    //simulation hierarchy
+    vpiHandle nibble1 = vpi_handle_by_name("tb.nibble1", NULL);
+
+    //vpi_put_value set the value to the passed signal handle
+    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 reads the value from the passed signal handle
+    vpi_get_value(sum, &val);
+    printf("get %s from tb.sum \n", val.value.str);
+
+    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
+};