Skip to content

Design proposal — 0.15.0: IP-XACT ports + bus interfaces

Status: proposed (decisions in §5). Target: 0.15.0. Continues workstream B of 0.14.0-git-and-ipxact.md: 0.14.0 added the IP-XACT 2022 output mode and parameter mapping (the optional, ignorable [ipxact.parameters] section) and explicitly deferred ports and bus interfaces. This release maps those, finishing the "richer IP-XACT" arc so a vendor tool can wire a packaged core into a block design.

1. Background — where 0.14.0 left it

to_ipxact(manifest, std) (ipxact.py) emits a 1685-2014 or 1685-2022 component: VLNV, a model of one view + componentInstantiation per [targets.*], the fileSets, and (from [ipxact.parameters]) a parameters block — all validated against the official vendored XSDs (both standards) by test_ipxact_xsd.py. What it does not emit is the part that describes a core's interface: its ports and its bus interfaces. Those are what let a tool auto-connect the core (e.g. recognize an AXI slave and wire it to an interconnect).

2. The core constraint (unchanged from 0.14.0)

Ports and bus interfaces describe the HDL interface, which ip.toml does not capture and the tool cannot infer without parsing HDL port/parameter lists (we have a token lexer, not a port parser — and the "no full parser" stance holds). So, as decided for parameters, the data is declared in the manifest (decision B-opt1): additive, optional [ipxact.*] tables the producer fills in, mapped straight through. No HDL parsing.

3. What to add

3a. Ports — model/ports/port

IP-XACT carries ports under ipxact:model/ipxact:ports. For a wire port the shape is name + wire (direction ∈ in/out/inout, optional vectors/vector/{left,right} for width). Both standards model this the same way (modulo namespace).

Proposed manifest ([ipxact.ports]): 

[ipxact.ports]
clk   = "in"                              # scalar shorthand: a 1-bit port, given direction
rst_n = "in"
data  = { direction = "out", width = 8 }  # width N -> vector [N-1:0]
addr  = { direction = "out", left = 11, right = 0 }   # explicit left/right
- A scalar value is the direction of a 1-bit port. - A table carries direction (required) and width as either width = N (→ left = N-1, right = 0) or explicit left/right. width and left/right are mutually exclusive. - Transactional/structured ports are out of scope (wire ports only).

3b. Bus interfaces — busInterfaces/busInterface

A bus interface names the core's role on a standardized bus. Its IP-XACT shape: name, busType (a VLNV reference to a bus definition), abstractionTypes/abstractionType/ abstractionRef (a VLNV to an abstraction definition), an interface mode, and portMaps mapping each logical (bus) port to a physical (this core's) port.

Proposed manifest ([ipxact.busInterfaces.<name>]): 

[ipxact.busInterfaces.s_axi]
busType         = "amba.com:AMBA4:AXI4Lite:r0p0_0"        # VLNV of the bus definition
abstractionType = "amba.com:AMBA4:AXI4Lite_rtl:r0p0_0"    # VLNV of the abstraction def
mode            = "target"                                # canonical (2022) vocabulary
[ipxact.busInterfaces.s_axi.portMaps]
ACLK    = "clk"            # logical (bus) port = physical (core) port
ARESETn = "rst_n"
AWADDR  = "addr"

The 2014 ↔ 2022 catch (the main design wrinkle). The interface-mode vocabulary changed: 2014 uses master/slave (+ system/mirrored*), 2022 uses initiator/target (+ system/mirrored*). The manifest must use one canonical vocabulary and the exporter must translate per target standard.

4. Options considered

  • Scope split. Ports are cheap and self-contained; bus interfaces are heavier (two VLNV refs, portMaps, the mode-vocabulary translation). Option (a): both in 0.15.0 as staged commits. Option (b): ports in 0.15.0, bus interfaces in 0.16.0. Recommend (a) but commit ports first so it can ship alone if bus-interface modeling needs more bake.
  • Mode vocabulary. Manifest could use 2014 names, 2022 names, or a neutral set. Use the 2022 vocabulary (initiator/target/system/mirroredInitiator/mirroredTarget/ monitor) as canonical and translate down to 2014 (master/slave/…) on 2014 export — it is the current standard and the natural default going forward.
  • VLNV refs. busType/abstractionType are free-form VLNV strings the producer supplies (parsed with the existing Vlnv/4-field grammar, emitted as the four IP-XACT attributes). The tool does not resolve or validate the referenced bus/abstraction definitions (they live in vendor libraries) — it carries them, mirroring the encrypted-IP "carry, not break" stance.

5. Decisions (proposed)

  1. Data source: B-opt1 again — declare in ip.toml; no HDL parsing.
  2. Ports: [ipxact.ports], scalar (1-bit, direction) or table (direction + width | left/right); wire ports only.
  3. Bus interfaces: [ipxact.busInterfaces.<name>] with busType, abstractionType (VLNV strings), mode (canonical 2022 vocabulary), and a portMaps logical→physical table. VLNV refs are carried, not resolved.
  4. 2014/2022: translate the mode vocabulary on 2014 export; validate both standards against their vendored XSDs (as for 2014.0's parameters).
  5. Schema: additive and ignorable (older hdlpkg skips [ipxact.*]) → no schema bump; unknown [ipxact.*] keys keep being rejected (no silent drops).
  6. Bundling: ports + bus interfaces in 0.15.0, staged so ports can ship alone.

6. Phasing — small staged commits (toward 0.15.0)

Each chunk is code + tests + doc + tracker update, gates green, on develop:

  1. Ports — IpxactPort model + [ipxact.ports] parsing (scalar/table, width vs left/right, validation) + model/ports export, both standards, XSD-validated.
  2. Bus interfaces — IpxactBusInterface model + [ipxact.busInterfaces.*] parsing (VLNV refs, mode, portMaps) + busInterfaces export with the 2014/2022 mode translation, both standards, XSD-validated against real example interfaces.
  3. Docs close-out — architecture/INDEX/user-guide (+ an example core gaining [ipxact.ports]/[ipxact.busInterfaces]); cut 0.15.0 via /release.

(Ports and bus interfaces are independent; if the bus-interface mode/portMap modeling needs more bake, ports ship as 0.15.0 and bus interfaces follow as 0.16.0.)

7. Out of scope (still deferred)

Memory maps / address blocks (a large IP-XACT subtree), transactional ports, and resolving the referenced bus/abstraction definitions. Supply-chain (Sigstore signing) and confidential IP (IEEE 1735) remain their own future releases — see the roadmap in progress_tracker.md.