xactflow 0.2.0__tar.gz → 0.4.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.4.0/PKG-INFO +242 -0
- xactflow-0.4.0/README.md +214 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/pyproject.toml +1 -1
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/runner.py +5 -2
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_01.py +81 -44
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_02.py +221 -87
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_03.py +29 -27
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_05.py +22 -19
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_06.py +122 -101
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_07.py +46 -28
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_08.py +6 -4
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_09.py +7 -7
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_10.py +1 -1
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_11.py +3 -3
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_12.py +2 -2
- xactflow-0.4.0/src/xactflow/SCR/scr_13.py +110 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_14.py +18 -18
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_15.py +1 -1
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/__init__.py +5 -1
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/cli.py +106 -39
- xactflow-0.4.0/src/xactflow/exporter.py +75 -0
- xactflow-0.4.0/src/xactflow/expressions.py +830 -0
- xactflow-0.4.0/src/xactflow/importer.py +72 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/library.py +61 -15
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/link/__init__.py +4 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/link/model.py +30 -10
- xactflow-0.4.0/src/xactflow/link/resolver.py +311 -0
- xactflow-0.4.0/src/xactflow.egg-info/PKG-INFO +242 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/SOURCES.txt +1 -0
- xactflow-0.4.0/src/xactflow.egg-info/requires.txt +5 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_cli.py +117 -75
- xactflow-0.4.0/tests/test_exporter.py +100 -0
- xactflow-0.4.0/tests/test_expressions.py +550 -0
- xactflow-0.4.0/tests/test_hierarchy.py +379 -0
- xactflow-0.4.0/tests/test_importer.py +94 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_library.py +112 -1
- {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_resolver.py +33 -9
- {xactflow-0.2.0 → xactflow-0.4.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/SCR/scr_13.py +0 -54
- xactflow-0.2.0/src/xactflow/exporter.py +0 -70
- xactflow-0.2.0/src/xactflow/expressions.py +0 -319
- xactflow-0.2.0/src/xactflow/importer.py +0 -60
- xactflow-0.2.0/src/xactflow/link/resolver.py +0 -164
- 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_exporter.py +0 -91
- xactflow-0.2.0/tests/test_expressions.py +0 -189
- xactflow-0.2.0/tests/test_importer.py +0 -75
- {xactflow-0.2.0 → xactflow-0.4.0}/LICENSE +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/setup.cfg +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/__init__.py +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/registry.py +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_04.py +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/diagnostics.py +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/py.typed +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/dependency_links.txt +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/entry_points.txt +0 -0
- {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/top_level.txt +0 -0
xactflow-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xactflow
|
|
3
|
+
Version: 0.4.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. This README follows `main`: the plugin API it describes is newer
|
|
46
|
+
than the 0.3.0 release (see [Plugins](#plugins)).
|
|
47
|
+
|
|
48
|
+
For development, `requirements-dev.txt` installs `ipxact-compiler` from a sibling checkout
|
|
49
|
+
(`../ipxact-compiler`); change the path if needed:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install -r requirements-dev.txt -e .
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Command line
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
xactflow link design.xml --lib DIR [--lib DIR ...] [--config designConfig.xml]
|
|
59
|
+
xactflow check file.xml
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- `link` scans the `--lib` folders, resolves the design against them, prints the diagnostics,
|
|
63
|
+
and exits with 1 if any is an error.
|
|
64
|
+
- `check` runs the checks that need only one file, without a library.
|
|
65
|
+
|
|
66
|
+
Each installed plugin adds its own subcommand (see [Plugins](#plugins)). Both kinds work on one
|
|
67
|
+
`Library`, scanned from the `--lib` folders:
|
|
68
|
+
|
|
69
|
+
- an exporter: `xactflow <exporter> file.xml --lib DIR [--config FILE] --output DIR` adds
|
|
70
|
+
`file.xml` to the library as the target to export, links it first if it is a design, and
|
|
71
|
+
passes the library to the exporter;
|
|
72
|
+
- an importer: `xactflow <importer> source --lib DIR` adds what it reads to the library, with
|
|
73
|
+
`--then <exporter>` to pass that same library straight to an exporter, without an
|
|
74
|
+
intermediate file:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
xactflow sv module.sv --option metadata=module_ipxact.json --then component --output out/
|
|
78
|
+
xactflow archidesc soc.py --lib ip/ --lib bus_definitions/ --then topgen --output out/
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`--option KEY=VALUE` sets a plugin option; `--then-option KEY=VALUE` sets one for the `--then`
|
|
82
|
+
exporter. If that exporter supports none of the importer's documents, the command prints a
|
|
83
|
+
one-line error naming both plugins.
|
|
84
|
+
|
|
85
|
+
## Python
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import ipxact
|
|
89
|
+
from xactflow import Library, link
|
|
90
|
+
|
|
91
|
+
library = Library.scan("path/to/ip/library")
|
|
92
|
+
design = ipxact.parse_file("path/to/top_design.xml")
|
|
93
|
+
linked = link(design, library) # optional: design_configuration=..., component=...
|
|
94
|
+
|
|
95
|
+
linked.instances # dict[str, LinkedInstance], by instance name
|
|
96
|
+
linked.interconnections # list[LinkedInterconnection], with the interfaces that resolved
|
|
97
|
+
linked.component # the component containing the design, or None
|
|
98
|
+
linked.diagnostics # list[Diagnostic]
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
A design's `hierInterface` and `externalPortReference` elements refer to the bus interfaces and
|
|
102
|
+
ports of the component containing it. `link()` uses the component given with `component=`, or
|
|
103
|
+
else the one component of the library with a view instantiating the design. With none, or
|
|
104
|
+
several, these references are not checked, and a warning says so.
|
|
105
|
+
|
|
106
|
+
Each `Diagnostic` has a `message`, a `severity` (`Severity.ERROR` or `Severity.WARNING`), a
|
|
107
|
+
`location` (a VLNV, a file, or a path such as `vendor:lib:top:1.0/conn0`), and, when it is an
|
|
108
|
+
Annex B rule, its `rule_id` and `rule_name`. `str(diagnostic)` gives the line the CLI prints:
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
error: [SCR 2.4] interconnection 'conn0' connects ... (example.org:soc:top:1.0/conn0)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`Library` indexes documents by VLNV:
|
|
115
|
+
|
|
116
|
+
- `Library.scan(*folders)` reads every IEEE 1685-2022 file under the folders. A missing folder
|
|
117
|
+
raises an error; files of another IP-XACT version, or a folder with no 1685-2022 file, give a
|
|
118
|
+
warning in `library.diagnostics`.
|
|
119
|
+
- `library.add_file(path)` adds one file, with the same checks.
|
|
120
|
+
- `library.add(document, path=None, replace=False, target=False)` adds a document that only
|
|
121
|
+
exists in memory, e.g. an importer's result. `path` only records where it came from.
|
|
122
|
+
- `library.documents(kind=None)` returns every document, or those of one type, e.g.
|
|
123
|
+
`library.documents(ipxact.Component)`.
|
|
124
|
+
- `library.targets(kind=None)` returns only the documents added with `target=True`: the ones
|
|
125
|
+
an exporter writes, as opposed to those it only looks up.
|
|
126
|
+
- `library.get(vlnv)` returns the document with that VLNV, or None; `get_component`,
|
|
127
|
+
`get_design`, `get_bus_definition`, `get_abstraction_definition` and
|
|
128
|
+
`get_design_configuration` also return None for a document of another type.
|
|
129
|
+
|
|
130
|
+
A duplicate VLNV is reported as an SCR 1.1 error, unless `replace=True`.
|
|
131
|
+
|
|
132
|
+
## Expression evaluation
|
|
133
|
+
|
|
134
|
+
IP-XACT values such as `addressOffset`, `size` or a parameter value are expressions, kept as
|
|
135
|
+
text by `ipxact-compiler`. `xactflow.evaluate()` computes them, following the expression
|
|
136
|
+
language of IEEE 1685-2022 Annex E (a subset of SystemVerilog):
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from xactflow import evaluate, parameter_resolver
|
|
140
|
+
|
|
141
|
+
evaluate("2 + 3 * 4") # 14
|
|
142
|
+
evaluate("{3{1'b1}}") # 7
|
|
143
|
+
evaluate("WIDTH - 1", resolve_parameter=lambda name: "8") # 7
|
|
144
|
+
|
|
145
|
+
resolve = parameter_resolver(component.parameters) # by parameterId
|
|
146
|
+
evaluate(register.size, resolve_parameter=resolve) # an ipxact.Expression
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- A referenced parameter is cast to its `type` and `sign`: a `byte` with value `200` is `-56`.
|
|
150
|
+
- A value outside its `minimum`/`maximum` raises `ExpressionError`, naming the parameter, or
|
|
151
|
+
the `name=` given to `evaluate()`.
|
|
152
|
+
- Supported: integral and real values, all non-string operators (with reductions, `->`,
|
|
153
|
+
`<->`, `inside`), casts, concatenation, replication, streaming, bit and part selects,
|
|
154
|
+
`'0`/`'1`, escaped identifiers, `$clog2` and the real math functions (`$ln`, `$pow`, ...).
|
|
155
|
+
- Not supported, because `evaluate()` returns one number: strings and `$sformatf`, array
|
|
156
|
+
parameters, and the `$ipxact_*` functions, whose value depends on the design environment.
|
|
157
|
+
- Arithmetic works on plain values, without SystemVerilog's context-dependent width rules:
|
|
158
|
+
`4'hF + 4'h1` is `16`.
|
|
159
|
+
- Numbers use SystemVerilog syntax only: write `'h1F`, not `0x1F`.
|
|
160
|
+
|
|
161
|
+
## Semantic Consistency Rules (SCR)
|
|
162
|
+
|
|
163
|
+
Annex B of the standard defines 281 SCRs in 15 tables. All are registered in `xactflow.SCR`,
|
|
164
|
+
one module per table, with their id, name and text as written in the standard (without its
|
|
165
|
+
"See also" references). 15 have a check today: SCR 1.2, 1.5, 1.9, 2.1 to 2.10, 2.17 and 13.5.
|
|
166
|
+
The others are placeholders that report nothing.
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from xactflow import SCR
|
|
170
|
+
|
|
171
|
+
len(SCR.all_rules()) # 281
|
|
172
|
+
[r.id for r in SCR.all_rules() if r.implemented] # the 15 rules with a check
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(linked)` can be called on
|
|
176
|
+
their own, e.g. by an exporter to check the IP-XACT it writes.
|
|
177
|
+
|
|
178
|
+
## Plugins
|
|
179
|
+
|
|
180
|
+
Plugins live in their own packages and are found through
|
|
181
|
+
[entry points](https://packaging.python.org/en/latest/specifications/entry-points/):
|
|
182
|
+
|
|
183
|
+
- an `xactflow.Importer` (group `xactflow.importers`) reads a non-IP-XACT source and adds
|
|
184
|
+
the IP-XACT documents it describes to a `Library`, with `target=True`.
|
|
185
|
+
- an `xactflow.Exporter` (group `xactflow.exporters`) writes an output from the targets of a
|
|
186
|
+
`Library`: RTL, documentation, IP-XACT XML... It looks up anything else it needs in the
|
|
187
|
+
library, e.g. with `link(design, library)`. Each exporter says which targets it supports and
|
|
188
|
+
raises `TypeError` when the library has none.
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
class MyImporter(Importer):
|
|
192
|
+
name = "mine"
|
|
193
|
+
|
|
194
|
+
def import_(self, source_path, library, **options):
|
|
195
|
+
library.add(build_component(source_path), target=True)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class MyExporter(Exporter):
|
|
199
|
+
name = "mine"
|
|
200
|
+
|
|
201
|
+
def export(self, library, output_dir, **options):
|
|
202
|
+
designs = list(library.targets(ipxact.Design))
|
|
203
|
+
if not designs:
|
|
204
|
+
raise TypeError("'mine' needs an ipxact.Design target")
|
|
205
|
+
for design in designs:
|
|
206
|
+
write_rtl(link(design, library), output_dir)
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
```toml
|
|
210
|
+
[project.entry-points."xactflow.importers"]
|
|
211
|
+
sv = "xactflow_sv:SVImporter"
|
|
212
|
+
|
|
213
|
+
[project.entry-points."xactflow.exporters"]
|
|
214
|
+
component = "xactflow_component:ComponentExporter"
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The entry point name is the subcommand.
|
|
218
|
+
|
|
219
|
+
A plugin that fails to load is skipped with a warning; the others keep working.
|
|
220
|
+
|
|
221
|
+
| Package | Kind | Subcommand | Does |
|
|
222
|
+
|---|---|---|---|
|
|
223
|
+
| [XactFlow-sv](https://github.com/IP-XACT/XactFlow-sv) | importer | `sv` | SystemVerilog module + metadata → `ipxact.Component` |
|
|
224
|
+
| [XactFlow-archidesc](https://github.com/IP-XACT/XactFlow-archidesc) | importer | `archidesc` | architecture description → `ipxact.Design` |
|
|
225
|
+
| [XactFlow-component](https://github.com/IP-XACT/XactFlow-component) | exporter | `component` | `ipxact.Component` → component XML |
|
|
226
|
+
| [XactFlow-design](https://github.com/IP-XACT/XactFlow-design) | exporter | `design` | `ipxact.Design` → design XML |
|
|
227
|
+
|
|
228
|
+
The plugins above were written for the previous API, where `import_` returned an object and
|
|
229
|
+
`export` took one; they need a release for this one.
|
|
230
|
+
|
|
231
|
+
## Limitations and plans
|
|
232
|
+
|
|
233
|
+
- **266 of the 281 SCRs have no check yet.** Next: the single-file rules, and the
|
|
234
|
+
overlap/alignment rules, which can now use `evaluate()`.
|
|
235
|
+
- **Monitor connections are not checked.** `link()` resolves them, but a broken reference is
|
|
236
|
+
dropped without a message.
|
|
237
|
+
- **One level of hierarchy.** `link()` checks a design against its instances and the
|
|
238
|
+
component containing it, but does not go into the designs of its instances.
|
|
239
|
+
|
|
240
|
+
## License
|
|
241
|
+
|
|
242
|
+
LGPL-3.0. See [LICENSE](LICENSE).
|
xactflow-0.4.0/README.md
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
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. This README follows `main`: the plugin API it describes is newer
|
|
18
|
+
than the 0.3.0 release (see [Plugins](#plugins)).
|
|
19
|
+
|
|
20
|
+
For development, `requirements-dev.txt` installs `ipxact-compiler` from a sibling checkout
|
|
21
|
+
(`../ipxact-compiler`); change the path if needed:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install -r requirements-dev.txt -e .
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Command line
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
xactflow link design.xml --lib DIR [--lib DIR ...] [--config designConfig.xml]
|
|
31
|
+
xactflow check file.xml
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
- `link` scans the `--lib` folders, resolves the design against them, prints the diagnostics,
|
|
35
|
+
and exits with 1 if any is an error.
|
|
36
|
+
- `check` runs the checks that need only one file, without a library.
|
|
37
|
+
|
|
38
|
+
Each installed plugin adds its own subcommand (see [Plugins](#plugins)). Both kinds work on one
|
|
39
|
+
`Library`, scanned from the `--lib` folders:
|
|
40
|
+
|
|
41
|
+
- an exporter: `xactflow <exporter> file.xml --lib DIR [--config FILE] --output DIR` adds
|
|
42
|
+
`file.xml` to the library as the target to export, links it first if it is a design, and
|
|
43
|
+
passes the library to the exporter;
|
|
44
|
+
- an importer: `xactflow <importer> source --lib DIR` adds what it reads to the library, with
|
|
45
|
+
`--then <exporter>` to pass that same library straight to an exporter, without an
|
|
46
|
+
intermediate file:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
xactflow sv module.sv --option metadata=module_ipxact.json --then component --output out/
|
|
50
|
+
xactflow archidesc soc.py --lib ip/ --lib bus_definitions/ --then topgen --output out/
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`--option KEY=VALUE` sets a plugin option; `--then-option KEY=VALUE` sets one for the `--then`
|
|
54
|
+
exporter. If that exporter supports none of the importer's documents, the command prints a
|
|
55
|
+
one-line error naming both plugins.
|
|
56
|
+
|
|
57
|
+
## Python
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
import ipxact
|
|
61
|
+
from xactflow import Library, link
|
|
62
|
+
|
|
63
|
+
library = Library.scan("path/to/ip/library")
|
|
64
|
+
design = ipxact.parse_file("path/to/top_design.xml")
|
|
65
|
+
linked = link(design, library) # optional: design_configuration=..., component=...
|
|
66
|
+
|
|
67
|
+
linked.instances # dict[str, LinkedInstance], by instance name
|
|
68
|
+
linked.interconnections # list[LinkedInterconnection], with the interfaces that resolved
|
|
69
|
+
linked.component # the component containing the design, or None
|
|
70
|
+
linked.diagnostics # list[Diagnostic]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
A design's `hierInterface` and `externalPortReference` elements refer to the bus interfaces and
|
|
74
|
+
ports of the component containing it. `link()` uses the component given with `component=`, or
|
|
75
|
+
else the one component of the library with a view instantiating the design. With none, or
|
|
76
|
+
several, these references are not checked, and a warning says so.
|
|
77
|
+
|
|
78
|
+
Each `Diagnostic` has a `message`, a `severity` (`Severity.ERROR` or `Severity.WARNING`), a
|
|
79
|
+
`location` (a VLNV, a file, or a path such as `vendor:lib:top:1.0/conn0`), and, when it is an
|
|
80
|
+
Annex B rule, its `rule_id` and `rule_name`. `str(diagnostic)` gives the line the CLI prints:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
error: [SCR 2.4] interconnection 'conn0' connects ... (example.org:soc:top:1.0/conn0)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`Library` indexes documents by VLNV:
|
|
87
|
+
|
|
88
|
+
- `Library.scan(*folders)` reads every IEEE 1685-2022 file under the folders. A missing folder
|
|
89
|
+
raises an error; files of another IP-XACT version, or a folder with no 1685-2022 file, give a
|
|
90
|
+
warning in `library.diagnostics`.
|
|
91
|
+
- `library.add_file(path)` adds one file, with the same checks.
|
|
92
|
+
- `library.add(document, path=None, replace=False, target=False)` adds a document that only
|
|
93
|
+
exists in memory, e.g. an importer's result. `path` only records where it came from.
|
|
94
|
+
- `library.documents(kind=None)` returns every document, or those of one type, e.g.
|
|
95
|
+
`library.documents(ipxact.Component)`.
|
|
96
|
+
- `library.targets(kind=None)` returns only the documents added with `target=True`: the ones
|
|
97
|
+
an exporter writes, as opposed to those it only looks up.
|
|
98
|
+
- `library.get(vlnv)` returns the document with that VLNV, or None; `get_component`,
|
|
99
|
+
`get_design`, `get_bus_definition`, `get_abstraction_definition` and
|
|
100
|
+
`get_design_configuration` also return None for a document of another type.
|
|
101
|
+
|
|
102
|
+
A duplicate VLNV is reported as an SCR 1.1 error, unless `replace=True`.
|
|
103
|
+
|
|
104
|
+
## Expression evaluation
|
|
105
|
+
|
|
106
|
+
IP-XACT values such as `addressOffset`, `size` or a parameter value are expressions, kept as
|
|
107
|
+
text by `ipxact-compiler`. `xactflow.evaluate()` computes them, following the expression
|
|
108
|
+
language of IEEE 1685-2022 Annex E (a subset of SystemVerilog):
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from xactflow import evaluate, parameter_resolver
|
|
112
|
+
|
|
113
|
+
evaluate("2 + 3 * 4") # 14
|
|
114
|
+
evaluate("{3{1'b1}}") # 7
|
|
115
|
+
evaluate("WIDTH - 1", resolve_parameter=lambda name: "8") # 7
|
|
116
|
+
|
|
117
|
+
resolve = parameter_resolver(component.parameters) # by parameterId
|
|
118
|
+
evaluate(register.size, resolve_parameter=resolve) # an ipxact.Expression
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
- A referenced parameter is cast to its `type` and `sign`: a `byte` with value `200` is `-56`.
|
|
122
|
+
- A value outside its `minimum`/`maximum` raises `ExpressionError`, naming the parameter, or
|
|
123
|
+
the `name=` given to `evaluate()`.
|
|
124
|
+
- Supported: integral and real values, all non-string operators (with reductions, `->`,
|
|
125
|
+
`<->`, `inside`), casts, concatenation, replication, streaming, bit and part selects,
|
|
126
|
+
`'0`/`'1`, escaped identifiers, `$clog2` and the real math functions (`$ln`, `$pow`, ...).
|
|
127
|
+
- Not supported, because `evaluate()` returns one number: strings and `$sformatf`, array
|
|
128
|
+
parameters, and the `$ipxact_*` functions, whose value depends on the design environment.
|
|
129
|
+
- Arithmetic works on plain values, without SystemVerilog's context-dependent width rules:
|
|
130
|
+
`4'hF + 4'h1` is `16`.
|
|
131
|
+
- Numbers use SystemVerilog syntax only: write `'h1F`, not `0x1F`.
|
|
132
|
+
|
|
133
|
+
## Semantic Consistency Rules (SCR)
|
|
134
|
+
|
|
135
|
+
Annex B of the standard defines 281 SCRs in 15 tables. All are registered in `xactflow.SCR`,
|
|
136
|
+
one module per table, with their id, name and text as written in the standard (without its
|
|
137
|
+
"See also" references). 15 have a check today: SCR 1.2, 1.5, 1.9, 2.1 to 2.10, 2.17 and 13.5.
|
|
138
|
+
The others are placeholders that report nothing.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from xactflow import SCR
|
|
142
|
+
|
|
143
|
+
len(SCR.all_rules()) # 281
|
|
144
|
+
[r.id for r in SCR.all_rules() if r.implemented] # the 15 rules with a check
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(linked)` can be called on
|
|
148
|
+
their own, e.g. by an exporter to check the IP-XACT it writes.
|
|
149
|
+
|
|
150
|
+
## Plugins
|
|
151
|
+
|
|
152
|
+
Plugins live in their own packages and are found through
|
|
153
|
+
[entry points](https://packaging.python.org/en/latest/specifications/entry-points/):
|
|
154
|
+
|
|
155
|
+
- an `xactflow.Importer` (group `xactflow.importers`) reads a non-IP-XACT source and adds
|
|
156
|
+
the IP-XACT documents it describes to a `Library`, with `target=True`.
|
|
157
|
+
- an `xactflow.Exporter` (group `xactflow.exporters`) writes an output from the targets of a
|
|
158
|
+
`Library`: RTL, documentation, IP-XACT XML... It looks up anything else it needs in the
|
|
159
|
+
library, e.g. with `link(design, library)`. Each exporter says which targets it supports and
|
|
160
|
+
raises `TypeError` when the library has none.
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
class MyImporter(Importer):
|
|
164
|
+
name = "mine"
|
|
165
|
+
|
|
166
|
+
def import_(self, source_path, library, **options):
|
|
167
|
+
library.add(build_component(source_path), target=True)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
class MyExporter(Exporter):
|
|
171
|
+
name = "mine"
|
|
172
|
+
|
|
173
|
+
def export(self, library, output_dir, **options):
|
|
174
|
+
designs = list(library.targets(ipxact.Design))
|
|
175
|
+
if not designs:
|
|
176
|
+
raise TypeError("'mine' needs an ipxact.Design target")
|
|
177
|
+
for design in designs:
|
|
178
|
+
write_rtl(link(design, library), output_dir)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```toml
|
|
182
|
+
[project.entry-points."xactflow.importers"]
|
|
183
|
+
sv = "xactflow_sv:SVImporter"
|
|
184
|
+
|
|
185
|
+
[project.entry-points."xactflow.exporters"]
|
|
186
|
+
component = "xactflow_component:ComponentExporter"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The entry point name is the subcommand.
|
|
190
|
+
|
|
191
|
+
A plugin that fails to load is skipped with a warning; the others keep working.
|
|
192
|
+
|
|
193
|
+
| Package | Kind | Subcommand | Does |
|
|
194
|
+
|---|---|---|---|
|
|
195
|
+
| [XactFlow-sv](https://github.com/IP-XACT/XactFlow-sv) | importer | `sv` | SystemVerilog module + metadata → `ipxact.Component` |
|
|
196
|
+
| [XactFlow-archidesc](https://github.com/IP-XACT/XactFlow-archidesc) | importer | `archidesc` | architecture description → `ipxact.Design` |
|
|
197
|
+
| [XactFlow-component](https://github.com/IP-XACT/XactFlow-component) | exporter | `component` | `ipxact.Component` → component XML |
|
|
198
|
+
| [XactFlow-design](https://github.com/IP-XACT/XactFlow-design) | exporter | `design` | `ipxact.Design` → design XML |
|
|
199
|
+
|
|
200
|
+
The plugins above were written for the previous API, where `import_` returned an object and
|
|
201
|
+
`export` took one; they need a release for this one.
|
|
202
|
+
|
|
203
|
+
## Limitations and plans
|
|
204
|
+
|
|
205
|
+
- **266 of the 281 SCRs have no check yet.** Next: the single-file rules, and the
|
|
206
|
+
overlap/alignment rules, which can now use `evaluate()`.
|
|
207
|
+
- **Monitor connections are not checked.** `link()` resolves them, but a broken reference is
|
|
208
|
+
dropped without a message.
|
|
209
|
+
- **One level of hierarchy.** `link()` checks a design against its instances and the
|
|
210
|
+
component containing it, but does not go into the designs of its instances.
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
LGPL-3.0. See [LICENSE](LICENSE).
|
|
@@ -16,13 +16,16 @@ def run_single_doc_checks(document: object) -> List[Diagnostic]:
|
|
|
16
16
|
|
|
17
17
|
|
|
18
18
|
def run_post_config_checks(linked: object) -> List[Diagnostic]:
|
|
19
|
-
"""Run every SCR rule that needs the relationships between documents
|
|
19
|
+
"""Run every SCR rule that needs the relationships between documents, or that applies after
|
|
20
|
+
configuration (post_config). A rule that is both single-doc and post_config is given each
|
|
21
|
+
document by run_single_doc_checks and the linked design here, so its check has to look at
|
|
22
|
+
what it is given.
|
|
20
23
|
|
|
21
24
|
Takes a link.LinkedDesign (accepted as object here to avoid a circular import
|
|
22
25
|
between xactflow.SCR and xactflow.link, since link.resolver itself calls this).
|
|
23
26
|
"""
|
|
24
27
|
diagnostics: List[Diagnostic] = []
|
|
25
28
|
for r in all_rules():
|
|
26
|
-
if not r.single_doc_check:
|
|
29
|
+
if not r.single_doc_check or r.post_config:
|
|
27
30
|
diagnostics.extend(r.check(linked))
|
|
28
31
|
return diagnostics
|