# xls2ipxact

> Convert XLS-based register definition to IP-XACT format

- Catalog id: `Xls2Ipxact`; bundle: `xls2ipxact`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: Excel to IP-XACT, register definition, XLS to IP-XACT, memory map generator
- 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/xls2ipxact.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Xls2Ipxact (latest file `xls2ipxact-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/xls2ipxact/
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/xls2ipxact/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/xls2ipxact-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 a register specification spreadsheet (`.xlsx`; `.xls` is deprecated) and writes the
registers and bit fields as IP-XACT: one addressBlock XML per block in the sheet, or one
memoryMap XML holding all blocks with `-mmap_name`. Output is IP-XACT 1685-2009 unless
`-v2014` / `-v2022` is given. The default reader is header driven and reads the layout
that `ipxactreg2xlsreg` writes; a column-map file (`-column_map`) selects the older
mapped reader for other layouts. Main class: `com.eu.miscedautils.xls2ipxact.xls2ipxact`
(jar `lib/csvxlsutils.jar`).

### Where it ships

Its own bundle, `xls2ipxact.tar.gz` (flow `xls2ipxact`; release tree
`release_scripts/xls2ipxact/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell** and
**designplayer-shell** bundles (`bin/xls2ipxact` running the shell's jar; this guide as
`tools/xls2ipxact/AGENTS.md`, examples under `tools/xls2ipxact/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
  (only the licence loader's own messages are printed; no summary line). Then feature
  `XLS2IPXACT` is checked when the converter is created: without it
  `Failed to checkout LICENSE for the feature : XLS2IPXACT` is printed and the run
  continues with exit 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).

### Invocation

```
xls2ipxact -in <regs.xlsx> [-out <file.xml>] [-v2014 | -v2022] [options]
```

| Option | Meaning |
|---|---|
| `-in <file>` | Input spreadsheet (mandatory) |
| `-out <file>` | Output XML (default `output.xml`) |
| (none) | Write IP-XACT 1685-2009 |
| `-v2014` / `-v2022` | Write IP-XACT 1685-2014 / 1685-2022 |
| `-start_row <n>` | Row where the register definitions start (the row after the header) |
| `-width <n>` | Register width in bits (default 32) |
| `-base_address <addr>` | Base address of the block, `0x` prefix for hex (default `0x0000`) |
| `-range <n[K|M|G]>` | Block range in address units (default `64K`) |
| `-mmap_name <name>` | Put all address blocks into one memory map of this name |
| `-bitunits <n>` | addressUnitBits of that memory map (default 8; only with `-mmap_name`) |
| `-xlsx` / `-xls` / `-csv` | Force the input type (default from the file extension; CSV is not supported for registers) |
| `-column_map <file>` | Column map (`FIELDNAME=F`, `FIELDOFFSET=C`, ...) for the mapped reader; implies `-legacy` (not in `-help`) |
| `-legacy` | Use the mapped reader; needs `-column_map` (prints a warning; not in `-help`) |
| `-user <email>` | Recorded for usage tracking only |
| `-help` | Print usage and exit (there is no `-h`, `-quiet`, `-nobanner` or `-suppress`) |

No arguments prints the usage. An unrecognised option prints
`Error: ...: Unrecognized option : <opt>` followed by the usage. A value-taking option
given last without its value prints the usage and exits 1.

### Inputs / Outputs

- Reads: the `-in` spreadsheet (hidden rows and columns are ignored); the `-column_map`
  file if given.
- Writes: the `-out` XML. Without `-mmap_name`, when the sheet holds several address
  blocks the first goes to `-out` and each further one to `<block name>.xml` in the
  current directory. With `-mmap_name` a single memoryMap goes to `-out`.
- Log: `xls2ipxact.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
  sheet, missing columns, missing `XLS2IPXACT` feature all return 0). 10 = no valid
  licence at start-up. 9 = licence subsystem failed to initialise. 1 = an option missing its
  value, or `EDAUTILS_ROOT` missing/invalid.
- Message format: `xls2ipxact: <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.
- Typical failures: `Missing mandatory switch -in sepcifying the input file ...`,
  `Unsupported file type found ...` (Warning; nothing written),
  `Mandatory input <name|offset|...> column index is missing ...`,
  `Failed to read file : ...`.
- The run ends with `xls2ipxact: Note: <id>: Found N error(s) and M warning(s) ...`
  (there is no `-nobanner`), except when it stopped at the usage.

### Examples

Shipped: `examples/example_latest/` (`runme.csh`, `runme.bat`, `register.xlsx`) and
`examples/multiple_address_blocks/` (`example.xlsx`; the directory also carries an Excel
lock file `~$marc_bennet_2.xlsx`, which is not an input):

```
cd $EDAUTILS_ROOT/examples/example_latest
xls2ipxact -in register.xlsx -out addrblk.xml
cd $EDAUTILS_ROOT/examples/multiple_address_blocks
xls2ipxact -in example.xlsx -range 4G -base_address 0x1000
```

From the regression suite (`tests.edautilscommandline/tests/xls2ipxact/wz_tech_1/runme.csh`
via `../runme_common.csh`, which diffs the XML against `<out>.gld`):

```
xls2ipxact -in register.xlsx -column_map columns.map -start_row 7 -range 4G \
    -base_address 0x100 -out addrblk.xml
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and the XML file(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** the
  `-out` file exists.

### See also

ipxactreg2xlsreg (the reverse direction), genregistercmodel, genregisteruvmmodel,
ipxactreg2verilog, xls2upf.
