# designplayer-shell

> All EDAUtils capabilities in commandline mode - Tcl Shell, Python and Java API

- Catalog id: `DesignplayerShell`; bundle: `designplayer-shell`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: IP-XACT tool, IP integration, RTL utilities, Tcl shell, Python API, Java API, EDA command line
- 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/designplayer-shell.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/DesignplayerShell (latest file `designplayer-shell-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/baya-soc-integration-platform/files/designplayer-shell/
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/designplayer-shell/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/designplayer-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.

DesignPlayer is the unified bundle: one Tcl shell that loads every EDAUtils command layer
(RTL utilities, IP-XACT, Baya SoC integration, UPF, SDC), plus the launchers of the other
shells and of every point tool. `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`. The launchers in `bin/` run 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`). `bin/ipxact-shell` passes `--add-opens`,
  which a Java 8 runtime rejects. 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).
- `EDAUTILS_ROOT` = this bundle root. Every launcher 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 flows use 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/designplayer-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) | `designplayer-shell -f script.tcl < /dev/null` (`-in script.tcl` and a bare `designplayer-shell script.tcl` are the same) |
| Interactive | `designplayer-shell` -- prompt `designplayer >`; `exit` or `quit` ends the session |
| Usage | `designplayer-shell -help` |

Options: `-ipxact2009` (IP-XACT 1685-2009 back end), `-verbose` (log every command as it
executes), `-suppress <id>:<id>...` (colon-separated message ids to silence). Any other
argument is taken as the script file name.

At start-up the shell sources `init.designplayer.tcl` from the protected files in `bin/tcl`,
which loads `init.rtlutils.tcl`, `init.ipxact.tcl`, `init.baya.tcl`, `init.upf.tcl` and
`init.sdc.tcl` -- so every shell's commands are available in one session.

The bundle also carries the single-domain shells, which run from the same jar:
`baya-shell`, `ipxact-shell`, `upf-shell` and `rtlutils-shell`. (`brigid-shell` was retired in s62; use `rtlutils-shell` and its `rtlutils_` commands.)

#### 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 DesignPlayer (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. |

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 `init.baya.tcl`, `init.ipxact.tcl`, `init.rtlutils.tcl`,
  `init.upf.tcl` and `init.sdc.tcl`; each entry starts `[N] Command : <name>`.
- Command namespaces: the EDAUtils commands live in `baya::`, `ipxact::` and `rtlutils::` namespaces --
  `baya::create_hierarchy`, `ipxact::load_component_file`, `rtlutils::read_verilog`. The old
  prefixed spellings (`baya_create_hierarchy` ...) are kept as deprecated aliases and still work;
  new scripts and generated Tcl use the namespaced form. SDC and UPF commands keep their standard
  names (`create_clock`, `set_input_delay`, `create_power_domain`, `upf_query_object_type` ...).
- At run time: `<command> -help` prints one command's usage; `info commands ::baya::*` (likewise
  `::ipxact::*`, `::rtlutils::*`) lists the commands of one namespace.
- `doc/html/` -- Java API (Javadoc).
- IEEE 1685-2022 TGI: every standard TGI operation is a `tgi::` command (from `init.ipxact.tcl`);
  it reads 1685-2009, -2014 and -2022 documents alike and writes 1685-2022. Session start, IDs,
  return values and fault messages are as in the ipxact-shell guide's TGI section.
- `doc/IntegrationMethodologies/` -- worked integration flows (see Examples) plus
  `README.txt`, `SoC-Intergration.txt`, `IP-XACT-Packaging.txt`.

### Restructure collateral (written after every restructure)

Every `baya::create_hierarchy` / `baya::remove_hierarchy`, and every `baya::punch_ports`,
`baya::feedthrough` and `baya::uniquify`, writes its collateral into an output directory the moment it
completes (punch, feedthrough and uniquify move no instance: their signal report lists the new ports as
ADDED at every instance path, and a uniquified clone shows in `eq_metadata.json`'s `after` hierarchy), and rewrites the cumulative files there; nothing has to be
asked for. The directory is `restructured` unless `-output_dir <dir>` names another; the choice is
kept for the rest of the session, and `baya::write_restructured_files -dir <dir>` writes the same
set into `<dir>` and makes it the directory from then on. An input file is never edited, and a
directory holding one of the design's source files is refused.

```tcl
baya::create_hierarchy -insts u_cpu,u_ddr -new_inst_name u_cpu_ss -new_mod_name cpu_ss \
                       -output_dir restructured_rtl -macro_files tb/tb_paths.vh
baya::remove_hierarchy -inst u_periph_ss           ;# writes into restructured_rtl as well
```

| file | what it holds |
|---|---|
| `<op>.<target>.rpt` | instance paths this operation changed (RENAMED/REPARENTED/MOVED/ADDED/REMOVED) |
| `<op>.<target>.signals.rpt` | nets and ports whose hierarchical name changed: MOVED, MERGED (a port of a dissolved level that is now the parent net), ADDED (with CONNECTED_TO for a new port), REMOVED |
| `restructure_summary.rpt` | original instance path -> final path, every restructure so far |
| `signal_summary.rpt` | original signal path -> final path, every restructure so far |
| `hierarchy_before.rpt`, `hierarchy_after.rpt` | the whole instance tree before the first and after the last restructure |
| `<module>.restructured.v`, `restructured.f`, `restructure_files.rpt` | each created or changed module; exactly those files; NEW / MODIFIED / REDUNDANT with both paths |
| `restructured_compile.f` | compiles and elaborates the restructured design: original files still needed, the restructured ones, `<module>.kept.v` for an untouched module of a file that also held a rewritten one, `+incdir+` lines (output directory first) |
| `<macro file>`, `macro_update.rpt` | the `` `define `` files with their hierarchical paths re-spelled (same name, in the output directory); UPDATED / NEEDS_A_HUMAN rows |
| `eq_metadata.json` | `fecad.eq_metadata/1` for an equivalence check of the restructured RTL against the original: `before`/`after` hierarchy (flattened instance path -> module) and filelists, `prefix_renames` (the outermost instance moves, `u_a.` -> `u_new.u_a.`) and `renames` (signal moves those prefixes do not imply, `u_sub.a` -> `u_sub.a` as yosys flattens the escaped `\\u_sub.a `). fecad's eq_check turns it into eqy match rules; `tools/regress/rtl_equiv.py -map` pairs nodes with it |
| `*.upf`, `*.sdc`, `intent_restructure.rpt` | with `-update_upf` / `-update_sdc`, as below |

- Signal names follow the flattener's own spelling: Baya lifts a dissolved level's net as the
  escaped `\<inst>.<net> `. A signal inside an instance that only moved is not listed: apply the
  instance report's BEFORE -> AFTER prefix to it.
- Each signal change is also printed (message 7241; `suppress_message`-able on a big design), with
  a one-line count per operation (7240) and the directory written (7242).
- Macro files: every file named with `-macro_files f1,f2` (on either command or on
  `baya::write_restructured_files`, kept for later restructures), plus every file the design read
  a `` `define `` from that defines no module. In each `` `define `` body a dotted path is re-rooted
  where its first component is an instance (or signal) of the original top, so a testbench prefix
  such as `tb.u_dut.` is kept. A path to something that no longer exists is left as it was and
  reported NEEDS_A_HUMAN (warning 7243). A body that now ends in an escaped identifier gets a line
  continuation onto an empty line, so its terminating space survives (iverilog and verilator).
- `restructured_compile.f` lists only modules reachable from the top; a REDUNDANT file and an
  ungrouped wrapper drop out. A Baya-BUILT design has no source files, so note 7244 lists the
  modules it cannot name: print the design first. Check it with
  `hdl_compile`-style tools or `iverilog -g2012 -s <top> -c restructured_compile.f`.
- VHDL restructures write their per-operation reports and the VHDL files the same way; the
  cumulative summaries and the hierarchy files cover the Verilog side.
- `rtlutils::verilog_create_hierarchy` and `rtlutils::verilog_module_remove_hierarchy` write the
  per-operation instance and signal reports, `hierarchy_before/after.rpt` and the macro files the
  same way (also `-output_dir` / `-macro_files`, kept for later calls), but no
  `restructured_compile.f`: they return a module object and print no RTL.

Hierarchical names follow every create/remove/move: a name in any module of the design that passes
through a moved or dissolved instance -- downward (`u_a.q`), absolute (`top.u_mid.u_a.q`), upward by
module name (`mid.u_a.q`) or by instance name -- is re-spelled (`u_grp.u_a.q`, the flattened `u_a_q`
or escaped `\u_a.q `, the instance's new path); a module changed only by that re-spelling is
written as MODIFIED. The point tools write it beside their output too.

### Tied and unconnected instance ports

`baya::report_tied_unconnected -output <file.json> [-rpt <file.rpt>]` on the loaded, elaborated
design (current module and below): one row per instance port bit range tied to a constant or left
open, and the top's ports nothing connects. It combines the connection database (constant
connections: `source {"connection_db": "<module>/<inst>/<pin>"}`) with the elaborated netlist:
constants in a port actual (sized / unsized literals, `'0` / `'1`, replications, parameters that
evaluate to a constant, per bit inside a concatenation), floating `baya_open_*` nets (`source
{"net": ...}`, message 50403 for the whole port, 51088 for some bits), output bits nothing reads
(51086), an empty actual `.p( )` and a port with no connection (`source "default"`). Bits are flat:
a packed `[3:0][7:0]` port is bits `[31:0]`. JSON schema `eu.baya.tied_unconnected/1`:
`{"schema", "top", "design", "rows": [{"instance_path", "module", "port", "direction",
"bits": [msb, lsb], "state": "tied0|tied1|tied_value|open|partially_open", "value",
"source", "message_id"}]}`; the `.rpt` is the same as a table. Returns the row count (-1 on error).
The existing `print_tied/open/unconnected/undriven_port_report` reports are unchanged. CSV row
provenance is not recorded by the connection database, so a CSV-made tie cites its connection.

```tcl
baya::import_verilog_filelist -file rtl.f
baya::elaborate -module soc_top
baya::report_tied_unconnected -output tied_unconnected.json
```

Example: `examples/report_tied_unconnected` (`examples/baya-shell/report_tied_unconnected` in designplayer-shell).

### Making a module structural

`baya::make_structural -module <m> [-group cluster|one|each] [-prefix <p>] [-output_dir <dir>]`
moves every non-instance item of a loaded module -- assigns, `always*`, `initial`, `final`, gates,
UDPs, concurrent assertions, operators in port actuals (a VHDL entity: processes and concurrent
assignments) -- into glue modules, the same engine as the `makestructural` point tool (see
`tools/makestructural/AGENTS.md`). Every signal stays declared in the module. The files go to
`-output_dir` (default `restructured`: the module, one file per glue, `makestructural.f`,
`makestructural.json`, `eq_metadata.json`); for Verilog the result is read back, so the module is
redefined in the session and `baya::print_verilog_file` writes the glue modules with it (also
those instantiated inside a generate). Returns 1 when the module was made structural; 0 with an
error naming file:line when something cannot move unchanged (nothing is changed then).

```tcl
baya::import_verilog_filelist -file rtl.f
baya::elaborate -module soc_top
baya::make_structural -module soc_top -output_dir structural
baya::print_verilog_file -module soc_top
```

Example: `examples/make_structural` (`examples/baya-shell/make_structural` in designplayer-shell).

`-update_upf` / `-update_sdc` (after `baya::import_upf` / `baya::import_sdc`): a register a moved
block drives, and a named gate / UDP instance, is now one level down inside its glue instance, so
`-elements`, retention elements, `get_cells` and `get_pins` naming it are re-spelled
(`u_mid/o3_reg` -> `u_mid/u_mid_glue_5/o3_reg`); nets keep their names (every signal stays declared
in the module). A wildcard at the module's level is listed under NEEDS A HUMAN. The updated files and
`intent_restructure.rpt` go into `-output_dir`. Glue inside a generate block is not re-spelled.

Hierarchical names in moved code: a read `u_sub.sig` becomes a glue input whose actual is the
hierarchical name; a continuous assign to a net below (`assign u_sub.n = ...`) becomes a glue output
with that actual, and to a literal select of one (`assign u_sub.n[3:2] = ...`) a slice port, so each
slice keeps its own driver (another select is refused, message 62011); absolute and upward names stay
as written; a procedural write below needs the design top (makestructural `-top`).

`baya::make_structural -unwrap [-module <m>] [-glue <regex>] [-output_dir <dir>]` is the inverse:
every instance of a glue module (default `.*_glue_[0-9]+`) -- in `-module`, or in every module, also
where create/remove/move hierarchy put it -- is replaced by the glue's statements with each port
replaced by its actual and each forwarded parameter by its override; a signal a glue drove
procedurally becomes a variable again (`wire` -> `reg`, `output` -> `output reg`); an operator port
actual makestructural moved out goes back into the instance and its net is removed; functions, tasks,
`let`, `property`, `sequence`, default clocking and package imports the glue carried are declared in
the module that lacks them. The changed modules are written (`unwrap.f`, `unwrap.json`) and read
back. Nothing changes when a glue cannot be unwrapped exactly (a select inside a slice port, a
connected-to-nothing port the body uses); returns the number of glue instances unwrapped, -1 then.

### Moving an instance to another hierarchy

`baya::move_instance <from> <to> [-new_name <n>] [-update_upf] [-update_sdc]` moves an instance
from its parent into another hierarchy and keeps every connection: the levels between it and the
common ancestor with its destination are ungrouped around it (it is lifted out, its connections
carried up), then the destination's levels are grouped around it (it is pushed down) -- confined to
the moved instance, so no other instance, net or statement moves or changes name. Paths are `/` or
`.` separated, with or without the top's name:

```tcl
baya::move_instance top/mid1/leaf1/grand_leaf1 top/mid2/leaf2/
baya::move_instance top.mid1.leaf1.grand_leaf1 top.mid2.leaf2 -new_name gl -update_upf -update_sdc
baya::move_instance mid1/leaf1/grand_leaf1 /        ;# up to the top
```

Many moves -- the normal case when a SoC is re-partitioned -- go in ONE call, a batch:

```tcl
baya::move_instance -file moves.txt                 ;# one pair per line: <from> <to> [<new name>], '#' comments
baya::move_instance -list {{top/ss0/cl0/u_dbg top/dbg_ss} {top/ss1/cl.*/u_trc top/dbg_ss/trc}}
baya::move_instance top/a/u_x top/b -list {...} -file more.txt -update_upf -update_sdc   ;# all one batch
```

- A `<from>` with a regular-expression character (`* + ? [ ] ( ) | { } ^ $`) is a pattern: every
  instance whose path matches it, level by level (each level a whole-name regular expression;
  levels `/`-separated, or `.`-separated where a `.` followed by `* + ? {` stays in its level), goes
  to that destination: `top/ss_[0-3]/u_cl_.*/u_dbg[01]`. A pattern that matches nothing refuses the batch.
- The batch checks every move first and changes nothing when any is refused (each reason printed,
  message 62263, then `... : nothing was changed`). Batch-only refusals: an instance moved twice, an
  instance inside another moved instance (two calls), two instances landing under one name in one
  module, destinations inside each other in a circle, a malformed line (`<file>:<line>`), an
  unreadable file, a half positional pair beside `-list` / `-file` (62262).
- Every destination is remembered before anything moves, as the instance it names: a destination
  inside an instance the same batch moves follows it, and a destination may be spelled where
  another moved instance lands (`{top/u_src/u_y top/u_far/u_box}` with `{top/u_side/u_box top/u_far}`).
- Then the ungroup (every instance lifted to the common ancestor with its destination), then the
  group (each pushed down into its destination). The hierarchical-name re-spelling, the
  UPF/SDC, the report (`move_instance.<N>_instances.rpt`) and the collateral are done once per
  batch, and the instantiation counts once, so a batch of N moves costs N route plans plus one
  pass over the design -- never N passes. Note 62267 counts the instances moved and modules changed.
  Measured (tests `bigparse/bigmove`, 8,700 leaves): 528 instances in one batch, 13.9 s for the whole
  run against 229 s as 528 calls; no heap beyond what reading the design needs.

- Each connected port of the instance becomes a route: from its old parent up through new ports
  (`<instance>_<port>`) to the common ancestor, then down through new ports to the destination,
  where the instance is connected to it. An input route starts `assign <route> = <old actual>` in
  the old parent, an output route ends `assign <old actual> = <route>`; where the old or new parent
  is the common ancestor its own expression is used. Literal constant inputs are connected in place.
- Parameter overrides are folded to the values they had on the old path (`#(.W(LW*2))` -> `#(.W(4))`).
- Hierarchical names through the instance (`mid1.leaf1.grand_leaf1.q`, `top.mid1...`) are
  re-spelled to its new absolute path.
- `-update_upf` / `-update_sdc`: the instance's paths (domain elements, retention, `get_cells`,
  `get_pins`) follow it; new ports crossing a domain boundary get their supplies / isolation as
  `baya::feedthrough` gives them.
- Refused, nothing changed, the reason printed (message 62263): a module on either branch below the
  common ancestor instantiated more than once (`baya::uniquify -inst <path>` first), an instance
  inside a generate block, a connected `inout`, a parameter or width that is not constant on the
  path, a destination inside the instance, a name already used there, a VHDL design.
- Collateral as for create/remove (`move_instance.<name>.rpt`, `REPARENTED` rows, signal reports,
  restructured files). Returns the number of modules changed, -1 when refused (a batch stopped by
  an unforeseen error after its checks reports how many instances it moved; none has been seen).

Example: `examples/baya-shell/move_instance` -- needs the command layer re-encrypted after this release's Tcl change (it predates `baya::move_instance`); it writes `out_rtl/`. `move_batch.tcl` there runs `moves.txt` as one batch -- grand_leaf1 renamed `gl` into leaf2 while the pattern `top/mid2/leaf.*` moves leaf2 into mid1, so gl ends at `top/mid1/leaf2/gl` -- into `out_batch/` (`restructured_batch/` holds what it writes).

### Restructuring with the power intent and the constraints

`baya::create_hierarchy` / `baya::remove_hierarchy` can keep the design's UPF and SDC in step with
the new hierarchy, each switched on separately:

```tcl
baya::import_upf soc_top.upf          ;# no -module/-inst: the design's own UPF (and every load_upf -scope file)
baya::import_sdc soc_top.sdc          ;# the design's own SDC (and every file sourced under current_instance)
baya::create_hierarchy -insts u_cpu,u_ddr -new_inst_name u_cpu_ss -new_mod_name cpu_ss -update_upf -update_sdc -partition_intent
baya::remove_hierarchy -inst u_periph_ss -update_upf -update_sdc
baya::write_restructured_files -dir out_rtl   ;# all of the collateral above, again, into out_rtl
```

- The RTL is the same with or without `-update_upf`/`-update_sdc`.
- Every instance, pin, cell and net name is re-spelled for the new hierarchy (`-elements`,
  `-scope`, `-ports`, isolation/retention signals, `u_x/PD.primary`-style names in power states,
  every `get_pins/get_cells/get_nets`, `current_instance`). A net that a removed level pulls up is
  named `<inst>.<net>` (the escaped Verilog identifier, spelled without backslash).
- `-partition_intent` (create only) gives the new hierarchy its own `<new_mod_name>.upf/.sdc`:
  the parent's `load_upf` of every scope now inside it moves there, each supply the parent
  connected inside it is punched through a supply port of the same name, and every SDC statement
  whose objects all lie inside it moves to a file sourced under `current_instance` from the top
  SDC. `baya::remove_hierarchy` inlines a file loaded at the dissolved scope back into its parent.
- Without `-partition_intent` (a flat UPF/SDC) only the names change.
- A statement that cannot be mapped to a definite new name (a wildcard at the level that changed,
  a removed pin, an unsupported command naming a changed object) keeps its text and is listed
  under `NEEDS A HUMAN` in `intent_restructure.rpt`; check that count before using the files.
- Verify the result with `elabvl -upf out_rtl/soc_top.upf -sdc out_rtl/soc_top.sdc -lint_upf
  -lint_sdc` on the restructured RTL: exit 0 means every name binds.

#### VHDL designs

A design imported with `baya::import_vhdl` / `baya::import_vhdl_filelist` is restructured as VHDL
(never converted to Verilog). `baya::set_current_module -name <entity>` selects the architecture
to work in, including an entity a previous `baya::create_hierarchy` created.

- `baya::create_hierarchy` moves the labelled instantiations into a new entity, instantiated back
  with `entity work.<new_mod_name>`. A signal the moved instances share only among themselves moves
  inside; any other becomes a port with the signal's own name and subtype indication. The new
  units get the parent's context clauses, so every package type (records, arrays, subtypes) stays
  visible; constants, types, subprograms and component declarations of the parent architecture the
  moved text names are copied in, and a parent generic it names becomes a generic mapped through.
  An `out` port also read inside is driven from a `<name>_int` signal (VHDL-93 legal).
- `baya::remove_hierarchy` inlines the instance's architecture: its declarations, generics (as
  constants) and statement labels are renamed `<inst>_<name>`; a port connected to a whole signal
  takes that signal's name, any other port goes through a `<inst>_<port>` signal. The child's
  context items join the parent architecture's. `-all_levels` inlines every VHDL instance it
  brings up in turn. In UPF/SDC a flattened name is `<inst>_<name>` (not `<inst>.<name>`).
- Not supported, reported as an error with nothing changed: a signal driven in part by the moved
  instances and still used outside them, a new port whose type the parent architecture declares
  locally, an `inout` port of a removed instance connected to anything but a whole signal.
- `baya::write_restructured_files` writes `<file>.restructured.vhd` for each changed file and
  `<entity>.restructured.vhd` for each new entity, `restructured.f` (exactly those files),
  `restructured_compile.f` (the whole design in analysis order, absolute paths), and
  `restructure_files.rpt` (NEW / MODIFIED / REDUNDANT). Check the result with
  `anvh -filelist out_rtl/restructured_compile.f` then `elabvh -top <top> -upf ... -sdc ...`.

#### Mixed Verilog/VHDL designs

`baya::import_mixed_hdl_filelist -filelist <list> -top <module or entity>` reads a list holding
both languages (`.vhd/.vhdl/.vho/.vhi/.vhq` are VHDL, `lib=file` names a VHDL library; the rest
are Verilog). Every VHDL entity becomes a module the Verilog side can instantiate; the VHDL text
is kept. The top may be in either language, with the languages layered at any depth.

- A restructure inside a VHDL architecture is written as VHDL (as above), one inside a Verilog
  module as Verilog; a VHDL group may hold Verilog component instances and a Verilog group VHDL
  instances. UPF/SDC paths are followed through both languages.
- `baya::remove_hierarchy` of a VHDL instance from a Verilog module (or with `-all_levels` over
  one) is refused: the Verilog side holds only the entity's ports. Dissolve VHDL from inside a
  VHDL architecture.
- `restructured_compile.f` lists the whole design, both languages: an original Verilog file is
  replaced by the restructured files when a module of it was rewritten (keep one module per file).
- A flattened name is `<inst>.<name>` on the Verilog side and `<inst>_<name>` on the VHDL side.

#### VHDL IPs in a Verilog SoC (print_verilog_file)

An IP imported with `baya::import_vhdl`, `baya::import_vhdl_filelist` or
`baya::import_mixed_hdl_filelist` stays VHDL. `baya::print_verilog_file` writes the SoC (it
instantiates the entity by name) and `components/<m>.v` for the other masters, but **no Verilog
for a VHDL master** -- the log says `Component '<m>' is a VHDL entity: not written as Verilog`.
(Before 2026-10-03 it wrote an empty Verilog module of the entity's ports, which shadowed the
real IP when both were compiled.) Beside `vlog.f` it then writes `mixed_compile.f`: every VHDL
file read, in analysis order (packages included, `lib=` dropped: all in `work`), then the Verilog
it wrote, relative to the list's directory. Hand that list to a mixed-language simulator (VHDL
analysed first) to compile the SoC together with its IPs; `vlog.f` alone no longer elaborates
when the SoC holds a VHDL IP. Verilog `#(...)` overrides are printed for VHDL generics; VHDL
names are case-insensitive and Baya prints them in lower case.

#### Punch ports, feedthrough and uniquify in Baya

`baya::punch_ports -module <m> -ports <name>[@<dir>[@<msb>:<lsb>]],...`,
`baya::feedthrough -from <src> -to <dst>[,...] [-through <inst>,...] [-name <base>] [-width <msb>:<lsb>] [-all_instances]`
and `baya::uniquify -inst <path>` run the punchports planner on Baya's in-memory design (a built
SoC has no source text) and apply its plan to the model; `baya::write_restructured_files` writes
the changed and the copied modules. A feedthrough changes only its own path: a module shared with
another path is copied as `<module>_<instance>` first, unless `-all_instances`. An existing,
connected source pin is reused. Verilog modules only (VHDL in Baya: punchports on the files).

With `-update_upf` / `-update_sdc` (the design's UPF/SDC imported first):

- a new port crossing a power-domain boundary gets `set_port_attributes -driver_supply` (input) or
  `-receiver_supply` (output) naming the primary supply set of the domain outside it;
- the input/output pair a feedthrough adds on a block it passes through is a repeater powered by
  the route's source domain: `set_port_attributes -repeater_supply` in a UPF 2.x file,
  `set_repeater ... -repeater_supply` from UPF 3.0;
- a new output leaving a domain that can be OFF (switched supply, or an OFF power state) is
  isolated: covered by an `-applies_to outputs` strategy, else a new `set_isolation` copying the
  domain's isolation signal, sense, supply and clamp; with no strategy to copy it is NEEDS A HUMAN;
- a new top port copies an existing top port's `set_input_delay` / `set_output_delay`; a
  through-block pair gets `set_max_delay <one clock period>` (one clock only, else NEEDS A HUMAN);
- `ref_name==<m>` and `get_designs <m>` also name the copies; `current_design <m>` is NEEDS A HUMAN.

#### IO pad ring and pinmux from a SPIDER workbook

`baya_generate_pinmux` and `baya_check_pinmux` read the SPIDER sheet of an `.xls`/`.xlsx` workbook, one
row per pad. Columns are found by header through an alias map, so a team's own header names work
unchanged; the column set, vocabulary, error ids and outputs are in `doc/PINMUX_SPIDER.md`.

```
baya_check_pinmux    -xlsx chip_pins.xlsx [-sheet SPIDER] [-waiver pinmux.waiver] [-report chip.pinmux.rpt]
baya_generate_pinmux -xlsx chip_pins.xlsx -out pinmux [-sheet SPIDER] [-top chip_pinmux] [-waiver pinmux.waiver] [-integrate]
                     [-no_ipxact_component] [-no_ipxact_busdef] [-busdef_lib <dir>]...
```

- A bad workbook (missing required column, unknown pad type, duplicate pad or ball, unparsable cell, a
  function on an instance or port the current design does not have) returns text starting
  `ERROR PINMUX : N errors, nothing written`, one indented line per error naming
  `worksheet '<sheet>' row <n> column '<header>'`, and writes nothing.
- Checks PMX-01..PMX-12 are listed by `baya_check_pinmux -help` (PMX-09..12: pad placement).
- An optional CONFIG sheet, or `-config key=value,...`, selects `architecture iomux`: IOMUX cell, IO mux, IP
  mux and IOMUX controller (MUX MODE + PAD SETTINGS registers, APB / AXI4-Lite / none, shadow commit,
  break-before-make, sticky locks), a chip IO top, an SV pad interface and a self-checking testbench. See
  doc/PINMUX_SPIDER.md "CONFIG sheet" and "IOMUX architecture". Waivers use the CDC/RDC format:
  `rule=PMX-01 from=<pad glob> to=<signal glob> reason="..." owner=<name>`; stale waivers are reported.
  An unwaived ERROR finding stops generation.
- Outputs in `-out`: `<top>.v`, `<top>_padring.v`, `<top>_regs.{rdl,xml,v}`, `<top>.h`, `<top>.dtsi`,
  `<top>_tb_pinmap.sv`, `<top>_conn.sva`, `<top>_pintable.txt`, `<top>_integrate.tcl` and
  `<top>.pinmux.rpt`, whose `SUMMARY` block is `key : value` lines (pads, functions, errors, warnings,
  waived, stale waivers, rules skipped, files). All outputs are deterministic.
- IP-XACT, on by default: `ipxact/<module>.xml`, an IEEE 1685-2022 component (vendor `edautils.com`, library
  `pinmux_rtl`) for each of `<top>`, `<top>_regs`, `<top>_padring`, `<top>_io_top` that was generated:
  ports, an APB3 (or AXI4-Lite) target with the register memory map, a `pad_if` interface to the pad ring,
  a `pad_io` interface per bidirectional function signal, and an `rtl` view of the `.v`. The bus and
  abstraction definitions are searched by VLNV in each `-busdef_lib` directory, in
  `EDAUTILS_IPXACT_SEARCH_PATH[_BUS_DEFINITIONS|_ABSTRACTION_DEFINITIONS]` and in
  `$EDAUTILS_ROOT/doc/IntegrationMethodologies/CommonData/BusDefs`; only a missing one is written, under
  `ipxact/busdefs/<vendor>/<library>/<name>/<version>/`. The result lines after `OK PINMUX` say which
  were found and which generated. `-no_ipxact_component` writes none of it; `-no_ipxact_busdef` keeps
  the components but searches for and writes no definitions.
- `-integrate` sources `<top>_integrate.tcl` into the current design: the pinmux and pad ring are
  instantiated and connected to the IP instances the workbook names.
- Success returns one line starting `OK PINMUX`.

### Bundled point tools

designplayer-shell carries every point tool. Each has its own guide, copied from that tool's
release, and its examples under `tools/<tool>/examples/` (run them from there with `bin/` on
`PATH`; `parseverilog`'s `printinfo` compiles against `verilogparser.jar` and is left out).
Launcher name = tool name unless shown otherwise.

| Tool (guide) | Launcher(s) in `bin/` |
|--------------|-----------------------|
| [compareconnectivitydatabase](tools/compareconnectivitydatabase/AGENTS.md) | `compareconnectiondb` |
| [compareentities](tools/compareentities/AGENTS.md) | |
| [compareipxact](tools/compareipxact/AGENTS.md) | |
| [comparemoduleinterfaces](tools/comparemoduleinterfaces/AGENTS.md) | |
| [comparesdc](tools/comparesdc/AGENTS.md) | |
| [compareupf](tools/compareupf/AGENTS.md) | |
| [createhierarchy](tools/createhierarchy/AGENTS.md) | |
| [findinstsornets](tools/findinstsornets/AGENTS.md) | |
| [flatteninstances](tools/flatteninstances/AGENTS.md) | |
| [flattenverilog](tools/flattenverilog/AGENTS.md) | |
| [genconnectiondb](tools/genconnectiondb/AGENTS.md) | |
| [gendocipxact](tools/gendocipxact/AGENTS.md) | |
| [gendocverilog](tools/gendocverilog/AGENTS.md) | |
| [genregistercmodel](tools/genregistercmodel/AGENTS.md) | |
| [genregisterdochtml](tools/genregisterdochtml/AGENTS.md) | |
| [genregisteruvmmodel](tools/genregisteruvmmodel/AGENTS.md) | |
| [genwrapperverilog](tools/genwrapperverilog/AGENTS.md) | |
| [genwrappervhdl](tools/genwrappervhdl/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) | |
| [ipxactlint](tools/ipxactlint/AGENTS.md) | |
| [ipxactreg2verilog](tools/ipxactreg2verilog/AGENTS.md) | |
| [ipxactreg2xlsreg](tools/ipxactreg2xlsreg/AGENTS.md) | |
| [lib2verilog](tools/lib2verilog/AGENTS.md) | |
| [mergemodules](tools/mergemodules/AGENTS.md) | |
| [parseliberty](tools/parseliberty/AGENTS.md) | |
| [parsesdc](tools/parsesdc/AGENTS.md) | |
| [parseupf](tools/parseupf/AGENTS.md) | |
| [parsevcd](tools/parsevcd/AGENTS.md) | |
| [parseverilog](tools/parseverilog/AGENTS.md) | `parseverilog`, `anvl`, `elabvl` (elaborate; `-upf`/`-sdc` bind UPF/SDC onto the elaborated design, `-annotate_*`, `-*_flatout`, `-lint_upf`/`-lint_sdc`; `-out_v2005` writes the elaborated design as Verilog-2005 for Yosys `read_verilog`), `elabmixed` (mixed Verilog/VHDL from the work library or from `-vl`/`-vh`/plain source files, both languages decompiled; same intent options), `genemptymoduleandcsv` |
| [parsevhdl](tools/parsevhdl/AGENTS.md) | `parsevhdl`, `anvh`, `elabvh` (intent options as `elabvl`) |
| [preprocessverilog](tools/preprocessverilog/AGENTS.md) | |
| [punchports](tools/punchports/AGENTS.md) | |
| [removeassignments](tools/removeassignments/AGENTS.md) | |
| [removehierarchy](tools/removehierarchy/AGENTS.md) | |
| [sdc2xls](tools/sdc2xls/AGENTS.md) | |
| [sdclint](tools/sdclint/AGENTS.md) | |
| [swapcells](tools/swapcells/AGENTS.md) | |
| [uniquifyverilog](tools/uniquifyverilog/AGENTS.md) | `uniquifyverilog`, `uniquifymodules` |
| [upflint](tools/upflint/AGENTS.md) | |
| [upgradeipxact](tools/upgradeipxact/AGENTS.md) | |
| [validateipxact](tools/validateipxact/AGENTS.md) | |
| [verilog2ipxact](tools/verilog2ipxact/AGENTS.md) | |
| [verilog2lib](tools/verilog2lib/AGENTS.md) | |
| [verilog2systemc](tools/verilog2systemc/AGENTS.md) | |
| [verilog2vhdl](tools/verilog2vhdl/AGENTS.md) | `verilog2vhdl`, `verilog2vhdlcomponent`, `verilog2vhdlentity` |
| [vhdl2ipxact](tools/vhdl2ipxact/AGENTS.md) | |
| [vhdl2systemc](tools/vhdl2systemc/AGENTS.md) | |
| [vhdl2verilog](tools/vhdl2verilog/AGENTS.md) | |
| [vhdltbgen](tools/vhdltbgen/AGENTS.md) | `gentbvhdl` |
| [vlogtbgen](tools/vlogtbgen/AGENTS.md) | `gentbvlog` |
| [xls2sdc](tools/xls2sdc/AGENTS.md) | |
| [xls2ipxact](tools/xls2ipxact/AGENTS.md) | |
| [xls2upf](tools/xls2upf/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 a designplayer-shell licence (feature `DESIGNPLAYERBACKBONE`), 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`.

All run from `lib/designplayer.jar` here. Other launchers in `bin/`: `verilog2baya`,
`verilog2bayadb`, `csv2bayatcl`, `bayadb2bayatcl`, `parsenetlist`.

### 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. Point-tool examples (`examples/<tool>/...`) are described in that tool's guide.

| Directory | Command |
|-----------|---------|
| `examples/designplayer-shell/baya/create_n_remove_hierarchy` (*) | `designplayer-shell create_design.tcl` |
| `examples/designplayer-shell/baya/Leon-System1` (*) | `designplayer-shell create_design.tcl` |
| `examples/designplayer-shell/ipxact/create_busdef_and_design` (*) | `designplayer-shell commands.tcl` |
| `examples/designplayer-shell/rtlutils/flattenverilog` (*) | `designplayer-shell commands.tcl` |
| `examples/baya-shell/<name>` (*) -- 11 flows | `baya-shell -f commands.tcl` / `-f example.tcl` / `create_design.tcl` (see each `runme.csh`) |
| `examples/baya-shell/vhdl_restructure_intent`, `mixed_restructure`, `feedthrough_intent` | `baya-shell restructure.tcl` / `feedthrough.tcl`: VHDL and mixed restructure, feedthrough and punch with the UPF/SDC updated (need the command layer re-encrypted after s61) |
| `examples/ipxact-shell/{create_busdef,create_busdef_and_design,design_compinst,i2c,import_verilog,verilog_include_dir_windows}` (*) | `ipxact-shell commands.tcl` |
| `examples/rtlutils-shell/{clock_reset_tree_1,clock_reset_tree_2,flattenverilog}` (*) | `rtlutils-shell commands.tcl` |
| `examples/UPF/parser` (*) | `UPF_DIR=$PWD upf-shell -f top.upf` -- a negative example: the self-test expects `Found 11 error(s)` |
| `examples/verilog2baya/Leon-System` (*) | `verilog2baya -f infile.list -top MySoC -out baya_commands.tcl`, then `baya-shell baya_commands.tcl` |
| `doc/IntegrationMethodologies/AdhocConnections` (*) | `baya-shell -f create_design.tcl` |
| `doc/IntegrationMethodologies/AutoConnectAutoTopPort` (*) | `baya-shell -f build_connection.tcl` |
| `doc/IntegrationMethodologies/CSVBasedConnections` (*) | `baya-shell -f build_design.tcl` |
| `doc/IntegrationMethodologies/CSVDirBasedModularConnectionsRecommended` | `baya-shell -f build.tcl` |
| `doc/IntegrationMethodologies/IPXACTCModel` (*) | `baya-shell -f designplayer_commands.tcl` |
| `doc/IntegrationMethodologies/IPXACTCreateBusDef` (*) | `baya-shell -ipxact2009 -f create_abstraction_definition.tcl` then `baya-shell -ipxact2009 -f create_bus_definition.tcl` |
| `doc/IntegrationMethodologies/IPXACTCreateComponent` (*) | `baya-shell -ipxact2009 -f build_component.tcl` |
| `doc/IntegrationMethodologies/IPXACTInterfaceConnection` (*) | `baya-shell -ipxact2009 -f create_design.tcl` |
| `doc/IntegrationMethodologies/SVInterfaceConnection` (*) | `baya-shell -f connect_intf.tcl` |

### Verifiers (`verifiers/`)

The bundle carries the checkers the EDAUtils regression uses to prove a tool's output, so a design
change can be verified on a customer machine (the EDAUtils AI SDK runs them before accepting any
change to a design). Each prints a one-word verdict as its last line; run with `python3`.

| verifier | proves | exit codes |
|---|---|---|
| `verifiers/rtl_equiv.py` | a design before and after a restructure is formally equivalent (yosys) | 0 proven, 1 not, 2 could not read |
| `verifiers/equiv_check.py` | two netlists wire their leaf instances the same way | 0 match, 1 differ, 2 usage/parse |
| `verifiers/vhdl_sv_equiv.py` | a vhdl2verilog output is equivalent to its VHDL (GHDL + yosys) | 0 proved, 1 different, 2 error, 3 bounded (not a pass) |
| `verifiers/hdl_compile.py` | RTL compiles and elaborates (iverilog, verilator, ghdl) | 0 clean, 1 failed, 2 error |
| `verifiers/intent_equiv.py` | power intent and constraints mean the same after a restructure | 0 match, 1 differ, 2 usage |
| `verifiers/intent_syntax.py` | generated UPF/SDC is syntactically valid | 0 pass, 1 fail, 2 a tool could not run |
| `verifiers/uvm_ral_check.py` | a generated UVM register model compiles (slang) | 0 clean, 1 errors, 3 checker missing |
| `verifiers/uvm_ral_sim.py` | a generated register model and its tests simulate clean (Verilator) | 0 pass, 1 fail, 3 simulator/UVM missing |

They need python3 and the free tools the EDAUtils installer provides (OSS CAD Suite with the ghdl and
slang yosys plugins, iverilog, Verilator 5.052 for `uvm_ral_sim`, UVM and pyslang for the RAL checks).
`python3 verifiers/vhdl_sv_equiv.py --self-check` and `python3 verifiers/intent_syntax.py --self-check`
prove the two from the bundle.

### Outputs and logs

- `<shell>.log` in the current directory (`designplayer-shell.log`, `baya-shell.log`,
  `ipxact-shell.log`, ...): every message, and the closing
  `Found N error(s) and M warning(s)` line. Each run overwrites it.
- Design outputs go where the script's commands write them, normally the run directory --
  for the examples, e.g. `system1.v`, `busdef.xml`, `design.xml` and a `components/`
  directory (plus `vlog.f`, and `mixed_compile.f` when
  a Baya design has VHDL IPs) (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. |
| 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 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. |
| Out of memory on a large design | Raise the heap: `JAVA_FLAGS=" -Xmx8g "`. |
