# ipxactreg2xlsreg

> Export the registers of an IP-XACT address block to an Excel register spreadsheet for review and documentation.

- Catalog id: `Ipxactreg2xlsreg`; bundle: `ipxactreg2xlsreg`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: IP-XACT to Excel, register spreadsheet, register export, 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/ipxactreg2xlsreg.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Ipxactreg2xlsreg (latest file `ipxactreg2xlsreg-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/ipxactreg2xlsreg/
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/ipxactreg2xlsreg/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/ipxactreg2xlsreg-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.

Reads an IP-XACT register description (an addressBlock, memoryMap, memoryMaps or component
XML) and writes the registers of each address block into an Excel workbook (`.xlsx`, one
sheet named `REGISTERS`) in the layout that `xls2ipxact` reads back, so the pair gives an
IP-XACT -> spreadsheet -> IP-XACT round trip. Main class:
`com.eu.miscedautils.ipxact2xls.ipxact2xls` (jar `lib/csvxlsutils.jar`).

### Where it ships

Its own bundle, `ipxactreg2xlsreg.tar.gz` (flow `ipxactreg2xlsreg`; release tree
`release_scripts/ipxactreg2xlsreg/1.0`), and as a point tool in the **ipxact-shell**,
**baya-shell** and **designplayer-shell** bundles (`bin/ipxactreg2xlsreg` running the shell's jar;
this guide as `tools/ipxactreg2xlsreg/AGENTS.md`, examples under
`tools/ipxactreg2xlsreg/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: two checks. At start-up any valid licence file is required, else exit status 10
  (the only messages are the licence loader's own, e.g. `Failed to checkout LICENSE, you
  must set environment variable 'EDAUTILS_LICENSE_FILE' ...`; no summary line). Then feature `IPXACT2XLS` is checked when
  the converter starts: without it the tool prints
  `Failed to checkout LICENSE for the feature : IPXACT2XLS`, writes nothing and 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).
- No external tools needed (no spreadsheet application is required to write the `.xlsx`).

### Invocation

```
ipxactreg2xlsreg -in <ipxact.xml> [-out <file.xlsx>] [-v2009 | -v2022]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT XML input (mandatory) |
| `-out <file>` | Output workbook (default `output.xlsx`) |
| (none) | Input read as IEEE 1685-2014 |
| `-v2009` | Input is IP-XACT 1685-2009 |
| `-v2022` | Input is IP-XACT 1685-2022 (not in the usage text) |
| `-user <email>` | Recorded for usage tracking only |

There is no `-help`, `-quiet`, `-nobanner` or `-suppress`: any other argument (including
`-help`) prints `Error: ...: Unrecognized option : <opt>` followed by the usage. No
arguments prints the usage. Missing `-in` prints
`Missing mandatory switch -in sepcifying the input file ...` and the usage.

### Inputs / Outputs

- Reads: the `-in` XML.
- Writes: the `-out` workbook. When a memory map holds more than one address block, each
  block is written to `<block name>.xlsx` (spaces removed) in the current directory instead,
  and `-out` is not used.
- Log: `ipxactreg2xlsreg.log` in the current directory (override with `EDAUTILS_LOG_FILE`).
- Side effect of the licence start-up: a per-user temporary directory
  `<java.io.tmpdir>/<user>/.edatuls/tcl/...` is created (nothing is decrypted into it,
  this bundle ships no protected Tcl).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing `-in`, unreadable
  XML, missing `IPXACT2XLS` feature all return 0). 10 = no valid licence at start-up.
  9 = licence subsystem failed to initialise (`Fatal Error: Failed EDAUtils init() ...` on
  stderr). 1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `ipxactreg2xlsreg: <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.
- Each workbook written is reported as `Created Register XLSX File : <file>`; an unreadable
  input as `Failed to read IP-XACT Register Definition File : <file>`.
- The run always ends with `ipxactreg2xlsreg: Note: <id>: Found N error(s) and M warning(s) ...`
  (there is no `-nobanner`), except when it stopped at the usage.

### Examples

Shipped: `examples/addressblk/` (`runme.csh`, `runme.bat`, `addrblk.xml`):

```
cd $EDAUTILS_ROOT/examples/addressblk
ipxactreg2xlsreg -v2009 -in addrblk.xml -out register.xlsx
```

From the regression suite (`tests.edautilscommandline/tests/ipxactreg2xlsreg/ipxact_2014/runme.csh`
via `../runme_common.csh`, which converts the workbook back with `xls2ipxact` and diffs the
XML against `output.xml.gld`):

```
ipxactreg2xlsreg -in i2c.xml -out i2c.xlsx
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and the workbook(s) 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** a
  `Created Register XLSX File` line for each expected workbook.

### See also

xls2ipxact (the reverse direction), genregisterdochtml, ipxactreg2verilog.
