# ipxact-shell

> All IP-XACT utilities in commandline with Tcl/Python API

- Catalog id: `IpxactShell`; bundle: `ipxact-shell`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT, IEEE 1685, IP-XACT editor, IP-XACT generator, Tcl API, Python API
- 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/ipxact-shell.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/IpxactShell (latest file `ipxact-shell-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/ipxact-shell/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/ipxact-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 IP-XACT Tcl shell: create, read, edit and write IP-XACT components, bus/abstraction
definitions, designs and register maps (IEEE 1685-2009, -2014, -2022), plus the IP-XACT
point tools. `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/ipxact-shell` also runs `java ... --add-opens
  java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED`, which Java 8 rejects. Extra
  JVM options go in `$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 `\`.
- VHDL import uses the precompiled libraries in `vhdl_pkgs/` (`lib/` with `qtmap.ini`, the
  IEEE 1076-2019 set `lib2019/` with `qtmap2019.ini`; `*.win.ini` on Windows).

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/ipxact-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 (script) | `ipxact-shell -f script.tcl < /dev/null` (`-in script.tcl` and a bare `ipxact-shell script.tcl` are the same) |
| Interactive | `ipxact-shell` -- prompt `ipxact >`; `exit` or `quit` ends the session |
| Usage | `ipxact-shell -help` |

Options: `-v2009` or `-v2022` select the IEEE 1685-2009 or -2022 back end; without either the
shell runs the 1685-2014 back end. A session runs against one revision only. `-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.ipxact.tcl` from the protected files in `bin/tcl` at start-up, then
runs your script line by line.

#### 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 IP-XACT 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. |
| 12 | Both `-v2009` and `-v2022` given (message 9508). |

The run ends with `Found N error(s) and M warning(s) ...`; a run is clean only when N is 0.
The release self-test judges every example exactly that way (`grep "Found 0 error(s)"`).

### Tcl command reference

- `doc/TclCommandReference.txt` -- generated at release time by running `<command> -help`
  for every command proc in the shipped `init.ipxact.tcl`; each entry starts
  `[N] Command : <name>`. (The `TclCommandReference.txt` at the bundle root is an older,
  hand-kept copy; use the one in `doc/`.)
- Command namespace: the IP-XACT commands live in the `ipxact::` namespace, e.g.
  `ipxact::load_component_file`. The old prefixed spellings (`ipxact_load_component_file` ...)
  are kept as deprecated aliases and still work; new scripts use the namespaced form.
- At run time: `<command> -help` prints one command's usage; `info commands ::ipxact::*` lists
  the IP-XACT commands.
- `doc/html/` -- Java API (Javadoc).

#### TGI (IEEE 1685-2022 Tight Generator Interface)

The `tgi::` namespace carries every IEEE 1685-2022 TGI operation (2,469), named and ordered
as in the standard: `tgi::getRegisterArrayID $reg`, `tgi::setFieldAccessPolicyAccess $p read-only`.

- Start a session with `tgi::init 2.1 fail "<message>"`; load a document with
  `tgi::registerVLNV <file> false`. 1685-2009 and -2014 documents are upgraded to 1685-2022
  in memory on load, so one script reads all three revisions; what TGI writes is 1685-2022,
  whichever back end (`-v2009`/`-v2022`) the shell runs.
- IDs are opaque strings (`tgi:6`). Lists come back as Tcl lists, booleans as `1`/`0`,
  `get<X>` returns the evaluated value and `get<X>Expression` the expression text.
- Registered documents are listed by `tgi::getComponentIDs`, `getDesignIDs`,
  `getDesignConfigurationIDs`, `getAbstractionDefIDs`, `getBusDefIDs`, `getAbstractorIDs`,
  `getGeneratorChainIDs` and `getCatalogIDs`; `tgi::createCatalog <vlnv>` makes a new catalog
  (`tgi::save` writes only designs and components).
- A failed call logs `Error: 59601: tgi::<op>: fault <N>: ...` (N = the IEEE 1685 fault code)
  and returns empty. It counts in `Found N error(s)`, and the exit code stays 0. An ID of the
  wrong kind for an operation (a component instance given to `getComponentChannelIDs`, say)
  is fault 5, `no element ... under a <class>`.
- Not every operation is served yet: one still unimplemented answers fault 5, `not supported
  yet`. From Tcl, `[[java::call com.eu.miscedautils.shell.Tgi instance] lastFault]` returns
  `"<code>: <message>"` for the last `tgi::` call, or empty when it succeeded.

### Bundled point tools

Each has its own guide, copied from that tool's release. Launcher name = tool name unless
shown otherwise. All run from `lib/ipxact.jar` in this bundle. Its examples ship under `tools/<tool>/examples/` (run them from there with `bin/` on `PATH`).

| Tool (guide) | Launcher(s) in `bin/` |
|--------------|-----------------------|
| [compareipxact](tools/compareipxact/AGENTS.md) | |
| [gendocipxact](tools/gendocipxact/AGENTS.md) | |
| [genregistercmodel](tools/genregistercmodel/AGENTS.md) | |
| [genregisterdochtml](tools/genregisterdochtml/AGENTS.md) | |
| [genregisteruvmmodel](tools/genregisteruvmmodel/AGENTS.md) | |
| [ipxact2tcl](tools/ipxact2tcl/AGENTS.md) | |
| [ipxact2tlm](tools/ipxact2tlm/AGENTS.md) | |
| [ipxact2verilog](tools/ipxact2verilog/AGENTS.md) | |
| [ipxact2vhdlentity](tools/ipxact2vhdlentity/AGENTS.md) | |
| [ipxactcoherencychecker](tools/ipxactcoherencychecker/AGENTS.md) | `ipxactcoherencycheckerverilog`, `ipxactcoherencycheckervhdl` |
| [ipxactinterface2svinterface](tools/ipxactinterface2svinterface/AGENTS.md) | |
| [ipxactreg2verilog](tools/ipxactreg2verilog/AGENTS.md) | |
| [ipxactreg2xlsreg](tools/ipxactreg2xlsreg/AGENTS.md) | |
| [ipxactlint](tools/ipxactlint/AGENTS.md) | |
| [parseverilog](tools/parseverilog/AGENTS.md) | `parseverilog`, `anvl`, `genemptymoduleandcsv`, `preprocessverilog` |
| [parsevhdl](tools/parsevhdl/AGENTS.md) | `parsevhdl`, `anvh` |
| [upgradeipxact](tools/upgradeipxact/AGENTS.md) | |
| [validateipxact](tools/validateipxact/AGENTS.md) | |
| [verilog2ipxact](tools/verilog2ipxact/AGENTS.md) | |
| [vhdl2ipxact](tools/vhdl2ipxact/AGENTS.md) | |
| [xls2ipxact](tools/xls2ipxact/AGENTS.md) | |

`ipxactlint` (IEEE 1685-2009/2014/2022 linter: the Annex B SCRs, the schemas' K.1/K.2 identity
constraints, and for 1685-2022 documents the `EU-2022-*` rules derived from the 2022 schema, User
Guide and release notes, pending the 2022 Annex B) runs under an ipxact-shell licence (feature `IPXACTBACKBONE`), which grants
its `IPXACTLINT` feature. Its examples under `tools/ipxactlint/examples/` -- clean, findings,
waivers, soc_2014, legacy_2009, dmac_2022, waiver_flow, ci_gate -- are run by this bundle's
self-test; each `runme.csh` exits 0 only when its expected result holds. Exit status, rules and
waivers: `tools/ipxactlint/AGENTS.md`.

`elabvh`, `elabvl` and `elabmixed` (mixed Verilog/VHDL) are also in `bin/` and run on `lib/ipxact.jar`: analyse
VHDL/Verilog into a work library (or hand `elabmixed` the source files directly), then elaborate,
optionally binding a UPF (`-upf`) and an SDC (`-sdc`) onto the elaborated design, with annotation,
flattened intent and Level 1 + Level 2 lint (options, reports and messages in the parseverilog and
parsevhdl AGENTS.md, "Intent options" and "elabmixed"). `bin/schemas` holds
IP-XACT XML schemas (`.xsd`) and `bin/xsl` IP-XACT version-conversion stylesheets.

### Examples

Run each from inside its directory with the environment above; `runme.csh` in each directory
holds the command. `(*)` = run and checked for `Found 0 error(s)` by the release self-test of
this bundle.

| Directory | Command |
|-----------|---------|
| `examples/create_busdef` (*) | `ipxact-shell commands.tcl` |
| `examples/create_busdef_and_design` (*) | `ipxact-shell commands.tcl` |
| `examples/design_compinst` (*) | `ipxact-shell commands.tcl` |
| `examples/i2c` (*) | `ipxact-shell commands.tcl` |
| `examples/import_verilog` (*) | `ipxact-shell commands.tcl` |
| `examples/verilog_include_dir_windows` (*) | `ipxact-shell commands.tcl` |
| `examples/create_register` | `ipxact-shell commands.tcl` |
| `examples/ipxact2tlmsystemc` (*) | `ipxact2tlm -in dma_regmodel.xml -outdir syscsrc -genregmodel` (log `GenTLMModel.log`) |
| `examples/compareipxact/i2c` | `compareipxact -revised i2c.xml -golden i2c.modified.xml -component -outfile Diff.rpt` |

`examples/comparemoduleinterfaces/` is also present, but its `comparemoduleinterfaces`
launcher is not in this bundle's `bin/`; run it from the comparemoduleinterfaces,
baya-shell or designplayer-shell bundle.

### Outputs and logs

- `ipxact-shell.log` in the current directory: every message, and the closing
  `Found N error(s) and M warning(s)` line. Each run overwrites it.
- IP-XACT and other outputs go where the script's commands write them, normally the run
  directory -- for the examples, e.g. `busdef.xml`, `design.xml`, `component.xml` (the files
  the release self-test deletes after checking the log).

### Common errors

| Symptom | Fix |
|---------|-----|
| `Environment variable EDAUTILS_ROOT is not set` | Export `EDAUTILS_ROOT` to the bundle root. |
| `Unrecognized option: --add-opens` from java | Java 8 on `PATH`; use Java 11 or newer (21 recommended). |
| 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. |
| Exit 12 | Give only one of `-v2009` / `-v2022`. |
| Exit 0 but the log says `Found N error(s)` with N > 0 | A command failed; the log names it and the script line. Exit status alone is not a pass. |
| `Failed to open file : '<script>' to read` (exit 1) | Wrong script path; it is resolved from the current directory. |
