Merge pull request #8 from jchabloz/nxt_v1.1.0

Changes for release 1.2.0

.gitignore

@@ -12,6 +12,8 @@ tags
 Makefile
 include/vpi_config.h
 *.fst
+obj_dir/
+cvcsim
 
 # autoconf files
 config.status

Makefile.in

@@ -7,6 +7,7 @@ BUILDDIR = build
 INCDIRS += $(SRCDIR)/include
 INCDIRS += $(SRCDIR)/cjson
 LIBVPI = $(BUILDDIR)/verisocks.vpi
+DOCSDIR = docs
 
 CC = @CC@
 CFLAGS = @CFLAGS@
@@ -45,7 +46,10 @@ $(BUILDDIR)/%.o: %.c
 	@mkdir -p $(BUILDDIR)
 	$(CC) -o $@ -c $(CFLAGS) $<
 
-.PHONY: clean all
+.PHONY: clean all docs
+
+docs:
+	$(MAKE) -C $(DOCSDIR) html
 
 clean:
 	-$(RM) $(OBJS)

docs/conf.py

@@ -9,8 +9,8 @@
 project = 'Verisocks'
 copyright = '2023, Jérémie Chabloz'
 author = 'Jérémie Chabloz'
-version = '1.1.0'
-release = '1.1.0'
+version = '1.2.0'
+release = '1.2.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/src/intro.rst

@@ -21,7 +21,7 @@ to trying and compile Verisocks:
   packaged version provided with your favorite distro.
 * GCC C or C++ compiler
 
-.. note:: 
+.. note::
 
     Older GCC versions will most likely complain about the variadic macros used
     for logging purposes. These warnings can normally be safely ignored...
@@ -68,6 +68,11 @@ not to impact your system's Python packages.
 
     pip install <path to your verisocks folder>/python
 
+.. note::
+
+  The main advantage of Verisock's socket interface is its versatility. The
+  Python client provided with the code can serve as a reference implementation
+  that can easily be replicated in any language with an API for TCP sockets.
 
 Run the examples
 ----------------
@@ -138,12 +143,23 @@ have to typically be:
   variable rising edge),
 * etc...
 
-.. note::
+.. _sec_alternative_simulators:
+
+Alternative simulators
+**********************
 
-    Note that while the Verisocks PLI application has been developed targeting
-    specifically Icarus as a verilog simulator, there is no known reason that
-    it would not be working as well with any other simulator that is supporting
-    the VPI interface standard, including mainstream commercial simulators. I
-    will gladly accept any contribution that may confirm or infirm this
-    statement...
+While the Verisocks PLI application has been developed targeting specifically
+Icarus as a verilog simulator, there is no known reason that it would not be
+working as well with any other simulator that is supporting the VPI normative
+interface (as defined in `IEEE Std 1364
+<https://ieeexplore.ieee.org/document/1620780>`_ and `IEEE Std 1800
+<https://ieeexplore.ieee.org/document/10458102>`_), including mainstream
+commercial simulators.
 
+.. note::
+    I will gladly accept any contribution to test Verisocks with other
+    simulators.
+    As of now, I have only successfully tested it with Cadence's XCelium 64
+    29.03. As soon as I get more material, I will make a short tutorial for it.
+    My next target will be Tachyon's CVC. If anybody is able to test it with
+    QuestaSim...

docs/src/release_notes.rst

@@ -8,6 +8,20 @@ Releases of documentation and code are using the same version numbers. The
 version numbering system follows the `semantic versioning
 <https://semver.org/>`_ principles.
 
+1.2.0 - 2024-03-16
+******************
+
+* Modified :py:class:`Verisocks<verisocks.verisocks.Verisocks>` constructor and
+  :py:meth:`Verisocks.connect() <verisocks.verisocks.Verisocks.connect>` method
+  to include arguments for multiple, delayed connection trials. Examples and
+  test have been simplified accordingly.
+* Added correct management of system call interrupts while waiting on client
+  connection in the server code (see
+  https://www.gnu.org/software/libc/manual/html_node/Interrupted-Primitives.html
+  for details).
+* Added section :ref:`sec_alternative_simulators`.
+* Added method :py:meth:`verisocks.utils.setup_sim_run` to simplify foreseen
+  support for alternative simulators.
 
 1.1.0 - 2024-02-07
 ******************

examples/hello_world/test_hello_world.py

@@ -1,7 +1,6 @@
 from verisocks.verisocks import Verisocks
 from verisocks.utils import setup_sim, find_free_port
 import socket
-import time
 import pytest
 import logging
 import os.path
@@ -11,7 +10,6 @@
 PORT = find_free_port()
 VS_TIMEOUT = 10
 LIBVPI = "../../build/verisocks.vpi"
-CONNECT_DELAY = 0.1
 
 
 def setup_test():
@@ -24,7 +22,6 @@ def setup_test():
             f"-DVS_TIMEOUT={VS_TIMEOUT}"
         ]
     )
-    time.sleep(CONNECT_DELAY)
 
 
 @pytest.fixture

examples/spi_master/spi_master.v

@@ -42,12 +42,12 @@ module spi_master(cs_b, mosi, miso, sclk);
     reg cs_b, mosi, sclk;
     reg [7:0] tx_buffer [6:0];
     reg [7:0] rx_buffer [7:0];
-    reg [7:0] tx_crc, rx_crc;
+    reg [7:0] rx_crc;
     reg [255:0] ascii_cmd_id;
     reg [255:0] ascii_ret_id;
     reg rx_crc_error;
-	event start_transaction;
-	event end_transaction;
+    event start_transaction;
+    event end_transaction;
     integer transaction_counter;
 
     /**************************************************************************
@@ -128,8 +128,8 @@ module spi_master(cs_b, mosi, miso, sclk);
     begin
         if (tx_mask[7] == 0) begin
             rx_crc_error = 1'b0;
-            crc = 8'hff; //Initialize CRC with correct seed
-            rx_crc = 8'hff;
+            crc = CRC_SEED; //Initialize CRC with correct seed
+            rx_crc = CRC_SEED;
         end
         for (i = 0; i < 7; i = i + 1) begin
             if (tx_mask[7 - i] == 0) begin
@@ -159,12 +159,44 @@ module spi_master(cs_b, mosi, miso, sclk);
     end
     endtask
 
+    task init_tx_buffer;
+        integer i;
+    begin
+        for (i=0; i < 7; i = i + 1) begin
+            tx_buffer[i] = 8'd0;
+        end
+    end
+    endtask
+
     /**************************************************************************
     Hook for Verisocks to trigger task execution using a named event
     **************************************************************************/
     always @(start_transaction)
         spi_transmit_buffer(8'd0);
 
+    /**************************************************************************
+    Hook for Verilator - A public task (as declared using the verilator public
+    comment is used here. It could also have been exported as a DPI method,
+    which would make it also compatible with other simulators, however, passing
+    arguments gets more complex. Another alternative would have been to declare
+    the start_transaction and tx_buffer variables as public (I tested, this
+    works fine), but such a task makes for a better, more readable,
+    encapsulation.
+    **************************************************************************/
+    `ifdef VERILATOR
+    task trigger_transaction;
+        /*verilator public*/
+        input [7:0] tx_val [6:0];
+        integer i;
+    begin
+        for (i=0; i < 7; i = i + 1) begin
+            tx_buffer[i] = tx_val[i];
+        end
+        ->start_transaction;
+    end
+    endtask
+    `endif
+
     /**************************************************************************
     Initial
     **************************************************************************/
@@ -175,7 +207,8 @@ module spi_master(cs_b, mosi, miso, sclk);
         ascii_cmd_id = "N/A";
         ascii_ret_id = "N/A";
         rx_crc_error = 1'b0;
-        transaction_counter = 1'b0;
+        transaction_counter = 0;
+        init_tx_buffer();
     end
 
 endmodule

examples/spi_master/test_spi_master.py

@@ -1,7 +1,6 @@
 from verisocks.verisocks import Verisocks
 from verisocks.utils import setup_sim, find_free_port
 import os.path
-import time
 import logging
 import pytest
 import socket
@@ -12,7 +11,6 @@
 HOST = socket.gethostbyname("localhost")
 PORT = find_free_port()
 LIBVPI = "../../build/verisocks.vpi"  # Relative path to this file!
-CONNECT_DELAY = 0.01
 VS_TIMEOUT = 10
 SRC = ["spi_master.v", "spi_slave.v", "spi_master_tb.v"]
 
@@ -29,7 +27,6 @@ def setup_test():
             "-DDUMP_FILE=\"spi_master_tb.fst\""
         ]
     )
-    time.sleep(CONNECT_DELAY)
 
 
 def send_spi(vs, tx_buffer):

python/test/test_verisocks.py

@@ -1,7 +1,6 @@
 from verisocks.verisocks import Verisocks, VerisocksError
 import subprocess
 import os.path
-import time
 import shutil
 import pytest
 import logging
@@ -17,7 +16,6 @@
 # Parameters
 HOST = socket.gethostbyname("localhost")
 LIBVPI = "../../build/verisocks.vpi"  # Relative path to this file!
-CONNECT_DELAY = 0.1
 VS_TIMEOUT = 2
 
 
@@ -81,10 +79,6 @@ def setup_iverilog(port, src_file):
     pop = subprocess.Popen(
         cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
     print(f"Launched Icarus with PID {pop.pid}")
-    # Some delay is required for Icarus to launch the Verisocks server before
-    # being able to connect - Please adjust CONNECT_DELAY if required.
-
-    time.sleep(CONNECT_DELAY)
     return pop
 
 
@@ -105,9 +99,9 @@ def test_already_connected(vs, caplog):
 def test_connect_error():
     """Tests trying to connect to a non-running server"""
     port = find_free_port()
-    with pytest.raises(ConnectionRefusedError):
+    with pytest.raises(ConnectionError):
         vs = Verisocks(HOST, port)
-        vs.connect()
+        vs.connect(trials=1)
     vs.close()
 
 

python/verisocks/__init__.py

@@ -1,4 +1,4 @@
 """Verisocks Python client API
 """
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"

python/verisocks/utils.py

@@ -29,19 +29,59 @@ def _format_path(cwd, path):
     return os.path.abspath(os.path.join(cwd, path))
 
 
+def setup_sim_run(elab_cmd, sim_cmd, capture_output=True):
+    """Run simulation setup commands.
+
+    This command is e.g. used by :py:meth:`setup_sim` with elaboration and
+    simulation commands formatted according to the provided arguments.
+
+    Args:
+        elab_cmd (list): Elaboration command. It has to be provided as a list
+            of command and arguments (see subprocess documentation). If None,
+            this step is skipped.
+        sim_cmd (list): Simulation command. It has to be provided as a list
+            of command and arguments (see subprocess documentation). This
+            command is mandatory and cannot be None.
+        capture_output (bool): Defines if stdout and stderr output
+            are "captured" (i.e. not visible).
+
+    Returns:
+        subprocess.Popen
+    """
+
+    if elab_cmd:
+        subprocess.check_call(elab_cmd)
+
+    if sim_cmd is None:
+        raise ValueError("Simulation command and arguments is mandatory")
+
+    if capture_output:
+        pop = subprocess.Popen(
+            sim_cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+    else:
+        pop = subprocess.Popen(sim_cmd)
+
+    logging.info(f"Launched Icarus with PID {pop.pid}")
+    return pop
+
+
 def setup_sim(vpi_libpath, *src_files, cwd=".", vvp_filepath=None,
               vvp_logpath="vvp.log", ivl_exec=None, ivl_args=None,
               vvp_exec=None, vvp_args=None, vvp_postargs=None,
               capture_output=True):
     """Set up Icarus simulation by elaborating the design with :code:`iverilog`
-    and launching the simulation with :code:`vvp`.
+    and launching the simulation with :code:`vvp`. Uses
+    :py:meth:`setup_sim_run` to run the concatenated commands and arguments.
 
     Args:
-        cwd (str): Reference path to be used for all paths provided as relative
-            paths.
         vpi_libpath (str): Path to the compiled Verisocks VPI library.
         src_files (str): Paths to all (verilog) source files to use for the
             simulation. All files have to be added as separate arguments.
+        cwd (str): Reference path to be used for all paths provided as relative
+            paths.
         vvp_filepath (str): Path to the elaborated VVP file (iverilog output).
             If None (default), "sim.vvp" will be used.
         vvp_logpath (str): Path to a simulation logfile. Default="vvp.log". If
@@ -95,7 +135,6 @@ def setup_sim(vpi_libpath, *src_files, cwd=".", vvp_filepath=None,
         *ivl_args,
         *src_file_paths
     ]
-    subprocess.check_call(ivl_cmd)
 
     # Simulation with vvp
     if vvp_exec:
@@ -121,14 +160,5 @@ def setup_sim(vpi_libpath, *src_files, cwd=".", vvp_filepath=None,
         *vvp_postargs
     ]
 
-    if capture_output:
-        pop = subprocess.Popen(
-            vvp_cmd,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL
-        )
-    else:
-        pop = subprocess.Popen(vvp_cmd)
-
-    logging.info(f"Launched Icarus with PID {pop.pid}")
+    pop = setup_sim_run(ivl_cmd, vvp_cmd, capture_output)
     return pop