ipxactlint is the EDAUtils linter for IP-XACT (IEEE 1685). A file can pass schema validation and still describe an IP that cannot be built or integrated: registers that overlap, a field wider than its register, a logical port mapped to a port of the wrong direction, a VLNV reference to a bus definition that does not exist. IEEE 1685 Annex B lists these as semantic consistency rules (SCRs). ipxactlint checks them, plus the name-uniqueness and local-reference constraints of the schemas, which an XSD or JAXB load does not check. It reports each violation with the file, the line, the rule and how to fix it.
At a glance
- Checks all 224 IEEE 1685-2014 and all 175 IEEE 1685-2009 Annex B semantic consistency rules (SCRs)
- IEEE 1685-2022 documents checked with the 1685-2014 rules (2022 renames and value types mapped) plus 22 EDAUtils EU-2022 rules on what 2022 added, derived from the 2022 schema, User Guide and release notes (not IEEE SCR numbers)
- Schema identity constraints a JAXB or XSD load does not check: unique names (K.1) and local references that resolve (K.2)
- Lints component, design, design configuration, bus definition, abstraction definition, abstractor, catalog and generator chain documents
- Cross-document rules across a library given with -lib, or across a whole directory with -in
- Every finding gives file, line, SCR number, rule name, what is wrong and a Fix: hint
- -lint_rules prints every rule with its 2014 and 2009 numbers and its fix hint, then the EU-2022 rules with their fix and source
- Waiver files by rule name, SCR number or EU-2022 id, file and message globs and line, with a mandatory reason and an optional owner
- Waiver report, stale-waiver warnings, and -waive_all / -gen_waivers to write a waiver file for the next run
- Exit status 0 clean, 2 lint errors, 1 usage or unreadable input, 10 no license: usable as a CI gate
- Ships with an AGENTS.md for AI agents; available as a tool in the EDAUtils AI SDK and as a FECAD static check
IEEE 1685 version coverage
ipxactlint reads documents as plain XML, so one rule implementation serves every revision. Each finding is reported under the rule number of the document's own standard, and a rule that one standard does not have is not applied to its documents.
| Standard | Rules applied | Notes |
|---|---|---|
| IEEE 1685-2009 | All 175 Annex B SCRs, 2009 numbering | SPIRIT 1.4 and 1.5 documents are treated the same way |
| IEEE 1685-2014 | All 224 Annex B SCRs, 2014 numbering | |
| IEEE 1685-2022 | The 1685-2014 rules, 2014 numbering, plus the 22 EDAUtils EU-2022-* rules | The 2022 standard's own Annex B is not available to the tool, so 2022 Annex B numbering is not used. The 2022 renames (initiator/target, access policies, array/dim, componentInstanceRef, initiatorRef, clearbox) and value types are mapped. SCR 8.3-8.15 are not applied, since 2022 filters a child's access by its parents'; EU-2022-ACC-3 reports a filtered access as a Warning instead. A Note says so for every 2022 document. |
Rules overview
For 1685-2009 and 1685-2014, the rules follow the tables of IEEE 1685 Annex B, plus two schema identity constraints. ipxactlint -lint_rules prints every rule with its numbers in both standards and its fix hint. Every rule has at least one failing regression case, the 22 EU-2022 rules included.
| Table | Rules | Examples |
|---|---|---|
| B.1 | Cross-references | VLNV references, and port connection equivalence classes |
| B.2 | Interconnections | interfaces connected in a design |
| B.3 | Channels, bridges, abstractors | mirrored interfaces, bridges, abstractor use |
| B.4 | Monitors | monitor interfaces and their connections |
| B.5 | Configurable elements and parameters | 1685-2009: XPath dependencies |
| B.6 | Port maps and ports | directions, widths, port connection compatibility |
| B.7 | Registers and fields | overlaps, fields that fit their register |
| B.8 | Memory maps | access consistency, e.g. read-only registers |
| B.9 | Addressing | addresses, ranges and widths |
| B.10 | Hierarchical families | interfaces exported through hierarchy |
| B.11 | Hierarchical memory maps | a hierarchical slave map against the sub-instance map it exports |
| B.12 | Constraints | |
| B.13 | Design configurations | |
| B.14 | Expression value types | 1685-2009: rules needing external knowledge |
| B.15 | Presence | isPresent |
| B.16 | Access handles | |
| K.1 | uniqueNames | schema identity constraint: names unique in their scope |
| K.2 | localRefExists | schema identity constraint: local references resolve |
Cross-document rules need the documents a file references: give them with -lib, or lint a directory. Without either, a Note says the cross-document rules were skipped. Expressions in 2014 and 2022 documents are evaluated as SystemVerilog (based literals, operators, ?:, $clog2, $pow, parameter references). An address, size or offset check that rests on a user-resolved or generated parameter is reported as a Warning, since configuration can change the verdict; everything else is an Error.
IEEE 1685-2022 rules (EU-2022)
What IEEE 1685-2022 added is checked by 22 EDAUtils rules, derived from the 1685-2022 schema, the Accellera IP-XACT 2022 User Guide and the IP-XACT 2022 release notes, pending the 2022 Annex B. Their ids, EU-2022-<area>-<n>, cannot be mistaken for IEEE SCR numbers. They apply to 1685-2022 documents only, and -lint_rules lists each with its fix and source. EU-2022-ACC-3 and EU-2022-DOC-1 are Warnings; the rest are Errors.
| Area | Rules | Checks |
|---|---|---|
| Modes | MODE-1, MODE-2 | mode conditions name existing port and field slices and modes; slice references resolve |
| Access policies | ACC-1 to ACC-4 | unique modeRef priorities, at most one default access policy, access narrowed by a container (Warning), readResponse only in a readable policy |
| Power | PWR-1, PWR-2 | power domain references resolve; design instances link each power domain once, to a declared domain |
| Ports | PORT-1 to PORT-3 | unique subPort names, port maps reach a leaf wire subPort, one domainTypeDef / signalTypeDef per view |
| Packets | PKT-1 | $ipxact_absdefport_value and $ipxact_packetfield_value name existing ports and packet fields |
| Arrays | ARR-1 to ARR-3 | stride covers an element, indexVar names unique and resolvable |
| Expressions | EXPR-1 | $ipxact_*() functions only where allowed, and no unknown ones |
| Port mapping | MAP-1, MAP-2 | allBits logical ports fully mapped; match logical ports mapped with the same bits on every end (needs -lib) |
| CPU | CPU-1 | a cpu region lies inside the cpu's range |
| Fields | FLD-1 | aliasOf / broadcastTo reach an existing field |
| Documentation | DOC-1 | a shortDescription shorter than its description (Warning) |
| Type definitions | TD-1 | a typeDefinitions attribute names an externalTypeDefinitions of the component |
Usage
ipxactlint -in <file.xml | directory> [-lib <file | directory>]...
[-waiver <file>]... [-waive_all] [-waiver_report <file>] [-gen_waivers <file>]
[-nobanner] [-quiet] [-user <email>]
ipxactlint -lint_rules
ipxactlint -help
| Option | Meaning |
|---|---|
-in <file or dir> | Required. The document to lint, or a directory: every IP-XACT .xml under it is linted, and the directory also serves as the library |
-lib <file or dir> | Repeatable. Documents the input references (bus and abstraction definitions, components, designs, abstractors); enables the cross-document rules |
-waiver <file> | Repeatable. Waiver file; a covered violation becomes a Waived note and is not counted |
-waive_all | Waive every violation and write a waiver file covering them (ipxactlint.waivers unless -gen_waivers names it) |
-waiver_report <file> | Waiver report path (default ipxactlint_waived.rpt) |
-gen_waivers <file> | Write a waiver file with one waiver per violation of this run, for -waiver next time |
-lint_rules | Print every rule: its 1685-2014 number (also used for 2022), its 1685-2009 number, its name and how to fix a violation; then the EU-2022 rules with id, name, fix and source |
-nobanner, -quiet | No banner and summary; silence every later message |
-help | Usage |
Findings and the summary Found N error(s) and M warning(s) go to the terminal and to ipxactlint.log in the current directory.
Example: five planted mistakes
The examples/findings directory of the bundle holds a UART register block with five planted mistakes. This is its output:
$ cd examples/findings
$ ipxactlint -in uart.xml -lib lib
ipxactlint: Error: 62300: uart.xml:37: K.2 localRefExists: reference to memoryMap 'uart_map', which does not exist in this component. Fix: point the reference at an element that is declared in this document, or declare the missing element
ipxactlint: Error: 62300: uart.xml:24: SCR 6.6 LogPortOutPortDir: logical port 'RDATA' is direction out for this slave interface but is mapped to port 'prdata' of direction in. Fix: map this logical port to a component port of direction out, inout or phantom (or swap the port's direction)
ipxactlint: Error: 62300: uart.xml:60: SCR 7.4 BitWithinRegister: field 'baud_div' bits [35:20] do not fit in register 'ctrl' of size 32. Fix: lower the field's bitOffset or bitWidth, or enlarge the register's size
ipxactlint: Error: 62300: uart.xml:77: SCR 8.5 ReadOnlyRegisterCondition: read-only register 'status' contains read-write field 'rx_full'. Fix: put only read-only fields in a read-only register, or change the register's access
ipxactlint: Error: 62300: uart.xml:66: SCR 7.1 RegisterOverlap: register 'status' [0x2..0x5] overlaps register 'ctrl' [0x0..0x3] in addressBlock 'uart_regs'. Fix: move the register to a free addressOffset, or give the two registers non-conflicting access (read-only vs write-only)
ipxactlint: Note: 53250: Found 5 error(s) and 0 warning(s) ...
$ echo $?
2
The same UART without the mistakes, in examples/clean, exits 0 with Found 0 error(s).
Shipped examples
The bundle ships eight examples under examples/ (tools/ipxactlint/examples/ in the shell bundles). Each runme.csh exits 0 only when its expected result holds, so each doubles as a check.
| Example | What it shows | Expected |
|---|---|---|
clean | A 1685-2014 UART register block | exit 0, Found 0 error(s) |
findings | The same UART with five planted mistakes (K.2, SCR 6.6, 7.1, 7.4, 8.5) | exit 2, Found 5 error(s) |
waivers | The five findings waived with reasons | exit 0, 5 waived violations |
soc_2014 | A 1685-2014 SoC subsystem: RV32 core on AXI4-lite, AXI4-lite-to-APB bridge, UART, GPIO, timer | exit 0 |
legacy_2009 | The same IPs and design as a 1685-2009 component library, linted as a directory | exit 0 |
dmac_2022 | A 1685-2022 version plus a DMA controller using modes, mode-specific access policies, readResponse, strided register arrays, a field alias, power domains and a structured port | exit 0 |
waiver_flow | -gen_waivers, review, then -waiver on a 2022 IP | exit 2, 1 error, 2 warnings waived |
ci_gate | A CI lint gate script over four trees, deciding on the exit status | exit 2, GATE: FAIL on one tree |
Waivers
A waiver names a rule by name or SCR number, can narrow it with file and message globs or a line number, and must give a reason. A waived violation is printed as a Note, is not counted, and is listed in the waiver report (ipxactlint_waived.rpt). A waiver that matches nothing is a Warning: its violation was fixed or renamed. A typical flow is to run -waive_all once, review the generated file, delete the lines for violations to be fixed, then run with -waiver <file> -gen_waivers <file> to keep it current. Generated waivers carry a TODO reason until someone replaces it.
# uart.waivers -- one waiver per line; reason= is required
rule=RegisterOverlap file=uart.xml msg="register 'status' *" reason="status aliases ctrl on purpose (legacy map)" owner=soc-team
rule=7.4 msg="field 'baud_div' *" reason="baud_div spills into the next word in this IP revision" owner=soc-team
rule=* file=*.xml line=315 reason="po is driven in test mode only"
$ ipxactlint -in uart.xml -lib lib -waiver uart.waivers -gen_waivers next.waivers
Using ipxactlint in CI
# lint every IP-XACT file under ipxact/, resolving references against busdefs/
cd build/lint # each parallel run in its own directory: the log is written to the cwd
ipxactlint -in ../../ipxact -lib ../../busdefs -waiver ../../ip.waivers -nobanner </dev/null
status=$? # 0 clean, 2 lint errors, 1 usage or unreadable input, 10 no license
[ $status -eq 0 ] || { grep -E 'Error:|Warning:' ipxactlint.log; exit $status; }
| Exit status | Meaning |
|---|---|
| 0 | No lint errors (warnings and waived violations do not fail the run) |
| 2 | Lint errors found |
| 1 | Usage error, an input, library or waiver file that does not exist or cannot be read, a malformed waiver line, or an internal error |
| 10 | No license for the IPXACTLINT feature (nor an ipxact-shell or designplayer-shell license) |
For AI agents and automated flows
- AGENTS.md: every bundle that carries ipxactlint has an
AGENTS.mddescribing the command line, the exit codes, the message format and the waiver syntax, so an agent can run the tool and act on eachFix:hint. - EDAUtils AI SDK: ipxactlint is a catalog tool (
eutools.ipxactlint). Its findings come back structured, with severity, file, line, rule, text and fix for each, plus a count of waived violations. - FECAD: the
static_checks/ipxact_lintflow lints an IP's IP-XACT, register map and design in one run against each sub-IP's library, applies waiver files, and fails on exit 2.
Install and prerequisites
ipxactlint ships as its own ipxactlint bundle, and as a point tool inside the ipxact-shell and designplayer-shell bundles. It runs on Linux and Windows and needs Java 11 or newer; setup_env finds one or offers to install it, sets EDAUTILS_ROOT and the license file, and puts bin/ on the PATH. It needs a license with the IPXACTLINT feature, which an ipxact-shell or designplayer-shell license also grants. It needs no schemas, no network and no other tools.
source setup_env.sh (or setup_env.csh, setup_env.bat)
cd examples/findings
ipxactlint -in uart.xml -lib lib
Known limits
- 2022 Annex B numbering is pending; 2022 documents get the 2014 rules plus the EU-2022 rules (see above).
- The 2014 rules read a 2022 element's access from its policy without a
modeRef; EU-2022-ACC-3 compares the accesses per mode. - A 1685-2022 register or register file array whose stride leaves gaps occupies only its elements for SCR 7.1 up to 4096 elements; bigger arrays keep their whole extent.
- 2022
typeDefinitionsdocuments and...DefinitionRefcontents are not resolved. - Not checked:
$sformatfcontexts, power-domain hierarchy cycles, whether mode conditions can be satisfied. - Port connection equivalence classes do not cross hierarchy levels.
- Parameters with no
type(it defaults to string) are not checked for casts. - Values that cannot be resolved (a real, x/z digits, an unknown system function, a parameter defined elsewhere) skip the numeric checks that need them.
Frequently asked questions
Related IP-XACT tools
- IP-XACT tools guide - validateipxact, upgradeipxact, compareipxact, register model generators
- verilog2ipxact and vhdl2ipxact - generate IP-XACT components from RTL, then lint them
- IP-XACT 1685 solution - component packaging, registers, memory maps and generators
- ipxactlint capability file - machine-readable summary for AI agents