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.
Files changed (60) hide show
  1. xactflow-0.4.0/PKG-INFO +242 -0
  2. xactflow-0.4.0/README.md +214 -0
  3. {xactflow-0.2.0 → xactflow-0.4.0}/pyproject.toml +1 -1
  4. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/runner.py +5 -2
  5. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_01.py +81 -44
  6. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_02.py +221 -87
  7. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_03.py +29 -27
  8. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_05.py +22 -19
  9. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_06.py +122 -101
  10. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_07.py +46 -28
  11. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_08.py +6 -4
  12. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_09.py +7 -7
  13. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_10.py +1 -1
  14. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_11.py +3 -3
  15. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_12.py +2 -2
  16. xactflow-0.4.0/src/xactflow/SCR/scr_13.py +110 -0
  17. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_14.py +18 -18
  18. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_15.py +1 -1
  19. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/__init__.py +5 -1
  20. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/cli.py +106 -39
  21. xactflow-0.4.0/src/xactflow/exporter.py +75 -0
  22. xactflow-0.4.0/src/xactflow/expressions.py +830 -0
  23. xactflow-0.4.0/src/xactflow/importer.py +72 -0
  24. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/library.py +61 -15
  25. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/link/__init__.py +4 -0
  26. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/link/model.py +30 -10
  27. xactflow-0.4.0/src/xactflow/link/resolver.py +311 -0
  28. xactflow-0.4.0/src/xactflow.egg-info/PKG-INFO +242 -0
  29. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/SOURCES.txt +1 -0
  30. xactflow-0.4.0/src/xactflow.egg-info/requires.txt +5 -0
  31. {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_cli.py +117 -75
  32. xactflow-0.4.0/tests/test_exporter.py +100 -0
  33. xactflow-0.4.0/tests/test_expressions.py +550 -0
  34. xactflow-0.4.0/tests/test_hierarchy.py +379 -0
  35. xactflow-0.4.0/tests/test_importer.py +94 -0
  36. {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_library.py +112 -1
  37. {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_resolver.py +33 -9
  38. {xactflow-0.2.0 → xactflow-0.4.0}/tests/test_scr.py +42 -0
  39. xactflow-0.2.0/PKG-INFO +0 -243
  40. xactflow-0.2.0/README.md +0 -215
  41. xactflow-0.2.0/src/xactflow/SCR/scr_13.py +0 -54
  42. xactflow-0.2.0/src/xactflow/exporter.py +0 -70
  43. xactflow-0.2.0/src/xactflow/expressions.py +0 -319
  44. xactflow-0.2.0/src/xactflow/importer.py +0 -60
  45. xactflow-0.2.0/src/xactflow/link/resolver.py +0 -164
  46. xactflow-0.2.0/src/xactflow.egg-info/PKG-INFO +0 -243
  47. xactflow-0.2.0/src/xactflow.egg-info/requires.txt +0 -5
  48. xactflow-0.2.0/tests/test_exporter.py +0 -91
  49. xactflow-0.2.0/tests/test_expressions.py +0 -189
  50. xactflow-0.2.0/tests/test_importer.py +0 -75
  51. {xactflow-0.2.0 → xactflow-0.4.0}/LICENSE +0 -0
  52. {xactflow-0.2.0 → xactflow-0.4.0}/setup.cfg +0 -0
  53. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/__init__.py +0 -0
  54. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/registry.py +0 -0
  55. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/SCR/scr_04.py +0 -0
  56. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/diagnostics.py +0 -0
  57. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow/py.typed +0 -0
  58. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/dependency_links.txt +0 -0
  59. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/entry_points.txt +0 -0
  60. {xactflow-0.2.0 → xactflow-0.4.0}/src/xactflow.egg-info/top_level.txt +0 -0
@@ -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).
@@ -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).
@@ -14,7 +14,7 @@ authors = [
14
14
  ]
15
15
  requires-python = ">=3.9"
16
16
  dependencies = [
17
- "ipxact-compiler>=0.1.2",
17
+ "ipxact-compiler>=0.2.0",
18
18
  "lxml",
19
19
  ]
20
20
  keywords = [
@@ -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