# compareconnectivitydatabase

> Diff the connectivity of two designs: genconnectiondb writes each design's connection database and compareconnectiondb reports every connection added, removed or changed -- did a restructuring change the design?

- Catalog id: `Compareconnectivitydatabase`; bundle: `compareconnectivitydatabase`; latest version 20261018
- Keywords: connectivity compare, netlist diff, restructuring check
- 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/compareconnectivitydatabase.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Compareconnectivitydatabase (latest file `compareconnectivitydatabase-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/baya-soc-integration-platform/files/compareconnectivitydatabase/
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/compareconnectivitydatabase/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/compareconnectivitydatabase-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

Run: `compareconnectiondb -help`

## How an agent runs it

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

Bundle with two launchers. `genconnectiondb` reads a Verilog/SystemVerilog design and writes a
Baya connection database (the connections, instances and parameter maps of the `-top` module,
optionally of all its sub-modules) as XML and JSON. `compareconnectiondb` compares two such XML
databases (`-revised` against `-golden`, EMF Compare) and writes a text difference report
(default `Diff.rpt`). Main classes: `com.eu.miscedautils.shell.Verilog2BayaDB` (genconnectiondb)
and `com.eu.miscedautils.shell.CompareConnectivityDB` (compareconnectiondb), both in jar
`lib/designplayer.jar`.

### Where it ships

Its own bundle, `compareconnectivitydatabase.tar.gz` (flow `compareconnectivitydatabase`; release
tree `release_scripts/compareconnectivitydatabase/1.0`), and as a point tool in the **baya-shell**
and **designplayer-shell** bundles (`bin/compareconnectiondb`, `bin/genconnectiondb` running the
shell's jar; this guide as `tools/compareconnectivitydatabase/AGENTS.md`, examples under
`tools/compareconnectivitydatabase/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`, `CLASSPATH` and prepends `bin/` to `PATH`.
- Licence. The licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`,
  `./edautils.lic` (run directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`.
  - genconnectiondb: feature `VERILOG2BAYACONNDB`; missing -> exit status 10.
  - compareconnectiondb: feature `COMPARECONNECTIONDBS`; missing -> exit status 10. It also
    needs feature `BAYACONNDB2BAYATCL`: the database loader (`BayaConnectivityRoot.loadConnectionDB`)
    silently returns nothing without it, and the comparison then runs on empty input.
- 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).
  genconnectiondb additionally: `EDAUTILS_LIBRARY_MAP_FILE` (default for `-mapfile`),
  `EDAUTILS_VERILOG_MERGE_CONCAT=true` (same effect as `-noconcatmerge`, see below).
- No external tools needed.

### Invocation

#### genconnectiondb

```
genconnectiondb -in <file.v> | -f <filelist>  -top <module>  [-out <db.xml>]  [options]
```

| Option | Meaning |
|---|---|
| `-top <module>` | Module to convert (mandatory; without it the usage is printed) |
| `-out <file>` | Database name (default `BayaConnectionDB.xml`); see Outputs for the XML/JSON pair |
| `-recursive` | Also convert every sub-module instantiated below `-top` |
| `-noelaborate` | Do not elaborate the top module (nor parameter-map values) |
| `-nomergeassgn` | Skip bit-splitting and assignment/port-map merging before conversion |
| `-noconcatmerge` | Despite the name, this **enables** concat merging (`FVPDescription.setMergeConcat(true)`; default off) |
| `-nouniquify` | Accepted and recorded, but the flag is not read anywhere in the conversion code |
| `-in_xml <file>` | Accepted and recorded, but the value is never used |
| `-help`, `-h` | Print usage and exit |

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>`,
`-f <filelist>`, `-excludefilelist <file>`, `+incdir+<p1>+<p2>`, `+define+A+B=1`, `-v95`
(no SystemVerilog keywords), `-nowildcard`, `-nokeywords a:b`, `-blackbox` (blackbox
undefined modules), `-declare_wires_for_undefined_obects`, `-dump`, `-restore <units>`,
`-work <lib>`, `-mapfile <ini>`, `-l <log>` / `-la <log>` (log file / append),
`-quiet`, `-nobanner`, `-dbg`, `-suppress <id1:id2>`, `-user <email>`, `-encryption_key`,
`-encryption_algorithm`, `-private_key_file`, `-public_key_file`.
An unrecognised option is an error ("Unrecognized option : <opt>") followed by the usage.

#### compareconnectiondb

```
compareconnectiondb -revised <db.xml> -golden <db.xml> [-out <report>] [-nobanner] [-quiet]
                    [-suppress <id1:id2>] [-user <email>]
```

| Option | Meaning |
|---|---|
| `-revised <file>` | Revised connection database, XML only (mandatory) |
| `-golden <file>` | Golden connection database, XML only (mandatory) |
| `-out <file>` | Difference report (default `Diff.rpt`) |
| `-nobanner` | Do not print the copyright banner |
| `-quiet` | Do not print log messages to the console |
| `-suppress <id1:id2>` | Suppress messages with these numbers |
| `-user <email>` | User id for usage registration |
| `-help` | Print usage and exit |

No arguments, or a missing `-revised`/`-golden`, prints the usage and exits. An unrecognised
option is an error ("Unrecognized option : <opt>") followed by the usage. An option given as
the last word without its value raises an internal exception (reported, exit 0).
A `.json` database is refused ("Only XML based connection database can be loaded").

### Inputs / Outputs

- genconnectiondb reads the Verilog files from `-in` / `-f` and their `` `include`` files. It
  writes the database twice, as `<stem>.xml` and `<stem>.json`, where `<stem>` is the `-out`
  name without its `.xml`/`.json` extension (default `BayaConnectionDB.xml` +
  `BayaConnectionDB.json`). It also creates the directory `myEdaUtilsWork/` in the current
  directory (parser work library). Nothing is written when `-top` is not found.
- compareconnectiondb reads the two XML databases and writes the `-out` report. Each entry reads
  `[ n ] Diff : <revised value>` then `--->` and the golden value; a one-sided change shows a
  single value. The log ends with `Note: <id>: Total diffs : N` (only when differences exist).
- Logs: `genconnectiondb.log` and `CompareConnectivityDB.log` (note the case) in the current
  directory (override with `EDAUTILS_LOG_FILE`; genconnectiondb also `-l`/`-la`). Every
  console line is also written to the log.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing mandatory options,
  top module not found, parse errors, unreadable database files all return 0).
  10 = licence checkout failed. 1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `<prefix>: <Severity>: <id>: <text>` with prefix `genconnectiondb` or
  `CompareConnectivityDB`, severity one of `Error`, `Fatal Error`, `Warning`, `Note`; `<id>`
  is a 5-digit message number. Usage and diff lines have no severity or id.
- Both tools end with `<prefix>: Note: <id>: Found N error(s) and M warning(s) ...`, **printed
  even with `-nobanner`** (neither tool guards it). The compareconnectiondb banner names
  itself "genconnectiondb" (hard-coded in `printBanner`).

### Examples

Shipped: `examples/simple_attrib_change/` (`runme.csh`, `example.gld.xml`, `example.rev.xml`):

```
cd $EDAUTILS_ROOT/examples/simple_attrib_change
compareconnectiondb -revised example.rev.xml -golden example.gld.xml
```

No genconnectiondb example ships in this bundle (see the genconnectiondb bundle).
From the regression suite (`tests.edautilscommandline/tests/genconnectiondb/multiple_connection_3/runme.csh`
via `../runme_common.csh`; `tests.edautilscommandline/tests/compareconnectiondb/simple_attrib_change/runme.csh`
via `../runme_common.csh`):

```
genconnectiondb -f infile.list -top MySoC -out example.xml -recursive
compareconnectiondb -revised example.rev.xml -golden example.gld.xml     # -> Diff.rpt
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Both write the log, the default output and (genconnectiondb) `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, genconnectiondb: exit 0 **and** `Found 0 error(s)` in the log **and** both
  `<stem>.xml` and `<stem>.json` exist. compareconnectiondb: exit 0 **and** `Found 0 error(s)`
  **and** the report exists; a report with no `[ n ] Diff` entry (just a newline) means no differences. The exit status never
  signals "databases differ".
- The report compares revised (left) to golden (right); keep the argument roles consistent.

### See also

genconnectiondb, bayadb2bayatcl (database to Baya Tcl), verilog2baya, baya-shell.
