vunit-python-bridge 0.1.0__py3-none-any.whl

vunit_python_bridge/hdl/src/python_pkg_vhpi.vhd

@@ -0,0 +1,270 @@
+-- This package provides a dictionary types and operations
+--
+-- 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
+
+use std.textio.all;
+
+library vunit_lib;
+use vunit_lib.id_pkg.all;
+use vunit_lib.integer_array_pkg.all;
+use vunit_lib.integer_vector_ptr_pkg.all;
+use vunit_lib.logger_pkg.all;
+
+package python_ffi_pkg is
+  -- The identity of the Python interface, the identity of python_logger and
+  -- the parent of the identities of the sessions created from a name
+  constant p_python_id : id_t := get_id("python_bridge:python");
+
+  -- A session is a Python namespace with an identity, created from a name
+  -- under the identity of the Python interface or from an identity of its
+  -- own. Only the default session, the __main__ namespace, is supported by
+  -- this foreign language interface.
+  type python_session_t is record
+    p_data : integer_vector_ptr_t;
+  end record;
+
+  impure function new_session(name : string) return python_session_t;
+  impure function new_session(id : id_t) return python_session_t;
+
+  -- The identity of a session, which is what two sessions are compared by
+  impure function get_id(session : python_session_t) return id_t;
+
+  -- The name of the identity of a session, without hierarchy
+  impure function name(session : python_session_t) return string;
+
+  -- The session the operations are performed in when no other one is given.
+  -- It is created the way new_session does, which cannot be called here since
+  -- its body is not elaborated until the package body is.
+  constant default_session : python_session_t :=
+    (p_data => new_integer_vector_ptr(1, value => to_integer(get_id("default", parent => p_python_id))));
+
+  procedure python_setup;
+  -- TODO: Looks like Riviera-PRO requires the path to the shared library to be fixed at compile time
+  -- and that may become a bit limited. VHDL standard allow for expressions.
+  attribute foreign of python_setup : procedure is "VHPI libraries/python python_setup";
+  procedure python_cleanup;
+  attribute foreign of python_cleanup : procedure is "VHPI libraries/python python_cleanup";
+
+  function p_eval_integer(expr : string) return integer;
+  attribute foreign of p_eval_integer : function is "VHPI libraries/python eval_integer";
+  impure function eval_integer(expr : string; session : python_session_t := default_session) return integer;
+  alias eval is eval_integer[string, python_session_t return integer];
+
+  function p_eval_real(expr : string) return real;
+  attribute foreign of p_eval_real : function is "VHPI libraries/python eval_real";
+  impure function eval_real(expr : string; session : python_session_t := default_session) return real;
+  alias eval is eval_real[string, python_session_t return real];
+
+  function p_eval_integer_vector(expr : string) return integer_vector;
+  attribute foreign of p_eval_integer_vector : function is "VHPI libraries/python eval_integer_vector";
+  impure function eval_integer_vector(
+    expr : string; session : python_session_t := default_session
+  ) return integer_vector;
+  alias eval is eval_integer_vector[string, python_session_t return integer_vector];
+
+  function p_eval_real_vector(expr : string) return real_vector;
+  attribute foreign of p_eval_real_vector : function is "VHPI libraries/python eval_real_vector";
+  impure function eval_real_vector(
+    expr : string; session : python_session_t := default_session
+  ) return real_vector;
+  alias eval is eval_real_vector[string, python_session_t return real_vector];
+
+  function p_eval_string(expr : string) return string;
+  attribute foreign of p_eval_string : function is "VHPI libraries/python eval_string";
+  impure function eval_string(expr : string; session : python_session_t := default_session) return string;
+  alias eval is eval_string[string, python_session_t return string];
+
+  procedure p_exec(code : string);
+  attribute foreign of p_exec : procedure is "VHPI libraries/python exec";
+  procedure exec(code : string; session : python_session_t := default_session);
+
+  -----------------------------------------------------------------------------
+  -- Private, the primitives the bridge operations of python_pkg are built on
+  -----------------------------------------------------------------------------
+  -- Some operations of python_pkg are implemented by the VUnit Python
+  -- bridge, which is only available for NVC, GHDL and Questa. The primitives
+  -- below are declared so that python_pkg has one body for every simulator,
+  -- but they report a failure when they are used.
+
+  -- Logger of the Python interface, the parent of the session loggers
+  constant python_logger : logger_t := get_logger(p_python_id);
+
+  -- Result kinds, must match src/vunit_python_bridge/runtime.py
+  constant p_kind_integer : integer := 0;
+  constant p_kind_real : integer := 1;
+  constant p_kind_boolean : integer := 2;
+  constant p_kind_string : integer := 3;
+  constant p_kind_std_ulogic : integer := 4;
+  constant p_kind_std_ulogic_vector : integer := 5;
+  constant p_kind_signed : integer := 6;
+  constant p_kind_unsigned : integer := 7;
+  constant p_kind_integer_array : integer := 8;
+  constant p_kind_integer_vector : integer := 9;
+  constant p_kind_real_vector : integer := 10;
+
+  -- Name of the operation, used in the error messages
+  impure function p_eval_operation(expr : string; session : python_session_t := default_session) return string;
+
+  -- Execute the Python file with the given name
+  impure function p_exec_file(
+    file_name : string; session : python_session_t := default_session
+  ) return boolean;
+
+  -- Evaluate expr and convert the value to the VHDL type given by kind. width
+  -- is the length of a std_ulogic_vector, signed or unsigned result, -1 when
+  -- it is not known.
+  impure function p_eval(
+    expr      : string;
+    kind      : integer;
+    width     : integer;
+    operation : string;
+    session   : python_session_t := default_session
+  ) return boolean;
+
+  -- The result of the last evaluation
+  impure function p_result_integer return integer;
+  impure function p_result_string return string;
+  impure function p_result_integer_array return integer_array_t;
+
+  -- Transfer an integer_array_t to Python and return the id it is staged
+  -- under, -1 on failure.
+  impure function p_stage_array(arr : integer_array_t; operation : string) return integer;
+end package;
+
+package body python_ffi_pkg is
+  impure function new_session(name : string) return python_session_t is
+  begin
+    return new_session(get_id(name, parent => p_python_id));
+  end;
+
+  impure function new_session(id : id_t) return python_session_t is
+  begin
+    return (p_data => new_integer_vector_ptr(1, value => to_integer(id)));
+  end;
+
+  impure function get_id(session : python_session_t) return id_t is
+  begin
+    return to_id(get(session.p_data, 0));
+  end;
+
+  impure function name(session : python_session_t) return string is
+  begin
+    return name(get_id(session));
+  end;
+
+  impure function p_is_default(session : python_session_t) return boolean is
+  begin
+    return get_id(session) = get_id(default_session);
+  end;
+
+  procedure p_check_session(session : python_session_t) is
+  begin
+    if not p_is_default(session) then
+      report "Python sessions are only supported with NVC, GHDL and Questa" severity failure;
+    end if;
+  end;
+
+  impure function eval_integer(expr : string; session : python_session_t := default_session) return integer is
+  begin
+    p_check_session(session);
+    return p_eval_integer(expr);
+  end;
+
+  impure function eval_real(expr : string; session : python_session_t := default_session) return real is
+  begin
+    p_check_session(session);
+    return p_eval_real(expr);
+  end;
+
+  impure function eval_integer_vector(
+    expr : string; session : python_session_t := default_session
+  ) return integer_vector is
+  begin
+    p_check_session(session);
+    return p_eval_integer_vector(expr);
+  end;
+
+  impure function eval_real_vector(
+    expr : string; session : python_session_t := default_session
+  ) return real_vector is
+  begin
+    p_check_session(session);
+    return p_eval_real_vector(expr);
+  end;
+
+  impure function eval_string(expr : string; session : python_session_t := default_session) return string is
+  begin
+    p_check_session(session);
+    return p_eval_string(expr);
+  end;
+
+  procedure exec(code : string; session : python_session_t := default_session) is
+  begin
+    p_check_session(session);
+    p_exec(code);
+  end;
+
+  -----------------------------------------------------------------------------
+  -- Private, the primitives the bridge operations of python_pkg are built on
+  -----------------------------------------------------------------------------
+  procedure p_unsupported(name : string) is
+  begin
+    failure(python_logger, name & " requires NVC, GHDL or Questa");
+  end;
+
+  impure function p_eval_operation(expr : string; session : python_session_t := default_session) return string is
+  begin
+    if p_is_default(session) then
+      return "eval(""" & expr & """)";
+    end if;
+    return "eval(""" & expr & """, session => """ & name(session) & """)";
+  end;
+
+  impure function p_exec_file(
+    file_name : string; session : python_session_t := default_session
+  ) return boolean is
+  begin
+    p_unsupported("exec_file");
+    return false;
+  end;
+
+  impure function p_eval(
+    expr      : string;
+    kind      : integer;
+    width     : integer;
+    operation : string;
+    session   : python_session_t := default_session
+  ) return boolean is
+  begin
+    p_unsupported(operation);
+    return false;
+  end;
+
+  impure function p_result_integer return integer is
+  begin
+    p_unsupported("p_result_integer");
+    return integer'low;
+  end;
+
+  impure function p_result_string return string is
+  begin
+    p_unsupported("p_result_string");
+    return "";
+  end;
+
+  impure function p_result_integer_array return integer_array_t is
+  begin
+    p_unsupported("p_result_integer_array");
+    return null_integer_array;
+  end;
+
+  impure function p_stage_array(arr : integer_array_t; operation : string) return integer is
+  begin
+    p_unsupported(operation);
+    return -1;
+  end;
+end package body;

vunit_python_bridge/hdl/tools/generate_python_pkg.py

@@ -0,0 +1,386 @@
+# 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
+
+"""
+Generate python_pkg.vhd from python_pkg.vhd.in in this directory.
+
+The template holds the parts of python_pkg that are written by hand. The
+generated parts are the argument value types of call, the result types of eval
+and call and the execution of Python files. They are mostly one overload per
+type, which is why they are generated. The operations that are implemented by
+the Python bridge (NVC, GHDL and Questa) are built on the p_ prefixed
+primitives of python_ffi_pkg, which the VHPI variant of that package
+implements by reporting a failure.
+"""
+
+from pathlib import Path
+from string import Template
+
+SRC_PATH = Path(__file__).parent.parent / "src"
+TEMPLATE_PATH = Path(__file__).parent
+
+# Like the operations of python_pkg, every operation takes the session it is
+# performed in as its last parameter
+SESSION = "session : python_session_t := default_session"
+
+# The 10 arguments of call
+ARGS = [f"arg{index}" for index in range(1, 11)]
+ARG_PARAMETERS = f"{', '.join(ARGS)} : arg_t := null_arg"
+ARG_ACTUALS = ", ".join(ARGS)
+ARG_SIGNATURE = ", ".join(["string"] + ["arg_t"] * len(ARGS) + ["python_session_t"])
+
+# Value types of arg and kwarg that are generated rather than declared in the
+# template.
+#
+# vhdl:   the VHDL type
+# impure: true when the functions must be impure
+# fails:  true when the conversion can fail, which makes p_arg_value take the
+#         name of the operation to report the value it cannot convert
+# suffix: appended to the arg and kwarg names, empty for an overload
+#
+# The integer_array_t value is transferred by the Python bridge, which makes it
+# available for NVC, GHDL and Questa only. The other values are built from the
+# Python source text of the value alone and work on any simulator.
+#
+# The unsigned and signed values are passed to typed names, arg_unsigned and
+# arg_signed, on purpose: plain overloads would make a string literal
+# argument, arg("Hello"), ambiguous since a string literal belongs to every
+# character array type. std_ulogic needs no such name, being a scalar, and
+# std_ulogic_vector is deliberately not among the types at all. Such values
+# are passed as arg(to_string(slv)) and arg_unsigned(unsigned(slv)).
+ARG_VALUES = [
+    dict(vhdl="real_vector", impure=False, fails=False, suffix=""),
+    dict(vhdl="integer_vector_ptr_t", impure=True, fails=False, suffix=""),
+    dict(vhdl="std_ulogic", impure=True, fails=True, suffix=""),
+    dict(vhdl="unsigned", impure=True, fails=True, suffix="_unsigned"),
+    dict(vhdl="signed", impure=True, fails=True, suffix="_signed"),
+    dict(vhdl="integer_array_t", impure=True, fails=True, suffix=""),
+]
+
+# Result types of eval and call.
+#
+# name:     suffix of eval_<name> and call_<name>
+# vhdl:     the VHDL type
+# kind:     result kind passed to the bridge, see src/vunit_python_bridge/runtime.py
+# value:    expression giving the result of a successful evaluation
+# default:  value returned after a failure
+# hand_written_eval/hand_written_call: true when the eval/call function is
+#           declared in the template rather than generated. value and default
+#           are only needed when the eval function is generated.
+RESULTS = [
+    dict(
+        name="integer",
+        vhdl="integer",
+        kind="p_kind_integer",
+        hand_written_eval=True,
+        hand_written_call=True,
+    ),
+    dict(
+        name="real",
+        vhdl="real",
+        kind="p_kind_real",
+        hand_written_eval=True,
+        hand_written_call=True,
+    ),
+    dict(
+        name="integer_vector",
+        vhdl="integer_vector",
+        kind="p_kind_integer_vector",
+        hand_written_eval=True,
+        hand_written_call=True,
+    ),
+    dict(
+        name="real_vector",
+        vhdl="real_vector",
+        kind="p_kind_real_vector",
+        hand_written_eval=True,
+        hand_written_call=False,
+    ),
+    dict(
+        name="string",
+        vhdl="string",
+        kind="p_kind_string",
+        hand_written_eval=True,
+        hand_written_call=False,
+    ),
+    dict(
+        name="integer_vector_ptr",
+        vhdl="integer_vector_ptr_t",
+        kind="p_kind_integer_vector",
+        hand_written_eval=True,
+        hand_written_call=False,
+    ),
+    dict(
+        name="boolean",
+        vhdl="boolean",
+        kind="p_kind_boolean",
+        value="p_result_integer /= 0",
+        default="false",
+        hand_written_eval=False,
+        hand_written_call=False,
+    ),
+    dict(
+        name="std_ulogic",
+        vhdl="std_ulogic",
+        kind="p_kind_std_ulogic",
+        value="p_to_std_ulogic(p_result_string(1))",
+        default="'U'",
+        hand_written_eval=False,
+        hand_written_call=False,
+    ),
+    dict(
+        name="std_ulogic_vector",
+        vhdl="std_ulogic_vector",
+        kind="p_kind_std_ulogic_vector",
+        value="p_to_std_ulogic_vector(p_result_string)",
+        default='""',
+        hand_written_eval=False,
+        hand_written_call=False,
+        # No eval/call alias: check_equal(eval("17"), 17) would otherwise be ambiguous
+        # with check_equal(std_ulogic_vector, natural). Use the explicit names.
+        alias_eval=False,
+        alias_call=False,
+    ),
+    dict(
+        name="integer_array",
+        vhdl="integer_array_t",
+        kind="p_kind_integer_array",
+        value="p_result_integer_array",
+        default="null_integer_array",
+        hand_written_eval=False,
+        hand_written_call=False,
+        # No eval alias: length(eval(...)) would otherwise be ambiguous between
+        # the integer_array_t and integer_vector_ptr_t results. Use eval_integer_array.
+        alias_eval=False,
+    ),
+]
+
+# Result types whose width is given by the actual of the result parameter
+PROCEDURE_RESULTS = [
+    dict(
+        name="std_ulogic_vector",
+        vhdl="std_ulogic_vector",
+        kind="p_kind_std_ulogic_vector",
+        value="p_to_std_ulogic_vector(p_result_string)",
+    ),
+    dict(
+        name="signed",
+        vhdl="signed",
+        kind="p_kind_signed",
+        value="signed(p_to_std_ulogic_vector(p_result_string))",
+    ),
+    dict(
+        name="unsigned",
+        vhdl="unsigned",
+        kind="p_kind_unsigned",
+        value="unsigned(p_to_std_ulogic_vector(p_result_string))",
+    ),
+]
+
+
+def call_name(result):
+    """
+    Name of the call function of a result type. The integer one is named
+    call_integer_w_arg by python_pkg.
+    """
+    return "call_integer_w_arg" if result["name"] == "integer" else f"call_{result['name']}"
+
+
+# -------------------------------------------------------------------------
+# arg and kwarg
+# -------------------------------------------------------------------------
+def arg_declarations():
+    """
+    Declarations of the generated arg and kwarg subprograms.
+    """
+    lines = []
+    for value in ARG_VALUES:
+        purity = "impure " if value["impure"] else ""
+        suffix = value["suffix"]
+        lines.append(f"  {purity}function arg{suffix}(value : {value['vhdl']}) return arg_t;")
+        lines.append(f"  {purity}function kwarg{suffix}(kw : string; value : {value['vhdl']}) return arg_t;")
+    return "\n".join(lines)
+
+
+def arg_functions():
+    """
+    Bodies of the generated arg and kwarg subprograms. p_arg_value reports a
+    value it cannot convert and gives it a Python source text raising the same
+    message, so that the call the argument is used in fails as well.
+    """
+    parts = []
+    for value in ARG_VALUES:
+        purity = "impure " if value["impure"] else ""
+        value_type = value["vhdl"]
+        suffix = value["suffix"]
+        for name, parameters, target in [
+            (f"arg{suffix}", f"value : {value_type}", "p_positional_arg"),
+            (f"kwarg{suffix}", f"kw : string; value : {value_type}", "kw"),
+        ]:
+            arg_value = f'p_arg_value(value, "{name}")' if value["fails"] else "p_arg_value(value)"
+            parts.append(
+                f"""\
+  {purity}function {name}({parameters}) return arg_t is
+  begin
+    return ({target}, {arg_value});
+  end;
+"""
+            )
+    return "\n".join(parts).rstrip("\n")
+
+
+# -------------------------------------------------------------------------
+# eval
+# -------------------------------------------------------------------------
+def eval_declarations():
+    """
+    Declarations of the generated eval functions and of the eval procedures.
+    """
+    lines = []
+    for result in RESULTS:
+        if result["hand_written_eval"]:
+            continue
+        lines.append(f"  impure function eval_{result['name']}(")
+        lines.append(f"    expr : string; {SESSION}")
+        lines.append(f"  ) return {result['vhdl']};")
+        if result.get("alias_eval", True):
+            lines.append(f"  alias eval is eval_{result['name']}[string, python_session_t return {result['vhdl']}];")
+        lines.append("")
+    for result in PROCEDURE_RESULTS:
+        lines.append(f"  procedure eval_{result['name']}(")
+        lines.append(f"    expr : string; result : out {result['vhdl']}; {SESSION}")
+        lines.append("  );")
+    return "\n".join(lines)
+
+
+def eval_subprograms():
+    """
+    Bodies of the generated eval functions and of the eval procedures.
+    """
+    parts = []
+    for result in RESULTS:
+        if result["hand_written_eval"]:
+            continue
+        parts.append(
+            f"""\
+  impure function eval_{result['name']}(
+    expr : string; {SESSION}
+  ) return {result['vhdl']} is
+  begin
+    if p_eval(expr, {result['kind']}, -1, p_eval_operation(expr, session), session) then
+      return {result['value']};
+    end if;
+    return {result['default']};
+  end;
+"""
+        )
+    for result in PROCEDURE_RESULTS:
+        parts.append(
+            f"""\
+  procedure eval_{result['name']}(
+    expr : string; result : out {result['vhdl']}; {SESSION}
+  ) is
+  begin
+    if p_eval(expr, {result['kind']}, result'length, p_eval_operation(expr, session), session) then
+      result := {result['value']};
+    end if;
+  end;
+"""
+        )
+    return "\n".join(parts).rstrip("\n")
+
+
+# -------------------------------------------------------------------------
+# call
+# -------------------------------------------------------------------------
+def call_declarations():
+    """
+    Declarations of the generated call functions and of the call procedures.
+    """
+    lines = []
+    for result in RESULTS:
+        if result["hand_written_call"]:
+            continue
+        name = call_name(result)
+        lines.append(f"  impure function {name}(")
+        lines.append(f"    identifier : string; {ARG_PARAMETERS};")
+        lines.append(f"    {SESSION}")
+        lines.append(f"  ) return {result['vhdl']};")
+        if result.get("alias_call", True):
+            lines.append(f"  alias call is {name}[")
+            lines.append(f"    {ARG_SIGNATURE} return {result['vhdl']}];")
+        lines.append("")
+    for result in PROCEDURE_RESULTS:
+        lines.append(f"  procedure call_{result['name']}(")
+        lines.append(f"    identifier : string; result : out {result['vhdl']};")
+        lines.append(f"    {ARG_PARAMETERS};")
+        lines.append(f"    {SESSION}")
+        lines.append("  );")
+    return "\n".join(lines)
+
+
+def call_subprograms():
+    """
+    Bodies of the generated call functions and of the call procedures. A call
+    is the evaluation of the Python expression calling the identifier with the
+    given arguments.
+    """
+    parts = []
+    for result in RESULTS:
+        if result["hand_written_call"]:
+            continue
+        parts.append(
+            f"""\
+  impure function {call_name(result)}(
+    identifier : string; {ARG_PARAMETERS};
+    {SESSION}
+  ) return {result['vhdl']} is
+  begin
+    return eval_{result['name']}(
+      to_call_str(identifier, {ARG_ACTUALS}), session
+    );
+  end;
+"""
+        )
+    for result in PROCEDURE_RESULTS:
+        parts.append(
+            f"""\
+  procedure call_{result['name']}(
+    identifier : string; result : out {result['vhdl']};
+    {ARG_PARAMETERS};
+    {SESSION}
+  ) is
+  begin
+    eval_{result['name']}(
+      to_call_str(identifier, {ARG_ACTUALS}), result, session
+    );
+  end;
+"""
+        )
+    return "\n".join(parts).rstrip("\n")
+
+
+def generate_package():
+    """
+    Generate python_pkg from the template and the generated declarations.
+    """
+    template = (TEMPLATE_PATH / "python_pkg.vhd.in").read_text(encoding="utf-8")
+    return Template(template).substitute(
+        arg_declarations=arg_declarations(),
+        arg_functions=arg_functions(),
+        eval_declarations=eval_declarations(),
+        call_declarations=call_declarations(),
+        eval_subprograms=eval_subprograms(),
+        call_subprograms=call_subprograms(),
+    )
+
+
+def main():
+    (SRC_PATH / "python_pkg.vhd").write_text(generate_package(), encoding="utf-8", newline="\n")
+
+
+if __name__ == "__main__":
+    main()