xactflow-archidesc 0.1.0__py3-none-any.whl

xactflow_archidesc/__init__.py

@@ -0,0 +1,44 @@
+__version__ = "0.1.0"
+
+import runpy
+import sys
+from pathlib import Path
+
+import ipxact
+from xactflow import Importer
+
+from .design import BusInterfaceRef, Design, IPInstance, PortRef
+
+
+class ArchiDescImporter(Importer):
+    """Runs a Python design description script and returns the ipxact.Design it describes.
+
+    The script must define a module-level variable named `design`, holding a Design. It runs
+    like `python script.py` would: its own folder is importable while it runs.
+    """
+
+    name = "archidesc"
+
+    def import_(self, source_path: Path, **options: object) -> ipxact.Design:
+        if options:
+            raise ValueError(f"the archidesc importer takes no options, got: {', '.join(options)}")
+        source_path = Path(source_path)
+        if not source_path.is_file():
+            raise ValueError(f"{source_path} is not a file")
+        sys.path.insert(0, str(source_path.parent))
+        try:
+            namespace = runpy.run_path(str(source_path))
+        finally:
+            sys.path.remove(str(source_path.parent))
+        if "design" not in namespace:
+            raise ValueError(f"{source_path} must define a module-level variable 'design'")
+        design = namespace["design"]
+        if not isinstance(design, Design):
+            kind = type(design)
+            raise ValueError(
+                f"{source_path}: 'design' must be a xactflow_archidesc.Design, got {kind.__module__}.{kind.__qualname__}"
+            )
+        return design.build()
+
+
+__all__ = ["__version__", "ArchiDescImporter", "BusInterfaceRef", "Design", "IPInstance", "PortRef"]

xactflow_archidesc/design.py

@@ -0,0 +1,474 @@
+"""design.py: the Design object a design description script builds."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, FrozenSet, List, Optional, Sequence, Set, Tuple, Union
+from xml.sax.saxutils import quoteattr
+
+import ipxact
+from xactflow import Library
+
+# Namespace of the vendor extensions this importer writes.
+XACTFLOW_NAMESPACE = "https://github.com/IP-XACT/XactFlow"
+
+# IP-XACT's naming rule for an instance name (an XML Name in the schema). ":" is also allowed
+# there but left out.
+_INSTANCE_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_.-]*")
+
+_Direction = ipxact.Direction
+_Mode = ipxact.InterfaceMode
+
+# The directions each wire port direction can be connected to by connect().
+_CONNECTABLE = {
+    _Direction.IN: {_Direction.OUT, _Direction.INOUT},
+    _Direction.OUT: {_Direction.IN, _Direction.INOUT},
+    _Direction.INOUT: {_Direction.IN, _Direction.OUT, _Direction.INOUT},
+}
+
+# The bus interface modes that can be connected together (IEEE 1685-2022 SCR 2.4, 2.5, 2.8, 2.9).
+_MODE_PAIRS = {
+    frozenset((_Mode.INITIATOR, _Mode.TARGET)),
+    frozenset((_Mode.INITIATOR, _Mode.MIRRORED_INITIATOR)),
+    frozenset((_Mode.MIRRORED_TARGET, _Mode.TARGET)),
+    frozenset((_Mode.SYSTEM, _Mode.MIRRORED_SYSTEM)),
+}
+
+# connect_bus() picks among these modes by itself. Any other mode must be named with .bus(name).
+_AUTO_MODES = {_Mode.INITIATOR, _Mode.TARGET}
+
+# The modes that act as the target of a connection, where the address mapping goes.
+_TARGET_SIDE_MODES = {_Mode.TARGET, _Mode.MIRRORED_INITIATOR}
+
+
+def _find(items: Sequence[Any], name: str, owner: str, kind: str) -> Any:
+    """Return the item called name, or raise ValueError listing the names that do exist."""
+    for item in items:
+        if item.name == name:
+            return item
+    available = ", ".join(item.name for item in items) or "none"
+    raise ValueError(f"{owner} has no {kind} {name!r}. Available {kind}s: {available}")
+
+
+class IPInstance:
+    """A handle on one component instance"""
+
+    def __init__(self, name: str, component: ipxact.Component) -> None:
+        self.name = name
+        self.component = component
+
+    def port(self, name: str) -> PortRef:
+        ports = self.component.model.ports if self.component.model is not None else []
+        port = _find(ports, name, repr(self), "port")
+        return PortRef(self, port.name, port)
+
+    def bus(self, name: str) -> BusInterfaceRef:
+        bus_interface = _find(self.component.bus_interfaces, name, repr(self), "bus interface")
+        return BusInterfaceRef(self, bus_interface.name, bus_interface)
+
+    def __getattr__(self, name: str) -> PortRef:
+        # Python only calls this for names that are not real attributes. Names starting with "_"
+        # are Python's own lookups, so they stay normal missing attributes.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return self.port(name)
+
+    def __repr__(self) -> str:
+        return f"IPInstance({self.name!r}, {self.component.vlnv})"
+
+
+# Two refs are equal when they point at the same instance and name. The ipxact object they
+# carry is left out of comparing, hashing and printing, it is only there to be read.
+
+
+@dataclass(frozen=True)
+class PortRef:
+    """One port of one component instance, used by Design.connect()."""
+
+    instance: IPInstance
+    name: str
+    port: ipxact.Port = field(compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class BusInterfaceRef:
+    """One bus interface of one component instance, used by Design.connect_bus()."""
+
+    instance: IPInstance
+    name: str
+    bus_interface: ipxact.BusInterface = field(compare=False, repr=False)
+
+
+def _port_kind(ref: PortRef) -> str:
+    if ref.port.wire is not None:
+        return "wire"
+    return "transactional" if ref.port.transactional is not None else "structured"
+
+
+def _describe(ref: PortRef) -> str:
+    detail = ref.port.wire.direction.value if ref.port.wire is not None else _port_kind(ref)
+    return f"{ref.instance.name}.{ref.name} ({detail})"
+
+
+def _port_problem(source: PortRef, target: PortRef) -> Optional[str]:
+    """Return why the two ports cannot be connected, or None if they can.
+
+    Only wire ports have their direction checked. Two transactional or two structured ports are
+    connected as they are.
+    """
+    if source == target:
+        return "cannot connect a port to itself"
+    kinds = (_port_kind(source), _port_kind(target))
+    if kinds[0] != kinds[1]:
+        return f"cannot connect a {kinds[0]} port to a {kinds[1]} port"
+    if kinds[0] != "wire":
+        return None
+    directions = (source.port.wire.direction, target.port.wire.direction)
+    if _Direction.PHANTOM in directions:
+        return "a phantom port cannot be connected"
+    if directions[1] not in _CONNECTABLE[directions[0]]:
+        return "needs one 'in' and one 'out' port, or an 'inout' one"
+    return None
+
+
+def _describe_bus(ref: BusInterfaceRef) -> str:
+    bus = ref.bus_interface
+    return f"{ref.instance.name}.{ref.name} ({bus.bus_type.vlnv}, {bus.mode.value})"
+
+
+def _label(side: object) -> str:
+    """How a connect_bus() side is shown in messages: "cpu", or "cpu.bus_if" when named."""
+    if isinstance(side, BusInterfaceRef):
+        return f"{side.instance.name}.{side.name}"
+    return side.name if isinstance(side, IPInstance) else repr(side)
+
+
+def _watches(monitor: ipxact.BusInterface, other: ipxact.BusInterface) -> bool:
+    return monitor.mode == _Mode.MONITOR and monitor.monitor.interface_mode == other.mode
+
+
+def _can_connect(a: BusInterfaceRef, b: BusInterfaceRef) -> bool:
+    """Same bus type, and modes that can be connected, or a monitor of the other side's mode.
+
+    Only the bus VLNV is compared for now, not the parameter values set on the bus type.
+    """
+    bus_a, bus_b = a.bus_interface, b.bus_interface
+    if bus_a.bus_type.vlnv != bus_b.bus_type.vlnv:
+        return False
+    return frozenset((bus_a.mode, bus_b.mode)) in _MODE_PAIRS or _watches(bus_a, bus_b) or _watches(bus_b, bus_a)
+
+
+def _no_match_reason(candidates_a: List[BusInterfaceRef], candidates_b: List[BusInterfaceRef]) -> str:
+    if not candidates_a or not candidates_b:
+        return "one side has no free bus interface to use"
+    same_bus = any(x.bus_interface.bus_type.vlnv == y.bus_interface.bus_type.vlnv for x in candidates_a for y in candidates_b)
+    return "their modes cannot be connected" if same_bus else "they share no bus type"
+
+
+def _active_interface(ref: BusInterfaceRef, address_mapping: List[str]) -> ipxact.ActiveInterface:
+    """One side of an interconnection. The address mapping only goes on the target side."""
+    on_target_side = ref.bus_interface.mode in _TARGET_SIDE_MODES
+    return ipxact.ActiveInterface(
+        component_instance_ref=ref.instance.name,
+        bus_ref=ref.name,
+        vendor_extensions=list(address_mapping) if on_target_side else [],
+    )
+
+
+def _monitor_interface(ref: BusInterfaceRef) -> ipxact.MonitorInterfaceRef:
+    return ipxact.MonitorInterfaceRef(component_instance_ref=ref.instance.name, bus_ref=ref.name)
+
+
+@dataclass
+class _InstanceRecord:
+    instance: IPInstance
+    component_instance: ipxact.ComponentInstance
+    call_site: str
+
+
+def _caller_site() -> str:
+    """Return "file:line" of the code that called the public Design method."""
+    caller = inspect.currentframe().f_back.f_back  # skip _caller_site itself, then the Design method
+    return f"{caller.f_code.co_filename}:{caller.f_lineno}"
+
+
+def _address_mapping_extensions(where: str, base_addr: Optional[int], size: Optional[int]) -> List[str]:
+    """Turn connect_bus()'s base_addr and size into a vendor extension, if either is given."""
+    attributes = ""
+    for attribute, value, minimum in (("baseAddr", base_addr, 0), ("size", size, 1)):
+        if value is None:
+            continue
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise TypeError(f"{where}: {attribute} must be an int, got {type(value).__name__}: {value!r}")
+        if value < minimum:
+            raise ValueError(f"{where}: {attribute} must be at least {minimum}, got: {value}")
+        attributes += f' {attribute}="0x{value:X}"'
+    if not attributes:
+        return []
+    return [f'<xactflow:addressMapping xmlns:xactflow="{XACTFLOW_NAMESPACE}"{attributes}/>']
+
+
+def _check_type(value: object, expected: type, what: str) -> None:
+    """Raise TypeError if value is not of the expected type."""
+    if not isinstance(value, expected):
+        raise TypeError(f"{what} must be a {expected.__name__}, got {type(value).__name__}: {value!r}")
+
+
+def _parse_vlnv(value: object, what: str) -> ipxact.VLNV:
+    _check_type(value, str, what)
+    fields = value.split(":")
+    if len(fields) != 4 or not all(fields):
+        raise ValueError(f"{what} must be a 'vendor:library:name:version' string, got: {value!r}")
+    return ipxact.VLNV(*fields)
+
+
+def _expression(value: object, what: str) -> str:
+    """Write a Python value as an IP-XACT expression string."""
+    if isinstance(value, bool):  # before int, since bool is an int
+        return "true" if value else "false"
+    if isinstance(value, (int, float, str)):
+        return str(value)
+    raise TypeError(f"{what} must be an int, float, bool or str, got {type(value).__name__}: {value!r}")
+
+
+def _config_element_values(
+    where: str, component: ipxact.Component, parameters: Optional[Dict[str, object]]
+) -> Dict[str, str]:
+    """Turn add_ip()'s parameter overrides into configurableElementValues, keyed by parameterId.
+
+    Only a parameter with resolve="user" can be overridden. The standard says an "immediate"
+    one cannot be modified through configuration, and a "generated" one is set by generators.
+    """
+    if parameters is None:
+        return {}
+    _check_type(parameters, dict, f"{where}: parameters")
+    values = {}
+    for name, value in parameters.items():
+        parameter = _find(component.parameters, name, f"{where}: {component.vlnv}", "parameter")
+        if parameter.parameter_id is None or parameter.resolve != "user":
+            raise ValueError(
+                f"{where}: parameter {name!r} of {component.vlnv} cannot be overridden, it needs a "
+                f"parameterId and resolve=\"user\" (it has parameterId={parameter.parameter_id!r}, "
+                f"resolve={parameter.resolve!r}). This needs fixing in the component file"
+            )
+        values[parameter.parameter_id] = _expression(value, f"{where}: parameter {name!r}")
+    return values
+
+
+def _transforms_extensions(where: str, transforms: Optional[List[str]]) -> List[str]:
+    """Turn add_ip()'s transforms into vendor extensions on the component instance.
+
+    The transformations are only recorded here, a separate transformer applies them later.
+    """
+    transforms = [] if transforms is None else transforms
+    if not isinstance(transforms, (list, tuple)) or not all(isinstance(t, str) and t for t in transforms):
+        raise TypeError(f"{where}: transforms must be a list of non-empty strings, got: {transforms!r}")
+    if not transforms:
+        return []
+    items = "".join(f"<xactflow:transform name={quoteattr(name)}/>" for name in transforms)
+    return [f'<xactflow:transforms xmlns:xactflow="{XACTFLOW_NAMESPACE}">{items}</xactflow:transforms>']
+
+
+class Design:
+    """Describes one flat design: its component instances and how they are connected.
+
+    build() turns it into an ipxact.Design.
+    """
+
+    def __init__(self, vlnv: str, library: Library) -> None:
+        self.vlnv = _parse_vlnv(vlnv, "Design(): vlnv")
+        self.library = library
+        self._instances: Dict[str, _InstanceRecord] = {}
+        self._ad_hoc_connections: Dict[FrozenSet[PortRef], ipxact.AdHocConnection] = {}
+        self._interconnections: List[ipxact.Interconnection] = []
+        self._monitor_interconnections: List[ipxact.MonitorInterconnection] = []
+        # Names of every connection of any kind, so that no two get the same name.
+        self._connection_names: Set[str] = set()
+        # Each "in" wire port already driven, and each bus interface already connected, with the
+        # name of the connection using it.
+        self._driven_ports: Dict[PortRef, str] = {}
+        self._used_bus_interfaces: Dict[BusInterfaceRef, str] = {}
+
+    def add_ip(
+        self,
+        instance_name: str,
+        vlnv: str,
+        parameters: Optional[Dict[str, object]] = None,
+        transforms: Optional[List[str]] = None,
+    ) -> IPInstance:
+        """Add one component instance, resolving its VLNV against the library right away."""
+        call_site = _caller_site()
+        self._check_new_instance_name(instance_name, call_site)
+        where = f"add_ip('{instance_name}')"
+        component_vlnv = _parse_vlnv(vlnv, f"{where}: vlnv")
+        component = self._resolve_component(where, component_vlnv)
+
+        component_instance = ipxact.ComponentInstance(
+            instance_name=instance_name,
+            component_ref=ipxact.VLNVRef(
+                **asdict(component_vlnv),
+                config_element_values=_config_element_values(where, component, parameters),
+            ),
+            vendor_extensions=_transforms_extensions(where, transforms),
+        )
+        instance = IPInstance(instance_name, component)
+        self._instances[instance_name] = _InstanceRecord(instance, component_instance, call_site)
+        return instance
+
+    def connect(self, source: PortRef, target: PortRef) -> None:
+        """Add one ad hoc connection between two whole ports."""
+        for what, ref in (("connect(): source", source), ("connect(): target", target)):
+            _check_type(ref, PortRef, what)
+            self._check_instance(ref.instance, what)
+        where = f"connect({_describe(source)}, {_describe(target)})"
+        problem = _port_problem(source, target)
+        if problem is not None:
+            raise ValueError(f"{where}: {problem}")
+        ports = frozenset((source, target))
+        if ports in self._ad_hoc_connections:
+            raise ValueError(f"{where}: these two ports are already connected")
+        driven = [ref for ref in (source, target) if ref.port.wire is not None and ref.port.wire.direction == _Direction.IN]
+        for ref in driven:
+            if ref in self._driven_ports:
+                raise ValueError(f"{where}: {_describe(ref)} is already driven by {self._driven_ports[ref]}")
+
+        name = self._new_connection_name(f"{source.instance.name}_{source.name}_to_{target.instance.name}_{target.name}")
+        self._ad_hoc_connections[ports] = ipxact.AdHocConnection(
+            name=name,
+            internal_port_references=[
+                ipxact.InternalPortReference(component_instance_ref=ref.instance.name, port_ref=ref.name)
+                for ref in (source, target)
+            ],
+        )
+        self._driven_ports.update((ref, name) for ref in driven)
+
+    def connect_bus(
+        self,
+        a: Union[IPInstance, BusInterfaceRef],
+        b: Union[IPInstance, BusInterfaceRef],
+        *,
+        base_addr: Optional[int] = None,
+        size: Optional[int] = None,
+    ) -> None:
+        """Connect one bus interface of a to one bus interface of b.
+
+        A side given as an IPInstance uses whichever of its free initiator or target interfaces
+        matches. A side given as a BusInterfaceRef uses exactly that one, whatever its mode. A
+        monitor interface becomes a monitor interconnection, watching the other side.
+        """
+        where = f"connect_bus({_label(a)}, {_label(b)})"
+        address_mapping = _address_mapping_extensions(where, base_addr, size)
+        instance_a, candidates_a = self._bus_side(a, f"{where}: a")
+        instance_b, candidates_b = self._bus_side(b, f"{where}: b")
+        if instance_a is instance_b:
+            raise ValueError(f"{where}: cannot connect an instance to itself")
+
+        pairs = [(x, y) for x in candidates_a for y in candidates_b if _can_connect(x, y)]
+        if not pairs:
+            tried = ", ".join(map(_describe_bus, candidates_a + candidates_b)) or "nothing"
+            raise ValueError(
+                f"{where}: nothing to connect, {_no_match_reason(candidates_a, candidates_b)}. Tried: {tried}"
+            )
+        if len(pairs) > 1:
+            choices = ", ".join(f"{_label(x)} with {_label(y)}" for x, y in pairs)
+            raise ValueError(f"{where}: more than one possible pair ({choices}). Pick one with .bus(name)")
+        [(ref_a, ref_b)] = pairs
+
+        # A monitor only watches the other side, which stays free for a normal connection.
+        monitor = next((ref for ref in (ref_a, ref_b) if ref.bus_interface.mode == _Mode.MONITOR), None)
+        connected = [monitor] if monitor is not None else [ref_a, ref_b]
+        for ref in connected:
+            if ref in self._used_bus_interfaces:
+                raise ValueError(f"{where}: {_label(ref)} is already used by {self._used_bus_interfaces[ref]}")
+        has_target_side = any(ref.bus_interface.mode in _TARGET_SIDE_MODES for ref in (ref_a, ref_b))
+        if address_mapping and (monitor is not None or not has_target_side):
+            raise ValueError(f"{where}: base_addr and size need a connection with a target side")
+
+        name = self._new_connection_name(f"{instance_a.name}_to_{instance_b.name}")
+        if monitor is not None:
+            watched = ref_b if monitor is ref_a else ref_a
+            self._monitor_interconnections.append(
+                ipxact.MonitorInterconnection(
+                    name=name,
+                    monitored_active_interface=_monitor_interface(watched),
+                    monitor_interfaces=[_monitor_interface(monitor)],
+                )
+            )
+        else:
+            self._interconnections.append(
+                ipxact.Interconnection(
+                    name=name,
+                    active_interface=_active_interface(ref_a, address_mapping),
+                    other_active_interfaces=[_active_interface(ref_b, address_mapping)],
+                )
+            )
+        self._used_bus_interfaces.update((ref, name) for ref in connected)
+
+    def build(self) -> ipxact.Design:
+        """Return the ipxact.Design described so far."""
+        return ipxact.Design(
+            vlnv=self.vlnv,
+            component_instances=[record.component_instance for record in self._instances.values()],
+            interconnections=list(self._interconnections),
+            monitor_interconnections=list(self._monitor_interconnections),
+            ad_hoc_connections=list(self._ad_hoc_connections.values()),
+        )
+
+    def _new_connection_name(self, base: str) -> str:
+        """Return base, or base with a number added if a connection already has that name."""
+        name, number = base, 1
+        while name in self._connection_names:
+            number += 1
+            name = f"{base}_{number}"
+        self._connection_names.add(name)
+        return name
+
+    def _check_new_instance_name(self, instance_name: object, call_site: str) -> None:
+        _check_type(instance_name, str, "add_ip(): instance name")
+        if not _INSTANCE_NAME.fullmatch(instance_name):
+            raise ValueError(
+                f"add_ip(): instance name must start with a letter or '_', not a digit, followed by letters, "
+                f"digits, '_', '.' or '-' (IP-XACT naming rule), got: {instance_name!r}"
+            )
+        earlier = self._instances.get(instance_name)
+        if earlier is not None:
+            raise ValueError(
+                f"add_ip() at {call_site}: instance name '{instance_name}' is already used "
+                f"by add_ip() at {earlier.call_site}"
+            )
+
+    def _check_instance(self, instance: IPInstance, what: str) -> None:
+        """Check that instance was added to this design."""
+        record = self._instances.get(instance.name)
+        if record is None or record.instance is not instance:
+            raise ValueError(f"{what}: {instance!r} was not added to this design")
+
+    def _bus_side(self, side: object, what: str) -> Tuple[IPInstance, List[BusInterfaceRef]]:
+        """Return the instance of one connect_bus() side, and the bus interfaces to try: the one
+        given, or the instance's initiators and targets that no connect_bus() has used yet."""
+        if isinstance(side, BusInterfaceRef):
+            instance, candidates = side.instance, [side]
+        elif isinstance(side, IPInstance):
+            instance = side
+            candidates = [
+                ref
+                for ref in (BusInterfaceRef(side, bus.name, bus) for bus in side.component.bus_interfaces)
+                if ref.bus_interface.mode in _AUTO_MODES and ref not in self._used_bus_interfaces
+            ]
+        else:
+            raise TypeError(f"{what} must be an IPInstance or a BusInterfaceRef, got {type(side).__name__}: {side!r}")
+        self._check_instance(instance, what)
+        return instance, candidates
+
+    def _resolve_component(self, where: str, vlnv: ipxact.VLNV) -> ipxact.Component:
+        document = self.library.get(vlnv)
+        if document is None:
+            message = f"{where}: no document with VLNV {vlnv} in the library"
+            if self.library.diagnostics:
+                message += f" (library.diagnostics has {len(self.library.diagnostics)} entries, a file may have failed to load)"
+            raise ValueError(message)
+        if not isinstance(document, ipxact.Component):
+            raise ValueError(f"{where}: VLNV {vlnv} is a {type(document).__name__}, not a Component")
+        return document

xactflow_archidesc-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: xactflow-archidesc
+Version: 0.1.0
+Summary: XactFlow importer plugin that serializes an architecture description into an ipxact.Design.
+Author: Maxime Travaillard
+License-Expression: LGPL-3.0-only
+Project-URL: Repository, https://github.com/IP-XACT/XactFlow-archidesc
+Project-URL: Issues, https://github.com/IP-XACT/XactFlow-archidesc/issues
+Keywords: IP-XACT,IEEE 1685,XML,Compiler,XactFlow,Architecture,Design,Importer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xactflow
+Requires-Dist: ipxact-compiler
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: xactflow-design; extra == "dev"
+Dynamic: license-file
+
+# xactflow-archidesc
+
+A [XactFlow](https://github.com/IP-XACT/XactFlow) importer plugin that turns a design described
+in a Python script (which IPs it uses, and how they are connected) into an `ipxact.Design` object,
+built on [`ipxact-compiler`](https://github.com/IP-XACT/ipxact-compiler)'s
+[IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) object model.
+
+IP-XACT `design` files are not made to be handwritten. With this package, a short script lists
+the IP instances, the bus connections between them, and any direct signal connections. The
+importer runs the script and returns the `Design`, which XactFlow's `elaborate()` can then check
+against the IP-XACT rules.
+
+The full description of the format is in
+[`doc/python-design-description.md`](doc/python-design-description.md). It describes the tool
+as it is meant to work once finished, so the current version can differ from it in small ways.
+The differences known today are listed in [Known limitations](#known-limitations).
+
+## Installation
+
+```bash
+pip install xactflow-archidesc
+```
+
+For local development, `requirements-dev.txt` overrides `ipxact-compiler`, `xactflow` and
+`xactflow-design` to local installations. It can be modified to adapt the paths or to keep any
+of them on PyPI.
+
+```bash
+pip install -r requirements-dev.txt -e .
+```
+
+Requires Python >= 3.9.
+
+## Usage
+
+A design script builds a `Design` from an IP library and keeps it in a module-level variable
+named `design`:
+
+```python
+from pathlib import Path
+
+from xactflow import Library
+from xactflow_archidesc import Design
+
+library = Library.scan(Path(__file__).parent / "ip")
+design = Design("example.org:soc:example:0.1", library)
+
+cpu = design.add_ip("cpu", "example.org:ip:cpu:1.0", transforms=["tmrg"])
+uart = design.add_ip("uart", "example.org:ip:uart:1.0", parameters={"BAUDRATE": 115200})
+timer = design.add_ip("timer", "example.org:ip:timer:1.0")
+debug = design.add_ip("debug", "example.org:ip:debug_module:1.0")
+bus = design.add_ip("bus", "example.org:ip:interconnect:1.0")
+
+design.connect_bus(cpu, bus)
+design.connect_bus(bus.bus("m0"), uart, base_addr=0x4001_0000, size=0x1000)
+design.connect_bus(bus, timer, base_addr=0x4002_0000, size=0x1000)
+
+design.connect(debug.debug_req_o, cpu.debug_req_i)
+design.connect(cpu.debug_resp_o, debug.debug_resp_i)
+```
+
+A runnable version of this script, with its IP library, is in
+[`tests/fixtures/soc.py`](tests/fixtures/soc.py).
+
+In short:
+
+- `add_ip(name, vlnv, ...)` adds an IP instance, with optional `parameters` overrides and
+  `transforms`.
+- `connect_bus(a, b, ...)` connects a bus interface of `a` to one of `b`. It picks them by
+  itself, or uses the one named with `instance.bus("name")`. `base_addr`/`size` place a target
+  in the address map.
+- `connect(source, target)` connects two ports. `instance.some_port` is short for
+  `instance.port("some_port")`.
+
+Each call checks its arguments right away, so a mistake is reported on the line that made it.
+All the details are in [the format description](doc/python-design-description.md#the-design-object).
+
+Once installed, the importer registers itself under the `xactflow.importers` entry point group
+as `archidesc`, so it runs as a XactFlow CLI command. With `xactflow-design` installed too,
+`--then` hands the result straight to that exporter. To try it on the example of this repo,
+create a virtual environment and install the package in it first. The `xactflow` command only
+exists inside that environment, so activate it again in each new terminal:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+xactflow archidesc tests/fixtures/soc.py --then design --output out/
+```
+
+This writes `out/example.xml`, named after the design's VLNV name.
+
+Or as a library, for example to elaborate the design first:
+
+```python
+from pathlib import Path
+
+from xactflow import Library, elaborate
+from xactflow_archidesc import ArchiDescImporter
+from xactflow_design import DesignExporter
+
+design = ArchiDescImporter().import_(Path("soc.py"))
+elaborated = elaborate(design, Library.scan("ip"))
+DesignExporter().export(design, Path("out"))
+```
+
+The script runs like `python soc.py` would: a helper module next to it can be imported, and a
+relative path in it is read from the current folder. `Path(__file__).parent` gives paths
+that do not depend on where the command is run from. The importer takes no options.
+
+## Design notes
+
+- **Vendor extensions.** Two things this format records have no place in IP-XACT, so they are
+  written as vendor extensions in the `https://github.com/IP-XACT/XactFlow` namespace:
+  `<xactflow:transforms>` on a component instance, listing the transformations in order, and
+  `<xactflow:addressMapping baseAddr="..." size="..."/>` on the target side of a bus
+  connection (a target or mirrored initiator interface).
+- **Transformations are not applied here.** A separate tool, a transformer, reads
+  `<xactflow:transforms>`, applies the transformations and returns the changed `Design`.
+- **Parameter overrides follow the standard.** Only a parameter with a `parameterId` and
+  `resolve="user"` can be overridden. The standard says an `immediate` parameter (the default)
+  cannot be changed through configuration.
+- **Connection names are unique.** A bus connection is named `<a>_to_<b>` and a port connection
+  `<instance>_<port>_to_<instance>_<port>`. A number is added when a name is already taken, by
+  any kind of connection.
+- **Monitors.** Connecting a monitor interface adds a `monitorInterconnection`. The interface it
+  watches stays free for a normal connection.
+
+## Known limitations
+
+- `connect_bus` compares the bus VLNV of the two interfaces, but not the parameter values set
+  on the bus type (a data width, for example). Comparing them needs XactFlow to evaluate
+  those values first. This should be changed in a future update.
+- XactFlow's `elaborate()` does not use the parameter overrides from `add_ip` yet. They are
+  written to the design and exported, but not applied during elaboration.
+- `connect` checks direction only for wire ports. Two transactional or two structured ports
+  are connected with no further check, only a mix of the two kinds is refused.
+- `connect` does not compare port widths.
+- A design describes one level only. Hierarchical designs, a real address mapping (instead of
+  the `addressMapping` placeholder) and protocol bridges are not handled yet, see the open
+  questions at the end of [the format description](doc/python-design-description.md).
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-dev.txt -e .
+pytest
+```
+
+The tests use a small IP library in `tests/fixtures/library`. `tests/test_end_to_end.py` runs
+the example script through the importer, elaborates the result, exports it with
+`xactflow-design` and reads the file back.
+
+## License
+
+LGPL-3.0. See [LICENSE](LICENSE).

xactflow_archidesc-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+xactflow_archidesc/__init__.py,sha256=yTxSxX-tm1avfhm22FJL4vH_WLEUY4oVHe1G32RYrHk,1587
+xactflow_archidesc/design.py,sha256=yscDFicctf_Ih2iXKj6NQXs90ep47AdQ_lwUI_ZSuFc,21564
+xactflow_archidesc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xactflow_archidesc-0.1.0.dist-info/licenses/LICENSE,sha256=7pB5GeyIycAXsfi2CNsglgtlmK78xP5YggvelV1l7Tw,7651
+xactflow_archidesc-0.1.0.dist-info/METADATA,sha256=wPaIA7AFmsBFG1Kr-_x5kqecD07Yj06zaT31BuGu2i4,8094
+xactflow_archidesc-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+xactflow_archidesc-0.1.0.dist-info/entry_points.txt,sha256=ZI-P-9ATmsHVT-KEHsRP1wE0pNr44nfpdSIe3iaXAIU,70
+xactflow_archidesc-0.1.0.dist-info/top_level.txt,sha256=X3oWkPAI7KnjqGWjhz9FC62r0CV2sPm8WmG602Vqumg,19
+xactflow_archidesc-0.1.0.dist-info/RECORD,,

xactflow_archidesc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xactflow_archidesc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xactflow.importers]
+archidesc = xactflow_archidesc:ArchiDescImporter

xactflow_archidesc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,164 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

xactflow_archidesc-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xactflow_archidesc