# validateipxact

> IP-XACT syntax and semantics validator

- Catalog id: `Validateipxact`; bundle: `validateipxact`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT validator, IEEE 1685, schema validation, semantic check, IP-XACT 2009 2014 2022
- Terms: as stated on edautils.com, EDAUtils tools are free for commercial and academic use, with no license server. The bundle's own metadata says: "Free to evaluate with the bundled licence; commercial licences from help@edautils.com". Licence prerequisites per tool are under "How an agent runs it".
- This file: https://edautils.com/capabilities/validateipxact.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Validateipxact (latest file `validateipxact-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/validateipxact/
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/validateipxact/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/validateipxact-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

Checks IP-XACT XML files. Three modes:

- **Semantic check** (default): loads the file and runs the rule checks on components, memory
  maps, address blocks, registers, bit-fields and abstraction definitions -- e.g. offset
  alignment, register/bit-field/address-space overlaps, widths against the address unit,
  volatility, banked blocks -- many reported with the IP-XACT semantic rule number (`SCR 8.1`).
- **Sanity check** (`-sanity <type>`): only unmarshals the file against the bindings of one
  document type, to say whether it is well formed for that type.
- **Lint** (`-lint`): checks any IP-XACT document -- component, design, design configuration,
  bus definition, abstraction definition, abstractor, catalog, generator chain -- against the
  semantic consistency rules (SCRs) of IEEE 1685 Annex B, plus the schemas' name-uniqueness and
  local-reference constraints. The standard revision is taken from each document's namespace;
  no `-v2009`/`-v2022` is needed. See "Lint mode" below.

Main class: `com.eu.miscedautils.ipxactvalidator.validateipxact` (jar `lib/validateipxact.jar`).

### Where it ships

Its own bundle, `validateipxact.tar.gz` (flow `validateipxact`; release tree
`release_scripts/validateipxact/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell**
and **designplayer-shell** bundles (`bin/validateipxact` running the shell's jar; this guide as
`tools/validateipxact/AGENTS.md`, examples under `tools/validateipxact/examples/`).

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`). Use Java 11 or newer (Java 21 recommended: the
  release is built and regression-tested with OpenJDK 21); the bundled JAXB and Eclipse libraries
  are class-file version 55, so a Java 8 runtime fails with `UnsupportedClassVersionError`.
- `EDAUTILS_ROOT` = the unpacked bundle directory (must contain `bin/` and `lib/`). The
  launcher exits 1 with "Environment variable EDAUTILS_ROOT is not set" otherwise.
  `source setup_env.sh` (or `setup_env.csh`) from the bundle root sets `EDAUTILS_ROOT`,
  `EDAUTILS_LICENSE_FILE=$EDAUTILS_ROOT/edautils.lic`, `CLASSPATH=$EDAUTILS_ROOT/lib/validateipxact.jar`
  and prepends `bin/` to `PATH`.
- Licence feature `IPXACTVALIDATOR`. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. No licence for the feature: Error
  "Failed to checkout LICENSE for the feature : IPXACTVALIDATOR", exit status 10.
- No XSD schemas or XSL files are read: both modes use compiled JAXB bindings, so the bundle
  ships neither `bin/schemas` nor `bin/xsl`. "Sanity" is therefore a binding unmarshal, not an
  XSD validation.
- Optional environment: `JAVA_FLAGS` (passed to the JVM, e.g. `-Xmx8g`; with no heap option in it the launcher adds `-Xmx` sized to the machine (`bin/eu_heap.sh`: the largest of 64/32/16/12/8/4 GB within 3/4 of physical or cgroup memory, else 2 GB; `EDAUTILS_MAX_HEAP_GB` caps it)),
  `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the second appends),
  `EDAUTILS_DISABLE_USAGE_TRACKING=true`, `EDAUTILS_PRINT_STACK_TRACE` (stack traces on
  internal exceptions), `EDAUTILS_ENABLE_DEBUG_ENVIRONMENT=1` (debug messages).
  The IP-XACT loaders read the `EDAUTILS_IPXACT_SEARCH_PATH*` variables; whether the semantic
  check ever resolves a reference through them was not determined.
- No external tools needed.

### Invocation

```
validateipxact -in <file.xml> [-v2009 | -v2022] [-sanity bd|ad|comp|des|config]
               [-nobanner] [-quiet]
validateipxact -lint -in <file.xml | directory> [-lib <file | directory>]...
               [-waiver <file>]... [-waive_all] [-waiver_report <file>] [-gen_waivers <file>]
               [-nobanner] [-quiet]
validateipxact -lint_rules
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT XML to check (mandatory in practice) |
| `-v2009` | Input is IEEE 1685-2009 (SPIRIT namespace) |
| `-v2022` | Input is IEEE 1685-2022 (semantic mode only; see below) |
| `-sanity <type>` | Sanity check only: `bd` bus definition, `ad` abstraction definition, `comp` component, `des` design, `config` design configuration |
| `-lint` | Lint mode (below). `-in` may then name a directory: every IP-XACT `.xml` under it is linted |
| `-lib <file or dir>` | Lint only, repeatable: IP-XACT documents the input references (bus/abstraction definitions, components, designs, abstractors). Searched recursively for `.xml`. Enables the cross-document rules |
| `-lint_rules` | Print every lint rule with its number in 1685-2014 and in 1685-2009 (`-` = not in that standard) and how to fix a violation, then the `EU-2022-*` rules with fix and source, then exit |
| `-waiver <file>` | Lint only, repeatable: waiver file (see "Waivers"). A covered violation becomes a `Waived` Note, is not counted, and is listed in the waiver report |
| `-waive_all` | Lint only: waive every violation; all go to the waiver report, and a waiver file covering them is written (`validateipxact.waivers` unless `-gen_waivers` names it) |
| `-waiver_report <file>` | Lint only: waiver report path (default `validateipxact_waived.rpt`; written when any waiver is given or `-waive_all`) |
| `-gen_waivers <file>` | Lint only: write a waiver file with one waiver per violation of this run (waived or not), for `-waiver` next time |
| `-nobanner` | No banner **and no completion summary** |
| `-quiet` | Silence every later message (log included); errors are then not counted |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and return |

Without `-v2009`/`-v2022` the file is read as IEEE 1685-2014. If both are given, `-v2009` wins
silently. In semantic mode a file that fails to load with the chosen revision is retried with the
2022 (when `-v2022`) and then the 2014 component loader, which may map its namespace onto 2014 and
log "Loaded the IP-XACT file ... by mapping its schema namespace onto IP-XACT 1685-2014".
`-sanity` has only 2009 and 2014 bindings: with `-v2022` (or no switch) it uses the 2014 ones.
An unknown `-sanity` value (e.g. `component`) is **silently ignored** and the semantic check runs.

There is no `-out`, `-suppress` or `-l`. Any other word prints "Unrecognized option : <opt>" and
the usage. No arguments prints the usage. Missing `-in` logs Error "NULL object passed as IP-XACT
file ...". An option given without its value throws an index exception, reported as an internal
error (exit 0).

### Inputs / Outputs

- Reads: the `-in` file only.
- Writes: no output files. Findings are messages on stdout and in the log.
- Log: `validateipxact.log` in the current directory (override with `EDAUTILS_LOG_FILE`).
- Semantic mode handles component, memoryMaps, memoryMap, addressBlock and abstraction definition
  roots. Other roots log Error "Unexpected object type found : semantic checks is supported only
  in Component/MemoryMap ip-xact files". A file that cannot be loaded logs Error
  "Failed to load specified IP-XACT XML file : <f>".
- Sanity mode: failure logs Error "Found error(s) in the input file : <f>" followed by the parser's
  message. Success prints nothing specific (no error lines).

### Lint mode

`-lint` reads documents as plain XML (no JAXB binding), so one rule implementation serves every
revision. Each rule carries its number in each standard, and is reported under the number of the
document's own standard; a rule that one standard does not have is not applied to its documents.

- **1685-2009** (`spirit` 1685-2009 namespace; SPIRIT 1.4/1.5 documents are treated the same):
  the 1685-2009 Annex B rules, 2009 numbering (e.g. `SCR 6.26 CantDriveOutputPort`).
- **1685-2014**: the 1685-2014 Annex B rules, 2014 numbering (`SCR 6.24 CantDriveOutputPort`).
- **1685-2022**: the 2022 standard's own Annex B is not available to this tool (the reference used
  is the 2022 User Guide and release notes), so 2022 documents get the 1685-2014 rules under 2014
  numbers, with the 2022 renames mapped (initiator/target, `accessPolicies`/`fieldAccessPolicies`,
  `array/dim`, `componentInstanceRef`, `initiatorRef`, clearbox for whitebox) and the 2022 value
  types (e.g. `dim` and memory `width` positive, `clockPulseValue` a bit). The access restriction
  rules SCR 8.3-8.15 are not applied: 2022 filters a child's access by its parents' instead (2022
  release notes). On top, 2022 documents get the 22 `EU-2022-*` rules on what 2022 added (modes,
  access policies per mode, power domains, structured ports, packets, arrays with stride, the
  `$ipxact_*()` functions, `allBits`/`match`, cpu regions, field aliases): EDAUtils rules derived
  from the 1685-2022 schema, User Guide and release notes, pending the 2022 Annex B -- not IEEE SCR
  numbers. The table, with each rule's source, is in ipxactlint's AGENTS.md ("1685-2022 rules");
  `-lint_rules` lists them. A Note says so for every 2022 document.
- **K.1 uniqueNames / K.2 localRefExists**: the schemas' identity constraints (names unique in
  their scope; `memoryMapRef`, `addressSpaceRef`, `masterRef`, port, view, fileSet, choice,
  remapState/mode, resetType ... references resolve). A JAXB load does not check these.

`-lint_rules` lists every rule with its fix hint. Implemented: all 224 SCRs of 1685-2014 and all
175 of 1685-2009, plus K.1/K.2, across every table: B.1 cross-references, B.2 interconnections,
B.3 channels/bridges/abstractors, B.4 monitors, B.5 configurable elements and parameters
(1685-2009: XPath dependencies), B.6 port maps, ports and port connection equivalence classes,
B.7 registers and fields, B.8 memory maps, B.9 addressing, B.10 hierarchical families, B.11
hierarchical memory maps, 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. Every rule has at least one failing regression case.

Cross-document rules need the referenced documents: give them with `-lib`, or lint a directory
(`-in dir` makes everything under it both input and library). Without either, a Note says the
cross-document rules are skipped -- and SCR 1.2 (`anyVLNVRefMustExist`, a VLNV that matches no
document) is reported only when a library was given.

Expressions (2014/2022) are evaluated as SystemVerilog: based literals (`'h10`, `8'b1010`),
operators, `?:`, `$clog2`, `$pow`, parameter references by `parameterId`. 2009 values are read as
literals (`0x10`, `#10`, `4K`). A value that cannot be resolved (a real, `x`/`z` digits, an unknown
system function, a parameter defined elsewhere) skips the numeric checks that need it.
Parameters with no `type` (it defaults to `string`) or `type="string"` are not parsed for SCR
5.17/5.18. `0x...` in a 2014/2022 value is SCR 5.17 (`0x` is C, not SystemVerilog).

Rules are judged on the values as written -- default values, before configuration. When an
address/size/offset check (overlaps, fits, widths) rests on a parameter with `resolve="user"` or
`"generated"`, it is reported as a **Warning** ending "(with the default values of configurable
parameters)", since configuration can change the verdict. EU-2022-ACC-3 and EU-2022-DOC-1 are
Warnings. Everything else is an Error.

Message format: `validateipxact: Error: <id>: <file>:<line>: SCR <n> <ruleName>: <text>. Fix: <how>`
(`K.<n> <ruleName>` for K.1/K.2, `EU-2022-<area>-<n> <ruleName>` for the 1685-2022 rules)
(or `K.<n> <ruleName>`). File is as given on the command line; line is the offending element's.
`<text>` names the elements and values involved; `Fix:` says what to change (the same per-rule
hint `-lint_rules` prints). Message ids: 12300 (+ the log's base offset) error, 12301 warning
(also a stale waiver), 12302 note (also each waived violation), 12303 a file that does not exist,
is not XML, or is not IP-XACT, and a bad waiver-file line.

#### Waivers

A waiver file has one waiver per line (`#` comments), in the key=value style of the CDC/RDC
checkers' waiver files; a value with spaces is double-quoted, `\"` and `\\` escape inside quotes:

```
rule=RegisterOverlap file=comp.xml reason="r1 aliases r0 by design" owner=kanai
rule="SCR 6.19" reason="paddr width comes from a generic set upstream"
rule=7.4 msg="field 'f2' *" reason="f2 spills into the next register on purpose"
rule=* file=*.xml line=315 reason="po is driven in test mode only"
```

| Key | Meaning |
|---|---|
| `rule` | Required. Rule name, its number in the document's standard (`7.1`, `SCR 7.1`, `K.1`), an `EU-2022-*` id, or `*` |
| `file` | Glob (`*`, `?`) over the document path as given, or its file name. Default `*` |
| `line` | Line of the finding. Default: any |
| `msg` | Glob over the finding text (the part after `<ruleName>: `, without `Fix:`). Default `*` |
| `reason` | Required: why the violation is acceptable |
| `owner` | Optional |

The first matching waiver wins. A waived violation is printed as
`Note: <id>: Waived error: <finding> [waived by <waiverfile>:<line> (<reason>; owner: <owner>)]`
and is not counted in `Found N error(s)`. A line with an unknown rule or key, no `reason`, or a
non-numeric `line` is an Error naming the waiver file and line, and that waiver is ignored. A
waiver that matches nothing is a Warning ("stale"): its violation was fixed or renamed.

The waiver report lists every waived violation with the waiver (or `-waive_all`) that waived it,
the stale waivers, and the count of violations not waived. The generated waiver file
(`-gen_waivers`, or `-waive_all`) has one line per distinct violation with `rule`, `file` and the
exact `msg` (line numbers inside the text globbed to `line *`, so edits elsewhere do not make it
stale); violations already waived keep their reason and owner, new ones get
`reason="TODO: why this violation is acceptable"` -- replace it before relying on the file.
Typical flow: `-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.

How the rules that look beyond one element judge:

- **Port connection equivalence classes** (B.1.6; SCR 6.9, 6.10, 6.14 of 1685-2009, 2.13 of
  1685-2009) are built per bit from bus interface port maps, interconnections between interfaces
  of the same abstraction and ad hoc connections, within one design. A port of the containing
  component is seen from inside: an input drives, requires and provides swap. SCR 6.9/6.10 use the
  whole class, so masters that reach one shared port of a bus component count as connected; SCR
  6.23/6.25 compare only ports connected directly (one interconnection or ad hoc connection), with
  the compatibility definitions of SCR 6.23 a)-f).
- **Hierarchical memory maps** (SCR 11.1-11.4) compare the memory map a hierarchical slave
  interface references with the one of the sub-instance interface it exports: visible addresses,
  subspace windows (masters matched through their own hierarchical families), the behaviour of
  every register bit (access, volatile, reset, modifiedWriteValue, readAction, testable) and, for
  1685-2009, aliases. Addresses are compared in bits, so members with different addressUnitBits
  compare.
- **Value types** (Table B.14) come from each version's schema, per context where one name has
  several types (`baseAddress`, `width`, `value`, `busWidth`, `dim` ...). A string type needs a
  quoted SystemVerilog string (or a string parameter); a file name (stringURIExpression) may be an
  unquoted path, but without spaces or backslashes. A bit vector must fit the field or port it
  sizes.
- **1685-2009 dependencies** (SCR 5.2-5.5) are compiled with the JDK's XPath 1.0 engine (the
  spirit:decode/pow/log/containsToken extensions accepted); id() targets are resolved in the
  document. SCR 14.2 checks that the vendor has the shape of a domain name; ownership cannot be
  checked.

Limits: 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 2022 register/register-file array whose stride
leaves gaps occupies only its elements for SCR 7.1 (up to 4096 elements);
2022 `typeDefinitions` and `...DefinitionRef` contents are not resolved; equivalence classes do not
cross hierarchy levels; parameters with no `type` (it defaults to string) are not checked for casts.

### Exit status and messages

- 0 on every normal return, **including runs that found errors** (the findings are the product,
  not a failure). 10 = licence checkout failed. 1 = out of memory, or `EDAUTILS_ROOT`
  missing/invalid (launcher).
- Message format: `validateipxact: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit number. Usage lines have no severity or id.
  Typical findings: `Error: ...: Address Block : SCR 8.1 : The width 32 is not multiple of address
  bit unit ...`, `Illegal offset '10' , not aligned with the bytecount for register ...`,
  `Register : SCR 7.8 : The volatility attribute must be set to 'true' ...`.
- The run ends with `validateipxact: Note: <id>: Found N error(s) and M warning(s) ...` (not with
  `-nobanner`).

#### Known false reports

**Address-overlap errors can be false.** The ledger (BUILD-STATE `CURRENT`, s51) records 91 overlap
errors on a SoC register map where the flagged blocks do not overlap, e.g. `sram`
(0x20000000-0x2000FFFF) against `gpio` (0x40001000). Before acting on an overlap error, check the
two ranges by hand. The volatility errors in the same run were real (from the source IP
descriptions), so do not dismiss other findings on the same basis.

### Examples

Shipped: `examples/i2c/` (`component.xml`, 1685-2009) and `examples/sanity/` (`clock.xml` bus
definition, `clock_rtl.xml` abstraction definition, both 1685-2009), each with `runme.csh`:

```
cd $EDAUTILS_ROOT/examples/i2c
validateipxact -in component.xml -v2009
cd $EDAUTILS_ROOT/examples/sanity
validateipxact -v2009 -in clock.xml -sanity bd
validateipxact -v2009 -in clock_rtl.xml -sanity ad
```

`examples/sanity/runme.bat` is broken: it runs `validateipxact -v2009 -in component.xml -component`,
but `sanity/` has no `component.xml` and `-component` is not an option (it prints "Unrecognized
option" and the usage). Use the two `runme.csh` commands above on Windows too.

From the regression suite (reference: `tests.edautilscommandline/tests/validateipxact/i2c/runme.csh`;
40 cases, each comparing the `Error`/`Warning` lines of `validateipxact.log` against
`validateipxact.log.gld` with message numbers masked). The 20 semantic-mode cases use `-v2009`
except `i2c_2014`:

```
validateipxact -in component.xml -v2009
validateipxact -in component.xml            # i2c_2014: 1685-2014 input
```

The twenty `lint_*` cases are documents in which each commented element breaks the rule named in
its comment, so the golden is the expected finding list:

```
validateipxact -lint -in comp.xml -lib lib     # lint_component_2014 (lib/: bus + abstraction definitions)
validateipxact -lint -in comp.xml              # lint_component_2009, lint_component_2022
validateipxact -lint -in top -lib lib          # lint_design_2014: design + design configuration
validateipxact -lint -in defs                  # lint_defs_2014: bus/abstraction definitions, abstractor, catalog
validateipxact -lint -in comp.xml -lib lib -waiver comp.waivers -waiver missing.waivers   # lint_waiver_2014
validateipxact -lint -in top -lib lib -waive_all                                         # lint_waive_all_2014
validateipxact -lint -in top -lib lib -waiver top.waivers -waiver_report reuse.rpt -gen_waivers next.waivers  # lint_waiver_reuse_2014
```

Rule by rule, every SCR of both standards fails in at least one of them: `lint_component_*`
(component rules), `lint_design_2014`, `lint_defs_2014`, `lint_values_2014`/`_2009` (value
types, parameters, arrays, dependencies, formats, file names, vendors), `lint_nets_2014`/`_2009`
(equivalence classes, presence, monitor paths, transactional connections), `lint_hier_2014`/`_2009`
(hierarchical families and memory maps), `lint_memory_2014` (registers, banks, access, virtual
registers, indirect interfaces), `lint_ports_2014`, `lint_refs_2014` (VLNV and configurable element
references), `lint_design2_2014` (interface pairings, abstractors), `lint_misc_2009`, and
`lint_access_2022` (the 1685-2022 differences). Each runs `validateipxact -lint -in <doc or dir>
[-lib lib]`.

`lint_waiver_2014` matches by rule name, SCR number, bare number with a `msg` glob, `line`, and
`rule=*`, a quoted message containing quotes, one stale and four malformed waivers, and a missing
waiver file; the waiver cases also compare the waiver report (and generated waiver file) with
`.gld` copies. `lint_waiver_reuse_2014` feeds a generated file back: no stale waivers, edited
reasons and owners carried into `next.waivers`, the two violations without a waiver still errors.

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log into the current directory: give each parallel run its own working directory
  (or a distinct `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Result test: exit status 0 **and** the log contains `Found N error(s)` (do not use
  `-nobanner`/`-quiet` if you rely on it). `Found 0 error(s)` means the file is clean for the
  checks implemented; N > 0 means findings, listed on the `Error:` lines above it.

### See also

upgradeipxact (upgrade before validating as 2014/2022), compareipxact, ipxactcoherencychecker,
ipxact-shell.
