Skip to content
39 changes: 36 additions & 3 deletions docs/types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Types
Type mapping
------------

* ``integer`` ↔ ``int``. Results outside the VHDL integer range fail.
* ``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).
Expand All @@ -23,6 +23,28 @@ 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 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``, 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:

dict_t and dict
Expand All @@ -46,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`` 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
deallocates. The values are converted strictly: ``int`` to ``integer``,
Expand All @@ -55,7 +86,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.

Expand All @@ -71,7 +103,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 <https://github.com/VUnit/vunit-python-bridge/issues/17>`__. It is
Expand Down
1 change: 1 addition & 0 deletions release_notes/news.d/45.bugfix.md
Original file line number Diff line number Diff line change
@@ -0,0 +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. A larger value is reported as an error, except in a `dict_t` argument, where VUnit's `set_integer` has already truncated it.
43 changes: 24 additions & 19 deletions src/vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in
Original file line number Diff line number Diff line change
Expand Up @@ -16,76 +16,81 @@
--
-- 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 can be 64 bits 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;
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(<id>).
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;

Loading
Loading