Skip to content

Commit 14ec13b

Browse files
PaebbelsPaebbels
authored
v0.23.0
2 parents 7a4b0e0 + cb46f1e commit 14ec13b

File tree

12 files changed

+484
-19
lines changed

12 files changed

+484
-19
lines changed

‎doc/Analyze/index.rst‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
.. _analyze:
2+
3+
Analyze
4+
#######
5+
6+
1. Dependency analysis
7+
8+
Dependency Analysis
9+
*******************
10+
11+
1. Create Dependency Graph
12+
==========================
13+
14+
Create unconnected vertices in the design's dependency graph for every VHDL library object and every design unit.
15+
16+
The vertex's ``ID`` field is set to a unique identifying string. |br|
17+
The following patterns are used:
18+
19+
Libraries
20+
The normalized library name: ``library``.
21+
Contexts
22+
The normalized library and context name: ``library.context``.
23+
Entities
24+
The normalized library and entity name: ``library.entity``.
25+
Architectures
26+
The normalized library, entity and architecture name in parenthesis: ``library.entity(architecture)``.
27+
Packages
28+
The normalized library and package name: ``library.package``.
29+
Package Bodies
30+
The normalized library and package name: ``library.package(body)``.
31+
32+
The vertex's ``Value`` field references to the library or design unit object respectively.
33+
34+
Each vertex has two attributes:
35+
36+
``"kind"``
37+
A kind attribute is set to an enumeration value of :py:class:`~pyVHDLModel.DependencyGraphVertexKind` representing
38+
vertex kind (type).
39+
``"predefined"``
40+
A predefined attribute is set to ``True``, if the library or design unit is a VHDL predefined language entity from
41+
e.g. from ``std`` or ``ieee``.
42+
43+
Lastly, every vertex is assigned to a :py:attr:``~pyVHDLModel.DesignUnit.DesignUnit._dependencyVertex`` field. Thus,
44+
there is a double reference from graph's vertex via ``Value`` to the DOM object as well as in reverse via
45+
``_dependencyVertex`` to the representing vertex.
46+
47+
.. code-block:: vhdl
48+
49+
predefinedLibraries = ("std", "ieee")
50+
51+
for libraryIdentifier, library in self._libraries.items():
52+
dependencyVertex = Vertex(vertexID=f"{libraryIdentifier}", value=library, graph=self._dependencyGraph)
53+
dependencyVertex["kind"] = DependencyGraphVertexKind.Library
54+
dependencyVertex["predefined"] = libraryIdentifier in predefinedLibraries
55+
library._dependencyVertex = dependencyVertex
56+
57+
for contextIdentifier, context in library._contexts.items():
58+
dependencyVertex = Vertex(vertexID=f"{libraryIdentifier}.{contextIdentifier}", value=context, graph=self._dependencyGraph)
59+
dependencyVertex["kind"] = DependencyGraphVertexKind.Context
60+
dependencyVertex["predefined"] = context._library._normalizedIdentifier in predefinedLibraries
61+
context._dependencyVertex = dependencyVertex
62+
63+
64+
2. Create Compile Order Graph
65+
=============================
66+
67+
3. Index Packages
68+
=================
69+
70+
4. Index Architectures
71+
======================
72+
73+
5. Link Contexts
74+
================
75+
76+
6. Link Architectures
77+
=====================
78+
79+
7. Link Package Bodies
80+
======================
81+
82+
8. Link Library References
83+
==========================
84+
85+
9. Link Package References
86+
==========================
87+
88+
10. Link Context References
89+
===========================
90+
91+
11. Link Components
92+
===================
93+
94+
12. Link Instantiations
95+
=======================
96+
97+
13. Create Hierarchy Graph
98+
==========================
99+
100+
14. Compute Compile Order
101+
=========================
102+
103+

‎doc/DataStructure/CompileOrderGraph.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _datastruct:compileorder:
2+
3+
Compile Order Graph
4+
###################

‎doc/DataStructure/DependencyGraph.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _datastruct:dependgraph:
2+
3+
Dependency Graph
4+
################

‎doc/DataStructure/HierarchyGraph.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _datastruct:dependgraph:
2+
3+
Hierarchy Graph
4+
###############

‎doc/DataStructure/index.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
.. _datastruct:
2+
3+
Data Structures
4+
###############
5+
6+
Besides the document object model as a tree-like structure, pyVHDLModel has either lists, lookup dictionaries, direct
7+
cross-references or dedicated data structure (tree, graph, …) for connecting multiple objects together.
8+
9+
Graphs
10+
******
11+
12+
pyVHDLModel uses the graph implementation from :pyTool:mod:`pyTooling.Graph` as it provides an object oriented programming
13+
interface to vertices and edges.
14+
15+
Dependency Graph
16+
================
17+
18+
The dependency graph describes dependencies between:
19+
20+
* Sourcecode files
21+
* VHDL libraries
22+
* Contexts
23+
* Packages
24+
* Entities
25+
* Architectures
26+
* Packages
27+
* Package Bodies
28+
* Configurations
29+
30+
The relation can be:
31+
32+
* Defined in source file
33+
* references
34+
* implements
35+
* instantiates
36+
* needs to be analyzed before
37+
38+
39+
Hierarchy Graph
40+
===============
41+
42+
The hierarchy graph can be derived from dependency graph by:
43+
44+
1. copying all entity and architecture vertices
45+
2. copying all implements dependency edges
46+
3. copying all instantiates edges in reverse direction
47+
48+
The graph can then be scanned for a root vertices (no inbound edges). If only a single root vertex exists, this vertex
49+
references the toplevel of the design.
50+
51+
52+
Compile Order Graph
53+
===================
54+
55+
The compile order can be derived from dependency graph by:
56+
57+
1. copying all document vertices
58+
2. iterating all edges in the dependency graph.
59+
1. resolve the source and the destination to the referenced design units
60+
2. resolved further to the documents these design units are declared in
61+
3. resolve further which vertices correspond in the compile order graph
62+
4. if edges does not yet exist, add an edge between two documents in the compile order graph
63+
64+
65+
.. toctree::
66+
:hidden:
67+
68+
DependencyGraph
69+
HierarchyGraph
70+
CompileOrderGraph

‎doc/Dependency.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ pyVHDLModel Package
2323
+--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
2424
| **Package** | **Version** | **License** | **Dependencies** |
2525
+========================================================+=============+==========================================================================================+=================================================================================================================================+
26-
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ | |
26+
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ | *None* |
2727
+--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
2828

2929

@@ -55,7 +55,7 @@ the mandatory dependencies too.
5555
+-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
5656
| `pytest-cov <https://GitHub.com/pytest-dev/pytest-cov>`__ | ≥4.0.0 | `MIT <https://GitHub.com/pytest-dev/pytest-cov/blob/master/LICENSE>`__ | *Not yet evaluated.* |
5757
+-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
58-
| `Coverage <https://GitHub.com/nedbat/coveragepy>`__ | ≥7.0 | `Apache License, 2.0 <https://GitHub.com/nedbat/coveragepy/blob/master/LICENSE.txt>`__ | *Not yet evaluated.* |
58+
| `Coverage <https://GitHub.com/nedbat/coveragepy>`__ | ≥7.1 | `Apache License, 2.0 <https://GitHub.com/nedbat/coveragepy/blob/master/LICENSE.txt>`__ | *Not yet evaluated.* |
5959
+-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
6060
| `mypy <https://GitHub.com/python/mypy>`__ | ≥0.990 | `MIT <https://GitHub.com/python/mypy/blob/master/LICENSE>`__ | *Not yet evaluated.* |
6161
+-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
@@ -123,7 +123,7 @@ install the mandatory dependencies too.
123123
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
124124
| **Package** | **Version** | **License** | **Dependencies** |
125125
+============================================================================+==============+==========================================================================================================+======================================================================================================================================================+
126-
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__ | *None* |
126+
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__ | *None* |
127127
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
128128
| `wheel <https://GitHub.com/pypa/wheel>`__ | ≥0.38.1 | `MIT <https://github.com/pypa/wheel/blob/main/LICENSE.txt>`__ | *Not yet evaluated.* |
129129
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+

0 commit comments

Comments
 (0)