# createhierarchy

> Group instances to build new Tile/Partition in SoC

- Catalog id: `Createhierarchy`; bundle: `createhierarchy`; latest version 20261018
- Documentation page: https://edautils.com/CreateHierarchy.html
- Keywords: create hierarchy, group instances, Verilog partition, RTL restructuring, SoC tile
- 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/createhierarchy.md

## Downloads

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

Reads a Verilog/SystemVerilog design, takes a list of instances inside one module (`-top`) and
moves them into a newly created module (`-new_mod_name`), instantiated back in the top module
under a new hierarchy name (`-new_hier_name`). Port count of the new module is optimised by
default. Output is a single Verilog file (default `output.v`) holding the modified top module
and its sub-modules. Main class: `com.eu.miscedautils.verilogparser.CreateHierarchy`
(jar `lib/verilogparser.jar`).

### Where it ships

Its own bundle, `createhierarchy.tar.gz` (flow `createhierarchy`; release tree
`release_scripts/createhierarchy/1.0`), and as a point tool in the **baya-shell** and
**designplayer-shell** bundles (`bin/createhierarchy` running the shell's jar; this guide as
`tools/createhierarchy/AGENTS.md`, examples under `tools/createhierarchy/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` and prepends `bin/` to `PATH`.
- Licence feature `CREATEHIERARCHY`. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. No licence for the feature: exit status 10.
- Optional environment: `JAVA_FLAGS` (passed to the JVM, e.g. `-Xmx8g`; 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), `EDAUTILS_ENABLE_DEBUG_ENVIRONMENT=1` (debug messages).
- No external tools needed.

### Invocation

```
createhierarchy -in <file.v> | -f <filelist>  -top <module>  -instances <i1:i2:...>
                -new_hier_name <inst name>  [-new_mod_name <module name>]  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Module that contains the instances (mandatory) |
| `-instances <i1:i2:...>` | Colon-separated instances to move (mandatory) |
| `-new_hier_name <name>` | Instance name of the new hierarchy (mandatory) |
| `-new_mod_name <name>` | Module name of the new hierarchy |
| `-out <file>` | Output Verilog file (default `output.v`; parent dirs created) |
| `-hier_delim <c>` | One-character delimiter used in generated names (default `_`) |
| `-no_elaborate` | Do not elaborate the top module |
| `-output_dir <dir>` | Where the restructure collateral is written (default `restructured`, created) |
| `-macro_files <f1,f2>` | Comma-separated files whose `` `define `` bodies spell hierarchical paths; re-spelled copies go into the output directory |
| `-eq_metadata <file>` | Where `eq_metadata.json` is written (default `<output_dir>/eq_metadata.json`) |
| `-unroll_generate` | Instances sit inside IF/FOR generate; give mangled names `<GENBLK>_<GENBLK>_<INDEX>_<inst>`; each unrolled copy is connected with the loop index substituted (`in1[i]` becomes `in1[0]`, `in1[1]`, ...) |
| `-spare_ports <n>` | Number of spare ports to add to the new module |
| `-no_optimize_port_count` | Disable port-count optimisation of the new module |
| `-no_optimize_port_count_partial_port_maps` | Disable 2nd-level optimisation for partially connected ports |
| `-no_optimize_port_count_output_multiple_access` | Skip the check that an output also drives other logic in the top |
| `-no_optimize_port_count_common_input_value` | Keep separate inputs even when one wire drives them all |
| `-no_optimize_port_count_tied_ports` | Keep ports that have constant/tied values |
| `-optimize_assignments` | Collapse cascaded assignments (`a=b; b=c;` -> `a=c`) in the new module |
| `-no_pattern_matching` | Disable pattern-based assignment optimisation |
| `-disable_intermediate_cleanup` | Skip intermediate cleanups (more memory, most optimised result) |
| `-disable_dummy_module_print` | Do not print dummy (blackbox) modules. A printed one declares the parameters its instances override, each with the default `0` |
| `-disable_sub_module_print` | Print only the top module into `-out`; the new module goes to `<new module>.v` beside it |
| `-preserve_port_names` / `-preserve_param_names` | Keep the port/parameter names of the moved instance's module |
| `-no_braced_expr` | Drop redundant `()` around binary expressions; the ones operator precedence needs are kept (`(a + 1) * 16`) |
| `-help`, `-h` | Print usage and exit |

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>`,
`-f <filelist>`, `-excludefilelist <file>`, `+incdir+<p1>+<p2>`, `+define+A+B=1`, `-v95`
(no SystemVerilog keywords), `-nowildcard`, `-nokeywords a:b`, `-blackbox` (blackbox
undefined modules), `-declare_wires_for_undefined_obects`, `-dump`, `-restore <units>`,
`-work <lib>`, `-mapfile <ini>`, `-l <log>` / `-la <log>` (log file / append),
`-quiet`, `-nobanner`, `-dbg`, `-suppress <id1:id2>`, `-encryption_key`,
`-encryption_algorithm`, `-private_key_file`, `-public_key_file`.
An unrecognised option is an error (message "Unrecognized option") followed by the usage.

### Inputs / Outputs

- Reads: the Verilog files from `-in` / `-f` and their `` `include`` files.
- Writes: `-out` file (default `output.v` in the current directory); with
  `-disable_sub_module_print` also `<new module name>.v` in the same directory.
- Writes the restructure collateral into `-output_dir` (default `restructured`), every run:
  - `create_hierarchy.<target>.rpt` -- instance paths that changed (RENAMED/REPARENTED/MOVED/ADDED/REMOVED);
  - `create_hierarchy.<target>.signals.rpt` -- nets and ports whose hierarchical name changed (MOVED, MERGED,
    ADDED with CONNECTED_TO for a new port, REMOVED). A net that now lives only inside the new hierarchy is MOVED; a port of the new module is ADDED with the parent net it connects to. Each row is also printed
    (message 7241, suppress with `-suppress`), after a count line (7240);
  - `hierarchy_before.rpt`, `hierarchy_after.rpt` -- the whole instance tree;
  - `restructured_compile.f` -- compiles and elaborates the result: the `-out` file(s), the
    original file of every other module still reachable from the top, and `<module>.kept.v` for a
    module whose original file also held the rewritten top; `+incdir+<output dir>` first when a
    macro file was updated. A module the input never defined (a dummy) is not listed: note 7244;
  - `eq_metadata.json` (or `-eq_metadata <file>`) -- `fecad.eq_metadata/1`: hierarchy before/after
    (flattened instance path -> module), the compile files, `prefix_renames` (instance moves) and
    `renames` (signal moves), for an equivalence check of the result against the input;
  - `<macro file>` and `macro_update.rpt` for each `-macro_files` file -- every dotted path in a
    `` `define `` body re-rooted where its first component is an instance or signal of the top
    (a testbench prefix such as `tb.u_dut.` is kept); a path to something that no longer exists is
    left as it was and listed NEEDS_A_HUMAN (warning 7243). The original is never edited.
- Log: `createhierarchy.log` in the current directory (override with `-l`/`-la` or
  `EDAUTILS_LOG_FILE`). Every console line is also written to the log.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing mandatory options,
  top module not found, parse errors all return 0). 10 = licence checkout failed.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `createhierarchy: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit message number. Usage lines have
  no severity or id.
- The run ends with `createhierarchy: Note: <id>: Found N error(s) and M warning(s) ...`;
  N is the number of Error/Fatal messages. This summary is **not printed with `-nobanner`**.

### Examples

Shipped: `examples/example1/` (`runme.csh`, `runme.bat`, `example1.v`):

```
cd $EDAUTILS_ROOT/examples/example1
createhierarchy -in example1.v -top example1 -out output.v -new_hier_name myNewInstance \
    -instances mid_in_top_inst1 -new_mod_name myNewModule
```

From the regression suite (reference:
`tests.edautilscommandline/tests/createhierarchy/cascaded_1/runme.csh` via `../runme_common.csh`):

```
createhierarchy -in cascaded_1.v -top cascaded_1 -out output.v -new_hier_name myNewInstance \
    -instances u_mid:u_bot2:u_bot1 -new_mod_name myNewModule \
    -optimize_assignments -disable_intermediate_cleanup
```

### Integration notes

- Hierarchical names follow the grouping: in every module of the design, a name through a grouped
  instance (`u_a.q` in the top module, `u_mid.u_a.q` or `top.u_mid.u_a.q` above it, `mid.u_a.q`
  upward) is re-spelled through the new hierarchy (`u_grp.u_a.q`); a module outside `-top` changed
  that way is written into `-out` after the top's modules. A parameter of the top that a moved net's
  range names becomes a parameter of the new module, forwarded `#(.W(W))`; an `integer` / `int` /
  `time` port keeps its type (and its width). Grouping a makestructural glue with its IP, or the glue
  or the IP alone, keeps the design compiling and equivalent; `makestructural -unwrap` undoes the glue
  where it now sits.
- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, default output and the `restructured/` collateral into the current directory:
  give each parallel run its own working directory (or distinct `-out`, `-l` and `-output_dir`).
- Only the last `-in` is read when several are given; pass a multi-file design with `-f`.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` (do not use
  `-nobanner` if you rely on that line) **and** the `-out` file exists.

### See also

removehierarchy, flatteninstances, uniquifyverilog, parseverilog.
