# =============================================================================
# ____ _ _ ____ _ _
# _ __ _ _ / ___| | | | _ \| | __| | ___ _ __ ___
# | '_ \| | | | | _| |_| | | | | | / _` |/ _ \| '_ ` _ \
# | |_) | |_| | |_| | _ | |_| | |___ | (_| | (_) | | | | | |
# | .__/ \__, |\____|_| |_|____/|_____(_)__,_|\___/|_| |_| |_|
# |_| |___/
# =============================================================================
# Authors:
# Patrick Lehmann
#
# Package module: DOM: Elements not covered by the VHDL standard.
#
# 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
# ============================================================================
"""
This module implements the non-standard classes :class:`Design`, :class:`Library` and :class:`Document`.
These three are not VHDL language constructs, but the entry points of :mod:`pyGHDL.dom`: a document reads
and parses a source file through *libghdl*, a library groups documents, and a design owns the libraries.
"""
from __future__ import annotations
import ctypes
from pathlib import Path
from typing import Any, Optional as Nullable, List
from pyTooling.Decorators import export, InheritDocString, readonly, DocStringMergeStrategy
from pyTooling.Stopwatch import Stopwatch, Duration
from pyTooling.Warning import WarningCollector
from pyVHDLModel import VHDLVersion, IEEEFlavor
from pyVHDLModel import Design as VHDLModel_Design
from pyVHDLModel import Library as VHDLModel_Library
from pyVHDLModel import Document as VHDLModel_Document
from pyGHDL.libghdl import (
ENCODING,
initialize as libghdl_initialize,
finalize as libghdl_finalize,
set_option as libghdl_set_option,
analyze_init_status as libghdl_analyze_init_status,
name_table,
files_map,
LibGHDLException,
flags,
utils,
files_map_editor,
)
from pyGHDL.libghdl.flags import Flag_Gather_Comments
from pyGHDL.libghdl.vhdl import nodes, sem_lib
from pyGHDL.libghdl.vhdl.parse import Flag_Parse_Parenthesis
from pyGHDL.dom import DOMException, Position
from pyGHDL.dom._Utils import GetIirKindOfNode, CheckForErrors, GetNameOfNode, GetDocumentationOfNode
from pyGHDL.dom.Name import SimpleName
from pyGHDL.dom.Symbol import LibraryReferenceSymbol
from pyGHDL.dom.DesignUnit import (
Entity,
Architecture,
Package,
PackageBody,
Context,
Configuration,
PackageInstantiation,
LibraryClause,
UseClause,
ContextReference,
)
from pyGHDL.dom.PSL import VerificationUnit, VerificationProperty, VerificationMode
[docs]
@export
@InheritDocString(VHDLModel_Design, strategy=DocStringMergeStrategy.BaseLast)
class Design(VHDLModel_Design):
"""
This class implements a :mod:`pyGHDL.dom` object derived from :class:`pyVHDLModel.Design`.
"""
_loadDefaultLibraryDuration: Nullable[Duration] #: :meth:`LoadDefaultLibraries`' duration, ``None`` if not called.
_analyzeDuration: Nullable[Duration] #: Duration of :meth:`Analyze`, ``None`` if not called.
_vhdlVersion: VHDLVersion #: The VHDL version this design is analyzed with.
_tabSize: int #: The number of columns between two tab stops.
_warnings: List #: Warnings raised by :mod:`pyVHDLModel` while the design is analyzed.
#: VHDL versions currently supported by this class. Older revisions (87, 93, 2000, 2002) are
#: not planned to be supported for now.
_SUPPORTED_VHDL_VERSIONS = (VHDLVersion.VHDL2008, VHDLVersion.VHDL2019)
#: Mapping from a supported VHDLVersion to GHDL's '--std=' option value.
_VHDL_VERSION_TO_STD_OPTION = {
VHDLVersion.VHDL2008: "08",
VHDLVersion.VHDL2019: "19",
}
[docs]
def __init__(self, name: str = None, vhdlVersion: VHDLVersion = VHDLVersion.VHDL2008, tabSize: int = 8) -> None:
"""
Initialize a VHDL design.
:param name: Optional, name of the design.
:param vhdlVersion: Optional, the VHDL version used to analyze this design.
:param tabSize: Optional, the number of columns between two tab stops. Default: ``8``.
:raises DOMException: If parameter 'vhdlVersion' is not supported.
:raises ValueError: If parameter 'tabSize' is None.
:raises TypeError: If parameter 'tabSize' is not of type :class:`int`.
:raises ValueError: If parameter 'tabSize' is out of range 1..120.
"""
super().__init__(name)
if vhdlVersion not in self._SUPPORTED_VHDL_VERSIONS:
supported = ", ".join(str(v) for v in self._SUPPORTED_VHDL_VERSIONS)
ex = DOMException(f"VHDL version '{vhdlVersion}' is not supported by pyGHDL.dom.")
ex.add_note(f"Supported versions: {supported}.")
raise ex
if tabSize is None:
raise ValueError("Parameter 'tabSize' is None.")
elif not isinstance(tabSize, int) or isinstance(tabSize, bool):
ex = TypeError("Parameter 'tabSize' is not of type 'int'.")
ex.add_note(f"Got type '{tabSize.__class__.__name__}'.")
raise ex
elif not 1 <= tabSize <= 120:
ex = ValueError("Parameter 'tabSize' is out of range 1..120.")
ex.add_note(f"Got value '{tabSize}'.")
raise ex
self._vhdlVersion = vhdlVersion
self._tabSize = tabSize
self._loadDefaultLibraryDuration = None
self._analyzeDuration = None
self._warnings = []
self.__ghdl_init()
@readonly
def VHDLVersion(self) -> VHDLVersion:
"""
Read-only property to access the VHDL version this design is analyzed with (:attr:`_vhdlVersion`).
The version is checked against :attr:`_SUPPORTED_VHDL_VERSIONS` when the design is created and is translated
to GHDL's ``--std=`` option value via :attr:`_VHDL_VERSION_TO_STD_OPTION`.
:returns: The design's VHDL version.
"""
return self._vhdlVersion
@readonly
def TabSize(self) -> int:
"""
Read-only property to access the number of columns between two tab stops (:attr:`_tabSize`).
*libghdl* expands tabs with it when it computes columns, like the ones of messages and of comment continuation
lines. The setting applies to *libghdl* as a whole, so to all documents loaded after this design was created.
:returns: The design's tab size.
"""
return self._tabSize
def __ghdl_init(self):
"""Initialization: set options and then load libraries."""
# Initialize libghdl
libghdl_finalize()
libghdl_initialize()
stdOption = self._VHDL_VERSION_TO_STD_OPTION[self._vhdlVersion]
libghdl_set_option(f"--std={stdOption}")
libghdl_set_option(f"-ftabstop={self._tabSize}")
Flag_Gather_Comments.value = True
Flag_Parse_Parenthesis.value = True
# Finish initialization. This will load the standard package.
if libghdl_analyze_init_status() != 0:
raise DOMException("Error initializing 'pyGHDL.dom'.") from LibGHDLException(
"Error initializing 'libghdl'."
)
[docs]
def LoadDefaultLibraries(self, flavor: Nullable[IEEEFlavor] = None):
"""
Loads the ``std`` and ``ieee`` libraries into the design.
How long this took is measured and kept in :attr:`_loadDefaultLibraryDuration`.
:param flavor: Optional, the IEEE library flavor to load, or ``None`` for the default.
"""
with Stopwatch() as stopwatch:
super().LoadStdLibrary()
super().LoadIEEELibrary(flavor)
self._loadDefaultLibraryDuration = stopwatch.Duration
[docs]
def Analyze(self):
"""
Analyzes all documents of this design.
How long this took is measured and kept in :attr:`_analyzeDuration`, and the warnings :mod:`pyVHDLModel` raises
during the analysis are collected in :attr:`_warnings`.
"""
with Stopwatch() as stopwatch, WarningCollector(self._warnings):
super().Analyze()
self._analyzeDuration = stopwatch.Duration
@readonly
def LoadDefaultLibraryDuration(self) -> Nullable[Duration]:
"""
Read-only property to access the duration of :meth:`LoadDefaultLibraries` (:attr:`_loadDefaultLibraryDuration`).
:returns: The duration of loading the ``std`` and ``ieee`` libraries, or ``None`` if they weren't loaded.
"""
return self._loadDefaultLibraryDuration
@readonly
def AnalyzeDuration(self) -> Nullable[Duration]:
"""
Read-only property to access the duration of :meth:`Analyze` (:attr:`_analyzeDuration`).
:returns: The duration of the design's analysis, or ``None`` if it wasn't analyzed.
"""
return self._analyzeDuration
[docs]
@export
@InheritDocString(VHDLModel_Library, strategy=DocStringMergeStrategy.BaseLast)
class Library(VHDLModel_Library):
"""
This class implements a :mod:`pyGHDL.dom` object derived from :class:`pyVHDLModel.Library`.
"""
pass
[docs]
@export
@InheritDocString(VHDLModel_Document, strategy=DocStringMergeStrategy.BaseLast)
class Document(VHDLModel_Document):
"""
This class implements a :mod:`pyGHDL.dom` object derived from :class:`pyVHDLModel.Document`.
"""
_filename: Path #: The source file this document was read from.
_warnings: List #: Warnings raised by :mod:`pyGHDL.dom` while this document is translated.
__ghdlFileID: Any #: *libghdl*'s name table identifier for :attr:`_filename`.
__ghdlSourceFileEntry: Any #: *libghdl*'s source file entry holding this document's source code.
__ghdlFile: Any #: The IIR design file node returned by *libghdl* when the source code was parsed.
__ghdlProcessingDuration: Nullable[Duration] #: Duration of *libghdl*'s parsing, ``None`` if it was skipped.
__domTranslationDuration: Nullable[Duration] #: Duration of the IIR to DOM translation, ``None`` if it was skipped.
[docs]
def __init__(
self,
path: Path,
sourceCode: str = None,
vhdlVersion: VHDLVersion = VHDLVersion.VHDL2008,
dontParse: bool = False,
dontTranslate: bool = False,
) -> None:
"""
Initializes a VHDL document.
:param path: Path to the document. ``None`` if in-memory document.
:param sourceCode: Optional, the source code to analyze, or ``None`` to read it from ``path``.
:param vhdlVersion: Optional, VHDL version used for analyzing this source file.
:param dontParse: Optional, ``True`` to skip parsing the source code.
:param dontTranslate: Optional, ``True`` to parse the source code, but skip translating it to the DOM.
"""
super().__init__(path, parent=None)
self._filename = path
self._warnings = []
self.__ghdlProcessingDuration = None
self.__domTranslationDuration = None
if sourceCode is None:
self.__loadFromPath()
else:
self.__loadFromString(sourceCode)
if not dontParse:
# Parse input file
with Stopwatch() as stopwatch:
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.__ghdlProcessingDuration = stopwatch.Duration
if not dontTranslate:
with Stopwatch() as stopwatch, WarningCollector(self._warnings):
self.translate()
self.__domTranslationDuration = stopwatch.Duration
def __loadFromPath(self):
"""
Reads the source file named by :attr:`_filename` and hands it to *libghdl*.
:raises DOMException: If the source file does not exist.
"""
try:
with self._filename.open("r", encoding=ENCODING) as file:
self.__loadFromString(file.read())
except FileNotFoundError as ex:
raise DOMException(f"Sourcefile '{self._filename}' not found.") from ex
def __loadFromString(self, sourceCode: str):
"""
Hands the given source code to *libghdl* under the name in :attr:`_filename`.
.. hint::
The source file itself is not read, which is how a document can be analyzed *in-memory* from a string.
:param sourceCode: The source code to analyze.
"""
sourcesBytes = sourceCode.encode(ENCODING)
sourceLength = len(sourcesBytes)
bufferLength = sourceLength + 128
dirId = name_table.Null_Identifier
self.__ghdlFileID = name_table.Get_Identifier(str(self._filename))
if files_map.Find_Source_File(dirId, self.__ghdlFileID) == files_map.No_Source_File_Entry:
self.__ghdlSourceFileEntry = files_map.Reserve_Source_File(dirId, self.__ghdlFileID, bufferLength)
files_map_editor.Fill_Text(self.__ghdlSourceFileEntry, ctypes.c_char_p(sourcesBytes), sourceLength)
CheckForErrors()
else:
raise DOMException(f"Source file '{self._filename}' already loaded.")
[docs]
def translate(self):
"""
Translates the design units of the parsed IIR tree to :mod:`pyGHDL.dom` objects.
:raises DOMException: If a design unit's kind is not handled.
:raises UnhandledExceptionError: If a construct is not supported yet and no
:class:`~pyTooling.Warning.WarningCollector` is active.
"""
self._documentation = GetDocumentationOfNode(self.__ghdlFile)
firstUnit = nodes.Get_First_Design_Unit(self.__ghdlFile)
for unit in utils.chain_iter(firstUnit):
libraryUnit = nodes.Get_Library_Unit(unit)
nodeKind = GetIirKindOfNode(libraryUnit)
contextItems = []
contextNames = []
context = nodes.Get_Context_Items(unit)
if context is not nodes.Null_Iir:
for item in utils.chain_iter(context):
itemKind = GetIirKindOfNode(item)
if itemKind is nodes.Iir_Kind.Library_Clause:
libraryIdentifier = GetNameOfNode(item)
contextNames.append(LibraryReferenceSymbol(item, SimpleName(item, libraryIdentifier)))
if nodes.Get_Has_Identifier_List(item):
continue
contextItems.append(LibraryClause(item, contextNames))
contextNames = []
elif itemKind is nodes.Iir_Kind.Use_Clause:
contextItems.append(UseClause.parse(item))
elif itemKind is nodes.Iir_Kind.Context_Reference:
contextItems.append(ContextReference.parse(item))
else:
pos = Position.parse(item)
raise DOMException(
f"Unknown context item kind '{itemKind.name}' in context at line {pos.Line}."
)
if nodeKind == nodes.Iir_Kind.Entity_Declaration:
entity = Entity.parse(libraryUnit, contextItems)
self._AddEntity(entity)
elif nodeKind == nodes.Iir_Kind.Architecture_Body:
architecture = Architecture.parse(libraryUnit, contextItems)
self._AddArchitecture(architecture)
elif nodeKind == nodes.Iir_Kind.Package_Declaration:
package = Package.parse(libraryUnit, contextItems)
self._AddPackage(package)
elif nodeKind == nodes.Iir_Kind.Package_Body:
packageBody = PackageBody.parse(libraryUnit, contextItems)
self._AddPackageBody(packageBody)
elif nodeKind == nodes.Iir_Kind.Package_Instantiation_Declaration:
package = PackageInstantiation.parse(libraryUnit, contextItems)
self._AddPackage(package)
elif nodeKind == nodes.Iir_Kind.Context_Declaration:
context = Context.parse(libraryUnit)
self._AddContext(context)
elif nodeKind == nodes.Iir_Kind.Configuration_Declaration:
configuration = Configuration.parse(libraryUnit, contextItems)
self._AddConfiguration(configuration)
elif nodeKind == nodes.Iir_Kind.Vunit_Declaration:
vunit = VerificationUnit.parse(libraryUnit)
self._AddVerificationUnit(vunit)
elif nodeKind == nodes.Iir_Kind.Vprop_Declaration:
vprop = VerificationProperty.parse(libraryUnit)
self._AddVerificationProperty(vprop)
elif nodeKind == nodes.Iir_Kind.Vmode_Declaration:
vmod = VerificationMode.parse(libraryUnit)
self._AddVerificationMode(vmod)
else:
raise DOMException(f"Unknown design unit kind '{nodeKind.name}'.")
@readonly
def LibGHDLProcessingDuration(self) -> Nullable[Duration]:
"""
Read-only property to access the duration of *libghdl*'s parsing (:attr:`__ghdlProcessingDuration`).
The duration is measured while the document is constructed, so it is set only if ``dontParse`` was ``False``.
:returns: The parse duration, or ``None`` if the document was constructed with ``dontParse=True``.
"""
return self.__ghdlProcessingDuration
@readonly
def DOMTranslationDuration(self) -> Nullable[Duration]:
"""
Read-only property to access the duration of the IIR to DOM translation (:attr:`__domTranslationDuration`).
The duration is measured while the document is constructed, so it is set only if neither ``dontParse`` nor
``dontTranslate`` was ``True``.
:returns: The translation duration, or ``None`` if the document was constructed with
``dontParse=True`` or ``dontTranslate=True``.
"""
return self.__domTranslationDuration