# xls2upf

> Generate a UPF (IEEE 1801) power-intent file from an Excel spreadsheet of power domains, supply sets, isolation, retention, level shifters and power states.

- Catalog id: `Xls2upf`; bundle: `xls2upf`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: Excel to UPF, UPF generator, power intent, IEEE 1801, low power spreadsheet
- 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/xls2upf.md

## Downloads

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

Translates a power-intent spreadsheet into a UPF (IEEE 1801) file, default `output.upf`, for UPF
2.1, 3.0, 3.1 (default) or 4.0. Two input layouts are read, `.xlsx` or `.xls` either way:

- **Template 2.0** (any workbook with a `[design]` block; write one with `-write_template`): every
  1801 command, names entered once and checked, supplies/supply sets/power states derived, sub-IPs
  (hierarchy), version checking. This is the layout to use.
- **Template 1.x** (the older one-worksheet-per-construct layout of the shipped `examples/*.xls`):
  still translated, worksheet by worksheet, without the checks above.

Main class: `com.eu.miscedautils.xls2upf.xls2upf` (jar `lib/csvxlsutils.jar`; the `.bat` launcher
uses the same class).

### Where it ships

Its own bundle, `xls2upf.tar.gz` (flow `xls2upf`; release tree `release_scripts/xls2upf/1.0`), and
as a point tool in the **upf-shell** and **designplayer-shell** bundles (`bin/xls2upf` running the
shell's jar; this guide as `tools/xls2upf/AGENTS.md`, examples under `tools/xls2upf/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`, prepends `bin/` to `PATH` and sets
  `CLASSPATH=$EDAUTILS_ROOT/lib/csvxlsutils.jar`.
- Licence: a valid licence file (none: exit status 10, messages 6037/6405) and feature
  `XLS2UPF` (the bundle's licence carries it). If the feature is missing,
  `Error: 6404: Failed to checkout LICENSE for the feature : XLS2UPF` is logged; from the source,
  the translation is not stopped by it (not exercised with a feature-less licence). 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; 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). No tool-specific environment variables are read.
- No external tools needed (Excel is not required; Apache POI is inside the jar).

### Invocation

```
xls2upf -in <file.xlsx|file.xls> [-out <file.upf>] [-upf_version 2.1|3.0|3.1|4.0] [-user <email>]
xls2upf -write_template <file.xlsx>
```

| Option | Meaning |
|---|---|
| `-in <file>` | Power-intent workbook to read (mandatory unless `-write_template`) |
| `-out <file>` | UPF file to write (default `output.upf`); sub-IP UPFs are written beside it |
| `-upf_version <v>` | UPF version to write: 2.1, 3.0, 3.1 or 4.0. Default: the workbook's `[design] upf_version`, else 3.1. Any other value exits 1 |
| `-write_template <file>` | Write the template 2.0 workbook (`.xlsx`) and exit |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and return (`-h` is not recognised) |

There is no `-nobanner`, `-quiet` or `-suppress`. Any other option prints Error 9075
"Unrecognized option : <opt>" followed by the usage.

### Template 2.0

The workbook is a set of blocks, on any worksheet. A row whose column A is `[command]` opens a
block; the next row names its columns; every following row with column A empty is one command. A `#`
in column A comments a row out. The template has one worksheet per area (Design, Sub IPs, Supplies,
Power Domains, Supply Sets, Logic, Power Switches, Port Attributes, Isolation, Level Shifters,
Repeaters, Retention, Power States, Library Cells, Cell Mapping, Simulation, Legacy), a help comment on
every column header, and drop-downs for enumerated values, yes/no flags and defined names.

- Columns are the 1801 option names without the dash (`domain`, `applies_to`, ...), `name` for the
  command's object, supply functions as columns in `create_supply_set` (`power`, `ground`, `nwell` ...),
  domain supply handles as columns in `create_power_domain` (`primary`, `default_isolation`,
  `default_retention`, `extra_supplies`), and for `add_power_state`/`add_state_transition` one row per
  state: `kind` (supply/domain/group/model/instance), `state`, `logic_expr`, `supply_expr`,
  `power_expr`, `simstate`, `legality`.
- Blocks of the workbook's own: `[design]` (design_top, scope, upf_version, power_model, module);
  `[supplies]` (name, port, voltage, switchable, domain, connect_ports, resolve) -- one row writes the
  supply port, net and connection; `[sub_ips]` (instance, source, mode, model, module, supply_map);
  `[raw_commands]` (text written as is, at the end); `[extern]` (kind, name: names another file
  defines -- the file that sources this one -- so a reference to them is not an error).
- **Sequenced workbooks** (what `upf2xlsx` writes; one schema for both tools): any block may carry a
  `seq` column. When a row has one, every row is written in `seq` order exactly as given -- nothing is
  re-sorted, derived or added (no `upf_version` header unless `[design]` names one, no generated
  states, no `-update`, no deferred `-supply`); `set_scope`, `upf_version`, `begin_power_model` and
  `end_power_model` are rows of their own; `[raw_commands]` rows land in place; a `[sub_ips]` row is a
  `load_upf` (mode `scope`; no instance: no `-scope`) or a `source` (mode `source`) where it stands, its
  UPF written at the sub-workbook's place below the top workbook's directory and named relative to
  the file that loads it. Names are then per scope (`u1/PD` after `set_scope u1`, `M::PD` inside power
  model M), a second definition is Warning 10635 (written as it stands), and `-reuse` never counts as
  one. A `seq` that is not a whole number is Error 10634.
- Every name is defined once. A second definition, or a reference to a name nothing defines, is an error
  naming the cell(s). A domain's handles (`PD.primary` ...) need no definition; a `create_supply_set` row
  named `PD.primary` gives that handle its nets (written with `-update`).
- Derived: supply sets whose power net has a voltage get an ON state (and OFF when the net is switchable
  or a power switch output, which also inherits the switch input's voltage) unless Power States gives
  their own; strategy names left empty become `<iso|ls|rep|ret>_<domain>_<n>`; a second state row for an
  object gets `-update`; commands are written in dependency order whatever the row order. Warnings
  10631/10632 name a domain that can be off with no isolation strategy, and domains at different
  voltages with no level-shifter strategy (the netlist is not read, so these are for review).
- Versions: a command or option not in the target version is an error with its cell. Legacy commands
  (`create_pst`, `add_pst_state`, `add_port_state`, `set_domain_supply_net` ...) warn up to 3.1 and are
  errors for 4.0. `add_power_state -group/-model/-instance`, power models, `set_repeater`,
  `use_interface_cell` and the `define_*` cells need 3.0; `add_state_transition` and `set_variation` 3.1.
  UPF 4.0 is written as 3.1 without the legacy commands: 1801-2024's own additions are not modelled.
- Sub-IPs (`[sub_ips]`): `source` is the sub-IP's `.xlsx`/`.xls` (translated recursively to
  `<stem>.upf` beside `-out`) or its `.upf`. `mode scope` (default) writes `load_upf <file> -scope
  <instance>`; `mode power_model` wraps the sub-IP in `begin_power_model <model> -for {<module>}` (unless
  its own `[design] power_model` says it is one) and writes `load_upf` plus `apply_power_model <model>
  -elements {<instance>} -supply_map ...`. The sub-IP's domains, supply sets, supply ports and nets can
  then be referred to as `<instance>/<name>`. A sub-IP that includes itself is an error.

### Template 1.x

- Worksheet names are matched case-insensitively with spaces removed: `HEADER`, `Custom Commands`,
  `Load Upf`, `Logic Ports Nets`, `Supply Ports Nets`, `CSN CLN CSS ASS`, `Supply Sets`,
  `Power Domains`, `SPA`, `SDA`, `Isolation`, `Retention`, `Level Shifter`, `Repeater`,
  `Power Switches`, `PM Cells`, `Power States`. Any other worksheet is skipped with Warning 9085.
- A `HEADER` sheet that declares a power model makes the output end with `end_power_model`.
- A cell whose text does not balance its braces/brackets is reported with its worksheet, row and
  column (Error 9458 if the assembled UPF does not balance). No name, reference or version checks.

### Inputs / Outputs

- Reads: the `-in` workbook, and each sub-IP source it names (relative paths are from the workbook's
  directory).
- Writes: `-out` (default `output.upf`) and, for spreadsheet sub-IPs, `<stem>.upf` in the same
  directory. Nothing is written when the input cannot be read (Error 9065).
- Log: `xls2upf.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0: translated with no error. 2: the translation reported errors (the UPF is still written, for
  inspection, but is not to be trusted), or `-write_template` failed. 1: an option without its value, or
  a bad `-upf_version`; also `EDAUTILS_ROOT` missing/invalid (launcher). 10: no valid licence file.
- Message format: `xls2upf: <Severity>: <id>: <text>`; template 2.0 messages start with the cell,
  e.g. `worksheet 'Isolation' row 3 column 'domain': the domain 'PD_B' is not defined anywhere in this
  workbook`.
- The run ends with `xls2upf: Note: <id>: Found N error(s) and M warning(s) ...`.

### Examples

`examples/soc_hierarchy/` (template 2.0): `soc_top.xlsx` with two spreadsheet sub-IPs (`dsp.xlsx`
loaded into its scope, `pll.xlsx` applied as a power model) and one UPF sub-IP (`mem.upf`).

```
cd $EDAUTILS_ROOT/examples/soc_hierarchy
xls2upf -in soc_top.xlsx -out soc_top.upf
upf-shell -f soc_top.upf        # reads it back
```

Template 1.x, each in its own directory with a `runme.csh`: `cpu`, `cpu_configuration`,
`cpu_constraints`, `cpu_implementation`, `MEMSRAM_1024X32`, `PHY3TX2RX0P8V`. These translate, but their
data has intent errors a UPF reader reports (supply nets before any domain, handles never given a
function); the `cpu` example loads its three sibling UPFs by name.

Regression: `tests.edautilscommandline/tests/xls2upf/<case>/` -- `template2_*` and `seq_*` (sequenced
workbooks, built by `make_workbook.py` from their `.spec.py`) cases via
`runme_template2.csh` (exit status, every `*.upf.gld`, the log, and a clean upf-shell read-back), and
`power_intent_template` (template 1.x).

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and outputs into the current directory: give each parallel run its own directory.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0. To check the UPF reads back, `upf-shell -f <out>` and look for `Error`
  in `upf-shell.log`.

### See also

upf2xlsx (the other direction: existing UPF into this workbook schema, one workbook per UPF file),
parseupf, compareupf, upf-shell, xls2ipxact.
