Merge pull request #2282 from Paebbels/paebbels/ams

Activate VHDL-2008 and VHDL-AMS based on selected VHDL dialect

12 files changed, 247 insertions, 35 deletions

diff --git a/pyGHDL/__init__.py b/pyGHDL/__init__.py
index 64a3c3d87..4e8bc2ca8 100644
--- a/pyGHDL/__init__.py
+++ b/pyGHDL/__init__.py
@@ -38,13 +38,13 @@
 GHDL offers two Python interfaces and a language server protocol service. All
 this is provided from a ``pyGHDL`` packages with four sub-packages:
 
-* ``pyGHDL.cli`` - Command line interface (CLI) applications.
-* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM).
+* :mod:`pyGHDL.cli` - Command line interface (CLI) applications.
+* :mod:`pyGHDL.dom` - A high-level API offering a document object model (DOM).
   The underlying abstract VHDL language model is provided by :doc:`pyVHDLModel <vhdlmodel:index>`.
   The DOM is using ``libghdl`` for file analysis and parsing.
-* ``pyGHDL.libghdl`` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
+* :mod:`pyGHDL.libghdl` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
   This is a procedural and C-like interface. It comes with some Python generators for easier iterating linked lists.
-* ``pyGHDL.lsp`` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
+* :mod:`pyGHDL.lsp` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
   written in Python. The implementation offers an HTTPS service that can be used e.g. by editors and IDEs supporting LSP.
 """
 __author__ = "Tristan Gingold and contributors"
diff --git a/pyGHDL/dom/NonStandard.py b/pyGHDL/dom/NonStandard.py
index db160faaf..0a2ead728 100644
--- a/pyGHDL/dom/NonStandard.py
+++ b/pyGHDL/dom/NonStandard.py
@@ -42,6 +42,8 @@ from typing import Any
 
 from pyTooling.Decorators import export
 
+from pyGHDL.dom.Names import SimpleName
+from pyVHDLModel import VHDLVersion
 from pyVHDLModel.SyntaxModel import (
     Design as VHDLModel_Design,
     Library as VHDLModel_Library,
@@ -50,6 +52,7 @@ from pyVHDLModel.SyntaxModel import (
 )
 
 from pyGHDL.libghdl import (
+    ENCODING,
     initialize as libghdl_initialize,
     finalize as libghdl_finalize,
     set_option as libghdl_set_option,
@@ -58,6 +61,7 @@ from pyGHDL.libghdl import (
     files_map,
     errorout_memory,
     LibGHDLException,
+    flags,
     utils,
     files_map_editor,
     ENCODING,
@@ -102,7 +106,6 @@ class Design(VHDLModel_Design):
         errorout_memory.Install_Handler()
 
         libghdl_set_option("--std=08")
-        libghdl_set_option("--ams")
 
         Flag_Gather_Comments.value = True
         Flag_Parse_Parenthesis.value = True
@@ -131,6 +134,7 @@ class Document(VHDLModel_Document):
         self,
         path: Path,
         sourceCode: str = None,
+        vhdlVersion: VHDLVersion = VHDLVersion.VHDL2008,
         dontParse: bool = False,
         dontTranslate: bool = False,
     ):
@@ -146,8 +150,16 @@ class Document(VHDLModel_Document):
         if not dontParse:
             # Parse input file
             t1 = time.perf_counter()
+
+            if vhdlVersion.IsAMS:
+                flags.AMS_Vhdl.value = True
+
             self.__ghdlFile = sem_lib.Load_File(self.__ghdlSourceFileEntry)
             CheckForErrors()
+
+            if vhdlVersion.IsAMS:
+                flags.AMS_Vhdl.value = False
+
             self.__ghdlProcessingTime = time.perf_counter() - t1
 
             if not dontTranslate:
diff --git a/pyGHDL/dom/_Utils.py b/pyGHDL/dom/_Utils.py
index 3b647013b..83f10eae8 100644
--- a/pyGHDL/dom/_Utils.py
+++ b/pyGHDL/dom/_Utils.py
@@ -49,17 +49,31 @@ __MODE_TRANSLATION = {
     nodes.Iir_Mode.Buffer_Mode: Mode.Buffer,
     nodes.Iir_Mode.Linkage_Mode: Mode.Linkage,
 }
+"""
+Translation table if IIR modes to pyVHDLModel mode enumeration values.
+"""
 
 
 @export
 def CheckForErrors() -> None:
+    """
+    Check if an error occurred in libghdl and raise an exception if so.
+
+    **Behavior:**
+
+    1. read the error buffer and clear it afterwards
+    2. convert it into a list of internal messages for a :exc:`LibGHDLException`
+    3. raise a :exc:`DOMException` with a nested :exc:`LibGHDLException` as a ``__cause__``.
+
+    :raises DOMException: If an error occurred in libghdl.
+    """
     errorCount = errorout_memory.Get_Nbr_Messages()
-    errors = []
     if errorCount != 0:
+        errors = []
         for i in range(errorCount):
             rec = errorout_memory.Get_Error_Record(i + 1)
             # FIXME: needs help from @tgingold
-            fileName = ""  # name_table.Get_Name_Ptr(files_map.Get_File_Name(rec.file))
+            fileName = "????"  # name_table.Get_Name_Ptr(files_map.Get_File_Name(rec.file))
             message = errorout_memory.Get_Error_Message(i + 1)
 
             errors.append(f"{fileName}:{rec.line}:{rec.offset}: {message}")
@@ -71,9 +85,13 @@ def CheckForErrors() -> None:
 
 @export
 def GetIirKindOfNode(node: Iir) -> nodes.Iir_Kind:
-    """Return the kind of a node in the IIR tree."""
+    """Return the kind of a node in the IIR tree.
+
+    :returns:           The IIR kind of a node.
+    :raises ValueError: If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetIirKindOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetIirKindOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     kind: int = nodes.Get_Kind(node)
     return nodes.Iir_Kind(kind)
@@ -81,9 +99,12 @@ def GetIirKindOfNode(node: Iir) -> nodes.Iir_Kind:
 
 @export
 def GetNameOfNode(node: Iir) -> str:
-    """Return the python string from node :obj:`node` identifier."""
+    """Return the Python string from node ``node`` identifier.
+
+    :raises ValueError: If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetNameOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetNameOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     identifier = utils.Get_Source_Identifier(node)
     return name_table.Get_Name_Ptr(identifier)
@@ -103,11 +124,15 @@ def GetDocumentationOfNode(node: Iir) -> str:
 
 @export
 def GetModeOfNode(node: Iir) -> Mode:
-    """Return the mode of a :obj:`node`."""
+    """Return the mode of a ``node``.
+
+    :raises ValueError:   If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    :raises DOMException: If mode returned by libghdl is not known by :py:data:`__MODE_TRANSLATION`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetModeOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetModeOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     try:
         return __MODE_TRANSLATION[nodes.Get_Mode(node)]
-    except KeyError:
-        raise LibGHDLException("Unknown mode.")
+    except KeyError as ex:
+        raise DOMException(f"Unknown mode '{ex.args[0]}'.") from ex
diff --git a/pyGHDL/dom/__init__.py b/pyGHDL/dom/__init__.py
index 12caccc1b..e60a4e211 100644
--- a/pyGHDL/dom/__init__.py
+++ b/pyGHDL/dom/__init__.py
@@ -9,8 +9,6 @@
 # Authors:
 #   Patrick Lehmann
 #
-# Package package:  Document object model (DOM) for pyGHDL.libghdl.
-#
 # License:
 # ============================================================================
 #  Copyright (C) 2019-2021 Tristan Gingold
@@ -30,6 +28,9 @@
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 # ============================================================================
+"""
+Document object model (DOM) for :mod:`pyGHDL.libghdl` based on :doc:`pyVHDLModel <vhdlmodel:index>`.
+"""
 from pathlib import Path
 
 from pyTooling.Decorators import export
diff --git a/pyGHDL/libghdl/__init__.py b/pyGHDL/libghdl/__init__.py
index 2cf9cff70..2be39d1d6 100644
--- a/pyGHDL/libghdl/__init__.py
+++ b/pyGHDL/libghdl/__init__.py
@@ -10,11 +10,9 @@
 #   Tristan Gingold
 #   Patrick Lehmann
 #
-# Package package:  Python binding and low-level API for shared library 'libghdl'.
-#
 # License:
 # ============================================================================
-#  Copyright (C) 2019-2021 Tristan Gingold
+#  Copyright (C) 2019-2022 Tristan Gingold
 #
 #  This program is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -31,6 +29,11 @@
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 # ============================================================================
+"""
+Python binding and low-level API for shared library ``libghdl``.
+
+In case of an error, a :exc:`LibGHDLException` is raised.
+"""
 from ctypes import c_char_p, CDLL
 from sys import platform as sys_platform, version_info as sys_version_info
 from os import environ as os_environ
@@ -48,9 +51,12 @@ from pyGHDL import __version__ as ghdlVersion
 
 Nullable = Optional
 
+__all__ = ["ENCODING"]
+
 ENCODING = "latin-1"
 
 
+@export
 class LibGHDLException(GHDLBaseException):
     _internalErrors: Nullable[List[str]]
 
@@ -63,6 +69,7 @@ class LibGHDLException(GHDLBaseException):
         return self._internalErrors
 
 
+@export
 def _get_libghdl_name() -> Path:
     """Get the name of the libghdl library (with version and extension)."""
     version = ghdlVersion.replace("-", "_").replace(".", "_")
@@ -70,6 +77,7 @@ def _get_libghdl_name() -> Path:
     return Path(f"libghdl-{version}.{ext}")
 
 
+@export
 def _check_libghdl_libdir(libdir: Path, basename: Path) -> Path:
     """Returns libghdl path in :obj:`libdir`, if found."""
     if libdir is None:
@@ -82,6 +90,7 @@ def _check_libghdl_libdir(libdir: Path, basename: Path) -> Path:
     raise FileNotFoundError(str(res))
 
 
+@export
 def _check_libghdl_bindir(bindir: Path, basename: Path) -> Path:
     if bindir is None:
         raise ValueError("Parameter 'bindir' is None.")
@@ -89,11 +98,12 @@ def _check_libghdl_bindir(bindir: Path, basename: Path) -> Path:
     return _check_libghdl_libdir((bindir / "../lib").resolve(), basename)
 
 
+@export
 def _get_libghdl_path():
     """\
     Locate the directory where the shared library is installed.
 
-    Search order:
+    **Search order:**
 
     1. `GHDL_PREFIX` - directory (prefix) of the vhdl libraries.
     2. `VUNIT_GHDL_PATH` - path of the `ghdl` binary when using VUnit.
@@ -145,6 +155,7 @@ def _get_libghdl_path():
     raise Exception(f"Cannot find libghdl {basename}")
 
 
+@export
 def _initialize():
     # Load the shared library
     _libghdl_path = _get_libghdl_path()
@@ -192,15 +203,15 @@ def initialize() -> None:
 
 @export
 # @BindToLibGHDL("libghdl__set_option")
-def set_option(Opt: str) -> bool:
+def set_option(opt: str) -> bool:
     """\
     Set option :obj:`opt`.
 
-    :param Opt: Option to set.
+    :param opt: Option to set.
     :return:    Return ``True``, if the option is known and handled.
     """
-    Opt = Opt.encode(ENCODING)
-    return libghdl.libghdl__set_option(c_char_p(Opt), len(Opt)) == 0
+    opt = opt.encode(ENCODING)
+    return libghdl.libghdl__set_option(c_char_p(opt), len(opt)) == 0
 
 
 @export
diff --git a/pyGHDL/libghdl/flags.py b/pyGHDL/libghdl/flags.py
index fadd3bb52..dc5da6d60 100644
--- a/pyGHDL/libghdl/flags.py
+++ b/pyGHDL/libghdl/flags.py
@@ -33,25 +33,53 @@
 # ============================================================================
 
 from ctypes import c_bool, sizeof
+from enum import unique, IntEnum
+
+from pyTooling.Decorators import export
 
 from pyGHDL.libghdl import libghdl
 
 __all__ = [
     "Flag_Elocations",
     "Verbose",
+    "MB_Comment",
+    "Explicit",
+    "Relaxed",
     "Flag_Elaborate_With_Outdated",
     "Flag_Force_Analysis",
+    "AMS_Vhdl",
     "Flag_Gather_Comments",
 ]
 
 assert sizeof(c_bool) == 1
 
+
+@export
+@unique
+class VhdlStandard(IntEnum):
+    """An enumeration representing libghdl's internal ``Vhdl_Std_Type`` enumeration type."""
+
+    Vhdl_87 = 0  #: VHDL'87
+    Vhdl_93 = 1  #: VHDL'93
+    Vhdl_00 = 2  #: VHDL'2000
+    Vhdl_02 = 3  #: VHDL'2002
+    Vhdl_08 = 4  #: VHDL'2008
+    Vhdl_19 = 5  #: VHDL'2019
+
+
 Flag_Elocations = c_bool.in_dll(libghdl, "flags__flag_elocations")
 
-Verbose = c_bool.in_dll(libghdl, "flags__verbose")
+Verbose = c_bool.in_dll(libghdl, "flags__verbose")  #: Internal boolean flag representing :option:`-v`.
+MB_Comment = c_bool.in_dll(libghdl, "flags__mb_comment")  #: Internal boolean flag representing :option:`--mb-comment`.
+Explicit = c_bool.in_dll(libghdl, "flags__flag_explicit")  #: Internal boolean flag representing :option:`-fexplicit`.
+Relaxed = c_bool.in_dll(
+    libghdl, "flags__flag_relaxed_rules"
+)  #: Internal boolean flag representing :option:`-frelaxed`.
 
 Flag_Elaborate_With_Outdated = c_bool.in_dll(libghdl, "flags__flag_elaborate_with_outdated")
 
 Flag_Force_Analysis = c_bool.in_dll(libghdl, "flags__flag_force_analysis")
 
+AMS_Vhdl = c_bool.in_dll(libghdl, "flags__ams_vhdl")  #: Internal boolean flag representing :option:`-ams`.
+
 Flag_Gather_Comments = c_bool.in_dll(libghdl, "flags__flag_gather_comments")
diff --git a/pyGHDL/libghdl/libraries.py b/pyGHDL/libghdl/libraries.py
index fe09fa920..f31d3ec5f 100644
--- a/pyGHDL/libghdl/libraries.py
+++ b/pyGHDL/libghdl/libraries.py
@@ -50,15 +50,18 @@ __all__ = ["Library_Location", "Work_Library"]
 
 Library_Location: LocationType = c_int32.in_dll(libghdl, "libraries__library_location")
 """
-A location for library declarations (such as library WORK). Use ``.value`` to
-access this variable inside libghdl.
+A location for library declarations (such as library WORK).
+
+Use the property ``.value`` to access the variable's value.
 """
 
 Work_Library: Iir_Library_Declaration = c_int32.in_dll(libghdl, "libraries__work_library")
 """
-Library declaration for the work library. Note: the identifier of the work_library
-is ``work_library_name``, which may be different from 'WORK'. Use ``.value`` to
-access this variable inside libghdl.
+Library declaration for the work library.
+
+.. note:: The identifier of the work_library is ``work_library_name``, which may be different from 'WORK'.
+
+Use the property ``.value`` to access the variable's value.
 """
 
 
diff --git a/pyGHDL/libghdl/vhdl/nodes.py b/pyGHDL/libghdl/vhdl/nodes.py
index f662ad6a7..d5a8d8e80 100644
--- a/pyGHDL/libghdl/vhdl/nodes.py
+++ b/pyGHDL/libghdl/vhdl/nodes.py
@@ -29,7 +29,19 @@ from pyGHDL.libghdl._types import (
 )
 from pyGHDL.libghdl.vhdl.tokens import Tok
 
+__all__ = [
+    "Null_Iir",
+    "Null_Iir_List",
+    "Iir_List_All",
+    "Null_Iir_Flist",
+    "Iir_Flist_Others",
+    "Iir_Flist_All",
+]
+
 Null_Iir = 0
+"""
+Null element for an IIR node reference.
+"""
 
 Null_Iir_List = 0
 Iir_List_All = 1
diff --git a/pyGHDL/libghdl/vhdl/std_package.py b/pyGHDL/libghdl/vhdl/std_package.py
index f2c46385a..d9035779c 100644
--- a/pyGHDL/libghdl/vhdl/std_package.py
+++ b/pyGHDL/libghdl/vhdl/std_package.py
@@ -46,12 +46,24 @@ __all__ = ["Std_Location", "Standard_Package", "Character_Type_Definition"]
 
 
 Std_Location: LocationType = c_int32.in_dll(libghdl, "vhdl__std_package__std_location")
-"""Virtual location for the ``std.standard`` package. Use ``.value`` to access this variable inside libghdl."""
+"""
+Virtual location for the ``std.standard`` package.
+
+Use the property ``.value`` to access the variable's value.
+"""
 
 Standard_Package: Iir_Package_Declaration = c_int32.in_dll(libghdl, "vhdl__std_package__standard_package")
-"""Virtual package ``std.package``. Use ``.value`` to access this variable inside libghdl."""
+"""
+Virtual package ``std.package``.
+
+Use the property ``.value`` to access the variable's value.
+"""
 
 Character_Type_Definition: Iir_Enumeration_Type_Definition = c_int32.in_dll(
     libghdl, "vhdl__std_package__character_type_definition"
 )
-"""Predefined character. Use ``.value`` to access this variable inside libghdl."""
+"""
+Predefined character.
+
+Use the property ``.value`` to access the variable's value.
+"""
diff --git a/scripts/pnodespy.py b/scripts/pnodespy.py
index caa06b2b9..b50f9c568 100755
--- a/scripts/pnodespy.py
+++ b/scripts/pnodespy.py
@@ -210,7 +210,19 @@ def do_libghdl_nodes():
         )
         from pyGHDL.libghdl.vhdl.tokens import Tok
 
+        __all__ = [
+            "Null_Iir",
+            "Null_Iir_List",
+            "Iir_List_All",
+            "Null_Iir_Flist",
+            "Iir_Flist_Others",
+            "Iir_Flist_All",
+        ]
+
         Null_Iir = 0
+        \"\"\"
+        Null element for an IIR node reference.
+        \"\"\"
 
         Null_Iir_List = 0
         Iir_List_All = 1
diff --git a/testsuite/pyunit/dom/Sanity.py b/testsuite/pyunit/dom/Sanity.py
index 54cb4103b..4fc721d55 100644
--- a/testsuite/pyunit/dom/Sanity.py
+++ b/testsuite/pyunit/dom/Sanity.py
@@ -34,6 +34,7 @@ from pathlib import Path
 
 from pytest import mark
 
+from pyVHDLModel import VHDLVersion
 from pyGHDL.dom.NonStandard import Design, Document
 
 
@@ -55,6 +56,8 @@ def test_AllVHDLSources(parameters):
     id, file = parameters.split(":")
     filePath = _TESTSUITE_ROOT / file
 
+    vhdlVersion = VHDLVersion.AMS2017 if "ams" in file else VHDLVersion.VHDL2008
+
     lib = design.GetLibrary(f"sanity_{id}")
-    document = Document(filePath)
+    document = Document(filePath, vhdlVersion=vhdlVersion)
     design.AddDocument(document, lib)
diff --git a/testsuite/pyunit/dom/VHDLLibraries.py b/testsuite/pyunit/dom/VHDLLibraries.py
new file mode 100644
index 000000000..9de39b81b
--- /dev/null
+++ b/testsuite/pyunit/dom/VHDLLibraries.py
@@ -0,0 +1,93 @@
+# =============================================================================
+#               ____ _   _ ____  _          _
+#  _ __  _   _ / ___| | | |  _ \| |      __| | ___  _ __ ___
+# | '_ \| | | | |  _| |_| | | | | |     / _` |/ _ \| '_ ` _ \
+# | |_) | |_| | |_| |  _  | |_| | |___ | (_| | (_) | | | | | |
+# | .__/ \__, |\____|_| |_|____/|_____(_)__,_|\___/|_| |_| |_|
+# |_|    |___/
+# =============================================================================
+# Authors:
+#   Patrick Lehmann
+#   Unai Martinez-Corral
+#
+# Testsuite:        Parse files from ieee2008 directory.
+#
+# License:
+# ============================================================================
+#  Copyright (C) 2019-2022 Tristan Gingold
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 2 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <gnu.org/licenses>.
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+# ============================================================================
+from pathlib import Path
+
+from pytest import mark
+
+from pyGHDL.dom.NonStandard import Design, Document
+
+
+if __name__ == "__main__":
+    print("ERROR: you called a testcase declaration file as an executable module.")
+    print("Use: 'python -m unitest <testcase module>'")
+    exit(1)
+
+
+_GHDL_ROOT = Path(__file__).parent.parent.parent.parent.resolve()
+_LIBRARIES_ROOT = _GHDL_ROOT / "libraries"
+
+_IEEE2008_ROOT = _LIBRARIES_ROOT / "ieee2008"
+_MENTOR_ROOT = _LIBRARIES_ROOT / "mentor"
+_SYNOPSYS_ROOT = _LIBRARIES_ROOT / "synopsys"
+_VITAL_ROOT = _LIBRARIES_ROOT / "vital2000"
+
+
+design = Design()
+
+
+@mark.parametrize("file", [str(f.relative_to(_IEEE2008_ROOT)) for f in _IEEE2008_ROOT.glob("*.vhdl")])
+def test_IEEE2008(file):
+    filePath = _IEEE2008_ROOT / file
+
+    lib = design.GetLibrary("ieee2008")
+    document = Document(filePath)
+    design.AddDocument(document, lib)
+
+
+@mark.parametrize("file", [str(f.relative_to(_MENTOR_ROOT)) for f in _MENTOR_ROOT.glob("*.vhdl")])
+def test_Mentor(file):
+    filePath = _MENTOR_ROOT / file
+
+    lib = design.GetLibrary("mentor")
+    document = Document(filePath)
+    design.AddDocument(document, lib)
+
+
+@mark.parametrize("file", [str(f.relative_to(_SYNOPSYS_ROOT)) for f in _SYNOPSYS_ROOT.glob("*.vhdl")])
+def test_Synopsys(file):
+    filePath = _SYNOPSYS_ROOT / file
+
+    lib = design.GetLibrary("synopsys")
+    document = Document(filePath)
+    design.AddDocument(document, lib)
+
+
+@mark.xfail(reason="Needs further investigations.")
+@mark.parametrize("file", [str(f.relative_to(_VITAL_ROOT)) for f in _VITAL_ROOT.glob("*.vhdl")])
+def test_Synopsys(file):
+    filePath = _VITAL_ROOT / file
+
+    lib = design.GetLibrary("vital")
+    document = Document(filePath)
+    design.AddDocument(document, lib)