Merge pull request #7 from jchabloz/pre_1.1.0

Merge for release 1.1.0

.github/workflows/builddocs.yml

@@ -1,4 +1,4 @@
-name: Build docs
+name: Build and deploy docs
 
 on:
   workflow_dispatch:
@@ -23,9 +23,9 @@ jobs:
     name: Build documentation
     steps:
     - name: Checkout repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3"
     - name: Install dependencies

.github/workflows/makefile.yml

@@ -12,7 +12,7 @@ jobs:
     name: Builds VPI library
     steps:
     - name: Checkout repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         submodules: true
     - name: Install dependencies
@@ -24,12 +24,12 @@ jobs:
     - name: Build and run cunit test
       run: cd test;make;cd ..
     - name: Upload build artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: libvpi
         path: build/verisocks.vpi
     - name: Archive cunit test artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: cunit-test-results
         path: |
@@ -43,9 +43,9 @@ jobs:
     name: Run pytest
     steps:
     - name: Checkout repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.7"
     - name: Install dependencies
@@ -55,7 +55,7 @@ jobs:
         pip install -e ./python
         pip install pytest pytest-cov
     - name: Download build artifact
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: libvpi
     - name: Check verisocks.vpi
@@ -67,7 +67,7 @@ jobs:
       run: pytest -x --log-cli-level=INFO --cov=verisocks
     - name: Archive test logs
       if: always()
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: test-logs
         path: |

.github/workflows/testdocs.yml

@@ -0,0 +1,32 @@
+name: Test building docs
+
+on:
+  push:
+    branches-ignore:
+      - 'main'
+    paths:
+      - 'docs/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Build documentation
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ./python
+        pip install sphinx sphinx-rtd-theme myst-parser
+    - name: Render
+      run: |
+        sphinx-build -M html ./docs ./docs/_build
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: "./docs/_build/html"

docs/conf.py

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

docs/src/python_client.rst

@@ -42,3 +42,13 @@ Python client API documentation
 .. automodule:: verisocks.verisocks
     :members:
 
+
+Miscellaneous utilitaries
+*************************
+
+The module :py:mod:`verisocks.utils` is a collection of miscellaneous
+utilitaries and helper functions to ease setting up simulations using
+Verisocks.
+
+.. automodule:: verisocks.utils
+    :members:

docs/src/release_notes.rst

@@ -9,6 +9,19 @@ version numbering system follows the `semantic versioning
 <https://semver.org/>`_ principles.
 
 
+1.1.0 - Ongoing
+***************
+
+* Added :py:mod:`verisocks.utils` Python utilitary functions, including
+  documentation.
+* Added :py:meth:`Verisocks.info() <verisocks.verisocks.Verisocks.info>` method
+  as a shortcut to implement the TCP protocol :keyword:`info
+  <sec_tcp_cmd_info>` command.
+* Corrected *SPI master* example for standalone execution.
+* Added a minimalistic *Hello world* example, working both for standalone
+  execution or with pytest.
+
+
 1.0.0 - 2024-01-04
 ******************
 

docs/src/tcp_protocol.rst

@@ -149,6 +149,9 @@ arbitrary text is then printed out to the VPI standard output.
   * :json:`"type": "ack"` (acknowledgement)
   * :json:`"value": "command info received"`
 
+With the provided Python client reference implementation, the method
+:py:meth:`Verisocks.info() <verisocks.verisocks.Verisocks.info>`
+corresponds to this command.
 
 .. _sec_tcp_cmd_finish:
 

examples/hello_world/README.md

@@ -0,0 +1,50 @@
+# Verisocks example - Hello World
+
+## Introduction
+
+This example shows how to use Verisocks with a minimalistic test case. The test
+does nothing except asking Verisocks for the simulator name and version and
+then send an "Hello World!" string to the simulator using the `info` command of
+the TCP protocol.
+
+This example uses the helper function `setup_sim()` in order to easily set up
+the simulation.
+
+## Files
+
+The example folder contains the following files:
+
+* [hello_world_tb.v](hello_world_tb.v): Top verilog testbench
+* [test_hello_world.py](test_hello_world.py): Verisocks Python testbench file
+
+## Running the example
+
+This example can be run by directly executing the Python file or by using
+[`pytest`](https://docs.pytest.org).
+
+### Standalone execution
+
+Simply run the test script:
+```sh
+python test_hello_world.py
+```
+
+The results of the test script execution can be checked from the content of the
+`vvp.log` file, which should look like this:
+
+```log
+INFO [Verisocks]: Server address: 127.0.0.1
+INFO [Verisocks]: Port: 44041
+INFO [Verisocks]: Connected to localhost
+INFO [Verisocks]: Command "get(sel=sim_info)" received.
+INFO [Verisocks]: Command "info" received.
+INFO [Verisocks]: Hello World!
+INFO [Verisocks]: Command "finish" received. Terminating simulation...
+INFO [Verisocks]: Returning control to simulator
+```
+
+### Using pytest
+
+If you already have it installed, simply run `pytest` from within the SPI
+master example directory or from a parent directory.
+Otherwise, follow [installation instruction](https://docs.pytest.org/en/latest/getting-started.html#install-pytest). 

examples/hello_world/hello_world_tb.v

@@ -0,0 +1,35 @@
+/******************************************************************************
+File: hello_world_tb.v
+Description: Hello world example testbench for Verisocks
+******************************************************************************/
+
+/*******************************************************************************
+Includes and misc definitions
+*******************************************************************************/
+`timescale 1us/10ps //Time scale definitions
+
+`ifndef VS_NUM_PORT
+`define VS_NUM_PORT 5100
+`endif
+
+`ifndef VS_TIMEOUT
+`define VS_TIMEOUT 120
+`endif
+
+/*******************************************************************************
+Testbench
+*******************************************************************************/
+module hello_world_tb();
+
+    initial begin
+
+        /* Launch Verisocks server after other initialization */
+        $verisocks_init(`VS_NUM_PORT, `VS_TIMEOUT);
+
+        /* Make sure that the simulation finishes after a while... */
+        #1000
+        $finish(0);
+
+    end
+
+endmodule

examples/hello_world/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+log_file = pytest.log
+log_file_level = DEBUG
+log_file_format = [%(levelname)s][%(module)s] %(asctime)s - %(message)s
+log_file_date_format = %Y-%m-%d %H:%M:%S

examples/hello_world/test_hello_world.py

@@ -0,0 +1,60 @@
+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
+
+
+HOST = socket.gethostbyname("localhost")
+PORT = find_free_port()
+VS_TIMEOUT = 10
+LIBVPI = "../../build/verisocks.vpi"
+CONNECT_DELAY = 0.1
+
+
+def setup_test():
+    setup_sim(
+        LIBVPI,
+        "hello_world_tb.v",
+        cwd=os.path.dirname(__file__),
+        ivl_args=[
+            f"-DVS_NUM_PORT={PORT}",
+            f"-DVS_TIMEOUT={VS_TIMEOUT}"
+        ]
+    )
+    time.sleep(CONNECT_DELAY)
+
+
+@pytest.fixture
+def vs():
+    setup_test()
+    _vs = Verisocks(HOST, PORT)
+    _vs.connect()
+    yield _vs
+    # Teardown
+    try:
+        _vs.finish()
+    except ConnectionError:
+        logging.warning("Connection error - Finish command not possible")
+    _vs.close()
+
+
+def test_hello_world(vs):
+
+    assert vs._connected
+    answer = vs.get("sim_info")
+    assert answer['type'] == "result"
+    print(f"Simulator: {answer['product']}")
+    print(f"Version: {answer['version']}")
+
+    answer = vs.info("Hello World!")
+    assert answer['type'] == "ack"
+
+
+if __name__ == "__main__":
+
+    setup_test()
+    with Verisocks(HOST, PORT) as vs_cli:
+        test_hello_world(vs_cli)

examples/spi_master/README.md

@@ -66,3 +66,21 @@ def send_spi(vs, tx_buffer):
     rx_buffer = answer['value']
     return rx_buffer, counter
 ```
+
+## Running the example
+
+This example can be run by directly executing the Python file or by using
+[`pytest`](https://docs.pytest.org).
+
+### Standalone execution
+
+Simply run the test script:
+```sh
+python test_spi_master.py
+```
+
+### Using pytest
+
+If you already have it installed, simply run `pytest` from within the SPI
+master example directory or from a parent directory.
+Otherwise, follow [installation instruction](https://docs.pytest.org/en/latest/getting-started.html#install-pytest). 

examples/spi_master/spi_master_tb.v

@@ -41,8 +41,10 @@ module spi_master_tb();
 
     /* Initial loop */
     initial begin
-        $dumpfile("spi_master_tb.fst");
+        `ifdef DUMP_FILE
+        $dumpfile(`DUMP_FILE);
         $dumpvars(0, spi_master_tb);
+        `endif
 
         /* Launch Verisocks server after other initialization */
         $verisocks_init(`VS_NUM_PORT, `VS_TIMEOUT);