# compareupf

> Compare two UPF power-intent files (IEEE 1801) and report added, removed and changed power domains, supply sets, isolation and retention strategies.

- Catalog id: `Compareupf`; bundle: `compareupf`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: UPF compare, UPF diff, power intent comparison, IEEE 1801
- 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/compareupf.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Compareupf (latest file `compareupf-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/compareupf/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/compareupf-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 UPF (IEEE 1801 power intent) files for logical equivalence. Each file is sourced into
an embedded Tcl interpreter running the upf-shell command layer, which builds a UPF data model;
the two models are then compared semantically (`UPFSemanticCompare`): every object is named by its
place in the design (`scope(/u_cpu) / PowerDomain PD1 / Isolation iso1`) and each of its modelled
attributes and references is a fact; the files are equivalent when their fact sets are equal.
Order of commands, how they were spelled (`-update`, loops, `load_upf`, one list or several
options) and file/line bookkeeping do not matter. Output is a numbered difference list in UPF
terms, written to a text file (default `diff.txt`) and echoed to the log.
Main class: `com.eu.miscedautils.upfparser.compareupf` (jar `lib/designplayer.jar` in this bundle;
the upf-shell bundle runs the same class from `lib/upf.jar`).

### Where it ships

Its own bundle, `compareupf.tar.gz` (flow `compareupf`; release tree
`release_scripts/compareupf/1.0`), and as a point tool in the **upf-shell** and
**designplayer-shell** bundles (`bin/compareupf` running the shell's jar; this guide as
`tools/compareupf/AGENTS.md`, examples under `tools/compareupf/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`.
- Protected Tcl layer: `$EDAUTILS_ROOT/bin/tcl/*.tcl.encrypted` plus the signed
  `edautils.manifest` (copied in from designplayer-shell by the release build). At start-up
  they are verified and decrypted into a private temp folder under `java.io.tmpdir`; the UPF
  commands come from `init.upf.tcl`. A missing/invalid signature (message 9410) or a failed
  decryption (9422) is a Fatal Error and exit status 11. Do not add, remove or edit files in `bin/tcl`.
- Licence features `UPFCOMPARE` (checked at start-up) and `UPFBACKBONE` (needed by the UPF
  command layer that reads the files, e.g. `load_upf`); the bundle's licence carries both. The
  licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run
  directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. No `UPFCOMPARE`: Error 6404
  `Failed to checkout LICENSE for the feature : UPFCOMPARE` and exit status 10.
- 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).
- No external tools needed (the Tcl interpreter is inside the jar).

### Invocation

```
compareupf -golden <file.upf> -revised <file.upf> [-outfile <file>] [-user <email>]
```

| Option | Meaning |
|---|---|
| `-golden <file>` | Golden UPF file (mandatory) |
| `-revised <file>` | Revised UPF file (mandatory) |
| `-outfile <file>` | Difference report (default `diff.txt`) |
| `-origin <file>` | Accepted and recorded, but never used (3-way compare is not implemented; not in the usage text) |
| `-user <email>` | User id for usage registration |

There is no `-help`, `-nobanner` or `-quiet`: any unknown word (including `-help`) gives
Error 7007 "Unrecognized option : <opt>", the usage, and exit 1. Missing `-golden`/`-revised`:
Error 5151 "Missing mandatory input(s) ..." (the text says "IP-XACT file"; it means UPF), the
usage, exit 1. The banner is always printed. An option given without its value is an internal
exception and exit 1.

### Inputs / Outputs

- Reads: the two UPF files, executed as Tcl through the UPF command layer. `load_upf` and
  `source` inside them are followed, so the files they name must be reachable from the
  current directory or the including file's directory.
- Writes: the `-outfile` report (empty when equivalent). One line per difference:
  `[  n] <kind> : <object> : <attribute> : <golden value> -> <revised value>`, kind one of
  `Changed`, `Missing in revised`, `Added in revised`; an object present on one side only is
  `[  n] Only in golden : <object>` / `[  n] Only in revised : <object>`. Example:
  `[  1] Changed : scope(/) / PowerDomain PD_WR / Isolation iso_wr : clampValue : latch -> 0`.
- `EDAUTILS_COMPAREUPF_DUMP=<prefix>`: also writes every fact of each model, one per line, to
  `<prefix>.golden.facts` and `<prefix>.revised.facts` (to see why two files compare as they do).
- What is not compared (documented normalisations): file/line, symbol tables and transient
  bookkeeping; `PowerDomain.supplyNets/supplyPorts` (a summary that set_domain_supply_net,
  handle `-function` and `create_supply_net -domain` fill differently -- the facts behind it are
  compared); `PowerDomain.defaultPowerDomain` (set by elaboration); `Instance.associatedPowerDomains`
  (the inverse of a domain's `-elements`); the scope attribute of nets and ports (their container
  is compared); a logic net's domain (where the parser met it -- IEEE 1801 has no
  `create_logic_net -domain`, so a decompiled file cannot carry it; a supply net's `-domain` is
  compared). Expressions compare with runs of white space collapsed; an enumeration left unset
  compares as its default (an unset `-isolation_sense` equals `low`); an unset port direction as
  `in` (the create_supply_port default). connect_supply_set `-connect` maps are compared.
- Log: `compareupf.log` in the current directory (override with `EDAUTILS_LOG_FILE`).
  The differences are echoed between `******************Differences ***` markers.

### Exit status and messages

- **0 = equivalent** (no differences). **1 = the files differ** (or an unrecognised option,
  missing mandatory input, or an internal exception). **2 = a file could not be read or loaded**
  (Error 10932 `Cannot read the UPF file '<f>'`, then Error 10930 `Could not load the golden or
  the revised UPF file, nothing compared`). 10 = licence checkout failed. 11 = protected Tcl
  content failed its signature check or decryption. 1 also = `EDAUTILS_ROOT` missing/invalid
  (launcher).
- Errors the UPF files themselves raise while loading (an undefined domain, a typo'd command)
  are reported and the load goes on with the next command (as `upf-shell -f` reads the same file; a Tcl error
  is Error 50111 with the Tcl message and the command), so a command that failed is in neither model; the
  comparison is only as good as the loads, so check the log's error count too.
- Message format: `compareupf: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`, `Programming Error`; `<id>` is a 5-digit message number.
  Key notes: `Loading golden file : <f>`, `Loading revised file : <f>`,
  `Found total differences : N`, `Written differences into file : <f>`, then 10931
  `The golden and revised UPF are equivalent ...` or `... differ ...`.
- The run ends with `compareupf: Note: <id>: Found N error(s) and M warning(s) ...`.

### Examples

Shipped: `examples/trivial_upf/` (`runme.csh`, `cpu_constraints.upf`,
`cpu_constraints.modified.upf`; two differences, so compareupf exits 1 and `runme.csh` maps
that to 0). The release self-test runs it and requires `Found 0 error(s)` in `compareupf.log`:

```
cd $EDAUTILS_ROOT/examples/trivial_upf
compareupf -revised cpu_constraints.modified.upf -golden cpu_constraints.upf -outfile Diff.rpt
```

From the regression suite (reference:
`tests.edautilscommandline/tests/compareupf/simple_upf_1/runme.csh`; golden `Diff.rpt.gld`;
the top files `load_upf` four more files each):

```
compareupf -revised cpu.modified.upf -golden cpu.upf -outfile Diff.rpt
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and the default report into the current directory: give each parallel run
  its own working directory (or distinct `-outfile` and `EDAUTILS_LOG_FILE`). Temp files use
  unique names, so parallel runs do not collide in `java.io.tmpdir`.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Equivalence test: exit status 0. Exit 1 = they differ (read the report); exit 2 = an input
  could not be loaded. Typical use -- prove a decompiled UPF is the input:
  `compareupf -golden top.upf -revised decompiled.upf -outfile compare.rpt; echo $?`
  (the regression family `tests/upfcorpus` does exactly this for real-life UPF).

### See also

comparesdc, parseupf, xls2upf, upf-shell.
