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.
- xactflow_rtl_gen-0.3.0/LICENSE +164 -0
- xactflow_rtl_gen-0.3.0/MANIFEST.in +5 -0
- xactflow_rtl_gen-0.3.0/PKG-INFO +443 -0
- xactflow_rtl_gen-0.3.0/README.md +413 -0
- xactflow_rtl_gen-0.3.0/docs/decisions.md +825 -0
- xactflow_rtl_gen-0.3.0/docs/findings.md +35 -0
- xactflow_rtl_gen-0.3.0/pyproject.toml +56 -0
- xactflow_rtl_gen-0.3.0/pytest.ini +2 -0
- xactflow_rtl_gen-0.3.0/requirements-dev.txt +4 -0
- xactflow_rtl_gen-0.3.0/setup.cfg +4 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/__init__.py +116 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/address_map.py +391 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/keywords.py +28 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/py.typed +0 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen/top_writer.py +2513 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/PKG-INFO +443 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/SOURCES.txt +38 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/dependency_links.txt +1 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/entry_points.txt +2 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/requires.txt +9 -0
- xactflow_rtl_gen-0.3.0/src/xactflow_rtl_gen.egg-info/top_level.txt +1 -0
- xactflow_rtl_gen-0.3.0/tests/builders.py +389 -0
- xactflow_rtl_gen-0.3.0/tests/conftest.py +25 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/lib/master.xml +55 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/lib/sbus.xml +9 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/lib/sbus_rtl.xml +65 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/lib/slave.xml +65 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/master_core.sv +27 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/slave.sv +17 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/struct_ips.sv +15 -0
- xactflow_rtl_gen-0.3.0/tests/fixtures/rtl/tb_soc.sv +30 -0
- xactflow_rtl_gen-0.3.0/tests/test_address_map.py +226 -0
- xactflow_rtl_gen-0.3.0/tests/test_adversarial.py +2040 -0
- xactflow_rtl_gen-0.3.0/tests/test_exporter.py +564 -0
- xactflow_rtl_gen-0.3.0/tests/test_generated_rtl.py +93 -0
- xactflow_rtl_gen-0.3.0/tests/test_module_parameters.py +377 -0
- xactflow_rtl_gen-0.3.0/tests/test_scenarios.py +875 -0
- xactflow_rtl_gen-0.3.0/tests/test_socgen_package.py +281 -0
- xactflow_rtl_gen-0.3.0/tests/test_top_component.py +457 -0
- 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,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).
|