merge branch 'tutorial'

Author: umarcor

.github/workflows/tests.yml

@@ -10,13 +10,15 @@ on:
 jobs:
 
 
-# GNU/Linux: VUnit Action (uses Docker image ghdl/vunit:llvm)
+# GNU/Linux: VUnit Action (uses Docker image ghdl/vunit:mcode)
 
   lin-vunit:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: VUnit/[email protected]
+      - uses: VUnit/vunit_action@master
+        with:
+          cmd: tdd/run.py
 
 
 # GNU/Linux: Custom Docker image
@@ -28,7 +30,13 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - run: docker build -t vunit/tdd - < .github/Dockerfile
-    - run: docker run --rm -v $(pwd):/src -w /src -e CI vunit/tdd python3 -m pytest -v -s -ra test.py --color=yes
+    - run: >-
+        docker run --rm
+        -v $(pwd):/src
+        -w /src
+        -e CI
+        vunit/tdd
+        python3 -m pytest -v -s -ra tdd/test_tdd.py tutorial/test_tutorial.py --color=yes
 
 
 # GNU/Linux: GHDL Action + custom Python packages
@@ -45,7 +53,7 @@ jobs:
         python-version: 3.8
     - run: |
         python -m pip install --progress-bar off pytest vunit_hdl
-        python -m pytest -v -s -ra test.py --color=yes
+        python -m pytest -v -s -ra tdd/test_tdd.py tutorial/test_tutorial.py --color=yes
 
 
 # Windows: MSYS2 Action + GHDL Action + custom Python packages
@@ -67,7 +75,7 @@ jobs:
         backend: llvm
     - run: |
         python -m pip install --progress-bar off pytest vunit_hdl
-        python -m pytest -v -s -ra test.py --color=yes
+        python -m pytest -v -s -ra tdd/test_tdd.py tutorial/test_tutorial.py --color=yes
 
 
 # Windows: standalone GHDL zipfile/tarball + custom Python packages
@@ -88,5 +96,6 @@ jobs:
         mv ../ghdl-tmp/GHDL/${WINDOWS_RELEASE}/ ../ghdl
         rm -rf ../ghdl-tmp ghdl.zip
         export PATH=$PATH:$(pwd)/../ghdl/bin
+
         python -m pip install --progress-bar off pytest vunit_hdl
-        python -m pytest -v -s -ra test.py --color=yes
+        python -m pytest -v -s -ra tdd/test_tdd.py tutorial/test_tutorial.py --color=yes

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+vunit_out/

run.py renamed to tdd/run.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python3
+
 """VUnit run script."""
 
 from pathlib import Path

src/string_pkg.vhd renamed to tdd/src/string_pkg.vhd

@@ -1,11 +1,9 @@
 import sys
 from sys import executable, platform
-from os import environ
 from pathlib import Path
 from subprocess import check_call, STDOUT
 from shutil import which
 import unittest
-import pytest
 
 
 class TestExamples(unittest.TestCase):
@@ -14,23 +12,21 @@ class TestExamples(unittest.TestCase):
     """
 
     def setUp(self):
-        self.shell = [which('bash')] if platform == 'win32' else []
+        self.shell = [which("bash")] if platform == "win32" else []
         self.root = Path(__file__).parent
 
-        print('\n::group::Log')
+        print("\n::group::Log")
         sys.stdout.flush()
 
     def tearDown(self):
-        print('\n::endgroup::')
+        print("\n::endgroup::")
         sys.stdout.flush()
 
-
     def _sh(self, args):
         check_call(self.shell + args, stderr=STDOUT)
 
     def _py(self, args):
         check_call([executable] + args, stderr=STDOUT)
 
-
     def test_vunit_runpy(self):
-        self._py([str(self.root / 'run.py'), '-v'])
+        self._py([str(self.root / "run.py"), "-v"])

test/tb_to_string.vhd renamed to tdd/test/tb_to_string.vhd

@@ -0,0 +1,146 @@
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std_unsigned.all;
+
+use work.incrementer_pkg.all;
+
+entity incrementer is
+  generic(
+    delay : positive := 1);
+  port(
+    clk : in std_logic;
+
+    input_tdata  : in  std_logic_vector;
+    input_tvalid : in  std_logic;
+    input_tready : out std_logic;
+    input_tlast  : in  std_logic := '1';
+
+    output_tdata  : out std_logic_vector;
+    output_tvalid : out std_logic := '0';
+    output_tready : in  std_logic := '1';
+    output_tlast  : out std_logic := '0';
+
+    ctrl_arready : out std_logic                    := '0';
+    ctrl_arvalid : in  std_logic                    := '0';
+    ctrl_araddr  : in  std_logic_vector(7 downto 0) := x"00";
+
+    ctrl_rready : in  std_logic                     := '0';
+    ctrl_rvalid : out std_logic                     := '0';
+    ctrl_rdata  : out std_logic_vector(31 downto 0) := (others => '0');
+    ctrl_rresp  : out std_logic_vector(1 downto 0)  := "00";
+
+    ctrl_awready : out std_logic                    := '0';
+    ctrl_awvalid : in  std_logic                    := '0';
+    ctrl_awaddr  : in  std_logic_vector(7 downto 0) := x"00";
+
+    ctrl_wready : out std_logic                     := '0';
+    ctrl_wvalid : in  std_logic                     := '0';
+    ctrl_wdata  : in  std_logic_vector(31 downto 0) := (others => '0');
+    ctrl_wstrb  : in  std_logic_vector(3 downto 0)  := x"0";
+
+    ctrl_bvalid : out std_logic                    := '0';
+    ctrl_bready : in  std_logic                    := '0';
+    ctrl_bresp  : out std_logic_vector(1 downto 0) := "00");
+begin
+  assert input_tdata'length = output_tdata'length;
+end;
+
+architecture a of incrementer is
+  type state_t is (idle,
+                   writing,
+                   write_response,
+                   reading);
+
+  signal increment : std_logic_vector(input_tdata'length - 1 downto 0) := (0 => '1', others => '0');
+  signal state     : state_t                                           := idle;
+  signal addr      : std_logic_vector(ctrl_araddr'range);
+begin
+  main : process is
+    type delay_line_t is array (natural range <>) of std_logic_vector(input_tdata'length + 1 downto 0);
+    variable delay_line : delay_line_t(1 to delay + 1) := (others => (others => '0'));
+  begin
+    wait until rising_edge(clk);
+    if not output_tvalid or output_tready then
+      delay_line(1)          := input_tlast & (input_tvalid and input_tready) & input_tdata;
+      delay_line(2 to delay) := delay_line(1 to delay - 1);
+    end if;
+    output_tlast  <= delay_line(delay)(input_tdata'length + 1);
+    output_tvalid <= delay_line(delay)(input_tdata'length);
+    output_tdata  <= delay_line(delay)(input_tdata'length - 1 downto 0) + increment;
+  end process main;
+
+  input_tready <= not output_tvalid or output_tready;
+
+  ctrl : process is
+    constant axi_response_ok     : std_logic_vector(1 downto 0) := "00";
+    constant axi_response_decerr : std_logic_vector(1 downto 0) := "11";
+
+    -- Compare addresses of 32-bit words discarding byte address
+    function cmp_word_address(byte_addr : std_logic_vector;
+                              word_addr : natural) return boolean is
+    begin
+      return to_integer(byte_addr(byte_addr'left downto 2)) = word_addr/4;
+    end;
+
+  begin
+    wait until rising_edge(clk);
+
+    ctrl_arready <= '0';
+    ctrl_awready <= '0';
+    ctrl_wready  <= '0';
+    ctrl_rvalid  <= '0';
+    ctrl_rdata   <= (others => '0');
+
+    case state is
+      when idle =>
+
+        if ctrl_arvalid then
+          ctrl_arready <= '1';
+          addr         <= ctrl_araddr;
+          state        <= reading;
+
+        elsif ctrl_awvalid then
+          ctrl_awready <= '1';
+          addr         <= ctrl_awaddr;
+          state        <= writing;
+        end if;
+
+      when writing =>
+        if ctrl_wvalid then
+          ctrl_wready <= '1';
+
+          ctrl_bvalid <= '1';
+          ctrl_bresp  <= axi_response_ok;
+
+          state <= write_response;
+
+          -- Ignore byte write enable
+          if cmp_word_address(addr, increment_reg_addr) then
+            increment <= ctrl_wdata(increment'length - 1 downto 0);
+          end if;
+        end if;
+
+      when write_response =>
+        if ctrl_bready then
+          ctrl_bvalid <= '0';
+          state       <= idle;
+        end if;
+
+      when reading =>
+        if not ctrl_rvalid then
+          ctrl_rvalid <= '1';
+          ctrl_rresp  <= axi_response_ok;
+
+          if cmp_word_address(addr, increment_reg_addr) then
+            ctrl_rdata(increment'range) <= increment;
+          else
+            ctrl_rresp <= axi_response_decerr;
+          end if;
+
+        elsif ctrl_rready then
+          state <= idle;
+        end if;
+    end case;
+
+  end process ctrl;
+end;

test.py renamed to tdd/test_tdd.py

@@ -0,0 +1,3 @@
+package incrementer_pkg is
+  constant increment_reg_addr : natural := 0;
+end package incrementer_pkg;

tutorial/common/src/incrementer.vhd

@@ -0,0 +1,92 @@
+# Exercise 01
+## Purpose
+
+* Learn how to write a `run.py` script
+* Learn how to compile your project
+* Learn how to make your existing testbench VUnit compliant
+* Learn how a testbench fails and how it passes
+
+After this exercise you will be able to turn a non-VUnit testbench into a fully automated VUnit testbench.
+
+More information on this topic can be found in our [user guide](http://vunit.github.io/user_guide.html) and in the run library [documentation](https://vunit.github.io/run/user_guide.html).
+
+## Instructions
+
+* Create a copy of `exercise_01/original` named `exercise_01/workspace`.
+* Open `exercise_01/workspace/run.py` in your text editor. Get acquainted with the content.
+* If you have **more than one** simulator on your path you need to select one of them. `<simulator>` = `ghdl`, `modelsim`, `rivierapro`, `activehdl` or `incisive`.
+    ``` console
+    set VUNIT_SIMULATOR=<simulator>
+    ```
+* Run the script from the command line with the compile option:
+
+    ``` console
+    python run.py --compile
+    ```
+
+    All project files (just `src/counter.vhd`) and VUnit packages are found and compiled in dependency order.
+
+* Re-run the compile command. Nothing is re-compiled because nothing has changed. You can always do a clean compile
+
+    ``` console
+    python run.py --compile --clean
+    ```
+
+* Modify `run.py` to add a `tb_lib` library and add all source files in `test/` to that library
+
+    ``` python
+    tb_lib = prj.add_library("tb_lib")
+    tb_lib.add_source_files(join(root, "test", "*.vhd"))
+    ```
+
+* Re-compile:
+
+    ``` console
+    python run.py --compile
+    ```
+
+    Only `tb_counter` needs to be compiled.
+
+* Open `test/tb_counter.vhd` and look at the five lines making this a VUnit testbench
+
+    ``` vhdl
+    -- Include VUnit functionality
+    library vunit_lib;
+    context vunit_lib.vunit_context;
+
+    -- The testbench is controlled through the runner_cfg generic
+    runner_cfg : string;
+
+    -- Setup VUnit
+    test_runner_setup(runner, runner_cfg);
+
+    -- This line will force the simulation to a stop
+    test_runner_cleanup(runner);
+    ```
+
+* Run `run.py` and watch it fail
+
+    ``` console
+    python run.py
+    ```
+
+* Remove/fix/comment these lines, one by one, and run the script in between. Watch the different ways to fail
+
+    ``` vhdl
+    -- Different ways to fail
+    assert count = 1;
+    check_equal(count, 1);
+    info("LSB of count = " & to_string(count(width)));
+    wait for 1 hr;
+    ```
+
+    Failing on a testbench that is stuck requires the `test_runner_watchdog`. It's not required for a VUnit testbench but can save you from wasting a lot of simulation time.
+
+    ``` vhdl
+    test_runner_watchdog(runner, 1 ms);
+    ```
+
+    Full automation requires that all types of errors are detected and handled gracefully.
+* The previous errors caused an immediate stop of the simulation. Using VUnit checks you can control when the simulation stops. Run again to see multiple errors.
+
+* Remove the remaining lines before `test_runner_cleanup` to make the testbench pass.

tutorial/common/src/incrementer_pkg.vhd

@@ -0,0 +1,18 @@
+# Import Python modules
+from vunit import VUnit
+from pathlib import Path
+
+# Setup Python test runner project from command line arguments
+PRJ = VUnit.from_argv()
+
+# Set the root to the directory of this script file
+ROOT = Path(__file__).resolve().parent
+
+# Create and add VHDL Libraries to project
+LIB = PRJ.add_library("lib")
+
+# Add all VHDL files to Libraries
+LIB.add_source_files(ROOT / "src" / "*.vhd")
+
+# Run VUnit
+PRJ.main()