| name | rtl-ipxact-gen |
| description | Generate IEEE 1685-2014 IP-XACT XML descriptor from RTL source — 'generate IP-XACT', IP handoff, or SoC/EDA integration needing component XML. |
| user-invocable | true |
| argument-hint | [module-name] |
| allowed-tools | Bash, Read, Write, Edit, Task, Grep, Glob |
Generate a standards-compliant IP-XACT (IEEE 1685-2014) XML descriptor for an RTL module. Extracts ports, parameters, and bus interfaces directly from the SystemVerilog source to ensure the descriptor stays accurate as RTL evolves. Output: `ipxact/{module_name}.xml`, validated against the IEEE 1685-2014 schema.
<Use_When>
- An RTL module needs an IP-XACT descriptor for EDA tool integration (Vivado, Quartus, Genus).
- IP handoff to a customer or partner requires IP-XACT.
- A SoC integration flow requires IP-XACT for automated port connection.
</Use_When>
<Do_Not_Use_When>
- Only Markdown documentation is needed — use
rtl-document instead.
- An IP-XACT descriptor already exists and is current.
- The module is internal-only with no EDA tool integration requirement.
</Do_Not_Use_When>
<Why_This_Exists>
IP-XACT is the industry standard for IP description and enables automated integration in EDA tools. Manual XML authoring is error-prone; generating from RTL source ensures port widths and parameter values match implementation. The skill splits deterministic extraction (port/parameter lists) from interpretive mapping (bus interface classification), making the contract surface explicit.
</Why_This_Exists>
Prerequisites
- RTL source at
rtl/{module}/{module}.sv must exist.
- Optional:
sv_to_ipxact CLI installed for schema-validated generation.
If the prerequisite is missing: WARNING — recommend running /rtl-agent-team:rtl-p4-implement first. Proceed with available artifacts; the orchestrator adapts scope.
| Path | Role |
|------|------|
| `templates/component-template.xml` | IP-XACT 2014 XML skeleton: vendor/library/name/version, busInterfaces, model/ports, parameters, memoryMaps stubs. |
| `scripts/gen_ipxact.py` | Deterministic IEEE 1685-2014 XML generator: parses SV module header (ANSI ports/parameters), emits VLNV + model/ports (widths kept as expressions) + parameters + fileSets. Stdlib-only fallback when `sv_to_ipxact` is unavailable. |
| `references/ipxact-conventions.md` | Port direction mapping, required XML sections, bus interface identification rules, anti-patterns. |
| `examples/` | Worked example: `pixel_fifo.sv` input + generated `pixel_fifo.xml` + README with the exact command and output checks. |
<Responsibility_Boundary>
- Scripts handle deterministic extraction:
sv_to_ipxact (when installed) parses SV source and emits schema-validated XML; rtl-explorer extracts port/parameter lists as structured data when the CLI is unavailable.
- LLM handles interpretive mapping: bus interface type classification (AXI3/AXI4/APB/AHB), memory map register inference, and vendor/library/version field population.
- Contract surface: output XML must pass IEEE 1685-2014 schema validation; conventions in
references/ipxact-conventions.md.
</Responsibility_Boundary>
1. Read `references/ipxact-conventions.md` for port direction mapping, required XML section order, and bus interface identification rules.
2. Attempt `sv_to_ipxact -i rtl/{module}/{module}.sv -o ipxact/{module}.xml --ipxact-2014 --validate`. If exit code 0, proceed to step 5. If `sv_to_ipxact` is not installed, run `python3 {plugin_root}/skills/rtl-ipxact-gen/scripts/gen_ipxact.py rtl/{module}/{module}.sv -o ipxact/{module}.xml` (`{plugin_root}` = plugin root resolved from `.rat/state/spawn-context.json`) for deterministic port/parameter extraction, then proceed to step 3.
3. Spawn `rtl-explorer` (see Tool_Usage) to extract all ports (name/direction/width), parameters, and identify AXI/APB/AHB bus interface groups by port name prefix.
4. Spawn `ipxact-generator` (see Tool_Usage) to write `ipxact/{module}.xml` — enriching the gen_ipxact.py output (or `templates/component-template.xml` scaffold) with bus interface and memory map sections. Preserve `i_`/`o_`/`io_` prefixes verbatim in `spirit:name`. Map `{domain}_clk` ports to clock roles and `{domain}_rst_n` to reset roles.
5. Validate: `xmllint --schema ipxact/{module}.xml --noout` (if xmllint available). Report PASS or FAIL with error summary.
6. Report the generated file path and validation result to the user.
Apply steps 1-6 to every requested module — do not stop after the first.
<Tool_Usage>
RTL extraction (sv_to_ipxact unavailable):
Task(subagent_type="rtl-agent-team:rtl-explorer",
prompt="Read rtl/dma_controller/dma_controller.sv. Extract all ports (name/direction/width), parameters, and identify AXI/APB/AHB bus interfaces by port name grouping. Port direction: i_ = input, o_ = output, io_ = inout. Clocks match {domain}_clk, resets match {domain}_rst_n. Provide structured summary for IP-XACT generation.")
XML authoring (after extraction):
Task(subagent_type="rtl-agent-team:ipxact-generator",
prompt="Generate IEEE 1685-2014 IP-XACT XML for dma_controller. Ports: {port_list}. Parameters: {param_list}. Bus interfaces: AXI4-Lite slave. Scaffold: {plugin_root}/skills/rtl-ipxact-gen/templates/component-template.xml. Preserve i_/o_/io_ prefixes in spirit:name. Map {domain}_clk to clock roles, {domain}_rst_n to reset roles. Write ipxact/dma_controller.xml.")
</Tool_Usage>
DMA controller with AXI4-Lite slave interface and 5 parameters.
examples/
`rtl-explorer` extracts 24 ports and 5 parameters; `ipxact-generator` produces valid IEEE 1685-2014 XML with one AXI4-Lite bus interface mapped; `xmllint` validation passes.
Module with parameterized port widths (e.g., `input logic [DATA_WIDTH-1:0] i_data`).
examples/
Port width recorded as expression `DATA_WIDTH` in IP-XACT rather than a hardcoded number; parameter `DATA_WIDTH` appears in the parameters section with its default value.
Bus interface type is ambiguous — ports match both AXI3 and AXI4 naming.
examples/
Generation pauses; user is asked to confirm AXI3 vs AXI4. XML is not delivered until the bus type is confirmed. No bus interface type is assumed or invented.
<Escalation_And_Stop_Conditions>
- XML schema validation fails → report the exact validation errors; do not deliver invalid XML.
- Bus interface type is ambiguous → ask the user to confirm before generating the busInterfaces section.
- Complex parameterized widths → document as expressions in
spirit:vector elements; do not resolve to literals.
- RTL source has syntax errors → report file and line; do not attempt generation on unparseable source.
</Escalation_And_Stop_Conditions>
Output
ipxact/{module_name}.xml — IEEE 1685-2014 IP-XACT XML: component description, port maps, bus interfaces, parameters, and register maps (when a register interface is present).- Schema validation result:
PASS or FAIL: {error summary}.
<Final_Checklist>
