feat: add external models to string_ptr; add byte_vector* as an alias

Author: umarcor

vunit/builtins.py

@@ -68,13 +68,61 @@ def _add_files(self, pattern):
 
             self._vunit_lib.add_source_file(file_name)
 
-    def _add_data_types(self):
+    def _add_data_types(self, use_external=None, impls=None):
         """
         Add data types packages
+
+        :param use_external: list of Booleans, to select whether to enable external models for string and/or
+        integer_vector, respectively.
+        :param impls: optional list of lists containing alternative implementations for external models.
         """
         self._add_files(join(VHDL_PATH, "data_types", "src", "types", "*.vhd"))
         self._add_files(join(VHDL_PATH, "data_types", "src", "*.vhd"))
 
+#        Add sources corresponding to VHPIDIRECT arrays (or their placeholders)
+
+        from vunit.test.common import simulator_check
+
+        use_ext = [False, False]
+        files = [None, None]
+
+        if use_external is not None:
+            for ind, val in enumerate(use_external):
+                use_ext[ind] = val
+        if impls is not None:
+            for ind, val in enumerate(impls):
+                files[ind] = val
+
+        for val in use_ext:
+            if val and simulator_check(lambda simclass: not simclass.supports_vhpi()):
+                raise RuntimeError("the selected simulator does not support VHPI; must use non-VHPI packages...")
+
+        ext_path = join(VHDL_PATH, "data_types", "src", "external")
+
+        def default_pkg(cond, type_str):
+            """
+            Return name of VHDL file with default VHPIDIRECT foreign declarations.
+            """
+            nostr = 'no'
+            if cond:
+                nostr = ''
+            return join(ext_path, 'external_' + type_str + '-' + nostr + 'vhpi.vhd')
+
+        if not files[0]:
+            files[0] = [
+                default_pkg(use_ext[0], 'string'),
+                join(ext_path, "external_string-body.vhd")
+            ]
+        if not files[1]:
+            files[1] = [
+                default_pkg(use_ext[1], 'integer_vector'),
+                join(ext_path, "external_integer_vector-body.vhd")
+            ]
+
+        for _, flist in enumerate(files):
+            for name in flist:
+                self._add_files(name)
+
     def _add_array_util(self):
         """
         Add array utility
@@ -168,11 +216,15 @@ def add_verilog_builtins(self):
         """
         self._vunit_lib.add_source_files(join(VERILOG_PATH, "vunit_pkg.sv"))
 
-    def add_vhdl_builtins(self):
+    def add_vhdl_builtins(self, use_external=None, impls=None):
         """
         Add vunit VHDL builtin libraries
+
+        :param use_external: list of Booleans, to select whether to enable external models for string and/or
+        integer_vector, respectively.
+        :param impls: optional list of lists containing alternative implementations for external models.
         """
-        self._add_data_types()
+        self._add_data_types(use_external=use_external, impls=impls)
         self._add_files(join(VHDL_PATH, "*.vhd"))
         for path in ("core", "logging", "string_ops", "check", "dictionary", "run", "path"):
             self._add_files(join(VHDL_PATH, path, "src", "*.vhd"))

vunit/ui.py

@@ -118,7 +118,7 @@
   A list of PLI file names.
 
 ``ghdl.flags``
-   Extra arguments passed to ``ghdl --elab-run`` command *before* executable specific flags. Must be a list of strings.
+   Extra arguments passed to ``ghdl --elab-run`` command *before* executable specific flags.
    Must be a list of strings.
 
 ``incisive.irun_sim_flags``
@@ -290,12 +290,17 @@ class VUnit(object):  # pylint: disable=too-many-instance-attributes, too-many-p
     """
 
     @classmethod
-    def from_argv(cls, argv=None, compile_builtins=True, vhdl_standard=None):
+    def from_argv(cls, argv=None, compile_builtins=True, vhdl_standard=None, use_external=None, impls=None):
         """
         Create VUnit instance from command line arguments.
 
         :param argv: Use explicit argv instead of actual command line argument
         :param compile_builtins: Do not compile builtins. Used for VUnit internal testing.
+        :param vhdl_standard: The VHDL standard used to compile files into this library,
+                              if None the VUNIT_VHDL_STANDARD environment variable is used
+        :param use_external: list of Booleans, to select whether to enable external models for string and/or
+                     integer_vector, respectively; if None, all of them are disabled
+        :param impls: optional list of lists containing alternative implementations for external models
         :returns: A :class:`.VUnit` object instance
 
         :example:
@@ -307,10 +312,16 @@ def from_argv(cls, argv=None, compile_builtins=True, vhdl_standard=None):
 
         """
         args = VUnitCLI().parse_args(argv=argv)
-        return cls.from_args(args, compile_builtins=compile_builtins, vhdl_standard=vhdl_standard)
+        return cls.from_args(
+            args,
+            compile_builtins=compile_builtins,
+            vhdl_standard=vhdl_standard,
+            use_external=use_external,
+            impls=impls
+        )
 
     @classmethod
-    def from_args(cls, args, compile_builtins=True, vhdl_standard=None):
+    def from_args(cls, args, compile_builtins=True, vhdl_standard=None, use_external=None, impls=None):
         """
         Create VUnit instance from args namespace.
         Intended for users who adds custom command line options.
@@ -319,12 +330,23 @@ def from_args(cls, args, compile_builtins=True, vhdl_standard=None):
 
         :param args: The parsed argument namespace object
         :param compile_builtins: Do not compile builtins. Used for VUnit internal testing.
+        :param vhdl_standard: The VHDL standard used to compile files into this library,
+                              if None the VUNIT_VHDL_STANDARD environment variable is used
+        :param use_external: list of Booleans, to select whether to enable external models for string and/or
+                     integer_vector, respectively; if None, all of them are disabled
+        :param impls: optional list of lists containing alternative implementations for external models
         :returns: A :class:`.VUnit` object instance
-        """
 
-        return cls(args, compile_builtins=compile_builtins, vhdl_standard=vhdl_standard)
+        """
+        return cls(
+            args,
+            compile_builtins=compile_builtins,
+            vhdl_standard=vhdl_standard,
+            use_external=use_external,
+            impls=impls
+        )
 
-    def __init__(self, args, compile_builtins=True, vhdl_standard=None):
+    def __init__(self, args, compile_builtins=True, vhdl_standard=None, use_external=None, impls=None):
         self._args = args
         self._configure_logging(args.log_level)
         self._output_path = abspath(args.output_path)
@@ -371,8 +393,9 @@ def test_filter(name, attribute_names):
         self._test_bench_list = TestBenchList(database=database)
 
         self._builtins = Builtins(self, self._vhdl_standard, simulator_class)
+        self._compile_builtins = compile_builtins
         if compile_builtins:
-            self.add_builtins()
+            self.add_builtins(use_external=use_external, impls=impls)
 
     def _create_database(self):
         """
@@ -858,7 +881,6 @@ def _main(self, post_run):
         """
         Base vunit main function without performing exit
         """
-
         if self._args.export_json is not None:
             return self._main_export_json(self._args.export_json)
 
@@ -1056,11 +1078,15 @@ def _run_test(self, test_cases, report):
                             no_color=self._args.no_color)
         runner.run(test_cases)
 
-    def add_builtins(self):
+    def add_builtins(self, use_external=None, impls=None):
         """
         Add vunit VHDL builtin libraries
+
+        :param use_external: list of Booleans, to select whether to enable external models for string and/or
+        integer_vector, respectively.
+        :param impls: optional list of lists containing alternative implementations for external models.
         """
-        self._builtins.add_vhdl_builtins()
+        self._builtins.add_vhdl_builtins(use_external=use_external, impls=impls)
 
     def add_com(self):
         """

vunit/vhdl/data_types/src/byte_vector_ptr_pkg.vhd

@@ -0,0 +1,37 @@
+-- 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-2019, Lars Asplund lars.anders.asplund@gmail.com
+--
+-- The purpose of this package is to provide a byte vector access type (pointer)
+-- that can itself be used in arrays and returned from functions unlike a
+-- real access type. This is achieved by letting the actual value be a handle
+-- into a singleton datastructure of string access types.
+--
+
+use work.byte_vector_pkg.all;
+use work.string_ptr_pkg.all;
+
+package byte_vector_ptr_pkg is
+
+  alias byte_vector_ptr_t is string_ptr_t;
+  alias null_byte_vector_ptr is null_string_ptr;
+
+  alias new_byte_vector_ptr is new_string_ptr[natural, integer, val_t return ptr_t];
+  alias new_byte_vector_ptr is new_string_ptr[natural, integer, natural return ptr_t];
+  alias new_byte_vector_ptr is new_string_ptr[string, integer return ptr_t];
+
+  alias is_external is is_external[ptr_t return boolean];
+  alias deallocate is deallocate[ptr_t];
+  alias length is length[ptr_t return integer];
+  alias set is set[ptr_t, natural, natural];
+  alias get is get[ptr_t, natural return natural];
+  alias reallocate is reallocate[ptr_t, natural, natural];
+  alias resize is resize[ptr_t, natural, natural, natural];
+
+--  alias write_byte is write_char;
+--  alias read_byte is read_char;
+--  alias byte_vector_access_t is string_access_t;
+
+end package;

vunit/vhdl/data_types/src/data_types_context.vhd

@@ -6,6 +6,8 @@
 
 context data_types_context is
   library vunit_lib;
+  use vunit_lib.byte_vector_pkg.all;
+  use vunit_lib.byte_vector_ptr_pkg.all;
   use vunit_lib.integer_vector_ptr_pkg.all;
   use vunit_lib.integer_vector_ptr_pool_pkg.all;
   use vunit_lib.integer_array_pkg.all;

vunit/vhdl/data_types/src/external/external_string-body.vhd

@@ -0,0 +1,31 @@
+-- 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-2019, Lars Asplund lars.anders.asplund@gmail.com
+
+package body external_string_pkg is
+  procedure
+  write_char(
+    id : integer;
+    i  : integer;
+    v  : character
+  )is begin
+    assert false report "VHPI write_char" severity failure;
+  end;
+
+  impure function
+  read_char(
+    id : integer;
+    i  : integer
+  ) return character is begin
+    assert false report "VHPI read_char" severity failure;
+  end;
+
+  impure function
+  get_ptr(
+    id : integer
+  ) return extstring_access_t is begin
+    assert false report "VHPI get_string_ptr" severity failure;
+  end;
+end package body;

vunit/vhdl/data_types/src/external/external_string-novhpi.vhd

@@ -0,0 +1,27 @@
+-- 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-2019, Lars Asplund lars.anders.asplund@gmail.com
+
+use work.string_pkg.all;
+
+package external_string_pkg is
+  procedure
+  write_char(
+    id : integer;
+    i  : integer;
+    v  : character
+  );
+
+  impure function
+  read_char(
+    id : integer;
+    i  : integer
+  ) return character;
+
+  impure function
+  get_ptr(
+    id : integer
+  ) return extstring_access_t;
+end package;

vunit/vhdl/data_types/src/external/external_string-vhpi.vhd

@@ -0,0 +1,30 @@
+-- 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-2019, Lars Asplund lars.anders.asplund@gmail.com
+
+use work.string_pkg.all;
+
+package external_string_pkg is
+  procedure
+  write_char(
+    id : integer;
+    i  : integer;
+    v  : character
+  );
+  attribute foreign of write_char : procedure is "VHPIDIRECT write_char";
+
+  impure function
+  read_char(
+    id : integer;
+    i  : integer
+  ) return character;
+  attribute foreign of read_char : function is "VHPIDIRECT read_char";
+
+  impure function
+  get_ptr(
+    id : integer
+  ) return extstring_access_t;
+  attribute foreign of get_ptr : function is "VHPIDIRECT get_string_ptr";
+end package;