# upf-shell

> UPF parser, editor, decompiler, and validator (IEEE 1801-2013 compliant)

- Catalog id: `UpfShell`; bundle: `upf-shell`; latest version 20261018
- Documentation page: https://edautils.com/UPF.html
- Keywords: UPF parser, IEEE 1801, UPF validator, UPF decompiler, power intent, low power
- 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/upf-shell.md

## Downloads

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

The UPF (IEEE 1801 power intent) Tcl shell: reads UPF files as Tcl scripts into a power-intent
data model you can query, edit and write back, plus the UPF point tools (compare, parse, lint, spreadsheet to UPF).
`README.txt` in this directory is the human overview; this file is the agent's reference.

All paths below are relative to the bundle root (the directory holding this file).

### 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). `bin/upf-shell` runs plain `java` with `$JAVA_FLAGS` (e.g. `JAVA_FLAGS=" -Xmx4g "`; unset
  or without a heap option, the launcher adds `-Xmx` sized to the machine, see `bin/eu_heap.sh`).
- `EDAUTILS_ROOT` = this bundle root. Every launcher in `bin/` exits 1 with
  "Environment variable EDAUTILS_ROOT is not set" otherwise.
- A licence. The bundle ships `edautils.lic`, a time-limited evaluation licence issued when
  the bundle was built. The tool looks for a licence in this order: `$EDAUTILS_LICENSE_FILE`,
  `./edautils.lic` (run directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`.
  It must carry this release's content key, or the protected Tcl layer in `bin/tcl` cannot be
  decrypted (exit 11, see below).
- Optional: `EDAUTILS_DISABLE_USAGE_TRACKING=1` (or `true`) stops the tool opening its
  usage-report mail connection -- set it in sandboxes and offline runs.
  `EDAUTILS_DISABLE_AUTO_EMAILS_TO_EDAUTILS=1` has the same effect.
- Optional: `EDAUTILS_TCL_ENABLE_SPACE_CHECK_IN_MULTILINE_CMD=1` makes the shell repair a
  script whose continuation lines have blanks after the trailing `\`.

Environment set-up, equivalent to `setup_env.sh` / `setup_env.csh` / `setup_env.bat`
(which must be sourced from the bundle root -- they use the current directory):

```sh
export EDAUTILS_ROOT=/path/to/upf-shell/<DATE>
export EDAUTILS_LICENSE_FILE=$EDAUTILS_ROOT/edautils.lic
export PATH=$EDAUTILS_ROOT/bin:$PATH
export EDAUTILS_DISABLE_USAGE_TRACKING=1
```

### Launching

| Mode | Command |
|------|---------|
| Batch (UPF or Tcl script) | `upf-shell -f top.upf < /dev/null` (`-in top.upf` and a bare `upf-shell top.upf` are the same) |
| Interactive | `upf-shell` -- prompt `upf-shell>`; `exit` or `quit` ends the session |
| Usage | `upf-shell -help` |

Options: `-verbose` logs every command as it executes; `-suppress <id>:<id>...` silences those
message ids; `-user <email>`. Any other argument is taken as the script file name.

The shell sources `init.upf.tcl` from the protected files in `bin/tcl` at start-up, then runs
your file line by line. A UPF file is itself the script: its `load_upf`, `source` and
`$env(...)` references are resolved as the file is executed.

#### Exit codes and how to judge a run

| Exit | Meaning |
|------|---------|
| 0 | The script reached its end (or `exit`). **Commands that failed do not change this** -- check the log. |
| 1 | The script file could not be opened (message 700), or `EDAUTILS_ROOT` unset (launcher). |
| 9 | Fatal start-up error in the licensing/init layer. |
| 10 | No valid licence, or the licence does not enable the UPF shell (messages 6037/6405). |
| 11 | Protected Tcl in `bin/tcl` failed its signature check (9410) or could not be decrypted (9422) -- wrong/old licence for this release, or a modified installation. |

A Tcl error in a command (a syntax error such as curly quotes read as words, an unknown command) is reported as
Error 50111 with the Tcl message and the first 200 characters of the command; the command is not executed and the
run goes on with the next one.

The run ends with `Found N error(s) and M warning(s) ...`; a run is clean only when N is 0.

### How UPF is read and written back

- Names are per scope: `set_scope` (relative, `..`, `/`; `.` returns to the scope the file started in -- the design
  top, or the `load_upf -scope` instance -- the way real decks end a `set_scope u_sub` block) and `load_upf -scope <inst>` make the
  scope current; a file loaded with `-scope` sees `/` as that instance, and the previous scope and
  file are restored when it ends. One IP UPF can be loaded into several instances.
- `-update` refines the existing object (domain, supply set, strategy, power state; a power
  state's `-logic_expr` is ANDed). A second `create_supply_set`/`create_power_domain` without
  `-update` warns and refines; a second `create_supply_net`/`create_*_port` without `-reuse` is
  reported (log 50652 / 53258).
- `associate_supply_set SS -handle PD.h` (and `create_power_domain -supply {h SS}`) records the
  association on both sets, and each takes the functions the other has (so `PD.h.power` is SS's
  power net), also when a function is given later. Different nets of the same scope for the same
  function are an error (log 60935); across a scope boundary the association is the connection.
- Lists are Tcl lists (`-elements {a b}`, `-lib_cells {..}`, `-isolation_signal {..}`, quoted
  items). A bus bit `n[0]` is a name; a logic net name keeps its dots.
- `decompile_upf_model <file>` writes legal 1801 Tcl (s64, checked by tools/regress/intent_syntax.py
  in the upf/upfcorpus/parseupf families): a name Tcl would substitute in -- a bus bit `n[0]`, `$`,
  `;` -- is braced (`create_logic_net {n[0]}`); a logic net is written without `-domain` (only
  `create_supply_net` has it); a switch state keeps an unbraced expression (`-on_state {ON in 10}`);
  `-ack_port {p "" expr}` keeps its empty net as `{}`; a `map_retention_cell` whose strategy did not
  resolve keeps the name it was given. It writes the whole model so that it reads back into the same model:
  `upf_version`/`set_design_top`, power models and cell definitions first, then every scope's
  objects and then every scope's relations, each section opened by an absolute `set_scope`.
  Commands the model does not interpret (`map_isolation_cell`, `merge_power_domains`,
  `set_pin_related_supply`, `sim_*`, `create_abstract_power_source`, ...) are recorded in their
  scope and written back as given (log 60920). `compareupf -golden <in> -revised <decompiled>`
  exits 0 when they are equivalent (see tools/compareupf/AGENTS.md).
- Messages added for this (log number = 60900 + n): 60900 `-version` ignored note, 60901/60903
  undefined supply set, 60904/60905 `-domain` not in the scope (net/port made without it), 60906
  function net stand-in, 60907/60908 domain `-elements`/`-scope`, 60909/60910 associate_supply_set
  inputs, 60911 set_isolation supplies, 60912 create_power_switch without a domain, 60913-60916
  apply_power_model maps, 60917 `-available_supplies`, 60918/60919 port attribute supplies,
  60920-60924 recorded commands / save_upf, 60925 `-hide_globals`, 60926 `-literal_supply`, 60927
  parameter variable, 60934 add_pst_state row longer than the table, 60935 conflicting association.

### Tcl command reference

- `doc/TclCommandReference.txt` -- generated at release time by running `<command> -help`
  for every command proc in the shipped `init.upf.tcl` (the EDAUtils `upf_*` query/edit
  commands); each entry starts `[N] Command : <name>`. The standard IEEE 1801 commands
  (`create_power_domain`, `load_upf`, ...) are the UPF language itself and are not listed there.
- At run time: `<command> -help` prints one command's usage; `info procs` lists the Tcl procs
  the command layer defines.
- `doc/html/` -- Java API (Javadoc) of the UPF data model and parser.

### Bundled point tools

Each has its own guide, copied from that tool's release, and ships its launchers (unix and
`.bat`). All run from `lib/upf.jar` here. Its examples ship under `tools/<tool>/examples/` (run
them from there with `bin/` on `PATH`).

| Tool (guide) | Launcher in `bin/` |
|--------------|--------------------|
| [compareupf](tools/compareupf/AGENTS.md) | `compareupf` |
| [parseupf](tools/parseupf/AGENTS.md) | `parseupf` |
| [upflint](tools/upflint/AGENTS.md) | `upflint` |
| [upf2xlsx](tools/upf2xlsx/AGENTS.md) | `upf2xlsx` |
| [xls2upf](tools/xls2upf/AGENTS.md) | `xls2upf` |

### Examples

Run each from inside its directory with the environment above. The release self-test of this
bundle runs none of them (designplayer-shell's self-test runs `examples/UPF/parser`, which is
the same `top.upf` flow as `mini_soc` below).

| Directory | Command |
|-----------|---------|
| `examples/mini_soc` | `UPF_DIR=$PWD upf-shell -f top.upf` (`runme.csh`; `top.upf` sources `$env(UPF_DIR)/soc/soc.upf`) |
| `examples/simple_2` | `upf-shell -f simple_2.upf` (no `runme.csh`; `simple_2.upf` loads `mid1.upf`, which loads `leaf1.upf`) |
| `examples/compareupf/trivial_upf` | `compareupf -revised cpu_constraints.modified.upf -golden cpu_constraints.upf -outfile Diff.rpt` |

### Outputs and logs

- `upf-shell.log` in the current directory: every message, and the closing
  `Found N error(s) and M warning(s)` line. Each run overwrites it.
- Anything else is written only where your script's commands write it.

### Common errors

| Symptom | Fix |
|---------|-----|
| `Environment variable EDAUTILS_ROOT is not set` | Export `EDAUTILS_ROOT` to the bundle root. |
| Exit 10, `Failed to checkout LICENSE ... EDAUTILS_LICENSE_FILE` | Point `EDAUTILS_LICENSE_FILE` at a valid licence (the shipped `edautils.lic` expires; ask help@edautils.com for a new one). |
| Exit 11, message 9410 or 9422 | The licence is not one issued for this release, or `bin/tcl` was changed. Use the licence that came with this bundle, reinstall the bundle. |
| `mini_soc` fails to source `soc/soc.upf` | `UPF_DIR` is not set; set it to the example directory. |
| Exit 0 but the log says `Found N error(s)` with N > 0 | A command failed; the log names it and the line. Exit status alone is not a pass. |
| `Failed to open file : '<file>' to read` (exit 1) | Wrong file path; it is resolved from the current directory. |
