xactflow-rtl-gen 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.
Files changed (40) hide show
  1. xactflow_rtl_gen-0.3.0/LICENSE +164 -0
  2. xactflow_rtl_gen-0.3.0/MANIFEST.in +5 -0
  3. xactflow_rtl_gen-0.3.0/PKG-INFO +443 -0
  4. xactflow_rtl_gen-0.3.0/README.md +413 -0
  5. xactflow_rtl_gen-0.3.0/docs/decisions.md +825 -0
  6. xactflow_rtl_gen-0.3.0/docs/findings.md +35 -0
  7. xactflow_rtl_gen-0.3.0/pyproject.toml +56 -0
  8. xactflow_rtl_gen-0.3.0/pytest.ini +2 -0
  9. xactflow_rtl_gen-0.3.0/requirements-dev.txt +4 -0
  10. xactflow_rtl_gen-0.3.0/setup.cfg +4 -0
  11. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/__init__.py +116 -0
  12. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/address_map.py +391 -0
  13. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/keywords.py +28 -0
  14. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/py.typed +0 -0
  15. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/top_writer.py +2513 -0
  16. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/PKG-INFO +443 -0
  17. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/SOURCES.txt +38 -0
  18. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/dependency_links.txt +1 -0
  19. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/entry_points.txt +2 -0
  20. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/requires.txt +9 -0
  21. xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/top_level.txt +1 -0
  22. xactflow_rtl_gen-0.3.0/tests/builders.py +389 -0
  23. xactflow_rtl_gen-0.3.0/tests/conftest.py +25 -0
  24. xactflow_rtl_gen-0.3.0/tests/fixtures/lib/master.xml +55 -0
  25. xactflow_rtl_gen-0.3.0/tests/fixtures/lib/sbus.xml +9 -0
  26. xactflow_rtl_gen-0.3.0/tests/fixtures/lib/sbus_rtl.xml +65 -0
  27. xactflow_rtl_gen-0.3.0/tests/fixtures/lib/slave.xml +65 -0
  28. xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/master_core.sv +27 -0
  29. xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/slave.sv +17 -0
  30. xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/struct_ips.sv +15 -0
  31. xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/tb_soc.sv +30 -0
  32. xactflow_rtl_gen-0.3.0/tests/test_address_map.py +226 -0
  33. xactflow_rtl_gen-0.3.0/tests/test_adversarial.py +2040 -0
  34. xactflow_rtl_gen-0.3.0/tests/test_exporter.py +564 -0
  35. xactflow_rtl_gen-0.3.0/tests/test_generated_rtl.py +93 -0
  36. xactflow_rtl_gen-0.3.0/tests/test_module_parameters.py +377 -0
  37. xactflow_rtl_gen-0.3.0/tests/test_scenarios.py +875 -0
  38. xactflow_rtl_gen-0.3.0/tests/test_socgen_package.py +281 -0
  39. xactflow_rtl_gen-0.3.0/tests/test_top_component.py +457 -0
  40. xactflow_rtl_gen-0.3.0/tests/test_type_parameters.py +472 -0
@@ -0,0 +1,164 @@
1
+ GNU LESSER GENERAL PUBLIC LICENSE
2
+ Version 3, 29 June 2007
3
+
4
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
5
+ Everyone is permitted to copy and distribute verbatim copies
6
+ of this license document, but changing it is not allowed.
7
+
8
+ This version of the GNU Lesser General Public License incorporates
9
+ the terms and conditions of version 3 of the GNU General Public
10
+ License, supplemented by the additional permissions listed below.
11
+
12
+ 0. Additional Definitions.
13
+
14
+ As used herein, "this License" refers to version 3 of the GNU Lesser
15
+ General Public License, and the "GNU GPL" refers to version 3 of the GNU
16
+ General Public License.
17
+
18
+ "The Library" refers to a covered work governed by this License,
19
+ other than an Application or a Combined Work as defined below.
20
+
21
+ An "Application" is any work that makes use of an interface provided
22
+ by the Library, but which is not otherwise based on the Library.
23
+ Defining a subclass of a class defined by the Library is deemed a mode
24
+ of using an interface provided by the Library.
25
+
26
+ A "Combined Work" is a work produced by combining or linking an
27
+ Application with the Library. The particular version of the Library
28
+ with which the Combined Work was made is also called the "Linked
29
+ Version".
30
+
31
+ The "Minimal Corresponding Source" for a Combined Work means the
32
+ Corresponding Source for the Combined Work, excluding any source code
33
+ for portions of the Combined Work that, considered in isolation, are
34
+ based on the Application, and not on the Linked Version.
35
+
36
+ The "Corresponding Application Code" for a Combined Work means the
37
+ object code and/or source code for the Application, including any data
38
+ and utility programs needed for reproducing the Combined Work from the
39
+ Application, but excluding the System Libraries of the Combined Work.
40
+
41
+ 1. Exception to Section 3 of the GNU GPL.
42
+
43
+ You may convey a covered work under sections 3 and 4 of this License
44
+ without being bound by section 3 of the GNU GPL.
45
+
46
+ 2. Conveying Modified Versions.
47
+
48
+ If you modify a copy of the Library, and, in your modifications, a
49
+ facility refers to a function or data to be supplied by an Application
50
+ that uses the facility (other than as an argument passed when the
51
+ facility is invoked), then you may convey a copy of the modified
52
+ version:
53
+
54
+ a) under this License, provided that you make a good faith effort to
55
+ ensure that, in the event an Application does not supply the
56
+ function or data, the facility still operates, and performs
57
+ whatever part of its purpose remains meaningful, or
58
+
59
+ b) under the GNU GPL, with none of the additional permissions of
60
+ this License applicable to that copy.
61
+
62
+ 3. Object Code Incorporating Material from Library Header Files.
63
+
64
+ The object code form of an Application may incorporate material from
65
+ a header file that is part of the Library. You may convey such object
66
+ code under terms of your choice, provided that, if the incorporated
67
+ material is not limited to numerical parameters, data structure
68
+ layouts and accessors, or small macros, inline functions and templates
69
+ (ten or fewer lines in length), you do both of the following:
70
+
71
+ a) Give prominent notice with each copy of the object code that the
72
+ Library is used in it and that the Library and its use are
73
+ covered by this License.
74
+
75
+ b) Accompany the object code with a copy of the GNU GPL and this license
76
+ document.
77
+
78
+ 4. Combined Works.
79
+
80
+ You may convey a Combined Work under terms of your choice that,
81
+ taken together, effectively do not restrict modification of the
82
+ portions of the Library contained in the Combined Work and reverse
83
+ engineering for debugging such modifications, if you also do each of
84
+ the following:
85
+
86
+ a) Give prominent notice with each copy of the Combined Work that
87
+ the Library is used in it and that the Library and its use are
88
+ covered by this License.
89
+
90
+ b) Accompany the Combined Work with a copy of the GNU GPL and this license
91
+ document.
92
+
93
+ c) For a Combined Work that displays copyright notices during
94
+ execution, include the copyright notice for the Library among
95
+ these notices, as well as a reference directing the user to the
96
+ copies of the GNU GPL and this license document.
97
+
98
+ d) Do one of the following:
99
+
100
+ 0) Convey the Minimal Corresponding Source under the terms of this
101
+ License, and the Corresponding Application Code in a form
102
+ suitable for, and under terms that permit, the user to
103
+ recombine or relink the Application with a modified version of
104
+ the Linked Version to produce a modified Combined Work, in the
105
+ manner specified by section 6 of the GNU GPL for conveying
106
+ Corresponding Source.
107
+
108
+ 1) Use a suitable shared library mechanism for linking with the
109
+ Library. A suitable mechanism is one that (a) uses at run time
110
+ a copy of the Library already present on the user's computer
111
+ system, and (b) will operate properly with a modified version
112
+ of the Library that is interface-compatible with the Linked
113
+ Version.
114
+
115
+ e) Provide Installation Information, but only if you would otherwise
116
+ be required to provide such information under section 6 of the
117
+ GNU GPL, and only to the extent that such information is
118
+ necessary to install and execute a modified version of the
119
+ Combined Work produced by recombining or relinking the
120
+ Application with a modified version of the Linked Version. (If
121
+ you use option 4d0, the Installation Information must accompany
122
+ the Minimal Corresponding Source and Corresponding Application
123
+ Code. If you use option 4d1, you must provide the Installation
124
+ Information in the manner specified by section 6 of the GNU GPL
125
+ for conveying Corresponding Source.)
126
+
127
+ 5. Combined Libraries.
128
+
129
+ You may place library facilities that are a work based on the
130
+ Library side by side in a single library together with other library
131
+ facilities that are not Applications and are not covered by this
132
+ License, and convey such a combined library under terms of your
133
+ choice, if you do both of the following:
134
+
135
+ a) Accompany the combined library with a copy of the same work based
136
+ on the Library, uncombined with any other library facilities,
137
+ conveyed under the terms of this License.
138
+
139
+ b) Give prominent notice with the combined library that part of it
140
+ is a work based on the Library, and explaining where to find the
141
+ accompanying uncombined form of the same work.
142
+
143
+ 6. Revised Versions of the GNU Lesser General Public License.
144
+
145
+ The Free Software Foundation may publish revised and/or new versions
146
+ of the GNU Lesser General Public License from time to time. Such new
147
+ versions will be similar in spirit to the present version, but may
148
+ differ in detail to address new problems or concerns.
149
+
150
+ Each version is given a distinguishing version number. If the
151
+ Library as you received it specifies that a certain numbered version
152
+ of the GNU Lesser General Public License "or any later version"
153
+ applies to it, you have the option of following the terms and
154
+ conditions either of that published version or of any later version
155
+ published by the Free Software Foundation. If the Library as you
156
+ received it does not specify a version number of the GNU Lesser
157
+ General Public License, you may choose any version of the GNU Lesser
158
+ General Public License ever published by the Free Software Foundation.
159
+
160
+ If the Library as you received it specifies that a proxy can decide
161
+ whether future versions of the GNU Lesser General Public License shall
162
+ apply, that proxy's public statement of acceptance of any version is
163
+ permanent authorization for you to choose that version for the
164
+ Library.
@@ -0,0 +1,5 @@
1
+ # The source distribution carries what it takes to run the tests and read the decisions.
2
+ graft tests
3
+ graft docs
4
+ include requirements-dev.txt pytest.ini
5
+ global-exclude __pycache__ *.py[cod]
@@ -0,0 +1,443 @@
1
+ Metadata-Version: 2.4
2
+ Name: xactflow-rtl-gen
3
+ Version: 0.3.0
4
+ Summary: XactFlow exporter plugin that generates a SystemVerilog top-level module from a linked IP-XACT design.
5
+ Author: Joonatan Alanampa
6
+ License-Expression: LGPL-3.0-only
7
+ Keywords: IP-XACT,IEEE 1685,RTL,XactFlow,SystemVerilog,Exporter
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3 :: Only
11
+ Classifier: Programming Language :: Python :: 3.9
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Topic :: Scientific/Engineering
18
+ Requires-Python: >=3.9
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: xactflow<0.5,>=0.4.0
22
+ Requires-Dist: ipxact-compiler>=0.2.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest; extra == "dev"
25
+ Requires-Dist: pyslang>=10.0.0; extra == "dev"
26
+ Requires-Dist: xactflow-archidesc>=0.3.0; extra == "dev"
27
+ Requires-Dist: xactflow-design>=0.2.1; extra == "dev"
28
+ Requires-Dist: xactflow-sv>=0.2.1; extra == "dev"
29
+ Dynamic: license-file
30
+
31
+ # xactflow-rtl-gen
32
+
33
+ A [XactFlow](https://github.com/IP-XACT/XactFlow) exporter plugin that generates the SystemVerilog
34
+ of an [IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) IP-XACT design: the module, its
35
+ instances and parameters, the bus and ad hoc wiring between them, and a package with its address map.
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ pip install xactflow-rtl-gen
41
+ ```
42
+
43
+ It adds the `rtl-gen` subcommand to `xactflow`. Requires Python >= 3.9, and XactFlow 0.4: the exporter uses a
44
+ private part of XactFlow's evaluator, so it is pinned below 0.5 until that is public.
45
+
46
+ For development, with the rest of the toolchain and the tests' tools:
47
+
48
+ ```bash
49
+ python3 -m venv .venv
50
+ .venv/bin/pip install -r requirements-dev.txt
51
+ ```
52
+
53
+ ## Usage
54
+
55
+ From a design file:
56
+
57
+ ```bash
58
+ xactflow rtl-gen soc.xml --lib ip/ --output rtl/
59
+ ```
60
+
61
+ Chained straight from an importer. The importer adds its design to the library scanned from `--lib`,
62
+ and the exporter links it there, so the folders hold the components and bus definitions it refers to:
63
+
64
+ ```bash
65
+ xactflow archidesc soc.py --lib ip/ --then rtl-gen --output rtl/
66
+ ```
67
+
68
+ `xactflow-archidesc` names the design `<name>.design` and builds the component that holds it,
69
+ `<name>.component`, from the top-level ports and bus interfaces the script declares. That component
70
+ defines the module's ports, and the module is called `<name>` (D45). An instance input the script
71
+ connects to nothing is refused by name; declare a port for it, or see `unconnected` below.
72
+
73
+ Both link the design and refuse it if the library or the link reports errors. Regenerating replaces an
74
+ earlier output, but a file not generated by this tool is never overwritten: if one is in the way, nothing
75
+ is written.
76
+
77
+ From Python:
78
+
79
+ ```python
80
+ from xactflow import Library, link
81
+ from xactflow_rtl_gen import RtlExporter, generate_files
82
+
83
+ library = Library.scan("ip")
84
+ library.add(design, target=True) # the design to export, as an importer adds it
85
+ RtlExporter().export(library, "rtl", common="clk_i,rst_ni") # linked, and written to rtl/
86
+
87
+ linked = link(design, library) # or linked by hand
88
+ files = generate_files(linked, common=["clk_i", "rst_ni"]) # file names and their text
89
+ RtlExporter().export(linked, "rtl", common="clk_i,rst_ni")
90
+ ```
91
+
92
+ ### What it writes
93
+
94
+ - `<module>.sv`: the design's module.
95
+ - `<module>_addr_map_pkg.sv`: its address map, if the design records address windows. Compile it first.
96
+ - One more `<module>.sv` for each hierarchical instance, at any depth.
97
+ - With the `filelist` option, a list of those files in an order that compiles.
98
+ - With the `socgen_package` option, one more package: every module's windows in PeakRDL-socgen's layout.
99
+
100
+ ### Options
101
+
102
+ - `common`: input port names to share across instances, for clocks and resets. Each one no connection
103
+ drives connects to one port of the module with that name. Comma-separated, or a list from Python.
104
+ - `top`: the VLNV of the hierarchical component to use, when more than one holds the design.
105
+ - `unconnected`: what happens to a port the design connects to nothing, in a module whose ports a
106
+ hierarchical component defines: an instance's input, or an output of the module. `refuse`, the default,
107
+ stops with an error. `open` leaves it as the design has it, open or undriven, with a comment that says
108
+ so (D38).
109
+ - `filelist`: a file name, such as `soc.f`. The files of this run are listed in it, packages first and the
110
+ design's module last, relative to the list: `verilator -F rtl/soc.f` (D39).
111
+ - `socgen_package`: a package name, such as `soc_addr_map_pkg`, for one more package holding the address
112
+ windows of every module this run generates in PeakRDL-socgen's layout, for testbenches and other files
113
+ written against that tool's package. See [Address map](#address-map) (D43).
114
+ - `socgen_names`: what socgen calls the decoders and targets in that package, as `instance:name` pairs,
115
+ comma-separated, or a dict from Python: `xbar_i:main_interconnect,ram_i:ram`. An instance not given goes by
116
+ its own name.
117
+
118
+ ## What the output looks like
119
+
120
+ Every connected instance port gets its own net, `<instance>_<port>`, and each connection is an
121
+ `assign` from the driving net to the receiving one:
122
+
123
+ ```systemverilog
124
+ // m_to_s: m.bus <-> s.bus (test.org:bus:sbus_rtl:1.0)
125
+ // s.bus address window: baseAddr 0x40000000, size 0x1000
126
+ assign s_valid_ni = ~m_valid_o; // VALID
127
+ assign s_wdata_i = m_wdata_o; // WDATA
128
+ assign m_rdata_i = s_rdata_o[7:0]; // RDATA
129
+ assign m_ready_i = 1'h1; // READY, abstraction default
130
+ assign m_err_i = 1'h0; // ERR, tied off by s
131
+
132
+ // IP-XACT VLNV: test.org:ip:master:1.0
133
+ master_core m (
134
+ // Interface: bus
135
+ .clk_i (clk_i),
136
+ ...
137
+ ```
138
+
139
+ That one shape covers part selects, inverted port maps, tie-offs and struct sub-ports. Two things add a
140
+ net of their own: a logical port mapped in slices, called `<connection>_<logical port>`, and an inout,
141
+ which has to share a net with what it connects to. A whole port wired to one of the module's own ports
142
+ connects directly, with no net in between, unless a part of it is taken elsewhere and the two number their
143
+ bits differently, or are structs of different types (D35). A net's name gets `_net` added if it would be a keyword, or already belongs to an
144
+ instance or a port.
145
+
146
+ ## Where the module's ports come from
147
+
148
+ **With a hierarchical component in the library**, the component whose view holds the design defines the
149
+ module: its name, and exactly its ports. This is the standard's own way, and you can connect to those
150
+ ports with `externalPortReference` and `hierInterface`. An input no connection reaches is an error,
151
+ unless it is listed in `common`, because the component says what the ports are and floating an input is
152
+ a bug, and so is an output of the module that nothing drives. The option `unconnected=open` leaves both as
153
+ they are, for a design that means them to be. An instance's output nothing reads is left open.
154
+
155
+ If that view also names a component instantiation with module parameters, the module declares them, so
156
+ that code which instantiates it with `#(...)` still compiles. They do not configure it: each has the one
157
+ value the module is generated for, and the module has the compiler refuse any other (D36). A parameter is
158
+ declared with no type, so that nothing converts what it is given before it is compared; only a typedef named
159
+ with its package is kept (D41):
160
+
161
+ ```systemverilog
162
+ module croc_soc #(
163
+ parameter GpioCount = 32
164
+ ) (
165
+ ...
166
+ );
167
+
168
+ if (GpioCount !== 32) begin : GpioCount_as_generated
169
+ $error("croc_soc is generated for GpioCount = 32, and was given another value");
170
+ initial $fatal(1, "croc_soc is generated for GpioCount = 32, and was given another value");
171
+ end
172
+ ```
173
+
174
+ `$error` stops a compiler as it elaborates the module. One that goes on past it stops when the simulation
175
+ starts, on the `$fatal` (D40).
176
+
177
+ **Without one**, the design is all there is. An `externalPortReference` declares a port. A port no
178
+ connection reaches becomes a top-level port, `<instance>_<port>`, or the shared `common` port, so
179
+ nothing floats silently. This is what you get from `archidesc` today, which cannot declare top-level
180
+ ports. Parts of a port with no hierarchical component are refused, and so is `hierInterface`, since only
181
+ the component can say which ports those are.
182
+
183
+ ## How connections are decided
184
+
185
+ - **Module name of an instance:** the configured view's `moduleName`, else the first view with an
186
+ instantiation, else the VLNV name. A component with no view takes its only component instantiation (D33).
187
+ - **A view's choices:** an instance uses the abstraction type, driver and type definitions of its view.
188
+ - **A design configuration:** the one given to `link()`, else the one the hierarchical component's view
189
+ holds, at any depth.
190
+ - **A hierarchical instance:** its view holds a design, which gets its own module. Every value in a generated
191
+ module is worked out, so an instance whose overrides change a parameter of its component gets a module of
192
+ its own, `<module>_1`, `<module>_2`, ..., one for each set of values, however each instance writes them, with
193
+ those values all the way down its design (D26). Its first line says which values it is for. If the module declares parameters (D36), the
194
+ instance is given the values it is generated for.
195
+ - **A design's parameters:** a component's reference to the design it holds can give them values, worked out
196
+ in the component, so a top component or a hierarchical instance sets its design's parameters this way. That
197
+ works when the view names a design configuration as well, as Kactus2 writes it (D25). Its reference to the
198
+ design configuration gives that one's parameters values the same way (D37).
199
+ - **Parameters:** every module parameter of the view is written, with its value in this design, because
200
+ the HDL's own default can differ from the component's. The exception is one worked out only from the
201
+ instance's other module parameters, as an imported HDL default such as `B = A + 8'd100` is: the HDL works
202
+ that out itself, exactly, unless an override sets it. A value with no parameters in it is written as it
203
+ stands, so `8'hA5` stays 8 bits, and so does a parameter's own value. One that uses other parameters is
204
+ worked out, by the same evaluator as the port widths, so the two cannot disagree. It honours a parameter's
205
+ declared type, and is written with the width the evaluator gives it, such as `8'd255`. What it can't work out, a
206
+ string or something in a package, goes to the compiler with the numbers filled in. Overrides are applied
207
+ here, since `link()` does not. A `runtime` parameter is left off the instance, and an override on one is
208
+ refused.
209
+ - **Type parameters:** a module parameter whose `dataType` is `type`, as `xactflow-sv` imports SystemVerilog's
210
+ `parameter type`, stands for a type. A port of that type is declared with the type its instance gives the
211
+ parameter, such as `croc_pkg::sbr_obi_req_t`. Where that is `logic [W-1:0]` the port is a plain vector, and its
212
+ width is checked like any other. A type parameter the HDL works out from its other parameters is left to
213
+ it (D31).
214
+ - **Arrays of structs:** on a port that is a packed array of a struct, a part select picks elements. `[3:3]` is
215
+ the element `[3]`: it connects to a struct of that type, and can have sub-ports, `[3].a.addr`, in a port map
216
+ as in a design. A longer range connects whole to an array of as many. Every element of such an input has to
217
+ be driven, whole or member by member (D32).
218
+ - **Expressions in the design:** part selects and tied values see the design's parameters, and then those
219
+ of its hierarchical component, not the instance's. Values in a design configuration see its own first.
220
+ - **Constants on a net:** `'1` is all ones at that net's width. On a port or sub-port of a named type, such as
221
+ an enum, a constant or an inverted value is cast to it, `mode_pkg::mode_e'(2)`. Where only the compiler knows
222
+ the width, the module has it check that the constant fits, with `$bits` and `$error` at elaboration. slang,
223
+ Verilator and Icarus 13 stop there. Icarus 12 skips such a line, and Verilator with `-Wno-fatal` only reports
224
+ it.
225
+ - **A port map with no logical range:** on a wire port it takes logical bits [the port's width - 1:0], as Annex
226
+ B.1.7 of the standard says, so an end narrower than the others gets the low bits, such as a 12-bit memory
227
+ address on a 32-bit bus. A bit read that no end drives is refused, as the standard doesn't say what it gets.
228
+ Where bits are picked by number, they have to lie within the abstraction's width for the port (SCR 6.19, D29).
229
+ - **A logical port with no driver on its bus:** the port map's `logicalTieOff`, else the abstraction's
230
+ `defaultValue`, else its receivers stay unconnected. Tie-offs can each cover a logical range, next to
231
+ bits a port drives. An abstraction's default reaches an inout only if nothing else on the bus connects to it.
232
+ - **An output a connected bus has no receiver for:** left open, `.port()`.
233
+ - **A port's own `defaultValue`:** applies only through an ad hoc `tiedValue="default"`, where it wins over
234
+ the abstraction's default. Without one, an input nothing connects is treated like any other, whatever
235
+ its default. This is 7.5.5 and Table C.2 of the standard, which `tests/test_scenarios.py` runs row by row.
236
+ - **Ad hoc `tiedValue`:** a constant, `open` for `.port()` on a whole port, or `default` for that default value. On a part
237
+ select, `default` takes those bits of the default. A port's drivers can each cover a range of its bits.
238
+ - **Transactional and phantom ports:** left out, as an RTL view of the component does not have them.
239
+
240
+ ## Address map
241
+
242
+ `archidesc`'s `connect_bus(..., base_addr=, size=)` records a window on the connection. The package holds
243
+ those windows as constants, and one rule table for each instance that decodes them:
244
+
245
+ ```systemverilog
246
+ localparam int unsigned DEC_NUM_RULES = 2;
247
+ typedef addr_rule_t [DEC_NUM_RULES-1:0] DEC_ADDR_RULES_t;
248
+ localparam DEC_ADDR_RULES_t DEC_ADDR_RULES = DEC_ADDR_RULES_t'({
249
+ {32'd1, 32'h40001000, 32'h40003000},
250
+ {32'd0, 32'h40000000, 32'h40001000}
251
+ });
252
+ ```
253
+
254
+ - A rule's `idx` is which interface of the decoder the window is behind, counted in the order the component
255
+ declares them, among its `initiator` and `mirroredTarget` interfaces, whatever order the script connected
256
+ them in. On a bus with several ends, the decoder is the end with one of those modes.
257
+ - A window reached through one of the module's own interfaces is listed under the module, with `idx`
258
+ counting the hierarchical component's interfaces.
259
+ - Each window has `_BASE`, `_END` and `_SIZE` constants, named after the decoder and interface, and the target
260
+ too when one interface reaches several windows.
261
+ - `addr_rule_t` has the same fields as PULP's `axi_pkg::xbar_rule_32_t`, and the same meaning: the end is
262
+ exclusive, and an end of 0 means the end of the address space. A decoder that takes a `rule_t`, such as
263
+ common_cells' `cc_addr_decode`, can take the table as it is.
264
+ - A decoder that declares module parameters called `ADDR_RULES` and `NUM_RULES` is given its table. Any
265
+ other decoder has to be pointed at the package by a parameter override, such as
266
+ `RULES="soc_addr_map_pkg::DEC_ADDR_RULES"`.
267
+ - `DEC_ADDR_PAIRS` holds the same windows as a flat vector of start and end pairs, rule 0 first, for a decoder
268
+ that takes them that way.
269
+ - The address width comes from the logical port the abstraction marks with `isAddress`, and may use the
270
+ abstraction's parameters. Each window has to fit its own bus; the package uses the widest. With no
271
+ `isAddress` at all, it is 32 bits, or 64 if a window needs it.
272
+
273
+ ### In PeakRDL-socgen's layout
274
+
275
+ A flow moving from PeakRDL-socgen may have testbenches or software that import its `soc_addr_map_pkg`. The
276
+ `socgen_package` option writes a package with that layout as well, from the same windows, for every module
277
+ the run generates, the top first. The modules themselves keep using their own packages.
278
+
279
+ ```systemverilog
280
+ localparam MAIN_INTC_NMASTER = 1;
281
+ localparam MAIN_INTC_NSLAVE = 3;
282
+ localparam MAIN_INTC_BASE_ADDRESS = 32'h10000000;
283
+ localparam logic [31:0] RAM_MAIN_INTC_START_ADDRESS = MAIN_INTC_BASE_ADDRESS + 32'h00000000;
284
+ localparam logic [31:0] RAM_MAIN_INTC_SIZE = 32'h00002000;
285
+ localparam logic [31:0] RAM_MAIN_INTC_END_ADDRESS = RAM_MAIN_INTC_START_ADDRESS + RAM_MAIN_INTC_SIZE;
286
+ localparam logic [31:0] RAM_MAIN_INTC_IDX = 32'd0;
287
+ ```
288
+
289
+ - Names follow socgen's: a decoder's constants start with its name with `interconnect` shortened to `intc`,
290
+ and a window's with the name of what it reaches, then the decoder's. socgen names them after its own
291
+ description, which a design does not hold, so `socgen_names` gives the names: `xbar_i:main_interconnect`
292
+ makes `MAIN_INTC`. Two constants that come out the same are refused.
293
+ - `_NMASTER` counts the decoder's `target` and `mirroredInitiator` interfaces the design connects. `_IDX` is
294
+ the rule's `idx`, as above. `_BASE_ADDRESS` is where the decoder's lowest window starts: socgen writes the
295
+ base of the subsystem, which is the same when its first window is at offset 0.
296
+ - `<INTC>_ADDR_RULES` holds the windows in `addr_map_rule_t`, three 32-bit fields `idx`, `start_addr` and
297
+ `end_addr`, the first window in the highest element as in socgen's.
298
+ - Its addresses are 32 bits, so a wider address map is refused, and so is a window reached from outside the
299
+ module, which socgen's layout has no place for.
300
+
301
+ ## What it refuses
302
+
303
+ It raises `ValueError` rather than writing wrong RTL:
304
+
305
+ - errors of the library and of the link, such as an ad hoc reference to a port that does not exist;
306
+ - width mismatches, evaluated after parameter overrides, which neither `archidesc` nor the SCR checks
307
+ catch today, including through an inout, and for a struct or sub-port when its sub-ports are declared (on a
308
+ bus, ends mapped with no logical range may differ, D29);
309
+ - a whole port of a type only the compiler knows, such as an enum or a struct with no sub-ports listed,
310
+ connected to anything but the same type or a constant, or tied to a default given in parts (one default for
311
+ the whole port is cast and checked like any constant, D27);
312
+ - a constant or an inversion into an unpacked struct;
313
+ - an input driven twice or only partly, a logical port with two drivers, two different tie-offs, or a real
314
+ driver and a tie-off on an end that would drive it, and logical bits read but never driven;
315
+ - an element of an array of structs that nothing drives, and a member of one, where the component lists the
316
+ struct's members;
317
+ - a top-level output nothing drives;
318
+ - a constant that does not fit its port, positive or negative, which would silently lose bits (for a type only the
319
+ compiler knows the width of, the compiler refuses it, through the check above);
320
+ - parameter overrides on a reference to a bus or an abstraction, or from a design configuration to its design,
321
+ which nothing here would apply;
322
+ - a view that names a design and a design configuration for another design;
323
+ - a value on a reference to a design or a design configuration, or on a hierarchical instance, for a parameter
324
+ that document or component does not have, and values for one design configuration when the design is linked
325
+ with another;
326
+ - on a generated module: a type parameter, a parameter whose value cannot be compared, such as an assignment
327
+ pattern, and one named like a port or an instance (D36);
328
+ - `tiedValue="open"` on a part of a port, as only a whole port can be left open;
329
+ - a name in a parameter's value that no parameter in scope explains, and a typedef whose name has no package,
330
+ which a generated module could not see;
331
+ - address windows that overlap on one decoder or pass the end of their bus's address space, a window with no
332
+ way to tell its decoder, and constants in the package whose names would come out the same;
333
+ - a parameter override that reaches no module parameter;
334
+ - a parameter or tied value that cannot be evaluated, or is outside its parameter's `minimum` or `maximum`;
335
+ - a design that contains itself, two different modules with the same name, and a generated module named like
336
+ the module of an IP;
337
+ - a name that is not a valid SystemVerilog identifier or is a keyword, such as a component called
338
+ `interconnect`, and an instance named like a port of the module;
339
+ - what would not stay where it is written: a parameter value that is not one value, a module parameter whose
340
+ name is no identifier, and a type that is more than a type's name (D34);
341
+ - a view that names a component instantiation its component lacks, and a component with several component
342
+ instantiations and no view to choose one.
343
+
344
+ ## Limitations
345
+
346
+ - **Decoding is not generated.** The address map is data for a decoder that already exists. Nothing writes
347
+ the crossbar itself.
348
+ - **Each error below is reported, not silently skipped.** Not supported yet: monitor interconnections,
349
+ unpacked arrays (an instance's output that nothing connects is left open, D28), interface ports, indexed part selects, a part select on an inout, a subPort, a struct that is not a
350
+ one-dimensional array, or a port with several dimensions, a part select running the other way from its port, a
351
+ sub-port of an array of structs with no element picked, a constant into several elements of one, an abstraction's default next to tie-offs for some of its bits, an ascending logical range, an inverted inout, two inouts of the module on one net, logical slices on an inout of the module
352
+ not declared from bit 0, abstractors, and type parameters on a generated module.
353
+ - **A generated module's parameters do not configure it.** It is generated for one value of each, and another
354
+ value needs it generated again (D36). The module's own check of that stops a compiler, or else the simulation
355
+ as it starts (D40).
356
+ - **A sub-port of a struct with no sub-ports listed cannot be width-checked.** `xactflow-sv` leaves them out.
357
+ Nor is its type known, so a member that is an enum gets no cast, and slang and Verilator reject what drives it.
358
+ Listing the sub-ports in the component fixes both (`docs/findings.md`, F2).
359
+ - **A width has to be something XactFlow's evaluator can work out.** `xactflow-sv` copies a port's dimensions
360
+ from the module's header as they are written. A call of a package's function there, or a member of a
361
+ struct-valued parameter, such as `cf_math_pkg::idx_width(N)` or `Cfg.AddrWidth`, is refused: the component has
362
+ to give the number, or the function's body. A type the module gets through `import pkg::*` needs its package
363
+ in the component as well.
364
+ - **Anything using a parameter goes through XactFlow's evaluator,** which simplifies some of SystemVerilog's
365
+ rules on sign and width. A value written without parameters is the compiler's to work out, so if it also
366
+ sizes a port, in a way the two read differently, they can disagree. Tools warn about the port width.
367
+ - **Transforms are not applied.** `<xactflow:transforms>` shows as a comment on the instance.
368
+ - **`common` is this plugin's own option, not IP-XACT.** It exists because `archidesc` has no way to fan
369
+ one input out to several instances. A design written in XML can use `externalPortReference` instead.
370
+ - **`archidesc` cannot write a `tiedValue`,** so a design script cannot ask for a port's default value.
371
+ - **Two behaviours rest on a reading the standard does not settle.** The 2022 text has no rule or example
372
+ for either. A `logicalTieOff` drives the receivers on the other side of the bus: 6.7.3.2 makes it the
373
+ connection for that logical port in place of a physical port, and 6.5.5.2 connects interfaces by logical
374
+ bit, but neither says the constant crosses over. `invert` applies on a hierarchical component's own port
375
+ map: 6.7.3.2 defines it for connections to the physical port and makes no exception, but doesn't name
376
+ this case either.
377
+
378
+ ## Compared with Kactus2
379
+
380
+ Kactus2 has the established open-source generator for this, and several ideas here come from studying it:
381
+ ports from the hierarchical component, a net per logical port for slices, and the list of situations a
382
+ generator has to handle. No code comes from it: it is GPL-2, written in C++.
383
+
384
+ Both were run on the same designs, 43 connection scenarios and the XactFlow author's example SoC. On 33 of
385
+ the 44 both pass the same simulation, or compile where there is none, and connect every bit the same way.
386
+ In the other 11 this tool passes and Kactus2 does not. The expected values are this project's own, so these
387
+ are differences to weigh, not proof:
388
+
389
+ - `invert` on a hierarchical component's own port map (1 design): Kactus2 ignores it. The standard makes no
390
+ exception for this case, but doesn't name it.
391
+ - `logicalTieOff` (2 designs): Kactus2's generator does not read it. The standard doesn't settle whether it
392
+ crosses the bus.
393
+ - Default values (3 designs): where `tiedValue="default"` or no default should apply, Kactus2 drives the input
394
+ twice. It also ties an unconnected input to its own default, which 7.5.5 and Table C.2 of the standard
395
+ rule out. This tool did the same, until checking the standard's text.
396
+ - `tiedValue="default"` on a part select (1 design): Kactus2 takes the low bits of the default.
397
+ - An inout tied to a constant (1 design): Kactus2 leaves it open.
398
+ - A port typed `int` (1 design): Kactus2 makes a 1-bit net.
399
+ - A design's parameter in a part select (1 design): Kactus2's output does not compile.
400
+ - The scenario using `common` (1 design), which Kactus2 does not have.
401
+
402
+ Kactus2 also generates Verilog that does not compile if a top-level port is called `<instance>_<port>`.
403
+
404
+ ## Tried on real designs
405
+
406
+ Besides its own tests, the exporter is run on whole SoCs, each chosen for a kind of input the others lack (D24
407
+ in `docs/decisions.md`). The scripts for these are kept outside this repository.
408
+
409
+ - **[Didactic SoC](https://github.com/Edu4Chip/Didactic-SoC)** (Edu4Chip): an IEEE 1685-2022 library made in
410
+ Kactus2, with three levels of hierarchy and design configurations. All eight modules generate, and every bit
411
+ of every instance is driven as in the Verilog Kactus2 generated, but for eight bits of one port that the RTL
412
+ makes narrower than the IP-XACT. Elaborated with the RTL in Didactic's repository, the generated modules fit
413
+ it, once four module parameters the RTL does not have are taken out of one component.
414
+ - **[Croc](https://github.com/pulp-platform/croc)** (PULP): a hand-written SoC of IPs with type parameters and
415
+ struct ports. Its `croc_soc` and `croc_domain` were described in IP-XACT, from components `xactflow-sv`
416
+ imported, and generated. With the generated modules in place of the hand-written ones, Croc's testbench
417
+ elaborates in slang and lints in Verilator with the same messages, and each of the 3769 port bits traced has
418
+ the same driver, and each of the 110 instance parameters the same value. Croc's firmware, nine programs run
419
+ in Verilator, passes on both and prints the same lines at the same simulation times. The generated `croc_soc`
420
+ declares the parameter Croc's testbench gives it, so the testbench is used as it is.
421
+
422
+ ## Development
423
+
424
+ ```bash
425
+ .venv/bin/pytest
426
+ ```
427
+
428
+ - `tests/test_scenarios.py` runs each connection scenario through slang, Verilator and an Icarus Verilog
429
+ simulation. Then it breaks every generated `assign` in turn and requires the simulation to notice.
430
+ - `tests/test_address_map.py` decodes real addresses through a generated module.
431
+ - `tests/test_exporter.py` and `tests/test_top_component.py` hold the rules around these, and every refusal.
432
+ - `tests/test_adversarial.py` holds designs written to get wrong RTL past the exporter, and that once did.
433
+ - `tests/test_type_parameters.py` holds type parameters and arrays of structs as PULP's IPs have them, the last
434
+ of them imported by `xactflow-sv` itself.
435
+ - `tests/test_module_parameters.py` holds the parameters of a generated module, and that each tool refuses an
436
+ instance that gives one another value.
437
+
438
+ Verilator and Icarus Verilog are skipped when not installed; slang always runs. CI installs both from Ubuntu's
439
+ packages.
440
+
441
+ ## License
442
+
443
+ LGPL-3.0. See [LICENSE](LICENSE).