# upf2xlsx

> Bring existing UPF (IEEE 1801) power intent into the xls2upf spreadsheet: evaluates the UPF, follows source/load_upf, and writes one workbook per UPF file that xls2upf turns back into equivalent UPF.

- Catalog id: `Upf2xlsx`; bundle: `upf2xlsx`; latest version 20261018
- Keywords: UPF to Excel, UPF to spreadsheet, power intent, IEEE 1801, UPF round trip
- 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/upf2xlsx.md

## Downloads

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

UPF (IEEE 1801 power intent) to the xls2upf power-intent workbook -- the inverse of `xls2upf`, on
the same workbook schema (template 2.0). It reads a top UPF file, **evaluates** it the way a
power-intent tool does (upflint's JTcl loader: `set`, `expr`, `foreach`, `proc`, `if` and
`$variables` run, `source` and `load_upf` are followed), and writes **one workbook per UPF file read**.
`xls2upf` on the top workbook writes every file back as UPF equivalent to the original
(`compareupf` exit 0 -- the regression gate).

Main class: `com.eu.miscedautils.upf2xlsx.upf2xlsx` (jar `lib/designplayer.jar`; the `.bat`
launcher uses the same class). Source: `designplayershell/src/com/eu/miscedautils/upf2xlsx/`
(`UpfToWorkbook.java` the mapping); the schema is xls2upf's
`csvxlsutils/src/com/eu/miscedautils/xls2upf/UpfSchema.java`, the loader upflint's `UpfLoader.java`.

### Where it ships

Its own bundle, `upf2xlsx.tar.gz` (flow `upf2xlsx` in `bundle_jar_files.csh`; release tree
`release_scripts/upf2xlsx/1.0`), and as a point tool in the **upf-shell** and **designplayer-shell**
bundles (`bin/upf2xlsx`; this guide as `tools/upf2xlsx/AGENTS.md`, examples under
`tools/upf2xlsx/examples/`). The regression harness runs it through `tools/regress/bin/upf2xlsx`.

### Prerequisites

- Java on `PATH`: 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).
- `EDAUTILS_ROOT` set to the installation directory (the launcher exits 1 without it); source
  `setup_env.csh` / `setup_env.sh` (or run `setup_env.bat`) from that directory.
- A licence with the `UPF2XLSX` feature (`EDAUTILS_LICENSE_FILE`, else `$EDAUTILS_ROOT/edautils.lic`);
  a `UPFBACKBONE` licence (upf-shell, designplayer-shell) includes it.

### Invocation

```
upf2xlsx -in <top.upf> [-outdir <dir>] [-nobanner] [-user <email>] [-help]
xls2upf  -in <dir>/<top>.xlsx -out <dir>/<top>.upf        # write it back
```

- `-in` -- the top UPF file (one). Every file it `source`s or `load_upf`s is read from it.
- `-outdir` -- where the workbooks go (default `upf2xlsx_out`). A file's workbook sits at the file's
  place below the top file's directory (`ip/cpu.upf` -> `<dir>/ip/cpu.xlsx`; a `..` step becomes
  `__up`). Run `xls2upf` with `-out` in the same directory as the top workbook: it writes each
  sourced or loaded file's UPF at the same relative place, so the regenerated `load_upf`/`source`
  paths resolve from there.

### The workbook (sequenced template 2.0)

One worksheet, `UPF`. A `[design]` block (a description), an `[extern]` block when needed, then one
block per 1801 command used, each row one evaluated command; columns are the schema's
(`AGENTS.md` of xls2upf, "Template 2.0"), plus **`seq`**: the command's place in the file.

- Every row is written back in `seq` order, exactly as given: nothing is re-sorted, invented or
  added (no `upf_version` header, no generated power states, no `-update`, no deferred `-supply`).
- `set_scope`, `upf_version`, `begin_power_model` and `end_power_model` are rows of their own, so
  any number of scope moves and power models sit beside other commands.
- `source f` is a `[sub_ips]` row of mode `source`; `load_upf f -scope i` one of mode `scope` with
  `instance` i (no instance: a plain `load_upf`). `source` names the child's workbook, relative to this
  one. A file read twice (one IP into two scopes) has one workbook and two rows.
- `add_power_state` / `add_state_transition` with several `-state`/`-transition`: one row per state,
  the second and later with `update` yes (`complete` on the last).
- `[extern]` (kind, name): names this file uses that another file defines (the file that sources it,
  a sibling). Found by xls2upf's own reference check, so the workbook translates on its own.
- Names are per scope: after `set_scope u1`, `PD` is `u1/PD`; inside a power model `M::PD`.
- Values are cells as xls2upf reads them: a value with spaces or Tcl specials is braced; an empty
  value is `{}`; a `find_objects` call is kept as `[find_objects ...]`.
- **Carried, never dropped**: a command the schema has no block for (`define_power_model`,
  `create_abstract_power_source`, a vendor or upf-shell command ...), an option or a value no cell can
  hold exactly, goes to `[raw_commands]` as evaluated, at its `seq` -- with Warning 10651 naming the
  file, line and construct, and a per-construct count in the summary (10657).
- Loops, variables and procs are written out evaluated: the workbook holds the commands the UPF ran.

### Inputs / Outputs

- Reads: the `-in` file and every file it sources or loads (relative paths as given, else beside the
  file that names them). `exec`, `open` and other machine-touching Tcl are not executed.
- Writes: one `.xlsx` per UPF file under `-outdir`. Nothing when nothing can be imported.
- Log: `upf2xlsx.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0: imported (warnings do not fail). 2: nothing could be imported (Error 10655: no 1801 command was
  read; no workbook written), or an internal error (10699). 1: usage error (10650: unknown option,
  missing `-in`, unreadable input). 10: no licence.
- Warnings: 10651 a construct carried in `[raw_commands]`; 10653 a statement not imported (a Tcl error
  in the input, a file `source`/`load_upf` names that cannot be read).
- Notes: 10654 each workbook written; 10652 the totals (rows, raw-carried, not imported); 10657 the
  raw-carried constructs with counts.
- Message format: `upf2xlsx: <Severity>: <id>: <text>` (the log adds 50000 to the id).

### Examples

Each in its own directory with a `runme.csh` that imports, writes back, and reads the result:

- `single_file/` -- one UPF file: supplies, domains, strategies, power states.
- `multi_file/` -- a top that `source`s a file and `load_upf -scope`s one IP into two instances
  (three UPF files, three workbooks).
- `power_model/` -- a power model file beside its `apply_power_model`.

```
cd $EDAUTILS_ROOT/examples/multi_file
./runme.csh            # upf2xlsx -in top.upf -outdir out; xls2upf -in out/top.xlsx -out out/top.upf
```

Regression: `tests.edautilscommandline/tests/upf2xlsx/<case>/` via `runme_roundtrip.sh`: upf2xlsx,
xls2upf exit 0, upf-shell reads the result with no more errors than the original, compareupf exit 0,
one workbook per file read (`workbooks.gld`), the raw-carried constructs (`raw.gld`), and
`intent_syntax.csh`. The cases run every upfcorpus case, the clean `upf` cases and upflint's
`clean_*` inputs (through `SRC`), plus `multi_source` and `nothing_importable`.

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes its log 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, then `xls2upf` exit 0 and `compareupf -golden <orig> -revised <regen>`
  exit 0. A 10651 warning means a construct is carried as text: equivalent, but not editable as cells.

### See also

xls2upf (the other direction, same schema), compareupf, upflint, upf-shell.
