Repository navigation
Releases
v0.3.1
xactflow-archidesc v0.3.1
connect_clk()andconnect_rst()connect a clock or reset to every IP port with theisClockorisResetqualifier (#10).- The generated component's view names the SoC module (
moduleName), with an optionalmodule_nameinDesign()(#11).
Full Changelog: v0.3.0...v0.3.1
v0.3.0
xactflow-archidesc v0.3.0
This release moves xactflow-archidesc to XactFlow 0.4.0, where importers and exporters share one
Library, and lets a design script declare the ports and bus interfaces the SoC offers to the
outside. The importer now produces the component containing the design next to the design
itself. It contains breaking changes: see "Upgrading" below.
XactFlow 0.4.0 (#9)
xactflow-archidesc now requires xactflow>=0.4.0, whose plugins share one Library per run.
ArchiDescImporter.import_(source_path, library) adds what the script builds to that library as
targets, instead of returning it. With --then, the exporter receives the same library, holding
the imported documents and everything scanned from --lib, so it can link the design:
xactflow archidesc soc.py --lib ip/ --lib bus_definitions/ --then design --output out/
The documents are rebuilt from the script on every run, so they replace the ones with the same
VLNV in the library, for example the previous output when out/ is also given with --lib.
Top-level ports and bus interfaces (#8)
A script can now declare the IOs of the SoC, and connect them to the instances:
clk = design.add_port("in", "clk_i", connect=cpu.clk_i)
irq = design.add_port("out", "irq_o", width=4)
ext = design.add_bus("ext_if", "example.org:bus:simplebus:1.0", "target", connect=bus.bus("s1"))
add_port(direction, name, width=None, *, connect=None)adds a top-level wire port.connect()
pairs it with an instance port of the same direction, or aninoutone, written as an
externalPortReference. A top-levelinport can drive several instance ports; a top-level
outport is driven once.add_bus(name, bus_type, mode, *, group=None, connect=None)adds a top-level bus interface.
connect_bus()pairs it with an instance interface of the same bus type and the same mode, as
the standard requires (SCR 2.4 to 2.10), written as ahierInterface. The top-level interface
copies the abstraction types and port maps of the internal one, and each mapped port becomes a
top-level port named<bus>_<logical port>.build_component()returns theipxact.Componentcontaining the design: its top-level ports
and bus interfaces, and ahierarchicalview whosedesignInstantiationrefers to the design.
link()finds the component through that view and checks the top-level connections against it.- The importer adds both the component and the design to the library. Write them with
--then componentand--then design.
Documentation
The README and the format description (.md and .tex) describe the shared library, the
top-level IOs and the generated component. The worked example now exposes two top-level ports.
Upgrading
xactflow>=0.4.0is required. See its release notes for its own breaking changes. The
exporters need a release for this API too: usexactflow-design>=0.2.1and
xactflow-component>=0.2.1.ArchiDescImporter.import_()takes the library as its second argument and returnsNone.
Read the results fromlibrary.targets(), e.g.library.targets(ipxact.Design).Design(vlnv, library)now names the SoC. The design gets.designappended to the name and
the component.component:"example.org:soc:example:0.1"gives the design
example.org:soc:example.design:0.1and the componentexample.org:soc:example.component:0.1.
design.vlnvis the design's VLNV, anddesign.component_vlnvis the component's.- The exported design file changes name accordingly, e.g.
example.org_soc_example.design_0.1.xmlinstead ofexample.org_soc_example_0.1.xml. Update
anything that refers to the old VLNV or file name. - A script that links its own design and uses top-level IOs adds the component to its library
first,library.add(design.build_component()), solink()can check them.
Known limitations
- A top-level bus interface copies whole internal ports: a port map onto part of a port is
refused, and a copied port keeps its width as written, even when it refers to a parameter of
the internal component. connect()does not compare the width of a top-level port with the instance port.
Full Changelog: v0.2.0...v0.3.0
v0.2.0
xactflow-archidesc v0.2.0
This release moves xactflow-archidesc to ipxact-compiler 0.2.0 and XactFlow 0.3.0, makes
connect_bus() follow more of the IEEE 1685-2022 connection rules, and fixes the importer when
several scripts are run in one process. It contains breaking changes: see "Upgrading" below.
ipxact-compiler 0.2.0 and XactFlow 0.3.0
xactflow-archidesc now requires ipxact-compiler>=0.2.0 and xactflow>=0.3.0. The parameter
overrides given to add_ip() are recorded as ipxact.Expression objects in
component_ref.config_element_values.
Bus connections (#1, #5)
connect_bus()accepts two bus definitions when oneextendsthe other, directly or not, as
link()already did (SCR 2.2) (#5).- A system and a mirrored-system interface are only connected when their
groupis the same
(SCR 2.13). Otherwise the error saystheir system groups differ(#1). - A monitor of a system or mirrored-system interface needs the same
groupas the interface it
watches (SCR 4.4).
Parameter values (#7)
add_ip() raises ValueError for a parameter value that is not a usable expression: an empty or
blank string, or a float that is not finite (nan, inf).
Importer (#2)
The modules a script imports from its own folder (a helpers.py next to it, for example) are
forgotten once the script has run. A second script in another folder no longer gets the first
script's helpers. Packages installed below the script's folder, in a .venv for example, are
left alone. If the script fails, its own error is the one raised.
Type hints (#6)
The package ships py.typed, and its type hints now pass mypy. CI runs mypy on every supported
Python version.
Documentation (#3, #4)
- The
.texformat description useslink()instead ofelaborate(), like the.md(#3). - The worked example of the format description names the interconnect ports, so it no longer
fails with "more than one possible pair", and its interconnect VLNV has all four fields (#4). - The format description and the README describe the new connection rules.
Upgrading
ipxact-compiler>=0.2.0andxactflow>=0.3.0are required. See their release notes for their
own breaking changes.config_element_valuesholdsipxact.Expressionobjects instead of strings. Use.valueto
get the text.connect_bus()now refuses connections it used to accept: a system and a mirrored-system
interface with different groups, and a monitor whose group differs from the system interface
it watches.add_ip()now refuses empty, blank and non-finite parameter values.- With xactflow-design 0.2.0, the exported design file is named
<vendor>_<library>_<name>_<version>.xml, for exampleexample.org_soc_example_0.1.xml.
Full Changelog: v0.1.1...v0.2.0
v0.1.1
Update to ipxact-compiler v0.2.0 and XactFlow v0.3.0
Full Changelog: v0.1.0...v0.1.1
v0.1.0
First public release of xactflow-archidesc, a XactFlow importer plugin that turns a design
described in a Python script (its IP instances, bus connections and port connections) into an
IEEE 1685-2022 ipxact.Design object.
What's included
- A
DesignAPI for design scripts:add_ip()to add IP instances from an IP-XACT library,
connect_bus()to connect bus interfaces, andconnect()to connect ports directly. add_ip()resolves each VLNV right away, records parameter overrides as
configurableElementValues(only forresolve="user"parameters, as the standard requires),
and records requested transformations for a separate transformer tool to apply.connect_bus()picks matching initiator/target interfaces by itself, connects the other
modes (mirrored, system, monitor) when they are named, and can record a target's address
withbase_addr/size.connect()checks port directions, refuses a second driver on an input, and gives every
connection a unique name.- Clear errors on the line that made the mistake: unknown VLNVs, parameters or ports,
duplicate names, interfaces already used, or more than one possible bus pair. ArchiDescImporter, registered under thexactflow.importersentry point, so
xactflow archidesc design.pyruns a script from the CLI, and--then designexports the
result to XML throughxactflow-design.- A test suite that includes an end-to-end run of the example: import,
elaborate()with no
diagnostics, export to XML withxactflow-design, and read the file back.
Status
This is an early, alpha-stage release. The format description in doc/ describes the tool as
it is meant to work once finished. The known differences are listed in the README: bus type
parameter values are not compared yet, elaborate() does not apply parameter overrides yet,
only wire ports are checked in detail, and port widths are not compared. Hierarchical designs
and a real address mapping are planned for later.
License
LGPL-3.0.
Full Changelog: https://github.com/IP-XACT/XactFlow-archidesc/commits/v0.1.0