Coverage for pyVHDLModel/Configuration.py: 100%
95 statements
« prev ^ index » next coverage.py v7.16.0, created at 2026-09-11 23:50 +0000
1# ==================================================================================================================== #
2# __ ___ _ ____ _ __ __ _ _ #
3# _ __ _ \ \ / / | | | _ \| | | \/ | ___ __| | ___| | #
4# | '_ \| | | \ \ / /| |_| | | | | | | |\/| |/ _ \ / _` |/ _ \ | #
5# | |_) | |_| |\ V / | _ | |_| | |___| | | | (_) | (_| | __/ | #
6# | .__/ \__, | \_/ |_| |_|____/|_____|_| |_|\___/ \__,_|\___|_| #
7# |_| |___/ #
8# ==================================================================================================================== #
9# Authors: #
10# Patrick Lehmann #
11# #
12# License: #
13# ==================================================================================================================== #
14# Copyright 2026-2026 Patrick Lehmann - Boetzingen, Germany #
15# #
16# Licensed under the Apache License, Version 2.0 (the "License"); #
17# you may not use this file except in compliance with the License. #
18# You may obtain a copy of the License at #
19# #
20# http://www.apache.org/licenses/LICENSE-2.0 #
21# #
22# Unless required by applicable law or agreed to in writing, software #
23# distributed under the License is distributed on an "AS IS" BASIS, #
24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
25# See the License for the specific language governing permissions and #
26# limitations under the License. #
27# #
28# SPDX-License-Identifier: Apache-2.0 #
29# ==================================================================================================================== #
30#
31"""
32This module contains parts of an abstract document language model for VHDL.
34Configurations: entity aspects, binding indications, component configurations (and the structurally
35identical configuration specifications), and block configurations.
36"""
37from typing import List, Iterable, Union, Optional as Nullable
39from pyTooling.Decorators import export, readonly
40from pyTooling.MetaClasses import ExtendedType
42from pyVHDLModel.Base import ModelEntity
43from pyVHDLModel.Name import Name
44from pyVHDLModel.Symbol import Symbol, EntitySymbol, ArchitectureSymbol, ConfigurationSymbol
45from pyVHDLModel.Symbol import ComponentInstantiationSymbol
46from pyVHDLModel.Association import GenericAssociationItem, PortAssociationItem
47from pyVHDLModel.Association import GenericMapAspectMixin, PortMapAspectMixin
50@export
51class EntityAspect(ModelEntity):
52 """
53 Base-class for the three forms an entity aspect can take in a binding indication: an entity
54 (optionally with an architecture), a configuration, or ``open``.
56 .. admonition:: Example
58 .. code-block:: VHDL
60 for U1 : comp use entity work.sub(behav);
61 -- ^^^^^^^^^^^^^^^^^^^^^^
63 .. seealso::
65 * :class:`Entity aspect entity <pyVHDLModel.Configuration.EntityAspectEntity>`
66 * :class:`Entity aspect configuration <pyVHDLModel.Configuration.EntityAspectConfiguration>`
67 * :class:`Entity aspect open <pyVHDLModel.Configuration.EntityAspectOpen>`
68 """
71@export
72class EntityAspectEntity(EntityAspect):
73 """
74 Represents an entity aspect naming an entity, optionally with an architecture.
76 .. admonition:: Example
78 .. code-block:: VHDL
80 use entity work.e_rest(rtl);
81 -- ^^^^^^^^^^^ <- Entity
82 -- ^^^ <- Architecture
83 """
85 _entity: EntitySymbol #: Reference to the named entity.
86 _architecture: Nullable[ArchitectureSymbol] #: Reference to the selected architecture, or ``None`` if none was given.
88 def __init__(
89 self,
90 entity: EntitySymbol,
91 architecture: Nullable[ArchitectureSymbol] = None,
92 parent: Nullable[ModelEntity] = None
93 ) -> None:
94 """
95 Initializes an entity aspect naming an entity, optionally with an architecture.
97 :param entity: Reference to the named entity.
98 :param architecture: Reference to the selected architecture, or ``None`` if none was given.
99 :param parent: The parent model entity of this entity.
100 """
101 super().__init__(parent)
103 self._entity = entity
104 entity.Parent = self
106 self._architecture = architecture
107 if architecture is not None:
108 architecture.Parent = self
110 @readonly
111 def Entity(self) -> EntitySymbol:
112 """
113 Read-only property to access the entity (:attr:`_entity`).
115 :returns: The entity.
116 """
117 return self._entity
119 @readonly
120 def Architecture(self) -> Nullable[ArchitectureSymbol]:
121 """
122 Read-only property to access the architecture (:attr:`_architecture`).
124 :returns: The architecture, or ``None`` if not set.
125 """
126 return self._architecture
129@export
130class EntityAspectConfiguration(EntityAspect):
131 """
132 Represents an entity aspect naming a configuration.
134 .. admonition:: Example
136 .. code-block:: VHDL
138 use configuration work.cfg;
139 -- ^^^^^^^^ <- Configuration
140 """
142 _configuration: ConfigurationSymbol #: Reference to the named configuration.
144 def __init__(self, configuration: ConfigurationSymbol, parent: Nullable[ModelEntity] = None) -> None:
145 """
146 Initializes an entity aspect naming a configuration.
148 :param configuration: Reference to the named configuration.
149 :param parent: The parent model entity of this entity.
150 """
151 super().__init__(parent)
153 self._configuration = configuration
154 configuration.Parent = self
156 @readonly
157 def Configuration(self) -> ConfigurationSymbol:
158 """
159 Read-only property to access the configuration (:attr:`_configuration`).
161 :returns: The configuration.
162 """
163 return self._configuration
166@export
167class EntityAspectOpen(EntityAspect):
168 """
169 Represents an open entity aspect, leaving the binding unspecified.
171 .. admonition:: Example
173 .. code-block:: VHDL
175 use open;
176 -- ^^^^ <- the aspect
177 """
180@export
181class BindingIndication(ModelEntity, GenericMapAspectMixin, PortMapAspectMixin):
182 """
183 Represents a binding indication: which design entity a component is bound to.
185 The entity aspect is available as :data:`EntityAspect`, together with the generic and port maps
186 (:data:`GenericAssociations`, :data:`PortAssociations`).
187 """
189 _entityAspect: Nullable[EntityAspect] #: The bound design entity, or ``None`` if not given.
191 def __init__(
192 self,
193 entityAspect: Nullable[EntityAspect] = None,
194 genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None,
195 portAssociationItems: Nullable[Iterable[PortAssociationItem]] = None,
196 parent: Nullable[ModelEntity] = None
197 ) -> None:
198 """
199 Initializes a binding indication.
201 :param entityAspect: The bound design entity, or ``None`` if not given.
202 :param genericAssociationItems: List of all generic associations in the generic map aspect.
203 :param portAssociationItems: List of all port associations in the port map aspect.
204 :param parent: The parent model entity of this entity.
205 """
206 super().__init__(parent)
207 GenericMapAspectMixin.__init__(self, genericAssociationItems)
208 PortMapAspectMixin.__init__(self, portAssociationItems)
210 self._entityAspect = entityAspect
211 if entityAspect is not None:
212 entityAspect.Parent = self
214 @readonly
215 def EntityAspect(self) -> Nullable[EntityAspect]:
216 """
217 Read-only property to access the entity aspect (:attr:`_entityAspect`).
219 :returns: The entity aspect, or ``None`` if not set.
220 """
221 return self._entityAspect
226@export
227class AllInstantiationList(ModelEntity):
228 """
229 Represents an instantiation list naming ``all`` instances of a component.
231 .. admonition:: Example
233 .. code-block:: VHDL
235 for all : comp use entity work.sub(behav);
236 -- ^^^ <- the instantiation list
237 """
240@export
241class OthersInstantiationList(ModelEntity):
242 """
243 Represents an instantiation list naming all instances not configured elsewhere.
245 .. admonition:: Example
247 .. code-block:: VHDL
249 for others : comp use entity work.sub(behav);
250 -- ^^^^^^ <- the instantiation list
251 """
254InstantiationListUnion = Union[List[Name], AllInstantiationList, OthersInstantiationList]
257@export
258class ComponentConfiguration(ModelEntity):
259 """
260 Represents a component configuration (inside a block configuration), or - structurally identical
261 - a configuration specification (declared directly in an architecture's declarative part).
263 .. admonition:: Example
265 .. code-block:: VHDL
267 for U1 : comp use entity work.sub(behav);
268 -- ^^ ^^^^
269 -- | Component name
270 -- Instantiation list
271 """
273 _instantiationList: InstantiationListUnion #: The instances this configuration applies to.
274 _componentName: ComponentInstantiationSymbol #: Reference to the component being configured.
275 _bindingIndication: Nullable[BindingIndication] #: The binding indication, or ``None`` if none was given.
277 def __init__(
278 self,
279 instantiationList: InstantiationListUnion,
280 componentName: ComponentInstantiationSymbol,
281 bindingIndication: Nullable[BindingIndication] = None,
282 parent: Nullable[ModelEntity] = None
283 ) -> None:
284 """
285 Initializes a component configuration.
287 :param instantiationList: The instances this configuration applies to.
288 :param componentName: Reference to the component being configured.
289 :param bindingIndication: The binding indication, or ``None`` if none was given.
290 :param parent: The parent model entity of this entity.
291 """
292 super().__init__(parent)
294 if isinstance(instantiationList, (AllInstantiationList, OthersInstantiationList)):
295 self._instantiationList = instantiationList
296 instantiationList.Parent = self
297 else:
298 self._instantiationList = [label for label in instantiationList]
299 for label in self._instantiationList:
300 label.Parent = self
302 self._componentName = componentName
303 componentName.Parent = self
305 self._bindingIndication = bindingIndication
306 if bindingIndication is not None:
307 bindingIndication.Parent = self
309 @readonly
310 def InstantiationList(self) -> InstantiationListUnion:
311 """
312 Read-only property to access the instantiation list (:attr:`_instantiationList`).
314 :returns: The instantiation list.
315 """
316 return self._instantiationList
318 @readonly
319 def ComponentName(self) -> ComponentInstantiationSymbol:
320 """
321 Read-only property to access the component name (:attr:`_componentName`).
323 :returns: The component name.
324 """
325 return self._componentName
327 @readonly
328 def BindingIndication(self) -> Nullable[BindingIndication]:
329 """
330 Read-only property to access the binding indication (:attr:`_bindingIndication`).
332 :returns: The binding indication, or ``None`` if not set.
333 """
334 return self._bindingIndication
337@export
338class BlockConfiguration(ModelEntity):
339 """
340 Represents the configuration of one block: an architecture, a block statement or a generate body.
342 Nested configurations are available as :data:`ConfigurationItems`.
344 .. admonition:: Example
346 .. code-block:: VHDL
348 for rtl
349 -- ^^^ <- Block
350 end for;
351 """
353 _blockSpecification: Symbol #: The configured block.
354 _items: List[Union["BlockConfiguration", ComponentConfiguration]] #: Nested configurations.
356 def __init__(
357 self,
358 blockSpecification: Symbol,
359 items: Nullable[Iterable[Union["BlockConfiguration", ComponentConfiguration]]] = None,
360 parent: Nullable[ModelEntity] = None
361 ) -> None:
362 """
363 Initializes a block configuration.
365 :param blockSpecification: The configured block.
366 :param items: Nested configurations.
367 :param parent: The parent model entity of this entity.
368 """
369 super().__init__(parent)
371 self._blockSpecification = blockSpecification
372 blockSpecification.Parent = self
374 self._items = []
375 if items is not None:
376 for item in items:
377 self._items.append(item)
378 item.Parent = self
380 @readonly
381 def BlockSpecification(self) -> Symbol:
382 """
383 Read-only property to access the block specification (:attr:`_blockSpecification`).
385 :returns: The block specification.
386 """
387 return self._blockSpecification
389 @readonly
390 def Items(self) -> List[Union["BlockConfiguration", ComponentConfiguration]]:
391 """
392 Read-only property to access the items (:attr:`_items`).
394 :returns: List of items.
395 """
396 return self._items