# comparemoduleinterfaces

> Compare port/parameter changes between Verilog modules to assess integration impact

- Catalog id: `Comparemoduleinterfaces`; bundle: `comparemoduleinterfaces`; latest version 20261018
- Documentation page: https://edautils.com/Baya.html
- Keywords: Verilog module compare, port comparison, parameter comparison, interface diff
- 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/comparemoduleinterfaces.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Comparemoduleinterfaces (latest file `comparemoduleinterfaces-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/comparemoduleinterfaces/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/comparemoduleinterfaces-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.

Compares two revisions of a Verilog/SystemVerilog module: the golden and revised sources
(single file or file lists) are parsed one after the other, the module named by `-top` is
found in each, and differences in parameters, ports, instance port maps and continuous
assignments are written as a text table (default `diff.txt`) and a CSV file (default
`diff.csv`). Main class: `com.eu.miscedautils.modulecomparator.verilog.CompareModules`
(jar `lib/modulecomparator.jar`).

### Where it ships

Its own bundle, `comparemoduleinterfaces.tar.gz` (flow `comparemoduleinterfaces`; release tree
`release_scripts/comparemoduleinterfaces/1.0`), and as a point tool in the **baya-shell** and
**designplayer-shell** bundles (`bin/comparemoduleinterfaces` running the shell's jar; this guide
as `tools/comparemoduleinterfaces/AGENTS.md`, examples under
`tools/comparemoduleinterfaces/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` and prepends `bin/` to `PATH`.
- Licence: a valid licence file is required (else exit status 10), plus feature
  `VERILOGMODULECOMPARE`, checked by the comparator; a missing feature prints the licence
  checkout failure but the run still exits 0. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`.
- 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),
  `EDAUTILS_LIBRARY_MAP_FILE` (default for `-mapfile`).
- No external tools needed.

### Invocation

```
comparemoduleinterfaces [-sv] -goldenFile <g.v> -revisedFile <r.v> | -goldenFileList <g.f> -revisedFileList <r.f>
                        -top <module> | -goldenTop <m> -revisedTop <m>  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-goldenFile <file>` / `-revisedFile <file>` | Golden / revised Verilog file |
| `-goldenFileList <f>` / `-revisedFileList <f>` | Filelists (`-f` format); may be repeated |
| `-top <module>` | Module name in both revisions (overrides `-goldenTop`/`-revisedTop`) |
| `-goldenTop <m>` / `-revisedTop <m>` | Module names when they differ. The revised design is searched for the **golden** name (code bug), so differing names end in "Top '<m>' not found in the revised input file(s)" |
| `-outtxt <file>` | Text report (default `diff.txt`) |
| `-outcsv <file>` | CSV report (default `diff.csv`) |
| `-elaborate` | Elaborate the modules before comparing |
| `-ignore_instances` | Do not compare instances |
| `-ignore_assigns` | Do not compare continuous assignments |
| `-sv` | Clears the `-v95` mode (SystemVerilog is already the default). Put it **first**: the check reads the raw argument array at the index of the remaining-options list, so elsewhere it usually falls through to the usage |
| `-help`, `-h` | Print usage and exit |

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`) that apply here:
`+incdir+<p1>+<p2>`, `+define+A+B=1`, `-v95`, `-nowildcard`, `-nokeywords a:b`,
`-excludefilelist <file>`, `-blackbox`, `-declare_wires_for_undefined_obects`,
`-l <log>` / `-la <log>`, `-quiet`, `-dbg`, `-suppress <id1:id2>`, `-user <email>`,
`-encryption_key`, `-encryption_algorithm`, `-private_key_file`, `-public_key_file`,
`-work`, `-mapfile`, `-dump`, `-restore`. `-in` and `-f` are overridden by the golden/revised
inputs; `-nobanner` is accepted but the banner is always printed. `-sort` and `-nopreprocess`
appear in the usage text but are not accepted (they print the usage and stop).
Any unrecognised option prints the usage **without** an error message and exits.
Missing top or inputs: Error "Missing mandatory input ..." then the usage.

### Inputs / Outputs

- Reads: golden and revised Verilog files / filelists and their `` `include`` files.
- Writes: `-outtxt` and `-outcsv` reports. Rows are golden value, revised value, comment
  (e.g. `Port Map mismatch for port b in the instance inst1`). Also creates `myEdaUtilsWork/`
  (parser work library) in the current directory.
- Log: `CompareModules.log` in the current directory (override with `-l`/`-la` or
  `EDAUTILS_LOG_FILE`). Every console line is also written to the log.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing options, module not
  found, parse errors, missing licence feature all return 0). 10 = no valid licence.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `CompareModules: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit message number. Usage lines have
  no severity or id.
- The run ends with `CompareModules: Note: <id>: Found N error(s) and M warning(s) ...`
  (also when the top module is not found; not affected by `-nobanner`).

### Examples

Shipped: `examples/complex_param/` and `examples/many_dimensions_input/`, each with
`runme.csh`, `<name>.golden.v`, `<name>.revised.v`:

```
cd $EDAUTILS_ROOT/examples/complex_param
comparemoduleinterfaces -sv -goldenFile complex_param.golden.v -revisedFile complex_param.revised.v \
    -top complex_param -outcsv output.diff.csv -outtxt output.diff.txt
```

From the regression suite (reference:
`tests.edautilscommandline/tests/comparemodules/simple_test/runme.csh` via
`../runme_common.csh`):

```
comparemoduleinterfaces -sv -goldenFile simple_test.golden.v -revisedFile simple_test.revised.v \
    -top simple_test -outcsv output.diff.csv -outtxt output.diff.txt
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, reports and `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 status 0 **and** the log contains `Found 0 error(s)` **and** both report
  files exist. The exit status never signals "modules differ"; read the reports.
- Keep the same module name in both revisions (`-top`) until the `-revisedTop` bug is fixed.

### See also

compareentities (VHDL counterpart), parseverilog, genwrapperverilog.
