From fbf015ef1940ce15e145d6c89d42b8d974a080e2 Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 11:05:49 +0100 Subject: [PATCH 1/9] Support a 64-bit integer in the foreign interface NVC uses a 64-bit integer with VHDL-2019, but the foreign subprograms of python_bridge_pkg were declared with integer while the native library takes and returns int32_t. Integer results, integer_vector and integer_array_t values and dict entries were transferred as garbage. The foreign subprograms now use c_int32_t, an integer type of their own with the 32-bit range, which every simulator passes as int32_t whatever the width of integer, and python_ffi_pkg converts to and from integer. Results stay limited to the 32-bit range, which runtime.py checks. Arguments are transferred as Python source code and are not limited. tests/integer_width runs with the VHDL standard of the run, and for NVC also with VHDL-2019. Fixes #43. Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 5 +- release_notes/news.d/45.bugfix.md | 1 + .../hdl/src/python_bridge_pkg.vhd.in | 42 ++++++----- .../hdl/src/python_ffi_pkg_bridge.vhd | 71 ++++++++++++------- tests/integer_width/run.py | 33 +++++++++ tests/integer_width/tb_integer_width.vhd | 70 ++++++++++++++++++ tests/run.py | 26 +++++++ 7 files changed, 201 insertions(+), 47 deletions(-) create mode 100644 release_notes/news.d/45.bugfix.md create mode 100644 tests/integer_width/run.py create mode 100644 tests/integer_width/tb_integer_width.vhd diff --git a/docs/types.rst b/docs/types.rst index 9891420..a066d22 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -4,7 +4,10 @@ Types Type mapping ------------ -* ``integer`` ↔ ``int``. Results outside the VHDL integer range fail. +* ``integer`` ↔ ``int``. Results outside the 32-bit range (-2**31 to + 2**31 - 1) fail, also when ``integer`` is 64 bits as for NVC with VHDL-2019. + Arguments are not limited: the full range of a 64-bit ``integer`` reaches + Python. * ``real`` ↔ ``float``. Strict: an ``int`` result is not accepted. * ``string`` ↔ ``str``. UTF-8. * ``boolean`` ↔ ``bool``/``numpy.bool_`` (Python bridge only). diff --git a/release_notes/news.d/45.bugfix.md b/release_notes/news.d/45.bugfix.md new file mode 100644 index 0000000..05379a7 --- /dev/null +++ b/release_notes/news.d/45.bugfix.md @@ -0,0 +1 @@ +The bridge works with a 64-bit `integer`, as NVC has with VHDL-2019. Integer results, `integer_vector` and `integer_array_t` values and dict entries were transferred as garbage, since the foreign interface took `integer` to be 32 bits. It now uses a 32-bit integer type of its own, so results are limited to the 32-bit range whatever the width of `integer`. diff --git a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in index b8aa051..c1897f6 100644 --- a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in +++ b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in @@ -16,76 +16,80 @@ -- -- Only scalars and constrained arrays cross the foreign interface since their -- ABI is identical for NVC and GHDL on all platforms and is translated to the --- FLI parameter passing conventions by native/fli.c. +-- FLI parameter passing conventions by native/fli.c. The integers are c_int32_t, +-- which is the int32_t of the native library whatever the width of integer: +-- integer is 64 bits for NVC with VHDL-2019. package python_bridge_pkg is constant chunk_length : positive := 1024; subtype string_chunk_t is string(1 to chunk_length); - subtype integer_chunk_t is integer_vector(0 to chunk_length - 1); + type c_int32_t is range -2147483647 - 1 to 2147483647; + type c_int32_vector_t is array (natural range <>) of c_int32_t; + subtype integer_chunk_t is c_int32_vector_t(0 to chunk_length - 1); subtype real_chunk_t is real_vector(0 to chunk_length - 1); -- Start the interpreter. Idempotent. - impure function vpy_setup return integer; + impure function vpy_setup return c_int32_t; attribute foreign of vpy_setup : function is "{foreign:vpy_setup}"; -- Flush Python's streams and drop the last result and the staged values. -- The interpreter is not finalized: later operations keep working. - impure function vpy_cleanup return integer; + impure function vpy_cleanup return c_int32_t; attribute foreign of vpy_cleanup : function is "{foreign:vpy_cleanup}"; - impure function vpy_buffer_clear return integer; + impure function vpy_buffer_clear return c_int32_t; attribute foreign of vpy_buffer_clear : function is "{foreign:vpy_buffer_clear}"; - impure function vpy_buffer_append(chunk : string_chunk_t; length : integer) return integer; + impure function vpy_buffer_append(chunk : string_chunk_t; length : c_int32_t) return c_int32_t; attribute foreign of vpy_buffer_append : function is "{foreign:vpy_buffer_append}"; -- Start an operation in the session named by the buffer ("default" is __main__). - impure function vpy_begin return integer; + impure function vpy_begin return c_int32_t; attribute foreign of vpy_begin : function is "{foreign:vpy_begin}"; -- Execute the buffer as Python source (is_file = 0) or as a file name (is_file = 1). - impure function vpy_execute(is_file : integer) return integer; + impure function vpy_execute(is_file : c_int32_t) return c_int32_t; attribute foreign of vpy_execute : function is "{foreign:vpy_execute}"; -- Evaluate the buffer as a Python expression 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 vpy_eval(kind, width : integer) return integer; + impure function vpy_eval(kind, width : c_int32_t) return c_int32_t; attribute foreign of vpy_eval : function is "{foreign:vpy_eval}"; - impure function vpy_push_array(length, width, height, depth, bit_width, is_signed : integer) return integer; + impure function vpy_push_array(length, width, height, depth, bit_width, is_signed : c_int32_t) return c_int32_t; attribute foreign of vpy_push_array : function is "{foreign:vpy_push_array}"; - impure function vpy_array_write(chunk : integer_chunk_t; length : integer) return integer; + impure function vpy_array_write(chunk : integer_chunk_t; length : c_int32_t) return c_int32_t; attribute foreign of vpy_array_write : function is "{foreign:vpy_array_write}"; -- Stage the pushed array and return its id (>= 1), -1 on error. Python -- source code refers to the value as __vunit__.staged(). - impure function vpy_stage return integer; + impure function vpy_stage return c_int32_t; attribute foreign of vpy_stage : function is "{foreign:vpy_stage}"; - impure function vpy_result_integer return integer; + impure function vpy_result_integer return c_int32_t; attribute foreign of vpy_result_integer : function is "{foreign:vpy_result_integer}"; impure function vpy_result_real return real; attribute foreign of vpy_result_real : function is "{foreign:vpy_result_real}"; - impure function vpy_result_meta(idx : integer) return integer; + impure function vpy_result_meta(idx : c_int32_t) return c_int32_t; attribute foreign of vpy_result_meta : function is "{foreign:vpy_result_meta}"; - impure function vpy_error_length return integer; + impure function vpy_error_length return c_int32_t; attribute foreign of vpy_error_length : function is "{foreign:vpy_error_length}"; - procedure vpy_result_read_string(chunk : out string_chunk_t; offset, length : integer); + procedure vpy_result_read_string(chunk : out string_chunk_t; offset, length : c_int32_t); attribute foreign of vpy_result_read_string : procedure is "{foreign:vpy_result_read_string}"; - procedure vpy_result_read_integers(chunk : out integer_chunk_t; offset, length : integer); + procedure vpy_result_read_integers(chunk : out integer_chunk_t; offset, length : c_int32_t); attribute foreign of vpy_result_read_integers : procedure is "{foreign:vpy_result_read_integers}"; - procedure vpy_result_read_reals(chunk : out real_chunk_t; offset, length : integer); + procedure vpy_result_read_reals(chunk : out real_chunk_t; offset, length : c_int32_t); attribute foreign of vpy_result_read_reals : procedure is "{foreign:vpy_result_read_reals}"; - procedure vpy_error_read(chunk : out string_chunk_t; offset, length : integer); + procedure vpy_error_read(chunk : out string_chunk_t; offset, length : c_int32_t); attribute foreign of vpy_error_read : procedure is "{foreign:vpy_error_read}"; end package; diff --git a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd index fde0258..b1da72e 100644 --- a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd +++ b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd @@ -252,14 +252,14 @@ package body python_ffi_pkg is -- Transfers through the bridge ----------------------------------------------------------------------------- impure function p_error_text return string is - constant len : natural := vpy_error_length; + constant len : natural := integer(vpy_error_length); variable result : string(1 to len); variable chunk : string_chunk_t; variable offset, n : natural := 0; begin while offset < len loop n := minimum(chunk_length, len - offset); - vpy_error_read(chunk, offset, n); + vpy_error_read(chunk, c_int32_t(offset), c_int32_t(n)); result(offset + 1 to offset + n) := chunk(1 to n); offset := offset + n; end loop; @@ -277,17 +277,24 @@ package body python_ffi_pkg is return false; end; + impure function p_succeeded( + status : c_int32_t; operation : string; logger : logger_t := python_logger + ) return boolean is + begin + return p_succeeded(integer(status), operation, logger); + end; + impure function p_send(text : string) return integer is alias normalized : string(1 to text'length) is text; variable chunk : string_chunk_t; variable offset, n : natural := 0; variable status : integer; begin - status := vpy_buffer_clear; + status := integer(vpy_buffer_clear); while offset < text'length and status = 0 loop n := minimum(chunk_length, text'length - offset); chunk(1 to n) := normalized(offset + 1 to offset + n); - status := vpy_buffer_append(chunk, n); + status := integer(vpy_buffer_append(chunk, c_int32_t(n))); offset := offset + n; end loop; return status; @@ -313,7 +320,7 @@ package body python_ffi_pkg is begin return p_begin(session, operation) and p_succeeded(p_send(text), operation, logger) - and p_succeeded(vpy_execute(is_file), operation, logger); + and p_succeeded(vpy_execute(c_int32_t(is_file)), operation, logger); end; impure function p_exec_file( @@ -334,7 +341,7 @@ package body python_ffi_pkg is begin return p_begin(session, operation) and p_succeeded(p_send(expr), operation, logger) - and p_succeeded(vpy_eval(kind, width), operation, logger); + and p_succeeded(vpy_eval(c_int32_t(kind), c_int32_t(width)), operation, logger); end; ----------------------------------------------------------------------------- @@ -342,7 +349,12 @@ package body python_ffi_pkg is ----------------------------------------------------------------------------- impure function p_result_integer return integer is begin - return vpy_result_integer; + return integer(vpy_result_integer); + end; + + impure function p_result_meta(idx : natural) return integer is + begin + return integer(vpy_result_meta(c_int32_t(idx))); end; impure function p_result_real return real is @@ -351,14 +363,14 @@ package body python_ffi_pkg is end; impure function p_result_string return string is - constant len : natural := vpy_result_meta(0); + constant len : natural := p_result_meta(0); variable result : string(1 to len); variable chunk : string_chunk_t; variable offset, n : natural := 0; begin while offset < len loop n := minimum(chunk_length, len - offset); - vpy_result_read_string(chunk, offset, n); + vpy_result_read_string(chunk, c_int32_t(offset), c_int32_t(n)); result(offset + 1 to offset + n) := chunk(1 to n); offset := offset + n; end loop; @@ -366,29 +378,31 @@ package body python_ffi_pkg is end; impure function p_result_integer_vector return integer_vector is - constant len : natural := vpy_result_meta(0); + constant len : natural := p_result_meta(0); variable result : integer_vector(0 to len - 1); variable chunk : integer_chunk_t; variable offset, n : natural := 0; begin while offset < len loop n := minimum(chunk_length, len - offset); - vpy_result_read_integers(chunk, offset, n); - result(offset to offset + n - 1) := chunk(0 to n - 1); + vpy_result_read_integers(chunk, c_int32_t(offset), c_int32_t(n)); + for idx in 0 to n - 1 loop + result(offset + idx) := integer(chunk(idx)); + end loop; offset := offset + n; end loop; return result; end; impure function p_result_real_vector return real_vector is - constant len : natural := vpy_result_meta(0); + constant len : natural := p_result_meta(0); variable result : real_vector(0 to len - 1); variable chunk : real_chunk_t; variable offset, n : natural := 0; begin while offset < len loop n := minimum(chunk_length, len - offset); - vpy_result_read_reals(chunk, offset, n); + vpy_result_read_reals(chunk, c_int32_t(offset), c_int32_t(n)); result(offset to offset + n - 1) := chunk(0 to n - 1); offset := offset + n; end loop; @@ -396,22 +410,22 @@ package body python_ffi_pkg is end; impure function p_result_integer_array return integer_array_t is - constant len : natural := vpy_result_meta(0); + constant len : natural := p_result_meta(0); variable result : integer_array_t := new_3d( - width => vpy_result_meta(1), - height => vpy_result_meta(2), - depth => vpy_result_meta(3), - bit_width => vpy_result_meta(4), - is_signed => vpy_result_meta(5) /= 0 + width => p_result_meta(1), + height => p_result_meta(2), + depth => p_result_meta(3), + bit_width => p_result_meta(4), + is_signed => p_result_meta(5) /= 0 ); variable chunk : integer_chunk_t; variable offset, n : natural := 0; begin while offset < len loop n := minimum(chunk_length, len - offset); - vpy_result_read_integers(chunk, offset, n); + vpy_result_read_integers(chunk, c_int32_t(offset), c_int32_t(n)); for idx in 0 to n - 1 loop - set(result, offset + idx, chunk(idx)); + set(result, offset + idx, integer(chunk(idx))); end loop; offset := offset + n; end loop; @@ -436,7 +450,10 @@ package body python_ffi_pkg is return -1; end if; if not p_succeeded( - vpy_push_array(len, width(arr), height(arr), depth(arr), bit_width(arr), boolean'pos(is_signed(arr))), + vpy_push_array( + c_int32_t(len), c_int32_t(width(arr)), c_int32_t(height(arr)), c_int32_t(depth(arr)), + c_int32_t(bit_width(arr)), c_int32_t(boolean'pos(is_signed(arr))) + ), operation ) then return -1; @@ -445,15 +462,15 @@ package body python_ffi_pkg is while offset < len loop n := minimum(chunk_length, len - offset); for idx in 0 to n - 1 loop - chunk(idx) := get(arr, offset + idx); + chunk(idx) := c_int32_t(get(arr, offset + idx)); end loop; - if not p_succeeded(vpy_array_write(chunk, n), operation) then + if not p_succeeded(vpy_array_write(chunk, c_int32_t(n)), operation) then return -1; end if; offset := offset + n; end loop; - staged_id := vpy_stage; + staged_id := integer(vpy_stage); if staged_id < 1 then failure(python_logger, operation & " failed:" & LF & p_error_text); return -1; @@ -485,7 +502,7 @@ package body python_ffi_pkg is impure function eval_integer(expr : string; session : python_session_t := default_session) return integer is begin if p_eval(expr, p_kind_integer, -1, p_eval_operation(expr, session), session) then - return vpy_result_integer; + return p_result_integer; end if; return integer'low; end; diff --git a/tests/integer_width/run.py b/tests/integer_width/run.py new file mode 100644 index 0000000..b4c67cc --- /dev/null +++ b/tests/integer_width/run.py @@ -0,0 +1,33 @@ +# 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 + +""" +Run script of the tests of the width of integer, see #43. The testbench checks +that the integer transfers work whatever the width of integer. It is a run of +its own since the standard is fixed for a run: VUNIT_VHDL_STANDARD selects it, +2019 gives NVC a 64-bit integer. +""" + +from pathlib import Path + +from vunit import VUnit + +ROOT = Path(__file__).parent + + +def main(): + vu = VUnit.from_argv() + vu.add_vhdl_builtins() + vu.add_package("vunit-python-bridge", allow_setup=True) + + lib = vu.add_library("lib") + lib.add_source_file(ROOT / "tb_integer_width.vhd") + + vu.main() + + +if __name__ == "__main__": + main() diff --git a/tests/integer_width/tb_integer_width.vhd b/tests/integer_width/tb_integer_width.vhd new file mode 100644 index 0000000..8af6e2b --- /dev/null +++ b/tests/integer_width/tb_integer_width.vhd @@ -0,0 +1,70 @@ +-- 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 +-- +-- The integers crossing the foreign interface are 32 bits whatever the width +-- of integer, which is 64 bits for NVC with VHDL-2019, see #43. The tests +-- pass with either width. + +library vunit_lib; +context vunit_lib.vunit_context; + +library python_bridge; +context python_bridge.python_context; + +entity tb_integer_width is + generic(runner_cfg : string); +end entity; + +architecture tb of tb_integer_width is +begin + test_runner : process + constant int32_low : integer := -2147483647 - 1; + constant int32_high : integer := 2147483647; + variable arr, result : integer_array_t; + begin + test_runner_setup(runner, runner_cfg); + info("integer'high is " & integer'image(integer'high)); + + while test_suite loop + if run("Test integer results") then + check_equal(eval_integer("3"), 3); + check_equal(eval_integer("-1"), -1); + check_equal(eval_integer("-2**31"), int32_low); + check_equal(eval_integer("2**31 - 1"), int32_high); + + elsif run("Test integer_vector results") then + check(eval_integer_vector("[3, 1, 4]") = integer_vector'(3, 1, 4)); + check( + eval_integer_vector("[-1, -2**31, 2**31 - 1, 0]") = integer_vector'(-1, int32_low, int32_high, 0) + ); + + elsif run("Test integer_array_t round trip") then + arr := new_1d(length => 4); + set(arr, 0, 3); + set(arr, 1, -1); + set(arr, 2, int32_low); + set(arr, 3, int32_high); + exec("def total(a): return int(sum(int(v) for v in a))"); + exec("def same(a): return a"); + check_equal(call_integer("total", arg(arr)), 3 - 1 - 1); + result := call_integer_array("same", arg(arr)); + check_equal(length(result), 4); + for idx in 0 to 3 loop + check_equal(get(result, idx), get(arr, idx)); + end loop; + + elsif run("Test that integer'high reaches Python") then + -- Arguments are transferred as Python source code, so all of a + -- 64-bit integer reaches Python + exec("high = " & integer'image(integer'high)); + check_equal(eval_integer("1 if high in (2**31 - 1, 2**63 - 1) else 0"), 1); + check_equal(eval_integer("high >> 32"), integer'high / 2**16 / 2**16); + end if; + end loop; + + test_runner_cleanup(runner); + end process; +end architecture; diff --git a/tests/run.py b/tests/run.py index c351673..7eadcf0 100644 --- a/tests/run.py +++ b/tests/run.py @@ -82,6 +82,31 @@ def run_file_base_tests(args): raise RuntimeError(f"The tests of tests/file_base/run.py with the base directory set by the {name} failed") +def run_integer_width_tests(args, simulator_name): + """ + Run the tests of the width of integer, which is fixed by the VHDL standard of a run + and therefore a run of its own, with the same simulator and an output path of its own. + It runs with the standard of this run, and with VHDL-2019 for NVC, which gives it a + 64-bit integer. + """ + standards = [os.environ.get("VUNIT_VHDL_STANDARD", "2008")] + if simulator_name == "nvc" and "2019" not in standards: + standards.append("2019") + for standard in standards: + command = [ + sys.executable, + str(ROOT / "integer_width" / "run.py"), + "-o", + str(Path(args.output_path) / "integer_width" / standard), + "-p", + str(args.num_threads), + ] + sys.stdout.flush() + env = dict(os.environ, VUNIT_VHDL_STANDARD=standard) + if subprocess.run(command, env=env, check=False).returncode != 0: + raise RuntimeError(f"The tests of tests/integer_width/run.py with VHDL-{standard} failed") + + def main(): args = VUnitCLI().parse_args() # The expected failure must not make the run script fail @@ -107,6 +132,7 @@ def main(): def post_run(results): verify(results, [ELABORATION_ARRAY_TEST]) run_file_base_tests(args) + run_integer_width_tests(args, vu.get_simulator_name()) vu.main(post_run=post_run) From d46fdf65c302c65d1b3f824e812e46b1d7709aac Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 12:40:17 +0100 Subject: [PATCH 2/9] Give integer results the full range of a 64-bit integer With a 64-bit integer, as for NVC with VHDL-2019, the results were limited to the 32-bit range of the foreign interface. VHDL now gives runtime.py the width of integer as the width of an integer, integer_vector or dict_t result, which vpy_eval takes but did not use for those kinds. runtime.py checks the results against that range, and a 64-bit value crosses the 32-bit interface as its low and high int32 halves: the integer and the first metadata value for a scalar, a pair per element for an integer_vector. python_ffi_pkg combines them. The native library is unchanged. The integers of a dict_t stay 32 bits since VUnit encodes them in 32 bits, and a larger dict_t integer result is an error saying so. The elements of an integer_array_t are at most 32 bits anyway. docs/types.rst describes the range of integer. The bounds were not literals, so ** started strong emphasis. tests/integer_width covers both halves and the bounds of a 64-bit integer, integer_vector_ptr_t, dict_t and boolean results and 64-bit arguments, and test_python_bridge.py the halves and ranges of runtime.py. The test of integer bounds in tb_python_pkg no longer assumes a 32-bit integer. Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 27 ++++- release_notes/news.d/45.bugfix.md | 2 +- .../hdl/src/python_bridge_pkg.vhd.in | 3 +- .../hdl/src/python_ffi_pkg_bridge.vhd | 45 ++++++- src/vunit_python_bridge/runtime.py | 111 ++++++++++++++---- tests/integer_width/tb_integer_width.vhd | 68 ++++++++++- tests/tb_python_pkg.vhd | 4 +- tests/test_python_bridge.py | 61 ++++++++++ 8 files changed, 279 insertions(+), 42 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index a066d22..316e6f7 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -4,10 +4,7 @@ Types Type mapping ------------ -* ``integer`` ↔ ``int``. Results outside the 32-bit range (-2**31 to - 2**31 - 1) fail, also when ``integer`` is 64 bits as for NVC with VHDL-2019. - Arguments are not limited: the full range of a 64-bit ``integer`` reaches - Python. +* ``integer`` ↔ ``int``, see :ref:`python_bridge:integer_range`. * ``real`` ↔ ``float``. Strict: an ``int`` result is not accepted. * ``string`` ↔ ``str``. UTF-8. * ``boolean`` ↔ ``bool``/``numpy.bool_`` (Python bridge only). @@ -26,6 +23,25 @@ Results are strict: a value that does not fit the VHDL type, or is of the wrong Python type, is an error. Values are never silently truncated or wrapped. +.. _python_bridge:integer_range: + +Range of integer +---------------- + +``integer`` has the range of the simulator: ``-2**31`` to ``2**31 - 1``, or +``-2**63`` to ``2**63 - 1`` when it is 64 bits, as for NVC with VHDL-2019. The +arguments and results of type ``integer``, ``integer_vector`` and +``integer_vector_ptr_t`` have that range, and so do the elements of a list in a +``dict_t``. A result outside it is an error. + +Two kinds of integers are 32 bits whatever the width of ``integer``: + +* An ``integer`` value of a ``dict_t``, since VUnit stores it in 32 bits. A + larger result is an error, while ``set_integer`` truncates a larger argument + value before the bridge sees it. +* An element of an ``integer_array_t``, whose ``bit_width`` is at most 32, see + :ref:`python_bridge:integer_array`. + .. _python_bridge:dict: dict_t and dict @@ -58,7 +74,8 @@ deallocates. The values are converted strictly: ``int`` to ``integer``, stored with ``set_integer_vector_ptr_t_ref``, ``set_integer_array_t_ref`` and ``set_dict_t_ref``. The bit width and signedness of an ``integer_array_t`` follow the dtype of the array like for ``eval_integer_array``, see -:ref:`python_bridge:integer_array`. ``None``, an ``int`` outside the VHDL integer range, a key +:ref:`python_bridge:integer_array`. ``None``, an ``int`` outside its range (see +:ref:`python_bridge:integer_range`), a key that is not a ``str`` or any other value is an error, and ``eval_dict`` then returns an empty ``dict_t`` after reporting it. diff --git a/release_notes/news.d/45.bugfix.md b/release_notes/news.d/45.bugfix.md index 05379a7..f9fc696 100644 --- a/release_notes/news.d/45.bugfix.md +++ b/release_notes/news.d/45.bugfix.md @@ -1 +1 @@ -The bridge works with a 64-bit `integer`, as NVC has with VHDL-2019. Integer results, `integer_vector` and `integer_array_t` values and dict entries were transferred as garbage, since the foreign interface took `integer` to be 32 bits. It now uses a 32-bit integer type of its own, so results are limited to the 32-bit range whatever the width of `integer`. +The bridge supports a 64-bit `integer`, as NVC has with VHDL-2019. Integer results, `integer_vector`, `integer_vector_ptr_t` and `integer_array_t` values and `dict_t` entries used to be garbage with it. Integers now have the full range of `integer`, except the integers of a `dict_t` and the elements of an `integer_array_t`, which VUnit stores in 32 bits. diff --git a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in index c1897f6..f380e86 100644 --- a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in +++ b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in @@ -18,7 +18,8 @@ -- ABI is identical for NVC and GHDL on all platforms and is translated to the -- FLI parameter passing conventions by native/fli.c. The integers are c_int32_t, -- which is the int32_t of the native library whatever the width of integer: --- integer is 64 bits for NVC with VHDL-2019. +-- integer is 64 bits for NVC with VHDL-2019, and its results then cross as two +-- halves, see python_ffi_pkg. package python_bridge_pkg is constant chunk_length : positive := 1024; diff --git a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd index b1da72e..c75b2e8 100644 --- a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd +++ b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd @@ -277,6 +277,33 @@ package body python_ffi_pkg is return false; end; + -- The width of integer: 64 bits for NVC with VHDL-2019, else 32 bits. The + -- foreign interface is 32 bits, so a 64-bit integer result crosses it as two + -- halves, see _integer_halves in runtime.py. + constant p_integer_width : positive := 32 + 32 * boolean'pos(integer'high > 2147483647); + + -- A 64-bit integer from its halves, low taken as unsigned. Only called with a + -- 64-bit integer since 2**32 does not fit in a 32-bit one. + function p_from_halves(low, high : c_int32_t) return integer is + variable half_range : integer := 2**16; + begin + half_range := half_range * half_range; + if low < 0 then + return integer(high) * half_range + (integer(low) + half_range); + end if; + return integer(high) * half_range + integer(low); + end; + + -- The width vpy_eval takes: the width of integer for an integer, integer_vector + -- or dict_t result, else the width of the result + function p_result_width(kind, width : integer) return integer is + begin + if kind = p_kind_integer or kind = p_kind_integer_vector or kind = p_kind_dict then + return p_integer_width; + end if; + return width; + end; + impure function p_succeeded( status : c_int32_t; operation : string; logger : logger_t := python_logger ) return boolean is @@ -341,14 +368,18 @@ package body python_ffi_pkg is begin return p_begin(session, operation) and p_succeeded(p_send(expr), operation, logger) - and p_succeeded(vpy_eval(c_int32_t(kind), c_int32_t(width)), operation, logger); + and p_succeeded(vpy_eval(c_int32_t(kind), c_int32_t(p_result_width(kind, width))), operation, logger); end; ----------------------------------------------------------------------------- -- Results ----------------------------------------------------------------------------- + -- With a 64-bit integer, the high half is the first metadata value impure function p_result_integer return integer is begin + if p_integer_width = 64 then + return p_from_halves(vpy_result_integer, vpy_result_meta(0)); + end if; return integer(vpy_result_integer); end; @@ -377,17 +408,23 @@ package body python_ffi_pkg is return result; end; + -- With a 64-bit integer, an element is its low and high halves impure function p_result_integer_vector return integer_vector is constant len : natural := p_result_meta(0); + constant halves : positive := p_integer_width / 32; variable result : integer_vector(0 to len - 1); variable chunk : integer_chunk_t; variable offset, n : natural := 0; begin while offset < len loop - n := minimum(chunk_length, len - offset); - vpy_result_read_integers(chunk, c_int32_t(offset), c_int32_t(n)); + n := minimum(chunk_length / halves, len - offset); + vpy_result_read_integers(chunk, c_int32_t(offset * halves), c_int32_t(n * halves)); for idx in 0 to n - 1 loop - result(offset + idx) := integer(chunk(idx)); + if halves = 2 then + result(offset + idx) := p_from_halves(chunk(2 * idx), chunk(2 * idx + 1)); + else + result(offset + idx) := integer(chunk(idx)); + end if; end loop; offset := offset + n; end loop; diff --git a/src/vunit_python_bridge/runtime.py b/src/vunit_python_bridge/runtime.py index 7929e8c..e837860 100644 --- a/src/vunit_python_bridge/runtime.py +++ b/src/vunit_python_bridge/runtime.py @@ -59,6 +59,11 @@ STD_ULOGIC_VALUES = frozenset("UX01ZWLH-") INTEGER_LOW = -(2**31) INTEGER_HIGH = 2**31 - 1 +# The width of VHDL integer: 32 bits, or 64 bits as for NVC with VHDL-2019. VHDL +# gives it as the width of an integer, integer_vector or dict_t result, -1 meaning +# 32. A 64-bit integer crosses the foreign interface as two int32 halves, see +# _integer_halves. +INTEGER_WIDTHS = (32, 64) TEXT_ENCODING = "utf-8" TEXT_ERRORS = "surrogateescape" @@ -583,24 +588,68 @@ def convert_result(self, kind, width): if kind == KIND_INTEGER_ARRAY: return self._array_result(value, array_meta) if kind == KIND_DICT: - return self._dict_result(value, array_meta) + return self._dict_result(value, array_meta, width) if kind not in VHDL_TYPE_NAMES: raise RuntimeError(f"Internal error: unknown result kind {kind}") converter = "bits" if kind in (KIND_SIGNED, KIND_UNSIGNED) else VHDL_TYPE_NAMES[kind] return getattr(self, f"_{converter}_result")(kind, value, width) @staticmethod - def _integer_result(kind, value, _width): + def _integer_width(width): """ - Convert an int result. + The width of VHDL integer given by VHDL, see INTEGER_WIDTHS. + """ + if width == -1: + return 32 + if width not in INTEGER_WIDTHS: + raise RuntimeError(f"Internal error: unsupported width of VHDL integer {width}") + return width + + @staticmethod + def _integer_range(width): + """ + The range of VHDL integer of a width. + """ + if width == 64: + return -(2**63), 2**63 - 1 + return INTEGER_LOW, INTEGER_HIGH + + @staticmethod + def _integer_halves(value): + """ + The low and high int32 halves of a 64-bit integer, low as a signed int32. + VHDL computes the value as high * 2**32 + low, low taken as unsigned. + """ + low = value & 0xFFFFFFFF + return low - (1 << 32) if low & 0x80000000 else low, value >> 32 + + def _integer_result(self, kind, value, width): + """ + Convert an int result. With a 64-bit integer, the high half is the first + metadata value. """ if not _is_integer(value): raise _type_error(kind, value, "int") + width = self._integer_width(width) + low, high = self._integer_range(width) value = int(value) - if not INTEGER_LOW <= value <= INTEGER_HIGH: - raise OverflowError(f"{value} is outside the range of VHDL integer ({INTEGER_LOW} to {INTEGER_HIGH})") + if not low <= value <= high: + raise OverflowError(f"{value} is outside the range of VHDL integer ({low} to {high})") + if width == 64: + value, high_half = self._integer_halves(value) + return (value, 0.0, b"", (high_half,)) return (value, 0.0, b"", ()) + def _integer_vector_data(self, integers, width): + """ + integer_vector data: native int32, or with a 64-bit integer the low and + high int32 halves of each element. + """ + if width == 64: + halves = [half for value in integers for half in self._integer_halves(value)] + return struct.pack(f"={len(halves)}i", *halves) + return struct.pack(f"={len(integers)}i", *integers) + @staticmethod def _real_result(kind, value, _width): """ @@ -688,11 +737,13 @@ def _sequence(kind, value): raise _type_error(kind, value, "a list or tuple") return value - def _integer_vector_result(self, kind, value, _width): + def _integer_vector_result(self, kind, value, width): """ - Convert a list/tuple of int to integer_vector data (native int32). + Convert a list/tuple of int to integer_vector data, see _integer_vector_data. """ values = self._sequence(kind, value) + width = self._integer_width(width) + integer_low, integer_high = self._integer_range(width) integers = [] for index, element in enumerate(values): if not _is_integer(element): @@ -701,14 +752,13 @@ def _integer_vector_result(self, kind, value, _width): f"a {_type_name(element)} ({element!r:.100}), to a VHDL integer; expected int" ) element = int(element) - if not INTEGER_LOW <= element <= INTEGER_HIGH: + if not integer_low <= element <= integer_high: raise OverflowError( f"Element {index} ({element}) is outside the range of VHDL integer " - f"({INTEGER_LOW} to {INTEGER_HIGH})" + f"({integer_low} to {integer_high})" ) integers.append(element) - data = struct.pack(f"={len(integers)}i", *integers) - return (0, 0.0, data, (len(integers),)) + return (0, 0.0, self._integer_vector_data(integers, width), (len(integers),)) def _real_vector_result(self, kind, value, _width): """ @@ -729,15 +779,15 @@ def _real_vector_result(self, kind, value, _width): data = struct.pack(f"={len(reals)}d", *reals) return (0, 0.0, data, (len(reals),)) - def _dict_result(self, value, array_meta): + def _dict_result(self, value, array_meta, width): """ Convert a dict and keep its entries for VHDL to fetch, see dict_kinds. - The result is the handle of the dict. + The result is the handle of the dict. width is the width of VHDL integer. """ self._dicts = [] - return (self._convert_dict(value, array_meta), 0.0, b"", ()) + return (self._convert_dict(value, array_meta, self._integer_width(width)), 0.0, b"", ()) - def _convert_dict(self, value, array_meta): + def _convert_dict(self, value, array_meta, width): """ Convert the entries of a dict, and of its nested dicts, and return its handle. """ @@ -747,18 +797,28 @@ def _convert_dict(self, value, array_meta): for key, item in value.items(): if not isinstance(key, str): raise TypeError(f"Cannot convert the dict key {key!r:.100}, a {_type_name(key)}; expected str") - entries.append((key,) + self._dict_value(key, item, array_meta)) + entries.append((key,) + self._dict_value(key, item, array_meta, width)) self._dicts.append(entries) return len(self._dicts) - 1 - def _dict_value(self, key, item, array_meta): + def _dict_value(self, key, item, array_meta, width): """ The result kind and the converted value of a dict entry. """ if _is_bool(item): return KIND_BOOLEAN, (int(bool(item)), 0.0, b"", ()) if _is_integer(item): - return KIND_INTEGER, (self._dict_integer(key, item), 0.0, b"", ()) + value = self._dict_integer(key, item, width) + if not INTEGER_LOW <= value <= INTEGER_HIGH: + # set_integer encodes the value in 32 bits whatever the width of integer + raise OverflowError( + f"{value} of dict key {key!r:.100} is outside the range of a dict_t integer, which VUnit " + f"stores in 32 bits ({INTEGER_LOW} to {INTEGER_HIGH})" + ) + if width == 64: + low, high = self._integer_halves(value) + return KIND_INTEGER, (low, 0.0, b"", (high,)) + return KIND_INTEGER, (value, 0.0, b"", ()) if _is_float(item): if not math.isfinite(item): raise ValueError(f"{item} of dict key {key!r:.100} cannot be represented as VHDL real") @@ -766,27 +826,26 @@ def _dict_value(self, key, item, array_meta): if isinstance(item, str): return KIND_STRING, self._string_result(KIND_STRING, item, -1) if isinstance(item, dict): - return KIND_DICT, (self._convert_dict(item, array_meta), 0.0, b"", ()) + return KIND_DICT, (self._convert_dict(item, array_meta, width), 0.0, b"", ()) if isinstance(item, numpy.ndarray): try: return KIND_INTEGER_ARRAY, self._array_result(item, array_meta) except (TypeError, ValueError, OverflowError) as error: raise type(error)(f"dict key {key!r:.100}: {error}") from None if isinstance(item, list) and all(_is_integer(element) for element in item): - integers = [self._dict_integer(key, element) for element in item] - return KIND_INTEGER_VECTOR, (0, 0.0, struct.pack(f"={len(integers)}i", *integers), (len(integers),)) + integers = [self._dict_integer(key, element, width) for element in item] + return KIND_INTEGER_VECTOR, (0, 0.0, self._integer_vector_data(integers, width), (len(integers),)) raise TypeError( f"Cannot convert the value of dict key {key!r:.100}, a {_type_name(item)} ({item!r:.100}); " "expected int, float, str, bool, a list of int, a NumPy array of integers or a dict" ) - @staticmethod - def _dict_integer(key, value): + def _dict_integer(self, key, value, width): + low, high = self._integer_range(width) value = int(value) - if not INTEGER_LOW <= value <= INTEGER_HIGH: + if not low <= value <= high: raise OverflowError( - f"{value} of dict key {key!r:.100} is outside the range of VHDL integer " - f"({INTEGER_LOW} to {INTEGER_HIGH})" + f"{value} of dict key {key!r:.100} is outside the range of VHDL integer ({low} to {high})" ) return value diff --git a/tests/integer_width/tb_integer_width.vhd b/tests/integer_width/tb_integer_width.vhd index 8af6e2b..e56f8b0 100644 --- a/tests/integer_width/tb_integer_width.vhd +++ b/tests/integer_width/tb_integer_width.vhd @@ -4,9 +4,8 @@ -- -- Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com -- --- The integers crossing the foreign interface are 32 bits whatever the width --- of integer, which is 64 bits for NVC with VHDL-2019, see #43. The tests --- pass with either width. +-- The transfers of integers with the width of integer, which is 64 bits for +-- NVC with VHDL-2019, see #43. The tests pass with either width. library vunit_lib; context vunit_lib.vunit_context; @@ -24,6 +23,10 @@ begin constant int32_low : integer := -2147483647 - 1; constant int32_high : integer := 2147483647; variable arr, result : integer_array_t; + variable ptr : integer_vector_ptr_t; + variable dict : dict_t; + variable two_32 : integer; + constant session_logger : logger_t := get_logger(get_id(default_session)); begin test_runner_setup(runner, runner_cfg); info("integer'high is " & integer'image(integer'high)); @@ -34,12 +37,28 @@ begin check_equal(eval_integer("-1"), -1); check_equal(eval_integer("-2**31"), int32_low); check_equal(eval_integer("2**31 - 1"), int32_high); + check_equal(eval_integer(integer'image(integer'low)), integer'low); + check_equal(eval_integer(integer'image(integer'high)), integer'high); + if integer'high > int32_high then + -- Both halves of a 64-bit integer. 2**32 is computed at run time + -- since it does not fit in a 32-bit integer. + two_32 := 2**16; + two_32 := two_32 * two_32; + check_equal(eval_integer("2**32 + 5"), two_32 + 5); + check_equal(eval_integer("-2**32 - 5"), -two_32 - 5); + check_equal(eval_integer("2**40 + 2**31"), two_32 * 256 + two_32 / 2); + check_equal(eval_integer("-2**40 - 1"), -two_32 * 256 - 1); + end if; elsif run("Test integer_vector results") then check(eval_integer_vector("[3, 1, 4]") = integer_vector'(3, 1, 4)); check( eval_integer_vector("[-1, -2**31, 2**31 - 1, 0]") = integer_vector'(-1, int32_low, int32_high, 0) ); + check( + eval_integer_vector("[" & integer'image(integer'low) & ", " & integer'image(integer'high) & "]") = + integer_vector'(integer'low, integer'high) + ); elsif run("Test integer_array_t round trip") then arr := new_1d(length => 4); @@ -56,12 +75,55 @@ begin check_equal(get(result, idx), get(arr, idx)); end loop; + elsif run("Test integer_vector_ptr_t results") then + ptr := eval_integer_vector_ptr("[-1, -2**31, 2**31 - 1]"); + check_equal(length(ptr), 3); + check_equal(get(ptr, 0), -1); + check_equal(get(ptr, 1), int32_low); + check_equal(get(ptr, 2), int32_high); + ptr := eval_integer_vector_ptr("[" & integer'image(integer'high) & ", " & integer'image(integer'low) & "]"); + check_equal(get(ptr, 0), integer'high); + check_equal(get(ptr, 1), integer'low); + + elsif run("Test dict_t results") then + dict := eval_dict("{'a': -1, 'b': 2**31 - 1, 'c': [-2**31, 3], 'd': True, 'e': {'f': -5}}"); + check_equal(get_integer(dict, "a"), -1); + check_equal(get_integer(dict, "b"), int32_high); + ptr := get_integer_vector_ptr_t_ref(dict, "c"); + check_equal(get(ptr, 0), int32_low); + check_equal(get(ptr, 1), 3); + check(get_boolean(dict, "d")); + check_equal(get_integer(get_dict_t_ref(dict, "e"), "f"), -5); + dict := eval_dict("{'c': [" & integer'image(integer'low) & ", " & integer'image(integer'high) & "]}"); + ptr := get_integer_vector_ptr_t_ref(dict, "c"); + check_equal(get(ptr, 0), integer'low); + check_equal(get(ptr, 1), integer'high); + + elsif run("Test that a dict_t integer outside 32 bits fails") then + -- VUnit stores the integers of a dict_t in 32 bits whatever the width of + -- integer. The failure is counted rather than mocked since VHDL-2019 gives + -- a log entry the location of its call path, which check_log compares. + disable_stop(session_logger, failure); + dict := eval_dict("{'a': 2**31}"); + check_equal(get_log_count(session_logger, failure), 1, "failures of eval_dict"); + reset_log_count(session_logger, failure); + + elsif run("Test boolean results") then + check(eval_boolean("True")); + check(not eval_boolean("False")); + elsif run("Test that integer'high reaches Python") then -- Arguments are transferred as Python source code, so all of a -- 64-bit integer reaches Python exec("high = " & integer'image(integer'high)); check_equal(eval_integer("1 if high in (2**31 - 1, 2**63 - 1) else 0"), 1); check_equal(eval_integer("high >> 32"), integer'high / 2**16 / 2**16); + exec("def top(v): return int(max(v) >> 32)"); + check_equal(call_integer("top", arg(integer_vector'(1, integer'high))), integer'high / 2**16 / 2**16); + ptr := new_integer_vector_ptr(2); + set(ptr, 1, integer'low); + check_equal(call_integer("top", arg(ptr)), 0); + -- Not a dict_t value: VUnit encodes the integers of a dict_t in 32 bits end if; end loop; diff --git a/tests/tb_python_pkg.vhd b/tests/tb_python_pkg.vhd index 78fb8ef..6b3949f 100644 --- a/tests/tb_python_pkg.vhd +++ b/tests/tb_python_pkg.vhd @@ -73,8 +73,8 @@ begin --------------------------------------------------------------------- if run("Test eval of integer expression") then check_equal(eval("17"), 17); - check_equal(eval("2**31 - 1"), integer'high); - check_equal(eval("-2**31"), integer'low); + check_equal(eval(integer'image(integer'high)), integer'high); + check_equal(eval(integer'image(integer'low)), integer'low); elsif run("Test eval of integer with overflow from Python to C") then mock(default_logger, failure); diff --git a/tests/test_python_bridge.py b/tests/test_python_bridge.py index 7947b81..2ec1cb8 100644 --- a/tests/test_python_bridge.py +++ b/tests/test_python_bridge.py @@ -15,6 +15,7 @@ import os import re import shutil +import struct import subprocess import sys import tempfile @@ -173,6 +174,66 @@ def test_the_simulator_dependent_vhdl_is_not_listed(self): self.assertNotIn("hdl/src/python_ffi_pkg_bridge.vhd", includes) +class TestIntegerWidth(unittest.TestCase): + """ + The integer results with the width of VHDL integer: 32 bits, or 64 bits as for NVC with + VHDL-2019, when a value crosses the 32-bit foreign interface as two halves. + """ + + def setUp(self): + from vunit_python_bridge import runtime # pylint: disable=import-outside-toplevel + + self.runtime = runtime + # The conversions do not need the session state that __init__ sets up + self.converter = runtime.Runtime.__new__(runtime.Runtime) + + def convert(self, kind, value, width): + self.converter._result = value # pylint: disable=protected-access + self.converter._array_meta = {} # pylint: disable=protected-access + return self.converter.convert_result(kind, width) + + @staticmethod + def from_halves(low, high): + return high * 2**32 + (low & 0xFFFFFFFF) + + def test_halves_are_signed_int32_and_give_the_value_back(self): + for value in (0, 1, -1, 2**31 - 1, -(2**31), 2**31, 2**32 + 5, -(2**40) - 1, 2**63 - 1, -(2**63)): + low, high = self.runtime.Runtime._integer_halves(value) # pylint: disable=protected-access + self.assertTrue(-(2**31) <= low < 2**31 and -(2**31) <= high < 2**31, value) + self.assertEqual(self.from_halves(low, high), value) + + def test_a_32_bit_integer_result_is_unchanged(self): + for width in (-1, 32): + self.assertEqual(self.convert(self.runtime.KIND_INTEGER, -5, width), (-5, 0.0, b"", ())) + + def test_a_64_bit_integer_result_has_the_high_half_as_metadata(self): + integer, _, _, meta = self.convert(self.runtime.KIND_INTEGER, -(2**40) - 1, 64) + self.assertEqual(self.from_halves(integer, meta[0]), -(2**40) - 1) + + def test_the_range_follows_the_width(self): + with self.assertRaisesRegex(OverflowError, r"\(-2147483648 to 2147483647\)"): + self.convert(self.runtime.KIND_INTEGER, 2**31, 32) + self.convert(self.runtime.KIND_INTEGER, 2**63 - 1, 64) + with self.assertRaisesRegex(OverflowError, r"\(-9223372036854775808 to 9223372036854775807\)"): + self.convert(self.runtime.KIND_INTEGER, 2**63, 64) + + def test_a_64_bit_integer_vector_is_pairs_of_halves(self): + values = [2**63 - 1, -1, -(2**63)] + _, _, data, meta = self.convert(self.runtime.KIND_INTEGER_VECTOR, values, 64) + halves = struct.unpack(f"={2 * len(values)}i", data) + self.assertEqual(meta, (3,)) + self.assertEqual([self.from_halves(*halves[i : i + 2]) for i in range(0, len(halves), 2)], values) + + def test_a_dict_integer_is_32_bits_with_a_64_bit_integer(self): + self.convert(self.runtime.KIND_DICT, {"a": [2**40]}, 64) + with self.assertRaisesRegex(OverflowError, "which VUnit stores in 32 bits"): + self.convert(self.runtime.KIND_DICT, {"a": 2**40}, 64) + + def test_an_unknown_width_is_an_internal_error(self): + with self.assertRaisesRegex(RuntimeError, "Internal error"): + self.convert(self.runtime.KIND_INTEGER, 1, 16) + + class TestObjectCreation(unittest.TestCase): """ __vunit__.instantiate_as_obj, which creates the object of a python_object_t in its session. From 9f471271d81bc004a1f9417c0c092bc296bee8c6 Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 12:48:45 +0100 Subject: [PATCH 3/9] Reword the release note and drop the simulator from the descriptions The release note says which integers have the full 64-bit range and which remain 32 bits. The documentation, comments and release note describe a 64-bit integer by VHDL-2019 rather than by a simulator. Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 2 +- release_notes/news.d/45.bugfix.md | 2 +- src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in | 2 +- src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd | 2 +- src/vunit_python_bridge/runtime.py | 2 +- tests/integer_width/run.py | 2 +- tests/integer_width/tb_integer_width.vhd | 2 +- tests/run.py | 4 ++-- tests/test_python_bridge.py | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 316e6f7..43cde33 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -29,7 +29,7 @@ Range of integer ---------------- ``integer`` has the range of the simulator: ``-2**31`` to ``2**31 - 1``, or -``-2**63`` to ``2**63 - 1`` when it is 64 bits, as for NVC with VHDL-2019. The +``-2**63`` to ``2**63 - 1`` when it is 64 bits, as with VHDL-2019. The arguments and results of type ``integer``, ``integer_vector`` and ``integer_vector_ptr_t`` have that range, and so do the elements of a list in a ``dict_t``. A result outside it is an error. diff --git a/release_notes/news.d/45.bugfix.md b/release_notes/news.d/45.bugfix.md index f9fc696..91bfe72 100644 --- a/release_notes/news.d/45.bugfix.md +++ b/release_notes/news.d/45.bugfix.md @@ -1 +1 @@ -The bridge supports a 64-bit `integer`, as NVC has with VHDL-2019. Integer results, `integer_vector`, `integer_vector_ptr_t` and `integer_array_t` values and `dict_t` entries used to be garbage with it. Integers now have the full range of `integer`, except the integers of a `dict_t` and the elements of an `integer_array_t`, which VUnit stores in 32 bits. +With a 64-bit `integer`, as with VHDL-2019, integer values crossing the bridge were garbage. They are now transferred correctly. `integer`, `integer_vector` and `integer_vector_ptr_t` values have the full 64-bit range, while the integers of a `dict_t` and the elements of an `integer_array_t` remain 32 bits, as VUnit stores them. diff --git a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in index f380e86..c6d86b9 100644 --- a/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in +++ b/src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in @@ -18,7 +18,7 @@ -- ABI is identical for NVC and GHDL on all platforms and is translated to the -- FLI parameter passing conventions by native/fli.c. The integers are c_int32_t, -- which is the int32_t of the native library whatever the width of integer: --- integer is 64 bits for NVC with VHDL-2019, and its results then cross as two +-- integer can be 64 bits with VHDL-2019, and its results then cross as two -- halves, see python_ffi_pkg. package python_bridge_pkg is diff --git a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd index c75b2e8..6db0c84 100644 --- a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd +++ b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd @@ -277,7 +277,7 @@ package body python_ffi_pkg is return false; end; - -- The width of integer: 64 bits for NVC with VHDL-2019, else 32 bits. The + -- The width of integer: 32 bits, or 64 bits as with VHDL-2019. The -- foreign interface is 32 bits, so a 64-bit integer result crosses it as two -- halves, see _integer_halves in runtime.py. constant p_integer_width : positive := 32 + 32 * boolean'pos(integer'high > 2147483647); diff --git a/src/vunit_python_bridge/runtime.py b/src/vunit_python_bridge/runtime.py index e837860..76340f1 100644 --- a/src/vunit_python_bridge/runtime.py +++ b/src/vunit_python_bridge/runtime.py @@ -59,7 +59,7 @@ STD_ULOGIC_VALUES = frozenset("UX01ZWLH-") INTEGER_LOW = -(2**31) INTEGER_HIGH = 2**31 - 1 -# The width of VHDL integer: 32 bits, or 64 bits as for NVC with VHDL-2019. VHDL +# The width of VHDL integer: 32 bits, or 64 bits as with VHDL-2019. VHDL # gives it as the width of an integer, integer_vector or dict_t result, -1 meaning # 32. A 64-bit integer crosses the foreign interface as two int32 halves, see # _integer_halves. diff --git a/tests/integer_width/run.py b/tests/integer_width/run.py index b4c67cc..2813852 100644 --- a/tests/integer_width/run.py +++ b/tests/integer_width/run.py @@ -8,7 +8,7 @@ Run script of the tests of the width of integer, see #43. The testbench checks that the integer transfers work whatever the width of integer. It is a run of its own since the standard is fixed for a run: VUNIT_VHDL_STANDARD selects it, -2019 gives NVC a 64-bit integer. +2019 gives a 64-bit integer with some simulators. """ from pathlib import Path diff --git a/tests/integer_width/tb_integer_width.vhd b/tests/integer_width/tb_integer_width.vhd index e56f8b0..5d721f3 100644 --- a/tests/integer_width/tb_integer_width.vhd +++ b/tests/integer_width/tb_integer_width.vhd @@ -5,7 +5,7 @@ -- Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com -- -- The transfers of integers with the width of integer, which is 64 bits for --- NVC with VHDL-2019, see #43. The tests pass with either width. +-- some simulators with VHDL-2019, see #43. The tests pass with either width. library vunit_lib; context vunit_lib.vunit_context; diff --git a/tests/run.py b/tests/run.py index 7eadcf0..e412bf1 100644 --- a/tests/run.py +++ b/tests/run.py @@ -86,8 +86,8 @@ def run_integer_width_tests(args, simulator_name): """ Run the tests of the width of integer, which is fixed by the VHDL standard of a run and therefore a run of its own, with the same simulator and an output path of its own. - It runs with the standard of this run, and with VHDL-2019 for NVC, which gives it a - 64-bit integer. + It runs with the standard of this run, and with VHDL-2019 for the simulators known to + have a 64-bit integer with it. """ standards = [os.environ.get("VUNIT_VHDL_STANDARD", "2008")] if simulator_name == "nvc" and "2019" not in standards: diff --git a/tests/test_python_bridge.py b/tests/test_python_bridge.py index 2ec1cb8..3c0cfd0 100644 --- a/tests/test_python_bridge.py +++ b/tests/test_python_bridge.py @@ -176,7 +176,7 @@ def test_the_simulator_dependent_vhdl_is_not_listed(self): class TestIntegerWidth(unittest.TestCase): """ - The integer results with the width of VHDL integer: 32 bits, or 64 bits as for NVC with + The integer results with the width of VHDL integer: 32 bits, or 64 bits as with VHDL-2019, when a value crosses the 32-bit foreign interface as two halves. """ From d730097bd628b00d79c0f0d6668c49a767a6709c Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 12:54:06 +0100 Subject: [PATCH 4/9] Report an integer_array_t argument element outside 32 bits With a 64-bit integer, VUnit lets an integer_array_t with a bit_width of 32 hold a value outside 32 bits, since its limits are integer'low and integer'high. The bridge transfers the elements as 32 bits, and such an element stopped the simulation with a range error of c_int32_t. It is now reported as a failure of the argument naming the element, like any other argument that cannot be converted. tests/integer_width checks that an element outside 32 bits fails as an argument and as a result. The documentation and release note say so. Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 8 ++++++-- release_notes/news.d/45.bugfix.md | 2 +- .../hdl/src/python_ffi_pkg_bridge.vhd | 16 +++++++++++++++ tests/integer_width/tb_integer_width.vhd | 20 +++++++++++++++++++ 4 files changed, 43 insertions(+), 3 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 43cde33..bbcb789 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -39,7 +39,10 @@ Two kinds of integers are 32 bits whatever the width of ``integer``: * An ``integer`` value of a ``dict_t``, since VUnit stores it in 32 bits. A larger result is an error, while ``set_integer`` truncates a larger argument value before the bridge sees it. -* An element of an ``integer_array_t``, whose ``bit_width`` is at most 32, see +* An element of an ``integer_array_t``, since the bridge transfers it as 32 + bits. With a 64-bit ``integer``, VUnit lets an ``integer_array_t`` with a + ``bit_width`` of 32 hold a larger value, and such an argument is an error. A + larger result does not fit the word size, which is an error too, see :ref:`python_bridge:integer_array`. .. _python_bridge:dict: @@ -91,7 +94,8 @@ integer_array_t and NumPy An ``integer_array_t`` argument is transferred to Python and referred to by the expression as a NumPy array of dtype ``int32``, so it can be reused in -several calls. Since it is transferred when the argument is made, the +several calls. An element that does not fit in 32 bits, which a 64-bit +``integer`` allows, is reported as a failure. Since it is transferred when the argument is made, the argument must be made after ``test_runner_setup``, not during elaboration, for example in a constant. Otherwise ``arg`` and ``kwarg`` report a failure, see `#17 `__. It is diff --git a/release_notes/news.d/45.bugfix.md b/release_notes/news.d/45.bugfix.md index 91bfe72..5e87be1 100644 --- a/release_notes/news.d/45.bugfix.md +++ b/release_notes/news.d/45.bugfix.md @@ -1 +1 @@ -With a 64-bit `integer`, as with VHDL-2019, integer values crossing the bridge were garbage. They are now transferred correctly. `integer`, `integer_vector` and `integer_vector_ptr_t` values have the full 64-bit range, while the integers of a `dict_t` and the elements of an `integer_array_t` remain 32 bits, as VUnit stores them. +With a 64-bit `integer`, as with VHDL-2019, integer values crossing the bridge were garbage. They are now transferred correctly. `integer`, `integer_vector` and `integer_vector_ptr_t` values have the full 64-bit range, while the integers of a `dict_t` and the elements of an `integer_array_t` remain 32 bits. A larger value is reported as an error, except in a `dict_t` argument, where VUnit's `set_integer` has already truncated it. diff --git a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd index 6db0c84..b8366ce 100644 --- a/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd +++ b/src/vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd @@ -486,6 +486,22 @@ package body python_ffi_pkg is ); return -1; end if; + -- The elements cross as 32 bits, which a 64-bit integer, and so an + -- integer_array_t with a bit_width of 32, can exceed + if p_integer_width = 64 then + for idx in 0 to len - 1 loop + if get(arr, idx) < integer(c_int32_t'low) or get(arr, idx) > integer(c_int32_t'high) then + failure( + python_logger, + operation & " failed:" & LF & + "Element " & integer'image(idx) & " (" & integer'image(get(arr, idx)) & ") of the integer_array_t " & + "does not fit in 32 bits (" & integer'image(integer(c_int32_t'low)) & " to " & + integer'image(integer(c_int32_t'high)) & ")." + ); + return -1; + end if; + end loop; + end if; if not p_succeeded( vpy_push_array( c_int32_t(len), c_int32_t(width(arr)), c_int32_t(height(arr)), c_int32_t(depth(arr)), diff --git a/tests/integer_width/tb_integer_width.vhd b/tests/integer_width/tb_integer_width.vhd index 5d721f3..137de9e 100644 --- a/tests/integer_width/tb_integer_width.vhd +++ b/tests/integer_width/tb_integer_width.vhd @@ -75,6 +75,26 @@ begin check_equal(get(result, idx), get(arr, idx)); end loop; + elsif run("Test that an integer_array_t element outside 32 bits fails") then + -- The elements cross as 32 bits. The failures are counted rather than + -- mocked since VHDL-2019 gives a log entry the location of its call + -- path, which check_log compares. + disable_stop(python_logger, failure, unset_children => true); + exec("import numpy"); + result := eval_integer_array("numpy.array([2**40])"); + check_equal(get_log_count(session_logger, failure), 1, "failures of a result"); + if integer'high > int32_high then + -- An integer_array_t with a bit_width of 32 holds a 64-bit integer + two_32 := 2**16; + two_32 := two_32 * two_32; + arr := new_1d(length => 3); + set(arr, 2, two_32 * 256); + exec("def same(a): return a"); + result := call_integer_array("same", arg(arr)); + check_equal(get_log_count(python_logger, failure), 1, "failures of an argument"); + end if; + reset_log_count(python_logger, failure); + elsif run("Test integer_vector_ptr_t results") then ptr := eval_integer_vector_ptr("[-1, -2**31, 2**31 - 1]"); check_equal(length(ptr), 3); From ea63b1783f654b7a2810f72f9a07b16df5d58959 Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 13:13:29 +0100 Subject: [PATCH 5/9] Say why the integer width tests include boolean results Co-Authored-By: Claude Opus 5.5 --- tests/integer_width/tb_integer_width.vhd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/integer_width/tb_integer_width.vhd b/tests/integer_width/tb_integer_width.vhd index 137de9e..93812bd 100644 --- a/tests/integer_width/tb_integer_width.vhd +++ b/tests/integer_width/tb_integer_width.vhd @@ -129,6 +129,8 @@ begin reset_log_count(session_logger, failure); elsif run("Test boolean results") then + -- A boolean result is read as an integer, which takes the high half + -- from the metadata with a 64-bit integer check(eval_boolean("True")); check(not eval_boolean("False")); From 763d820e2c4b1d44484ada04611e345b64f2bc5f Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Wed, 18 Nov 2026 13:15:43 +0100 Subject: [PATCH 6/9] Say why the integer width tests are a run of their own Co-Authored-By: Claude Opus 5.5 --- tests/run.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/run.py b/tests/run.py index e412bf1..75b4c32 100644 --- a/tests/run.py +++ b/tests/run.py @@ -88,6 +88,10 @@ def run_integer_width_tests(args, simulator_name): and therefore a run of its own, with the same simulator and an output path of its own. It runs with the standard of this run, and with VHDL-2019 for the simulators known to have a 64-bit integer with it. + + It cannot be a testbench of this run with a VHDL standard of its own: VUnit rejects + mixed standards for NVC, and the bridge packages and VUnit must be compiled with the + standard too, since it decides the width of integer. """ standards = [os.environ.get("VUNIT_VHDL_STANDARD", "2008")] if simulator_name == "nvc" and "2019" not in standards: From e0e3dbd5dbdadfb64cc0e481288200fca373c33f Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Fri, 20 Nov 2026 11:38:32 +0100 Subject: [PATCH 7/9] Warn that set_integer truncates a 64-bit dict_t value Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/types.rst b/docs/types.rst index bbcb789..a73ed76 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -68,6 +68,15 @@ visited in the order of ``get_key``, which VUnit does not specify. set_real(cfg, "gain", 0.5); call("model.configure", arg(cfg)); +.. warning:: + + VUnit stores an ``integer`` value of a ``dict_t`` in 32 bits. With a 64-bit + ``integer``, as with VHDL-2019, ``set_integer`` silently keeps only the low + 32 bits of a value outside ``-2**31`` to ``2**31 - 1``, so Python receives a + different number with no error. The bridge cannot detect this, since the + value is truncated before it is read. Store such a value in an + ``integer_vector_ptr_t``, which has the full range. + ``eval_dict`` and ``call_dict`` (aliased ``eval`` and ``call``) convert a Python ``dict`` with ``str`` keys to a new ``dict_t`` that the caller owns and deallocates. The values are converted strictly: ``int`` to ``integer``, From a8e0997006f085f8ba2074fc71daa7c69a791efa Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Fri, 20 Nov 2026 11:40:06 +0100 Subject: [PATCH 8/9] Mention the simulator warning of a truncated dict_t value Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types.rst b/docs/types.rst index a73ed76..625c42b 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -73,7 +73,7 @@ visited in the order of ``get_key``, which VUnit does not specify. VUnit stores an ``integer`` value of a ``dict_t`` in 32 bits. With a 64-bit ``integer``, as with VHDL-2019, ``set_integer`` silently keeps only the low 32 bits of a value outside ``-2**31`` to ``2**31 - 1``, so Python receives a - different number with no error. The bridge cannot detect this, since the + different number with only a simulator warning. The bridge cannot detect this, since the value is truncated before it is read. Store such a value in an ``integer_vector_ptr_t``, which has the full range. From 16dbdf09e4c4c9d21b7bda7722bf405ed56573d5 Mon Sep 17 00:00:00 2001 From: Sebastian Abrahamsson Date: Fri, 20 Nov 2026 11:40:32 +0100 Subject: [PATCH 9/9] Reflow the dict_t truncation warning Co-Authored-By: Claude Opus 5.5 --- docs/types.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 625c42b..f7ebf95 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -71,11 +71,11 @@ visited in the order of ``get_key``, which VUnit does not specify. .. warning:: VUnit stores an ``integer`` value of a ``dict_t`` in 32 bits. With a 64-bit - ``integer``, as with VHDL-2019, ``set_integer`` silently keeps only the low - 32 bits of a value outside ``-2**31`` to ``2**31 - 1``, so Python receives a - different number with only a simulator warning. The bridge cannot detect this, since the - value is truncated before it is read. Store such a value in an - ``integer_vector_ptr_t``, which has the full range. + ``integer``, as with VHDL-2019, ``set_integer`` keeps only the low 32 bits + of a value outside ``-2**31`` to ``2**31 - 1``, so Python receives a + different number with only a simulator warning. The bridge cannot detect + this, since the value is truncated before it is read. Store such a value in + an ``integer_vector_ptr_t``, which has the full range. ``eval_dict`` and ``call_dict`` (aliased ``eval`` and ``call``) convert a Python ``dict`` with ``str`` keys to a new ``dict_t`` that the caller owns and