# removehierarchy

> Remove Verilog RTL hierarchies as specified while maintaining design intent

- Catalog id: `Removehierarchy`; bundle: `removehierarchy`; latest version 20261018
- Documentation page: https://edautils.com/RemoveHierarchy.html
- Keywords: remove hierarchy, ungroup instances, Verilog flatten, RTL restructuring
- 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/removehierarchy.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Removehierarchy (latest file `removehierarchy-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/removehierarchy/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/removehierarchy-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 and ungroups the instances of the module given with
`-top`: by default only the instances placed directly in the top are dissolved (one level),
with `-all` every level is. Generated names are joined with the hierarchy delimiter. Output
is a single Verilog file (default `output.v`) holding the resulting top module. Main class:
`com.eu.miscedautils.verilogparser.RemoveHierarchy` (jar `lib/verilogparser.jar`).

### Where it ships

Its own bundle, `removehierarchy.tar.gz` (flow `removehierarchy`; release tree
`release_scripts/removehierarchy/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/removehierarchy` running the shell's jar; this guide as `tools/removehierarchy/AGENTS.md`,
examples under `tools/removehierarchy/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`, `CLASSPATH` and prepends `bin/` to `PATH`.
- Licence feature `REMOVEHIERARCHY`. 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 **with no
  message** (the check runs before anything is printed).
- 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),
  `EDAUTILS_LIBRARY_MAP_FILE` (default for `-mapfile`, used with `-dump`/`-restore`).
- No external tools needed.

### Invocation

```
removehierarchy -in <file.v> | -f <filelist>  -top <module>  [-out <file>]  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Module whose hierarchy is removed (mandatory; missing -> usage only, no error message) |
| `-out <file>` | Output Verilog file (default `output.v`; parent dirs created) |
| `-all` | Remove every level of hierarchy, not just the first |
| `-stop_at_leaf` | Leave leaf modules (modules without instances) as instances |
| `-preserve_instance_names` | Try to keep the instance names intact |
| `-hier_delim <c>` | One-character delimiter for generated names (default `_`); longer value = error 776 and usage |
| `-no_braced_expr` | Drop redundant `()` around binary expressions; the ones operator precedence needs are kept (`(a + 1) * 16`) |
| `-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`) |
| `-help`, `-h` | Print usage and return |

`-hier_delim` given as the last argument with no value raises an internal exception (reported
in the log, exit 0). The code does not check that `-in` or `-f` was given.

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>` (wildcards
expanded unless `-nowildcard`), `-f <filelist>` (repeatable; one file per line, `#`/`// `
comments, `+incdir+`/`+define+` and option lines allowed, `$VAR` resolved),
`-excludefilelist <file>`, `+incdir+<p1>+<p2>`, `+define+A+B=1`, `-v95`, `-nowildcard`,
`-nokeywords a:b`, `-blackbox`, `-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>`, `-user <email>`,
`-encryption_key`, `-encryption_algorithm`, `-private_key_file`, `-public_key_file`.
An unrecognised option is error 7046 "Unrecognized option : <opt>" followed by the usage.

### Inputs / Outputs

- Reads: the Verilog files from `-in` / `-f` and their `` `include`` files.
- Writes: the `-out` file (default `output.v` in the current directory), created only when
  the top module is found.
- Writes the restructure collateral into `-output_dir` (default `restructured`), every run:
  - `remove_hierarchy.<target>.rpt` -- instance paths that changed (RENAMED/REPARENTED/MOVED/ADDED/REMOVED);
  - `remove_hierarchy.<target>.signals.rpt` -- nets and ports whose hierarchical name changed (MOVED, MERGED,
    ADDED with CONNECTED_TO for a new port, REMOVED). A lifted signal is named `<inst><hier_delim><name>` (recursively under `-all`), and the row names where it was (`/u_m0/u_l0/a -> /u_m0_u_l0_a`). 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.
- An instance of an undefined module (a blackbox) is never flattened: it stays an instance, its
  connections rewritten to the flattened nets.
- Log: `removehierarchy.log` in the current directory (override with `-l`/`-la` or
  `EDAUTILS_LOG_FILE`). `myEdaUtilsWork/` is created in the current directory.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (top module not found =
  error 2572, parse errors). 10 = licence feature missing. 1 = `EDAUTILS_ROOT`
  missing/invalid, or out of memory (Fatal Error 3092, JVM halted).
- Message format: `removehierarchy: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; usage lines have no severity or id.
- The run ends with `removehierarchy: 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`, `simple_and_1.v`):

```
cd $EDAUTILS_ROOT/examples/example1
removehierarchy -in simple_and_1.v -top simple_and_1 -out output.v
```

From the regression suite
(`tests.edautilscommandline/tests/removehierarchy/simple_and_2/runme.csh`):

```
removehierarchy -all -in simple_and_2.v -top simple_and_2 -out output.v
```

### Integration notes

- Hierarchical names follow the flattening: a name through a dissolved instance (`u_a.st` in the
  top module, a name inside the dissolved module that starts at its own instances, `top.u_mid.u_s.z`
  anywhere, `mid.u_a.q` upward) is re-spelled to the flattened net or instance (`u_a_st`,
  `u_s_u_deep.cnt`); a module outside `-top` changed that way is written into `-out` after the
  flattened module.
- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, default output, `myEdaUtilsWork/` and the `restructured/` collateral into the current directory: give each
  parallel run its own working directory (or distinct `-out` and `-l`).
- A silent exit 10 means the licence lacks `REMOVEHIERARCHY` (or no licence was found).
- 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

flattenverilog (all levels, more options), flatteninstances, createhierarchy, removeassignments.
