# ipxactcoherencychecker

> Check an IP-XACT component against its RTL for coherency: ports, parameters and bus interfaces that disagree between the two are reported.

- Catalog id: `Ipxactcoherencychecker`; bundle: `ipxactcoherencychecker`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT coherency, IP-XACT vs RTL check, IP packaging verification, IEEE 1685
- 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/ipxactcoherencychecker.md

## Downloads

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

Run: `ipxactcoherencycheckerverilog -help`

## How an agent runs it

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

Checks that an IP-XACT component agrees with its RTL: it imports the component, parses the
RTL, finds the module/entity with the component's name and compares parameters/generics,
port count, port names, directions and widths. Differences are written as a text table
(default `diff.txt`) and a CSV (default `diff.csv`). Two launchers, both in
`lib/designplayer.jar`:

- `ipxactcoherencycheckerverilog` -- Verilog RTL; main class
  `com.eu.miscedautils.shell.IPXACTCoherencyCheckerVerilog`.
- `ipxactcoherencycheckervhdl` -- VHDL RTL; main class
  `com.eu.miscedautils.shell.IPXACTCoherencyCheckerVhdl`.

### Where it ships

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

### Prerequisites

- Java on `PATH` (the launchers run 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
  launchers exit 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` and prepends `bin/` to `PATH`.
- Licence features `IPXACTCOHERENCYCHECKERVERILOG` / `IPXACTCOHERENCYCHECKERVHDL`. The
  licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic`,
  `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. No licence: exit status 10.
  (`README.txt` still says `EDAUTILS_LICENSE_KEY`; that variable is not read.)
- VHDL launcher: the standard packages come from `$EDAUTILS_ROOT/vhdl_pkgs/qtmap.ini`
  (`qtmap.win.ini` on Windows), which maps `std`/`ieee`/... to the precompiled libraries in
  `$EDAUTILS_ROOT/vhdl_pkgs/`. The bundle ships `vhdl_pkgs/`; a missing map gives
  "Failed to read VHDL precompiled library map file file : <path>".
- Optional environment: `JAVA_FLAGS` (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`, `EDAUTILS_DISABLE_USAGE_TRACKING=true`,
  `EDAUTILS_PRINT_STACK_TRACE`, `EDAUTILS_ENABLE_DEBUG_ENVIRONMENT=1`,
  `EDAUTILS_IPXACT_SEARCH_PATH*` (read by the IP-XACT loaders used for the import).

### Invocation

#### ipxactcoherencycheckerverilog

```
ipxactcoherencycheckerverilog -xml <component.xml> -verilog <file.v> | -f <filelist>
        [-outtxt <diff.txt>] [-outcsv <diff.csv>] [+define+A+B=1] [-excludefilelist <f>]
        [-nowildcard] [-suppress <id1:id2>]
```

| Option | Meaning |
|---|---|
| `-xml <file>` | IP-XACT component (mandatory) |
| `-verilog <file>` / `-f <filelist>` | Verilog file or file list (one of them mandatory) |
| `-outtxt <file>` / `-outcsv <file>` | Diff outputs (defaults `diff.txt`, `diff.csv`) |
| `+define+A+B=1` | Macro definitions |
| `+incdir+<p1>+<p2>` | Accepted but **ignored**: the paths are collected and never passed to the parser |
| `-excludefilelist <f>` | Files to exclude from `-f` |
| `-nowildcard` | No wildcard expansion of file names |
| `-suppress <id1:id2>` | Message numbers to suppress |
| `-user <email>` | Usage-tracking user id |

The usage text swaps the meaning of `-verilog` and `-xml`; the code above is authoritative.

#### ipxactcoherencycheckervhdl

```
ipxactcoherencycheckervhdl -xml <component.xml> -vhdl <file.vhd> | -filelist <filelist>
        [-outtxt <diff.txt>] [-outcsv <diff.csv>] [-work <lib>] [-mapfile <map.ini>] [-analyze]
```

| Option | Meaning |
|---|---|
| `-xml <file>` | IP-XACT component (mandatory) |
| `-vhdl <file>` / `-filelist <f>` | VHDL file or file list (exactly one; both is an error) |
| `-outtxt <file>` / `-outcsv <file>` | Diff outputs (defaults `diff.txt`, `diff.csv`) |
| `-work <lib>` | Work library (default `work`, physical dir `myEdaUtilsWork` unless mapped) |
| `-mapfile <file>` | Local library map `logical=physical` (default `qtmap.ini`; read if present, rewritten at the end) |
| `-analyze` | Analyse mode (requires `-vhdl`) |
| `-quiet` | Silence every later message (log included); errors are then not counted |
| `-suppress <id1:id2>`, `-user <email>` | As for the Verilog launcher |
| `-nobanner`, `-sort`, `-nowildcard`, `-excludefilelist <f>` | Accepted but have no effect |

Both launchers: any other token (including `-help`) prints the usage and exits 0 without an
"Unrecognized option" error. Missing `-xml` or RTL input: error "Missing mandatory input ..."
and the usage. Neither accepts `-l`/`-la`.

### Inputs / Outputs

- Reads: the `-xml` component and the RTL. The RTL module/entity is looked up by the
  component's name (case-insensitive for VHDL).
- Writes: `-outtxt` (ASCII table: columns RTL side, IP-XACT side, comment) and `-outcsv`
  (same rows). VHDL: also `-mapfile` (default `./qtmap.ini`) and the work directory
  (default `./myEdaUtilsWork/`) when `-vhdl` is used.
- Log: `ipxactcoherencycheckerverilog.log` / `ipxactcoherencycheckervhdl.log` in the current
  directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on every normal return, including failures (component not importable, top not found in
  the RTL). 10 = licence checkout failed. 1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `<launcher>: <Severity>: <id>: <text>`; `<id>` is a 5-digit number.
- **Differences are not errors**: a mismatching pair still ends with `Found 0 error(s)`; the
  count is in the Note "Completed comparison, total number of differences : N". The summary
  `Found N error(s) and M warning(s) ...` is always printed (no `-nobanner`).
- The VHDL launcher's banner says "IP-XACT Coherency Checker( Verilog )" (cosmetic).

### Examples

Shipped: `examples/verilog/i2c/` and `examples/vhdl/i2c/` (`runme.csh`, `i2c.xml`, RTL):

```
cd $EDAUTILS_ROOT/examples/verilog/i2c
ipxactcoherencycheckerverilog -xml i2c.xml -verilog i2c.v -outcsv output.diff.csv -outtxt output.diff.txt
cd $EDAUTILS_ROOT/examples/vhdl/i2c
ipxactcoherencycheckervhdl -xml i2c.xml -vhdl i2c.vhd -outcsv output.diff.csv -outtxt output.diff.txt
```

From the regression suite (references:
`tests.edautilscommandline/tests/ipxactcoherencychecker/verilog/i2c/runme.csh` and
`.../vhdl/i2c/runme.csh`, each via its `../runme_common.csh`): the same command lines; the
test diffs `output.diff.txt` and `output.diff.csv` against goldens.

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, default outputs and (VHDL) `qtmap.ini` / `myEdaUtilsWork/` into the current
  directory: give each parallel run its own working directory.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit 0 **and** `Found 0 error(s)` in the log **and** both diff files exist.
  "Coherent" means the diff table has no data rows (or the differences Note says 0).

### See also

comparemoduleinterfaces, compareentities, verilog2ipxact, vhdl2ipxact, validateipxact.
