tb_example.vhd

-- This Source Code Form is subject to the terms of the Mozilla Public
-- License, v. 2.0. If a copy of the MPL was not distributed with this file,
-- You can obtain one at http://mozilla.org/MPL/2.0/.
--
-- Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com

library vunit_lib;
context vunit_lib.vunit_context;
use vunit_lib.random_pkg.all;

library python_bridge;
context python_bridge.python_context;

use work.filter_vc_pkg.all;

library ieee;
use ieee.std_logic_1164.all;
use ieee.math_real.all;
use ieee.numeric_std.all;
use ieee.numeric_std_unsigned.all;

entity tb_example is
  generic(
    runner_cfg : string;
    debug_mode : boolean := true
  );
end entity;

architecture tb of tb_example is
  constant clk_period : time := 10 ns;
  signal clk : std_logic := '0';
  signal in_tvalid, in_tlast : std_logic := '0';
  signal in_tdata : std_logic_vector(7 downto 0);
  signal out_tvalid, out_tlast : std_logic := '0';
  signal out_tdata : std_logic_vector(7 downto 0);
  signal crc_error : std_logic;

  -- Ports of the python_model component
  signal model_x : integer := 0;
  signal model_y : integer;

  -- Ports of the two accumulator_model instances
  signal acc_a_x, acc_b_x : integer := 0;
  signal acc_a_y, acc_b_y : integer;

  -- A Python object made by the testbench and given to a filter_vc, which the
  -- testbench keeps using
  constant shared_average : python_object_t := new_python_object("filter_model.MovingAverage", kwarg("window", 3));

  -- Ports of the three filter_vc instances
  signal filter_valid : std_logic := '0';
  signal filter_x : integer := 0;
  signal filter_a_y, filter_b_y, filter_c_y : integer;
begin
  test_runner : process
    constant pi : real := 3.141592653589793;
    constant test_real_vector : real_vector := (-3.4028234664e38, -1.9, 0.0, 1.1, -3.4028234664e38);
    constant crc : std_logic_vector(7 downto 0) := x"17";
    constant expected : std_logic_vector(7 downto 0) := x"21";

    variable gcd, vhdl_integer : integer;
    variable test_input, packet : integer_vector_ptr_t;
    variable y : real;
    variable coordinate : real_vector(1 to 3);
    variable input_stimuli : integer_array_t;
    variable seed : integer;
    variable test_lengths : integer_vector_ptr_t;
    variable vhdl_real : real;

    -- A session is a Python namespace of its own, which is what makes it
    -- possible to have two models that both define model and config
    constant golden : python_session_t := new_session("golden");
    constant fixed_point : python_session_t := new_session("fixed_point");

    -- The operations of a session report on the logger of the identity of the
    -- session. python_logger is the parent of these loggers, so it is the one
    -- to configure, while it is the logger of the session that is mocked.
    constant default_logger : logger_t := get_logger(get_id(default_session));

    variable cycles : unsigned(63 downto 0) := x"123456789ABCDEF0";
    variable value : unsigned(31 downto 0) := x"DEADBEEF";
    variable offset : signed(15 downto 0) := to_signed(-12345, 16);
    variable received : unsigned(63 downto 0);
    variable status : unsigned(15 downto 0);
    variable image, transposed : integer_array_t;
    variable coefficients : real_vector(0 to 2);
    variable table : integer_vector_ptr_t;

    procedure set_tcl_installation is
    begin
      exec("from os import environ");
      exec("from sys import prefix");
      exec("from pathlib import Path");
      exec("old_environ = environ");
      exec(
        "if (Path(prefix) / 'lib' / 'tcl8.6').exists():" +
        "    environ['TCL_LIBRARY'] = str(Path(prefix) / 'lib' / 'tcl8.6')" +
        "else:" +
        "    environ['TCL_LIBRARY'] = str(Path(prefix) / 'tcl' / 'tcl8.6')"
      );
      exec(
        "if (Path(prefix) / 'lib' / 'tk8.6').exists():" +
        "    environ['TK_LIBRARY'] = str(Path(prefix) / 'lib' / 'tk8.6')" +
        "else:" +
        "    environ['TK_LIBRARY'] = str(Path(prefix) / 'tcl' / 'tk8.6')"
      );
    end;

    procedure unset_tcl_installation is
    begin
      exec("environ = old_environ");
    end;

    procedure query_if(expr : boolean; check_result : check_result_t) is
      variable logger : logger_t;
      variable log_level : log_level_t;
      variable line_num : natural;
      variable continue : boolean;
      alias log_check_result is log[check_result_t]; -- TODO: Fix that location preprocessing is too friendly with this
    begin
      if not is_pass(check_result) then
        if expr then
          log_level := get_log_level(check_result);
          logger := get_logger(get_checker(check_result));
          line_num := get_line_num(check_result);

          -- Make the query
          -- @formatter:off
          if line_num = 0 then
            continue := eval("psg.popup_yes_no('" & get_msg(check_result) & "\nDo you want to Continue?', title = '" &
              title(to_string(get_log_level(check_result))) & "')") = string'("Yes");
          else
            continue := eval("psg.popup_yes_no('" & get_msg(check_result) & "\nDo you want to Continue?', title = '" &
              title(to_string(get_log_level(check_result))) & " at " & get_file_name(check_result) & " : " &
              to_string(line_num) & "')") = string'("Yes");
          end if;
          -- @formatter:on

          if continue then
            -- If needed, increase stop count to prevent simulation stop
            if not has_stop_count(logger, log_level) then
              set_stop_count(logger, log_level, 2);
            elsif get_log_count(logger, log_level) = get_stop_count(logger, log_level) - 1 then
              set_stop_count(logger, log_level, get_log_count(logger, log_level) + 2);
            end if;
          end if;
        end if;

        log_check_result(check_result);
      end if;
    end;

    -- TODO: Time to make this part of the VUnit release even though it won't be supported for VHDL-93
    impure function new_integer_vector_ptr(
      vec : integer_vector;
      mode : storage_mode_t := internal;
      eid : index_t := -1
    ) return integer_vector_ptr_t is
      variable result : integer_vector_ptr_t;
      constant vec_normalized : integer_vector(0 to vec'length - 1) := vec;
    begin
      result := new_integer_vector_ptr(vec'length, mode => mode, eid => eid);

      for idx in vec_normalized'range loop
        set(result, idx, vec_normalized(idx));
      end loop;

      return result;
    end;

    -- The model of the device used in some of the examples below is the Python
    -- module device_model.py, next to this testbench. Like every relative file
    -- name the testbench gives exec_file and import_module_from_file, it is
    -- relative to the directory of this testbench file, which needs
    -- test_runner_setup to have completed.
    procedure import_device_model is
    begin
      import_module_from_file("device_model.py", "device_model");  -- <testbench directory>/device_model.py
    end;

  begin
    test_runner_setup(runner, runner_cfg);

    -- To avoid mixup with the Riviera-PRO TCL installation I had to
    -- set the TCL_LIBRARY and TK_LIBRARY environment variables
    -- to the Python installation. TODO: Find a better way if possible
    set_tcl_installation;

    show(display_handler, debug);

    -- @formatter:off
    while test_suite loop
      -------------------------------------------------------------------------------------
      -- Basic eval and exec examples
      -------------------------------------------------------------------------------------
      if run("Test basic exec and eval") then
        -- python_pkg provides the Python functions exec and eval.
        -- exec executes a string of Python code while eval evaluates
        -- a string containing a Python expression. Only eval returns
        -- a value.
        exec("a = -17");
        check_equal(eval("abs(a)"), 17);

      elsif run("Test multiline code") then
        -- Multiline code can be expressed in several ways. At least

        -- 1. Using multiple eval/exec calls:
        exec("a = 5");
        exec("b = 2 * a");
        check_equal(eval("b"), 10);

        -- 2. Using semicolon:
        exec("from math import factorial; a = factorial(5)");
        check_equal(eval("a"), 120);

        -- 3. Using LF:
        exec(
          "l = ['a', 'b', 'c']" & LF &
          "s = ', '.join(l)"
        );
        check_equal(eval("s"), string'("a, b, c"));

        -- 4. Using + as a shorthand for & LF &:
        exec(
          "def fibonacci(n):" +
          "    if n == 0:" +
          "        return [0]" +
          "    elif n == 1:" +
          "        return [0, 1]" +
          "    elif n > 1:" +
          "        result = fibonacci(n - 1)" +
          "        result.append(sum(result[-2:]))" +
          "        return result" +
          "    else:" +
          "        return []");

        exec("print(f'fibonacci(7) = {fibonacci(7)}')");

      elsif run("Test working with Python types") then
        -- Since exec and eval work with strings, VHDL types
        -- must be converted to a suitable string representation
        -- before being used.
        --
        -- Sometimes to_string is enough
        exec("an_integer = " & to_string(17));
        check_equal(eval("an_integer"), 17);

        -- Sometimes a helper function is needed
        exec("a_list = " & to_py_list_str(integer_vector'(1, 2, 3, 4)));
        check_equal(eval("sum(a_list)"), 10);

        -- For eval it is simply a matter of using a suitable
        -- overloaded variant
        coordinate := eval("[1.5, -3.6, 9.1]"); -- coordinate is real_vector(1 to 3)
        check_equal(coordinate(1), 1.5);
        check_equal(coordinate(2), -3.6);
        check_equal(coordinate(3), 9.1);

        -- Every eval has a more explicit alias that may be needed to help the compiler
        exec("from math import pi");
        vhdl_real := eval_real("pi");
        info("pi = " & to_string(vhdl_real));

        -- Since Python is more dynamically typed than VHDL it is sometimes useful to use
        -- dynamic VUnit types
        exec(
          "from random import randint" +
          "test_input = [randint(0, 255) for i in range(randint(1, 100))]");
        test_input := eval("test_input"); -- test_input is a variable of integer_vector_ptr_t type
        check(length(test_input) >= 1);
        check(length(test_input) <= 100);

      elsif run("Test result types of eval and call") then
        -- eval and call convert the Python value to the VHDL type the context expects.
        -- The result types a function cannot size by itself are given the width.
        import_device_model;

        -- A boolean result can be used directly as a condition
        if eval("device_model.is_busy()") then
          info("The device reports that it is busy");
        else
          check_failed("The device should report that it is busy");
        end if;
        check_true(call_boolean("device_model.is_busy"));

        -- A single bit and a vector of bits, std_ulogic characters on the Python side
        check_equal(call_std_ulogic("device_model.parity"), '1', result("for the parity of the status"));
        check_equal(call_std_ulogic_vector("device_model.status_bits"), std_ulogic_vector'(x"BEEF"));

        -- The procedure form takes the width of the result from the variable it writes to
        call_unsigned("device_model.status_word", status);
        check_equal(status, unsigned'(x"BEEF"));
        -- The function form takes it like to_unsigned, as a length or as size_res
        check_equal(call_unsigned("device_model.status_word", status'length), unsigned'(x"BEEF"));

        -- Strings, real vectors and dynamically sized integer vectors
        check_equal(call_string("device_model.status_name"), "running");
        coefficients := call_real_vector("device_model.coefficients");
        check_equal(coefficients(0), 0.5);
        check_equal(coefficients(2), 0.125);
        table := call_integer_vector_ptr("device_model.sine_table", arg(4));
        check_equal(length(table), 4);
        check_equal(get(table, 0), 0);
        check_equal(get(table, 3), 30273);

      elsif run("Test run script functions") then
        -- As we've seen we can define Python functions with exec (fibonacci) and we can import functions from
        -- Python packages. Writing large functions in exec strings is not optimal since we don't
        -- have the support of a Python-aware editor (syntax highlighting etc). Instead we can put our functions
        -- in a Python module, make sure that the module is on the Python search path, and then use a regular import.
        -- However, sometimes it is convenient to simply import a function defined in the run script without
        -- doing any extra steps. That approach is shown below.

        -- Without a parameter to the import_run_script procedure, the imported module will be named after the
        -- run script. In this case the run script is run.py and the module is named run.
        import_run_script;

        -- Now we can call functions defined in the run script
        exec("run.hello_world()");

        -- We can also give a name to the imported module
        import_run_script("my_run_script");
        exec("my_run_script.hello_world()");

        -- Regardless of module name, direct access is also possible
        exec("from my_run_script import hello_world");
        exec("hello_world()");

      elsif run("Test exec_file and import_module_from_file") then
        -- Any Python file can be executed as it is, or imported as a module by its path.
        -- The difference shows for a file that has a state of its own.

        -- exec_file executes the file in the namespace we have been using all along,
        -- which puts counter and bump there. A relative file name is relative to the
        -- directory of this testbench file, where bump.py is.
        exec_file("bump.py");  -- <testbench directory>/bump.py
        check_equal(integer'(call("bump")), 1);
        check_equal(integer'(call("bump")), 2);

        -- Executing it a second time executes counter = 0 again, which is easy to miss
        exec_file("bump.py");
        check_equal(integer'(call("bump")), 1, result("for the counter after re-executing the file"));

        -- import_module_from_file gives us the module object, which keeps its state
        import_module_from_file("bump.py", "bumper");  -- <testbench directory>/bump.py
        check_equal(integer'(call("bumper.bump")), 1);
        check_equal(integer'(call("bumper.bump")), 2);

        -- Executing the file once more does not touch the module
        exec_file("bump.py");
        check_equal(integer'(call("bumper.bump")), 3, result("for the counter of the imported module"));

      elsif run("Test sessions") then
        -- So far all Python code has been running in one and the same namespace. Every
        -- operation also takes a session that selects a namespace of its own, which is
        -- what makes it possible to have two models of the same integrator, both
        -- defining model and config, loaded side by side.
        exec_file("golden_model.py", golden);  -- <testbench directory>/golden_model.py
        exec_file("fixed_point_model.py", fixed_point);  -- <testbench directory>/fixed_point_model.py

        check_equal(eval_string("config['name']", golden), "golden");
        check_equal(eval_string("config['name']", fixed_point), "fixed_point");

        -- Each model keeps a state of its own. The golden model integrates in full
        -- precision while the fixed point model rounds every step.
        check_equal(real'(call("model.step", arg(3), session => golden)), 1.5);
        check_equal(real'(call("model.step", arg(3), session => fixed_point)), 2.0);
        check_equal(real'(call("model.step", arg(3), session => golden)), 3.0);
        check_equal(real'(call("model.step", arg(3), session => fixed_point)), 4.0);

        -- Only the names defined by the executed code are separate. Imported modules are
        -- shared, so the NumPy the fixed point model imported is the one the golden
        -- session gets and an attribute set on it is visible in both.
        exec("import numpy as np", golden);
        exec("np.vunit_example_marker = 7", fixed_point);
        check_equal(eval_integer("np.vunit_example_marker", golden), 7);

      elsif run("Test function call helpers") then
        exec("from math import gcd"); -- gcd = greatest common divisor

        -- Function calls are fundamental to using the eval and exec subprograms. To simplify
        -- calls with many arguments, there are a number of helper subprograms. Rather than:
        gcd := eval("gcd(" & to_string(35) & ", " & to_string(77) & ", " & to_string(119) & ")");
        check_equal(gcd, 7);

        -- we can use the call function:
        gcd := call("gcd", arg(35), arg(77), arg(119));
        check_equal(gcd, 7);

        -- Calls within an exec string can also be simplified
        exec("gcd = " & to_call_str("gcd", arg(35), arg(77), arg(119)));
        check_equal(eval("gcd"), 7);

        -- Calls to functions without a return value can be simplified with the call procedure
        call("print", arg(35), arg(77), arg(119));

        -- Keyword arguments are also suppored.
        check_equal(call("round", arg(3.14159), kwarg("ndigits", 3)), 3.142);

        exec("l = [1, 2]");
        call("l.sort", kwarg("reverse", true));
        check_equal(eval("l[0]"), 2);
        check_equal(eval("l[1]"), 1);

      elsif run("Test argument groups") then
        -- Arguments combined with & become a single argument. That makes it
        -- possible to pass more than the 10 arguments call takes, and to build the
        -- arguments of a call in steps, for example one group per register block.
        import_device_model;

        -- A register dump: five samples passed positionally and 20 status registers
        -- passed as one keyword argument group after them. The group uses one of the
        -- 10 argument slots no matter how many keyword arguments it holds.
        check_equal(
          integer'(call(
            "device_model.check_status",
            arg(integer_vector'(3, 1, 4, 1, 5)),

            -- The data path registers...
            (kwarg("temperature", 42) & kwarg("voltage", 3300) & kwarg("fifo_level", 17) &
             kwarg("fifo_depth", 64) & kwarg("overflows", 0) & kwarg("underflows", 0) &
             kwarg("packets_in", 1024) & kwarg("packets_out", 1024) & kwarg("crc_errors", 0) &
             kwarg("dropped", 0)) &

            -- ...and the link registers, as a group of their own
            (kwarg("link_up", true) & kwarg("lane_count", 4) & kwarg("gain", 1.5) &
             kwarg("threshold", -3) & kwarg("window", 8) & kwarg("mode", string'("loopback")) &
             kwarg("revision", 2) & kwarg("uptime", 86400) & kwarg("retries", 3) &
             kwarg("errors", 0))
          )),
          20,
          result("for the number of status registers Python received")
        );

      elsif run("Test wide integers and status bits") then
        -- An unsigned or signed argument of any width becomes an exact Python integer and
        -- is therefore not limited to the range of a VHDL integer, while a std_ulogic
        -- argument becomes a bool. These have names of their own rather than being arg
        -- overloads since a string literal belongs to every character array type.
        import_device_model;

        -- A 64 bit cycle counter, a negative offset and a 32 bit value above 2**31 all
        -- reach Python with their exact values
        check_equal(
          call_string(
            "device_model.status_text",
            arg_unsigned(cycles), arg_signed(offset),
            kwarg_unsigned("value", value) & kwarg("flag", '1')
          ),
          "cycles=1311768467463790320 offset=-12345 value=3735928559 flag=True"
        );

        -- H and L are read as 1 and 0, here in the flag
        check_equal(
          call_string(
            "device_model.status_text",
            arg_unsigned(cycles), arg_signed(offset),
            kwarg_unsigned("value", value) & kwarg("flag", 'H')
          ),
          "cycles=1311768467463790320 offset=-12345 value=3735928559 flag=True"
        );

        -- The width of the result is given by the variable the procedure form writes to
        call_unsigned("device_model.roundtrip", received, arg_unsigned(cycles));
        check_equal(received, cycles);

      -------------------------------------------------------------------------------------
      -- Examples related to error management
      --
      -- Errors can obviously occur in the executed Python code. They will all cause the
      -- test to fail with information about what was the cause
      -------------------------------------------------------------------------------------
      elsif run("Test syntax error") then
        exec(
          "def hello_word():" +
          "    print('Hello World)"); -- Missing a ' after Hello World
        exec("hello_world()");

      elsif run("Test type error") then
        vhdl_integer := eval("1 / 2"); -- Result is a float (0.5) and should be assigned to a real variable

      elsif run("Test Python exception") then
        vhdl_integer := eval("1 / 0"); -- Division by zero exception

      elsif run("Test error handling of a Python model") then
        -- The failures above are reported on the logger of the session the failing
        -- operation was performed in, here the default session, and that logger can be
        -- mocked. That is how a model is tested for what it does with invalid input,
        -- here an empty sine table, without the test failing.
        import_device_model;
        exec("from device_model import sine_table, failure_text");

        mock(default_logger, failure);
        table := call_integer_vector_ptr("sine_table", arg(0));
        check_only_log(
          default_logger,
          -- The message is the failing operation and the Python traceback, ending with
          -- the text of the exception. failure_text reproduces the traceback by
          -- evaluating the same expression; the source name in the traceback is the one
          -- the failing eval got, the first of this test case since exec is counted
          -- separately.
          "eval(""sine_table(0)"") failed:" & LF &
          call_string(
            "failure_text", arg(string'("sine_table(0)")), arg(string'("<eval #1>"))
          ),
          failure
        );
        unmock(default_logger);

      -------------------------------------------------------------------------------------
      -- Examples related to the simulation environment
      --
      -- VHDL comes with some functionality to manage the simulation environment such
      -- as working with files, directories, time, and dates. While this feature set was
      -- extended in VHDL-2019, it is still limited compared to what Python offers and the
      -- VHDL-2019 extensions are yet to be widely supported by simulators. Below are some
      -- examples of what we can do with Python.
      -------------------------------------------------------------------------------------
      elsif run("Test logging simulation platform") then
        -- Logging the simulation platform can be done directly from the run script but
        -- here we get the information included in the same log used by the VHDL code
        exec("from datetime import datetime");
        exec("import platform");
        exec("from vunit import VUnit");

        info(
          colorize("System name: ", cyan) & eval("platform.node()") +
          colorize("Operating system: ", cyan) & eval("platform.platform()") +
          colorize("Processor: ", cyan) & eval("platform.processor()") +
          colorize("Simulator: ", cyan) & eval("VUnit.from_argv().get_simulator_name()") +
          colorize("Simulation started: ", cyan) & eval("datetime.now().strftime('%Y-%m-%d %H:%M:%S')")
        );

      elsif run("Test globbing for files") then
        -- glob finds all files matching a pattern, in this case all Python files in the directory tree
        -- rooted in the testbench directory. The pattern is absolute, built from tb_path, since Python
        -- resolves a relative one against its working directory, which differs between simulators.
        exec("from glob import glob");
        exec("python_files = glob('" & join(tb_path(runner_cfg), "**", "*.py") & "', recursive=True)");

        for idx in 0 to eval("len(python_files)") - 1 loop
          -- Be aware that you may receive backslashes that should be replaced with forward slashes to be
          -- VHDL compatible
          info(replace(eval("python_files[" & to_string(idx) & "]"), "\", "/"));
        end loop;

      -------------------------------------------------------------------------------------
      -- Examples of user interactions
      --
      -- The end goal should always be fully automated testing but during an exploratory
      -- phase and while debugging it can be useful to allow for some user control of
      -- the simulation
      -------------------------------------------------------------------------------------
      elsif run("Test GUI browsing for input stimuli file") then
        if debug_mode then
          exec("import PySimpleGUI as psg"); -- Install PySimpleGUI with pip install pysimplegui
          input_stimuli := load_csv(replace(eval("psg.popup_get_file('Select input stimuli file')"), "\", "/"));
        end if;

      elsif run("Test querying for randomization seed") then
        if debug_mode then
          exec("import PySimpleGUI as psg");
          seed := integer'value(eval("psg.popup_get_text('Enter seed', default_text='1234')"));
        else
          seed := 1234;
        end if;
        info("Seed = " & to_string(seed));

      elsif run("Test controlling progress of simulation") then
        exec("import PySimpleGUI as psg");

        -- We can let the answers to yes/no pop-ups (psg.popup_yes_no) decide how to proceed,
        -- for example if the simulation shall continue on an error. Putting that into an
        -- action procedure to a check function and we can have a query_if wrapper like this:
        query_if(debug_mode, check_equal(crc, expected, result("for CRC")));

        info("Decided to continue");

      -------------------------------------------------------------------------------------
      -- Example math functions
      --
      -- You can find almost anything in the Python ecosystem so here are just a few
      -- examples of situations where that ecosystem can be helpful
      -------------------------------------------------------------------------------------

      -- Have you ever wished VHDL had some a of the features that SystemVerilog has?
      -- The support for a constraint solver is an example of something SystemVerilog has
      -- and VHDL does not. However, there are Python constraint solvers that might be helpful
      -- if a randomization constraint is difficult to solve with a procedural VHDL code.
      -- This is not such a difficult problem but just an example of using a Python constraint solver.
      elsif run("Test constraint solving") then
        exec("from constraint import Problem"); -- Install with pip install python-constraint
        exec("from random import choice");
        exec(
          "problem = Problem()" +
          "problem.addVariables(['x', 'y', 'z'], list(range(16)))" + -- Three variables in the 0 - 15 range

          -- Constrain the variable
          "problem.addConstraint(lambda x, y, z: x != z)" +
          "problem.addConstraint(lambda x, y, z: y <= z)" +
          "problem.addConstraint(lambda x, y, z: x + y == 8)" +

          -- Pick a random solution
          "solutions = problem.getSolutions()" +
          "solution = choice(solutions)"
        );

        -- Check that the constraints were met
        check(eval_integer("solution['x']") /= eval_integer("solution['z']"));
        check(eval_integer("solution['y']") <= eval_integer("solution['z']"));
        check_equal(eval_integer("solution['x']") + eval_integer("solution['y']"), 8);

      elsif run("Test NumPy arrays both ways") then
        -- integer_array_t is the VUnit type for data sets such as images and it is passed
        -- to Python as a NumPy array of the same shape. An array returned by Python
        -- becomes a new integer_array_t. The indexing matches: get(a, x, y) is a[x, y].
        import_module_from_file("image_model.py", "image_model");  -- <testbench directory>/image_model.py

        -- A 4 x 3 image with the column in the ones and the row in the tens
        image := new_2d(width => 4, height => 3, bit_width => 8, is_signed => false);
        for y in 0 to height(image) - 1 loop
          for x in 0 to width(image) - 1 loop
            set(image, x, y, 10 * y + x);
          end loop;
        end loop;

        -- Python sees the pixel VHDL sees, with the indices the other way around
        check_equal(integer'(call("image_model.pixel", arg(image), arg(2), arg(1))), get(image, 2, 1));

        -- NumPy transposes the image and the result comes back as an integer_array_t
        transposed := call_integer_array("image_model.transpose", arg(image));
        check_equal(width(transposed), height(image), result("for the width of the transposed image"));
        check_equal(height(transposed), width(image), result("for the height of the transposed image"));
        for y in 0 to height(image) - 1 loop
          for x in 0 to width(image) - 1 loop
            check_equal(get(transposed, y, x), get(image, x, y));
          end loop;
        end loop;
        deallocate(transposed);

      elsif run("Test using a Python module as the golden reference") then
        -- In this example we want to test that a receiver correctly accepts
        -- a packet with a trailing CRC. While we can generate a correct CRC to
        -- our test packets in VHDL, it is easier to use a Python package that
        -- already provides most standard CRC calculations. By doing so, we
        -- also have an independent opinion of how the CRC should be calculated.

        -- crccheck (install with pip install crccheck) supports more than 100 standard CRCs.
        -- Using the 8-bit Bluetooth CRC for this example
        exec("from crccheck.crc import Crc8Bluetooth");

        -- Let's say we should support packet payloads between 1 and 128 bytes and want to test
        -- a subset of those.
        test_lengths := new_integer_vector_ptr(integer_vector'(1, 2, 8, 16, 32, 64, 127, 128));
        for idx in 0 to length(test_lengths) - 1 loop
          -- Randomize a payload but add an extra byte to store the CRC
          packet := random_integer_vector_ptr(get(test_lengths, idx) + 1, min_value => 0, max_value => 255);

          -- Calculate and insert the correct CRC
          exec("packet = " & to_py_list_str(packet));
          set(packet, get(test_lengths, idx), eval("Crc8Bluetooth.calc(packet[:-1])"));

          -- This is where we would apply the generated packet to the tested receiver and verify that the CRC
          -- is accepted as correct
        end loop;

      elsif run("Test using Python in an behavioral model") then
        -- When writing VHDL behavioral models we want the model to be as high-level as possible.
        -- Python creates opportunities to make these models even more high-level

        -- In this example we use the crccheck package to create a behavioral model for a receiver.
        -- Such a model would normally be in a separate process or component so the code below is more
        -- an illustration of the general idea. We have a minimalistic incoming AXI stream (in_tdata/tvalid/tlast)
        -- receiving a packet from a transmitter (at the bottom of this file). The model collects the incoming packet
        -- in a dynamic vector (packet). in_tlast becomes active along with the last recevied byte which is also the
        -- CRC. At that point the packet collected before the CRC is pushed into Python where the expected CRC is
        -- calculated. If it differs from the received CRC, crc_error is set
        --
        -- The model also pass the incoming AXI stream to the output (out_tdata/tvalid/tlast)
        exec("from crccheck.crc import Crc8Bluetooth");
        packet := new_integer_vector_ptr;
        out_tvalid <= '0';
        crc_error <= '0';
        loop
          wait until rising_edge(clk);
          exit when out_tlast;
          out_tvalid <= in_tvalid;
          if in_tvalid then
            out_tdata <= in_tdata;
            out_tlast <= in_tlast;
            if in_tlast then
              exec("packet = " & to_py_list_str(packet));
              crc_error <= '1' when eval_integer("Crc8Bluetooth.calc(packet)") /= to_integer(in_tdata) else '0';
            else
              resize(packet, length(packet) + 1, value => to_integer(in_tdata));
            end if;
          end if;
        end loop;
        check_equal(crc_error, '0');
        out_tvalid <= '0';
        out_tlast <= '0';
        crc_error <= '0';

      elsif run("Test a verification component written in Python") then
        -- Taking the previous example one step further, the behavioral model can be a
        -- component of its own. The behaviour of python_model is a Python function and
        -- the VHDL only passes values, so this test case never mentions Python.
        for idx in 1 to 3 loop
          model_x <= idx;
          wait for clk_period;
          check_equal(model_y, 2 * idx + 1, result("for the output of the model"));
        end loop;

      elsif run("Test independent models of two instances") then
        -- Both accumulator_model instances execute the same Python file, each in a
        -- session of its own, so each keeps a total of its own
        for idx in 1 to 3 loop
          acc_a_x <= idx;
          acc_b_x <= 10 * idx;
          wait for clk_period;
          check_equal(acc_a_y, idx * (idx + 1) / 2, result("for the total of instance a"));
          check_equal(acc_b_y, 10 * idx * (idx + 1) / 2, result("for the total of instance b"));
        end loop;


      elsif run("Test Python objects as backends of verification components") then
        -- Every filter_vc has a MovingAverage object of its own, but filter_c_inst
        -- uses the one of the testbench, which the testbench can query too
        for idx in 1 to 4 loop
          wait until rising_edge(clk);
          filter_valid <= '1';
          filter_x <= 10 * idx;
        end loop;
        wait until rising_edge(clk);
        filter_valid <= '0';
        wait until rising_edge(clk);
        check_equal(filter_a_y, 35, result("for the average of the last 2 inputs"));
        check_equal(filter_b_y, 25, result("for the average of the last 4 inputs"));
        check_equal(filter_c_y, 30, result("for the average of the last 3 inputs"));
        check_equal(integer'(call(shared_average, "num_samples")), 4, result("for the shared object"));

      ---------------------------------------------------------------------
      -- Examples of string manipulation
      --
      -- Python has tons of functionality for working with string. One of the
      -- features most commonly missed in VHDL is the support for format
      -- specifiers. Here are two ways of dealing with that
      ---------------------------------------------------------------------
      elsif run("Test C-style format specifiers") then
        exec("from math import pi");
        info(eval("'pi is about %.2f' % pi"));

      elsif run("Test Python f-strings") then
        exec("from math import pi");
        info(eval("f'pi is about {pi:.2f}'"));

      ---------------------------------------------------------------------
      -- Examples of plotting
      --
      -- Simulators have a limited set of capabilities when it comes to
      -- Visualize simulation output beyond signal waveforms. Python has
      -- almost endless capabilities
      ---------------------------------------------------------------------
      elsif run("Test simple plot") then
        exec("from matplotlib import pyplot as plt"); -- Matplotlib is installed with pip install matplotlib
        exec("fig = plt.figure()");
        exec("plt.plot([1,2,3,4,5], [1,2,3,4,5])");
        exec("plt.show()");

      elsif run("Test advanced plot") then
        import_run_script("my_run_script");

        exec(
          "from my_run_script import Plot" +
          "plot = Plot(x_points=list(range(360)), y_limits=(-1.1, 1.1), title='Matplotlib Demo'," +
          "            x_label='x [degree]', y_label='y = sin(x)')");

        -- A use case for plotting from VHDL is to monitor the progress of slow simulations where we want to update
        -- the plot as more data points become available. This is not a slow simulation but the updating of the plot
        -- is a bit slow. This is not due to the VHDL code but inherent to Matplotlib. For the use case where we
        -- actually have a slow VHDL simulation, the overhead on the Matplotlib is of no significance.
        for x in 0 to 359 loop
          y := sin(pi * real(x) / 180.0);

          call("plot.update", arg(x), arg(y));
        end loop;

        exec("plot.close()");

      end if;
    end loop;
    -- @formatter:on

    -- Revert to old environment variables
    unset_tcl_installation;
    test_runner_cleanup(runner);
  end process;

  clk <= not clk after clk_period / 2;

  packet_transmitter : process is
    -- Packet with valid CRC
    constant packet : integer_vector := (48, 43, 157, 58, 110, 67, 192, 76, 119, 97, 235, 143, 131, 216, 60, 121, 111);
  begin
    -- Transmit the packet once
    in_tvalid <= '0';
    for idx in packet'range loop
      wait until rising_edge(clk);
      in_tdata <= to_slv(packet(idx), in_tdata);
      in_tlast <= '1' when idx = packet'right else '0';
      in_tvalid <= '1';
    end loop;
    wait until rising_edge(clk);
    in_tvalid <= '0';
    in_tlast <= '0';
    wait;
  end process;

  -- A component whose behaviour is a Python function
  python_model_inst : entity work.python_model
    generic map (
      model_file => "python_model.py"
    )
    port map (
      x => model_x,
      y => model_y
    );

  -- Two instances of a component with a stateful Python model
  acc_a_inst : entity work.accumulator_model
    generic map (
      model_file => "accumulator_model.py"
    )
    port map (
      x => acc_a_x,
      y => acc_a_y
    );

  acc_b_inst : entity work.accumulator_model
    generic map (
      model_file => "accumulator_model.py"
    )
    port map (
      x => acc_b_x,
      y => acc_b_y
    );

  -- Verification components whose behaviour is a Python object: two of their
  -- own, one named by an id and one enumerated, and the one of the testbench
  filter_a_inst : entity work.filter_vc
    generic map (
      filter => new_filter_vc(window => 2, id => get_id("filter_a"))
    )
    port map (
      clk   => clk,
      valid => filter_valid,
      x     => filter_x,
      y     => filter_a_y
    );

  filter_b_inst : entity work.filter_vc
    generic map (
      filter => new_filter_vc(window => 4)
    )
    port map (
      clk   => clk,
      valid => filter_valid,
      x     => filter_x,
      y     => filter_b_y
    );

  filter_c_inst : entity work.filter_vc
    generic map (
      filter => new_filter_vc(model => shared_average)
    )
    port map (
      clk   => clk,
      valid => filter_valid,
      x     => filter_x,
      y     => filter_c_y
    );
end;