xactflow 0.2.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- xactflow-0.3.0/PKG-INFO +189 -0
- xactflow-0.3.0/README.md +161 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/pyproject.toml +1 -1
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_01.py +8 -9
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_02.py +6 -3
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/__init__.py +1 -1
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/cli.py +20 -5
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/exporter.py +17 -12
- xactflow-0.3.0/src/xactflow/expressions.py +830 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/importer.py +17 -13
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/library.py +26 -7
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/link/resolver.py +27 -3
- xactflow-0.3.0/src/xactflow.egg-info/PKG-INFO +189 -0
- xactflow-0.3.0/src/xactflow.egg-info/requires.txt +5 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_cli.py +11 -5
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_exporter.py +24 -4
- xactflow-0.3.0/tests/test_expressions.py +550 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_importer.py +24 -4
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_library.py +62 -1
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_resolver.py +30 -6
- {xactflow-0.2.0 → xactflow-0.3.0}/tests/test_scr.py +42 -0
- xactflow-0.2.0/PKG-INFO +0 -243
- xactflow-0.2.0/README.md +0 -215
- xactflow-0.2.0/src/xactflow/expressions.py +0 -319
- xactflow-0.2.0/src/xactflow.egg-info/PKG-INFO +0 -243
- xactflow-0.2.0/src/xactflow.egg-info/requires.txt +0 -5
- xactflow-0.2.0/tests/test_expressions.py +0 -189
- {xactflow-0.2.0 → xactflow-0.3.0}/LICENSE +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/setup.cfg +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/__init__.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/registry.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/runner.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_03.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_04.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_05.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_06.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_07.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_08.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_09.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_10.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_11.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_12.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_13.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_14.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/SCR/scr_15.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/diagnostics.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/link/__init__.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/link/model.py +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow/py.typed +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow.egg-info/SOURCES.txt +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow.egg-info/dependency_links.txt +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow.egg-info/entry_points.txt +0 -0
- {xactflow-0.2.0 → xactflow-0.3.0}/src/xactflow.egg-info/top_level.txt +0 -0
xactflow-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xactflow
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Multi-file IP-XACT linking and semantic consistency checking on top of ipxact-compiler.
|
|
5
|
+
Author: Maxime Travaillard
|
|
6
|
+
License-Expression: LGPL-3.0-only
|
|
7
|
+
Project-URL: Repository, https://github.com/IP-XACT/XactFlow
|
|
8
|
+
Project-URL: Issues, https://github.com/IP-XACT/XactFlow/issues
|
|
9
|
+
Keywords: IP-XACT,IEEE 1685,XML,Compiler,XactFlow
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: ipxact-compiler>=0.2.0
|
|
24
|
+
Requires-Dist: lxml
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest; extra == "dev"
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# XactFlow
|
|
30
|
+
|
|
31
|
+
Multi-file [IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) IP-XACT linking and
|
|
32
|
+
checking, built on [`ipxact-compiler`](https://github.com/IP-XACT/ipxact-compiler).
|
|
33
|
+
|
|
34
|
+
`ipxact-compiler` reads one IP-XACT file into Python objects and can validate it against the
|
|
35
|
+
XSD. XactFlow works across files: it resolves a `Design` against a library of components, bus
|
|
36
|
+
definitions and abstraction definitions, and checks the result against the Semantic Consistency
|
|
37
|
+
Rules (SCRs) of the standard.
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pip install xactflow
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Requires Python 3.9 or later.
|
|
46
|
+
|
|
47
|
+
For development, `requirements-dev.txt` installs
|
|
48
|
+
`ipxact-compiler` from a sibling checkout (`../ipxact-compiler`); change the path if needed:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install -r requirements-dev.txt -e .
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Command line
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
xactflow link design.xml --lib DIR [--lib DIR ...] [--config designConfig.xml]
|
|
58
|
+
xactflow check file.xml
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `link` scans the `--lib` folders, resolves the design against them, prints the diagnostics,
|
|
62
|
+
and exits with 1 if any is an error.
|
|
63
|
+
- `check` runs the checks that need only one file, e.g. in CI or a pre-commit hook.
|
|
64
|
+
|
|
65
|
+
Each installed plugin adds its own subcommand (see [Plugins](#plugins)):
|
|
66
|
+
|
|
67
|
+
- an exporter: `xactflow <exporter> design.xml --lib DIR --output DIR`, which links the design
|
|
68
|
+
and passes the `LinkedDesign` to the exporter;
|
|
69
|
+
- an importer: `xactflow <importer> source --output DIR`, with `--then <exporter>` to pass its
|
|
70
|
+
result straight to an exporter, without an intermediate file:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
xactflow sv module.sv --option metadata=module_ipxact.json --then component --output out/
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`--option KEY=VALUE` sets a plugin option; `--then-option KEY=VALUE` sets one for the `--then`
|
|
77
|
+
exporter. If that exporter does not accept the importer's result, the command prints a one-line
|
|
78
|
+
error naming both plugins.
|
|
79
|
+
|
|
80
|
+
## Python
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import ipxact
|
|
84
|
+
from xactflow import Library, link
|
|
85
|
+
|
|
86
|
+
library = Library.scan("path/to/ip/library")
|
|
87
|
+
design = ipxact.parse_file("path/to/top_design.xml")
|
|
88
|
+
linked = link(design, library)
|
|
89
|
+
|
|
90
|
+
linked.instances # dict[str, LinkedInstance], by instance name
|
|
91
|
+
linked.interconnections # list[LinkedInterconnection], with the endpoints that resolved
|
|
92
|
+
linked.diagnostics # list[Diagnostic]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`Library` indexes documents by VLNV:
|
|
96
|
+
|
|
97
|
+
- `Library.scan(*folders)` reads every IEEE 1685-2022 file under the folders. A missing folder
|
|
98
|
+
raises an error; files of another IP-XACT version, or a folder with no 1685-2022 file, give a
|
|
99
|
+
warning in `library.diagnostics`.
|
|
100
|
+
- `library.add_file(path)` adds one file, with the same checks.
|
|
101
|
+
- `library.add(document, path=None, replace=False)` adds a document that only exists in
|
|
102
|
+
memory, e.g. an importer's result. `path` only records where it came from.
|
|
103
|
+
|
|
104
|
+
A duplicate VLNV is reported as an SCR 1.1 error, unless `replace=True`.
|
|
105
|
+
|
|
106
|
+
## Expression evaluation
|
|
107
|
+
|
|
108
|
+
IP-XACT values such as `addressOffset`, `size` or a parameter value are expressions, kept as
|
|
109
|
+
text by `ipxact-compiler`. `xactflow.evaluate()` computes them, following the expression
|
|
110
|
+
language of IEEE 1685-2022 Annex E (a subset of SystemVerilog):
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from xactflow import evaluate, parameter_resolver
|
|
114
|
+
|
|
115
|
+
evaluate("2 + 3 * 4") # 14
|
|
116
|
+
evaluate("{3{1'b1}}") # 7
|
|
117
|
+
evaluate("WIDTH - 1", resolve_parameter=lambda name: "8") # 7
|
|
118
|
+
|
|
119
|
+
resolve = parameter_resolver(component.parameters) # by parameterId
|
|
120
|
+
evaluate(register.size, resolve_parameter=resolve) # an ipxact.Expression
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
- A referenced parameter is cast to its `type` and `sign`: a `byte` with value `200` is `-56`.
|
|
124
|
+
- A value outside its `minimum`/`maximum` raises `ExpressionError`, naming the parameter, or
|
|
125
|
+
the `name=` given to `evaluate()`.
|
|
126
|
+
- Supported: integral and real values, all non-string operators (with reductions, `->`,
|
|
127
|
+
`<->`, `inside`), casts, concatenation, replication, streaming, bit and part selects,
|
|
128
|
+
`'0`/`'1`, escaped identifiers, `$clog2` and the real math functions (`$ln`, `$pow`, ...).
|
|
129
|
+
- Not supported, because `evaluate()` returns one number: strings and `$sformatf`, array
|
|
130
|
+
parameters, and the `$ipxact_*` functions, whose value depends on the design environment.
|
|
131
|
+
- Arithmetic works on plain values, without SystemVerilog's context-dependent width rules:
|
|
132
|
+
`4'hF + 4'h1` is `16`.
|
|
133
|
+
- Numbers use SystemVerilog syntax only: write `'h1F`, not `0x1F`.
|
|
134
|
+
|
|
135
|
+
## Semantic Consistency Rules (SCR)
|
|
136
|
+
|
|
137
|
+
Annex B of the standard defines 281 SCRs in 15 tables. All are registered in `xactflow.SCR`,
|
|
138
|
+
one module per table, with their id, name and text. 7 have a check today: SCR 1.2, 1.9 and
|
|
139
|
+
2.1 to 2.5. The others are placeholders that report nothing.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from xactflow import SCR
|
|
143
|
+
|
|
144
|
+
len(SCR.all_rules()) # 281
|
|
145
|
+
[r.id for r in SCR.all_rules() if r.implemented] # the 7 rules with a check
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(linked)` can be called on
|
|
149
|
+
their own, e.g. by an exporter to check the IP-XACT it writes.
|
|
150
|
+
|
|
151
|
+
## Plugins
|
|
152
|
+
|
|
153
|
+
Plugins live in their own packages and are found through
|
|
154
|
+
[entry points](https://packaging.python.org/en/latest/specifications/entry-points/):
|
|
155
|
+
|
|
156
|
+
- an `xactflow.Exporter` (group `xactflow.exporters`) writes an output from an object: RTL,
|
|
157
|
+
documentation, IP-XACT XML... Each exporter says which objects it accepts and raises
|
|
158
|
+
`TypeError` for the others.
|
|
159
|
+
- an `xactflow.Importer` (group `xactflow.importers`) reads a non-IP-XACT source and returns
|
|
160
|
+
IP-XACT objects.
|
|
161
|
+
|
|
162
|
+
```toml
|
|
163
|
+
[project.entry-points."xactflow.exporters"]
|
|
164
|
+
component = "xactflow_component:ComponentExporter"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
A plugin that fails to load is skipped with a warning; the others keep working.
|
|
168
|
+
|
|
169
|
+
| Package | Kind | Subcommand | Does |
|
|
170
|
+
|---|---|---|---|
|
|
171
|
+
| [XactFlow-sv](https://github.com/IP-XACT/XactFlow-sv) | importer | `sv` | SystemVerilog module + metadata → `ipxact.Component` |
|
|
172
|
+
| [XactFlow-archidesc](https://github.com/IP-XACT/XactFlow-archidesc) | importer | `archidesc` | architecture description → `ipxact.Design` |
|
|
173
|
+
| [XactFlow-component](https://github.com/IP-XACT/XactFlow-component) | exporter | `component` | `ipxact.Component` → component XML |
|
|
174
|
+
| [XactFlow-design](https://github.com/IP-XACT/XactFlow-design) | exporter | `design` | `ipxact.Design` → design XML |
|
|
175
|
+
|
|
176
|
+
The two exporters take an `ipxact.Component` / `ipxact.Design`, not a `LinkedDesign`: use them
|
|
177
|
+
from Python or after an importer with `--then`.
|
|
178
|
+
|
|
179
|
+
## Limitations and plans
|
|
180
|
+
|
|
181
|
+
- **274 of the 281 SCRs have no check yet.** Next: the single-file rules, and the
|
|
182
|
+
overlap/alignment rules, which can now use `evaluate()`.
|
|
183
|
+
- **Monitor and ad hoc connections are not checked.** `link()` resolves them, but a broken
|
|
184
|
+
reference is dropped without a message.
|
|
185
|
+
- **Flat-design only.** `link()` does not go into designs nested in the hierarchy.
|
|
186
|
+
|
|
187
|
+
## License
|
|
188
|
+
|
|
189
|
+
LGPL-3.0. See [LICENSE](LICENSE).
|
xactflow-0.3.0/README.md
ADDED
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# XactFlow
|
|
2
|
+
|
|
3
|
+
Multi-file [IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) IP-XACT linking and
|
|
4
|
+
checking, built on [`ipxact-compiler`](https://github.com/IP-XACT/ipxact-compiler).
|
|
5
|
+
|
|
6
|
+
`ipxact-compiler` reads one IP-XACT file into Python objects and can validate it against the
|
|
7
|
+
XSD. XactFlow works across files: it resolves a `Design` against a library of components, bus
|
|
8
|
+
definitions and abstraction definitions, and checks the result against the Semantic Consistency
|
|
9
|
+
Rules (SCRs) of the standard.
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install xactflow
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Requires Python 3.9 or later.
|
|
18
|
+
|
|
19
|
+
For development, `requirements-dev.txt` installs
|
|
20
|
+
`ipxact-compiler` from a sibling checkout (`../ipxact-compiler`); change the path if needed:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pip install -r requirements-dev.txt -e .
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Command line
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
xactflow link design.xml --lib DIR [--lib DIR ...] [--config designConfig.xml]
|
|
30
|
+
xactflow check file.xml
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `link` scans the `--lib` folders, resolves the design against them, prints the diagnostics,
|
|
34
|
+
and exits with 1 if any is an error.
|
|
35
|
+
- `check` runs the checks that need only one file, e.g. in CI or a pre-commit hook.
|
|
36
|
+
|
|
37
|
+
Each installed plugin adds its own subcommand (see [Plugins](#plugins)):
|
|
38
|
+
|
|
39
|
+
- an exporter: `xactflow <exporter> design.xml --lib DIR --output DIR`, which links the design
|
|
40
|
+
and passes the `LinkedDesign` to the exporter;
|
|
41
|
+
- an importer: `xactflow <importer> source --output DIR`, with `--then <exporter>` to pass its
|
|
42
|
+
result straight to an exporter, without an intermediate file:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
xactflow sv module.sv --option metadata=module_ipxact.json --then component --output out/
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`--option KEY=VALUE` sets a plugin option; `--then-option KEY=VALUE` sets one for the `--then`
|
|
49
|
+
exporter. If that exporter does not accept the importer's result, the command prints a one-line
|
|
50
|
+
error naming both plugins.
|
|
51
|
+
|
|
52
|
+
## Python
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import ipxact
|
|
56
|
+
from xactflow import Library, link
|
|
57
|
+
|
|
58
|
+
library = Library.scan("path/to/ip/library")
|
|
59
|
+
design = ipxact.parse_file("path/to/top_design.xml")
|
|
60
|
+
linked = link(design, library)
|
|
61
|
+
|
|
62
|
+
linked.instances # dict[str, LinkedInstance], by instance name
|
|
63
|
+
linked.interconnections # list[LinkedInterconnection], with the endpoints that resolved
|
|
64
|
+
linked.diagnostics # list[Diagnostic]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`Library` indexes documents by VLNV:
|
|
68
|
+
|
|
69
|
+
- `Library.scan(*folders)` reads every IEEE 1685-2022 file under the folders. A missing folder
|
|
70
|
+
raises an error; files of another IP-XACT version, or a folder with no 1685-2022 file, give a
|
|
71
|
+
warning in `library.diagnostics`.
|
|
72
|
+
- `library.add_file(path)` adds one file, with the same checks.
|
|
73
|
+
- `library.add(document, path=None, replace=False)` adds a document that only exists in
|
|
74
|
+
memory, e.g. an importer's result. `path` only records where it came from.
|
|
75
|
+
|
|
76
|
+
A duplicate VLNV is reported as an SCR 1.1 error, unless `replace=True`.
|
|
77
|
+
|
|
78
|
+
## Expression evaluation
|
|
79
|
+
|
|
80
|
+
IP-XACT values such as `addressOffset`, `size` or a parameter value are expressions, kept as
|
|
81
|
+
text by `ipxact-compiler`. `xactflow.evaluate()` computes them, following the expression
|
|
82
|
+
language of IEEE 1685-2022 Annex E (a subset of SystemVerilog):
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from xactflow import evaluate, parameter_resolver
|
|
86
|
+
|
|
87
|
+
evaluate("2 + 3 * 4") # 14
|
|
88
|
+
evaluate("{3{1'b1}}") # 7
|
|
89
|
+
evaluate("WIDTH - 1", resolve_parameter=lambda name: "8") # 7
|
|
90
|
+
|
|
91
|
+
resolve = parameter_resolver(component.parameters) # by parameterId
|
|
92
|
+
evaluate(register.size, resolve_parameter=resolve) # an ipxact.Expression
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
- A referenced parameter is cast to its `type` and `sign`: a `byte` with value `200` is `-56`.
|
|
96
|
+
- A value outside its `minimum`/`maximum` raises `ExpressionError`, naming the parameter, or
|
|
97
|
+
the `name=` given to `evaluate()`.
|
|
98
|
+
- Supported: integral and real values, all non-string operators (with reductions, `->`,
|
|
99
|
+
`<->`, `inside`), casts, concatenation, replication, streaming, bit and part selects,
|
|
100
|
+
`'0`/`'1`, escaped identifiers, `$clog2` and the real math functions (`$ln`, `$pow`, ...).
|
|
101
|
+
- Not supported, because `evaluate()` returns one number: strings and `$sformatf`, array
|
|
102
|
+
parameters, and the `$ipxact_*` functions, whose value depends on the design environment.
|
|
103
|
+
- Arithmetic works on plain values, without SystemVerilog's context-dependent width rules:
|
|
104
|
+
`4'hF + 4'h1` is `16`.
|
|
105
|
+
- Numbers use SystemVerilog syntax only: write `'h1F`, not `0x1F`.
|
|
106
|
+
|
|
107
|
+
## Semantic Consistency Rules (SCR)
|
|
108
|
+
|
|
109
|
+
Annex B of the standard defines 281 SCRs in 15 tables. All are registered in `xactflow.SCR`,
|
|
110
|
+
one module per table, with their id, name and text. 7 have a check today: SCR 1.2, 1.9 and
|
|
111
|
+
2.1 to 2.5. The others are placeholders that report nothing.
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from xactflow import SCR
|
|
115
|
+
|
|
116
|
+
len(SCR.all_rules()) # 281
|
|
117
|
+
[r.id for r in SCR.all_rules() if r.implemented] # the 7 rules with a check
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(linked)` can be called on
|
|
121
|
+
their own, e.g. by an exporter to check the IP-XACT it writes.
|
|
122
|
+
|
|
123
|
+
## Plugins
|
|
124
|
+
|
|
125
|
+
Plugins live in their own packages and are found through
|
|
126
|
+
[entry points](https://packaging.python.org/en/latest/specifications/entry-points/):
|
|
127
|
+
|
|
128
|
+
- an `xactflow.Exporter` (group `xactflow.exporters`) writes an output from an object: RTL,
|
|
129
|
+
documentation, IP-XACT XML... Each exporter says which objects it accepts and raises
|
|
130
|
+
`TypeError` for the others.
|
|
131
|
+
- an `xactflow.Importer` (group `xactflow.importers`) reads a non-IP-XACT source and returns
|
|
132
|
+
IP-XACT objects.
|
|
133
|
+
|
|
134
|
+
```toml
|
|
135
|
+
[project.entry-points."xactflow.exporters"]
|
|
136
|
+
component = "xactflow_component:ComponentExporter"
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
A plugin that fails to load is skipped with a warning; the others keep working.
|
|
140
|
+
|
|
141
|
+
| Package | Kind | Subcommand | Does |
|
|
142
|
+
|---|---|---|---|
|
|
143
|
+
| [XactFlow-sv](https://github.com/IP-XACT/XactFlow-sv) | importer | `sv` | SystemVerilog module + metadata → `ipxact.Component` |
|
|
144
|
+
| [XactFlow-archidesc](https://github.com/IP-XACT/XactFlow-archidesc) | importer | `archidesc` | architecture description → `ipxact.Design` |
|
|
145
|
+
| [XactFlow-component](https://github.com/IP-XACT/XactFlow-component) | exporter | `component` | `ipxact.Component` → component XML |
|
|
146
|
+
| [XactFlow-design](https://github.com/IP-XACT/XactFlow-design) | exporter | `design` | `ipxact.Design` → design XML |
|
|
147
|
+
|
|
148
|
+
The two exporters take an `ipxact.Component` / `ipxact.Design`, not a `LinkedDesign`: use them
|
|
149
|
+
from Python or after an importer with `--then`.
|
|
150
|
+
|
|
151
|
+
## Limitations and plans
|
|
152
|
+
|
|
153
|
+
- **274 of the 281 SCRs have no check yet.** Next: the single-file rules, and the
|
|
154
|
+
overlap/alignment rules, which can now use `evaluate()`.
|
|
155
|
+
- **Monitor and ad hoc connections are not checked.** `link()` resolves them, but a broken
|
|
156
|
+
reference is dropped without a message.
|
|
157
|
+
- **Flat-design only.** `link()` does not go into designs nested in the hierarchy.
|
|
158
|
+
|
|
159
|
+
## License
|
|
160
|
+
|
|
161
|
+
LGPL-3.0. See [LICENSE](LICENSE).
|
|
@@ -45,12 +45,9 @@ stub(
|
|
|
45
45
|
)
|
|
46
46
|
def _check_component_ref_is_component(linked: "LinkedDesign") -> Iterator[Diagnostic]:
|
|
47
47
|
for instance_ref in linked.design.component_instances:
|
|
48
|
-
resolved = linked.instances.get(instance_ref.instance_name)
|
|
49
|
-
# Identity, not just name presence: two componentInstance elements can share a name,
|
|
50
|
-
# linked.instances only has room for one entry per name.
|
|
51
|
-
if resolved is not None and resolved.source is instance_ref:
|
|
52
|
-
continue
|
|
53
48
|
vlnv = instance_ref.component_ref.vlnv
|
|
49
|
+
if linked.library.get_component(vlnv) is not None:
|
|
50
|
+
continue
|
|
54
51
|
existing = linked.library.get(vlnv)
|
|
55
52
|
if existing is None:
|
|
56
53
|
detail = f"no document with VLNV {vlnv} was found in the library"
|
|
@@ -81,8 +78,10 @@ def _check_component_ref_is_component(linked: "LinkedDesign") -> Iterator[Diagno
|
|
|
81
78
|
),
|
|
82
79
|
)
|
|
83
80
|
def _check_bus_interface_vlnv_refs_exist(linked: "LinkedDesign") -> Iterator[Diagnostic]:
|
|
84
|
-
|
|
85
|
-
|
|
81
|
+
# once per component, not per instance: the reference is in the component's file.
|
|
82
|
+
components = {instance.component_vlnv: instance.component for instance in linked.instances.values()}
|
|
83
|
+
for component_vlnv, component in components.items():
|
|
84
|
+
for bus_interface in component.bus_interfaces:
|
|
86
85
|
bus_vlnv = bus_interface.bus_type.vlnv
|
|
87
86
|
if linked.library.get_bus_definition(bus_vlnv) is None:
|
|
88
87
|
yield Diagnostic(
|
|
@@ -91,7 +90,7 @@ def _check_bus_interface_vlnv_refs_exist(linked: "LinkedDesign") -> Iterator[Dia
|
|
|
91
90
|
f"{bus_vlnv}, which does not resolve to a busDefinition in the library"
|
|
92
91
|
),
|
|
93
92
|
severity=Severity.ERROR,
|
|
94
|
-
location=f"{
|
|
93
|
+
location=f"{component_vlnv}/{bus_interface.name}",
|
|
95
94
|
rule_id="SCR 1.2",
|
|
96
95
|
rule_name="anyVLNVRefMustExist",
|
|
97
96
|
)
|
|
@@ -105,7 +104,7 @@ def _check_bus_interface_vlnv_refs_exist(linked: "LinkedDesign") -> Iterator[Dia
|
|
|
105
104
|
f"abstractionDefinition in the library"
|
|
106
105
|
),
|
|
107
106
|
severity=Severity.ERROR,
|
|
108
|
-
location=f"{
|
|
107
|
+
location=f"{component_vlnv}/{bus_interface.name}",
|
|
109
108
|
rule_id="SCR 1.2",
|
|
110
109
|
rule_name="anyVLNVRefMustExist",
|
|
111
110
|
)
|
|
@@ -7,7 +7,7 @@ SCR.all_rules(), with no check logic yet.
|
|
|
7
7
|
|
|
8
8
|
from __future__ import annotations
|
|
9
9
|
|
|
10
|
-
from typing import TYPE_CHECKING, Dict, Iterator,
|
|
10
|
+
from typing import TYPE_CHECKING, Dict, Iterator, Set, Tuple
|
|
11
11
|
|
|
12
12
|
import ipxact
|
|
13
13
|
|
|
@@ -69,10 +69,13 @@ def _bus_definitions_compatible(a: ipxact.VLNV, b: ipxact.VLNV, library) -> bool
|
|
|
69
69
|
),
|
|
70
70
|
)
|
|
71
71
|
def _check_active_interfaces_exist(linked: "LinkedDesign") -> Iterator[Diagnostic]:
|
|
72
|
+
design_instance_names = {instance.instance_name for instance in linked.design.component_instances}
|
|
72
73
|
for interconnection in linked.design.interconnections:
|
|
73
74
|
for active_interface in _active_interfaces(interconnection):
|
|
74
75
|
instance = linked.instances.get(active_interface.component_instance_ref)
|
|
75
76
|
if instance is None:
|
|
77
|
+
if active_interface.component_instance_ref in design_instance_names:
|
|
78
|
+
continue
|
|
76
79
|
yield Diagnostic(
|
|
77
80
|
message=(
|
|
78
81
|
f"interconnection '{interconnection.name}' activeInterface "
|
|
@@ -146,11 +149,11 @@ def _check_interconnection_bus_compat(linked: "LinkedDesign") -> Iterator[Diagno
|
|
|
146
149
|
def _check_interface_connected_once(document: object) -> Iterator[Diagnostic]:
|
|
147
150
|
if not isinstance(document, ipxact.Design):
|
|
148
151
|
return
|
|
149
|
-
seen: Dict[Tuple[str, str],
|
|
152
|
+
seen: Dict[Tuple[str, str], Dict[str, None]] = {}
|
|
150
153
|
for interconnection in document.interconnections:
|
|
151
154
|
for active_interface in _active_interfaces(interconnection):
|
|
152
155
|
key = (active_interface.component_instance_ref, active_interface.bus_ref)
|
|
153
|
-
seen.setdefault(key, [
|
|
156
|
+
seen.setdefault(key, {})[interconnection.name] = None
|
|
154
157
|
for (instance_ref, bus_ref), interconnection_names in seen.items():
|
|
155
158
|
if len(interconnection_names) > 1:
|
|
156
159
|
yield Diagnostic(
|
|
@@ -2,6 +2,7 @@ from __future__ import annotations
|
|
|
2
2
|
|
|
3
3
|
import argparse
|
|
4
4
|
import sys
|
|
5
|
+
import warnings
|
|
5
6
|
from pathlib import Path
|
|
6
7
|
from typing import Dict, List, Optional, Sequence, Tuple, Type
|
|
7
8
|
|
|
@@ -167,9 +168,17 @@ def _add_exporter_subparser(
|
|
|
167
168
|
) -> None:
|
|
168
169
|
parser = subparsers.add_parser(name, help=f"link a design and run the '{name}' exporter on it")
|
|
169
170
|
parser.add_argument("design", help="path to the top-level design XML file")
|
|
170
|
-
parser.add_argument(
|
|
171
|
-
|
|
172
|
-
|
|
171
|
+
parser.add_argument(
|
|
172
|
+
"--lib",
|
|
173
|
+
action="append",
|
|
174
|
+
default=[],
|
|
175
|
+
metavar="DIR",
|
|
176
|
+
help="directory to scan for IP-XACT files; may be given multiple times",
|
|
177
|
+
)
|
|
178
|
+
parser.add_argument(
|
|
179
|
+
"--config", default=None, metavar="FILE", help="path to the matching designConfiguration XML file"
|
|
180
|
+
)
|
|
181
|
+
parser.add_argument("--output", default=".", metavar="DIR", help="output directory for the exporter")
|
|
173
182
|
parser.add_argument(
|
|
174
183
|
"--option", action="append", type=_parse_option, metavar="KEY=VALUE",
|
|
175
184
|
help="an exporter-specific option, may be given multiple times",
|
|
@@ -224,9 +233,15 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
224
233
|
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
225
234
|
_add_builtin_subparsers(subparsers)
|
|
226
235
|
|
|
236
|
+
with warnings.catch_warnings(record=True) as discovery_warnings:
|
|
237
|
+
exporters = discover_exporters()
|
|
238
|
+
importers = discover_importers()
|
|
239
|
+
for warning in discovery_warnings:
|
|
240
|
+
print(f"warning: {warning.message}", file=sys.stderr)
|
|
241
|
+
|
|
227
242
|
registered_names = set(_BUILTIN_COMMANDS)
|
|
228
243
|
registered_exporters: Dict[str, Type[Exporter]] = {}
|
|
229
|
-
for name, exporter_class in sorted(
|
|
244
|
+
for name, exporter_class in sorted(exporters.items()):
|
|
230
245
|
if name in registered_names:
|
|
231
246
|
print(
|
|
232
247
|
f"warning: exporter '{name}' conflicts with an existing xactflow subcommand, skipping",
|
|
@@ -237,7 +252,7 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
237
252
|
registered_names.add(name)
|
|
238
253
|
registered_exporters[name] = exporter_class
|
|
239
254
|
|
|
240
|
-
for name, importer_class in sorted(
|
|
255
|
+
for name, importer_class in sorted(importers.items()):
|
|
241
256
|
if name in registered_names:
|
|
242
257
|
print(
|
|
243
258
|
f"warning: importer '{name}' conflicts with an existing xactflow subcommand, skipping",
|
|
@@ -2,6 +2,7 @@ from __future__ import annotations
|
|
|
2
2
|
|
|
3
3
|
import abc
|
|
4
4
|
import sys
|
|
5
|
+
import warnings
|
|
5
6
|
from importlib.metadata import entry_points
|
|
6
7
|
from pathlib import Path
|
|
7
8
|
from typing import Dict, Type
|
|
@@ -46,25 +47,29 @@ def _entry_points_for_group(group: str):
|
|
|
46
47
|
|
|
47
48
|
|
|
48
49
|
def discover_exporters() -> Dict[str, Type[Exporter]]:
|
|
49
|
-
"""Find every Exporter subclass registered
|
|
50
|
-
|
|
51
|
-
Third-party packages register under the "xactflow.exporters" entry point group, e.g. in
|
|
52
|
-
their own pyproject.toml:
|
|
50
|
+
"""Find every Exporter subclass registered under the "xactflow.exporters" entry point group:
|
|
53
51
|
|
|
54
52
|
[project.entry-points."xactflow.exporters"]
|
|
55
|
-
|
|
53
|
+
component = "xactflow_component:ComponentExporter"
|
|
56
54
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
caller (e.g. the CLI) asks the user for.
|
|
55
|
+
Keyed by entry point name (e.g. "component"), the name the CLI uses, not by Exporter.name.
|
|
56
|
+
An entry point that fails to load, or is not an Exporter subclass, is skipped with a warning.
|
|
60
57
|
"""
|
|
61
58
|
exporters: Dict[str, Type[Exporter]] = {}
|
|
62
59
|
for entry_point in _entry_points_for_group(_ENTRY_POINT_GROUP):
|
|
63
|
-
|
|
60
|
+
try:
|
|
61
|
+
exporter_class = entry_point.load()
|
|
62
|
+
except Exception as exc:
|
|
63
|
+
warnings.warn(
|
|
64
|
+
f"skipping entry point '{entry_point.name}' in group '{_ENTRY_POINT_GROUP}': "
|
|
65
|
+
f"failed to load: {exc}"
|
|
66
|
+
)
|
|
67
|
+
continue
|
|
64
68
|
if not (isinstance(exporter_class, type) and issubclass(exporter_class, Exporter)):
|
|
65
|
-
|
|
66
|
-
f"entry point '{entry_point.name}' in group '{_ENTRY_POINT_GROUP}'
|
|
67
|
-
f"resolve to an Exporter subclass: {exporter_class!r}"
|
|
69
|
+
warnings.warn(
|
|
70
|
+
f"skipping entry point '{entry_point.name}' in group '{_ENTRY_POINT_GROUP}': "
|
|
71
|
+
f"does not resolve to an Exporter subclass: {exporter_class!r}"
|
|
68
72
|
)
|
|
73
|
+
continue
|
|
69
74
|
exporters[entry_point.name] = exporter_class
|
|
70
75
|
return exporters
|