# flatteninstances

> Flatten selective hierarchies in SoC keeping RTL intent intact

- Catalog id: `Flatteninstances`; bundle: `flatteninstances`; latest version 20261018
- Documentation page: https://edautils.com/Flattener.html
- Keywords: flatten instances, selective flatten, Verilog hierarchy, RTL flattening
- 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/flatteninstances.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Flatteninstances (latest file `flatteninstances-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/flatteninstances/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/flatteninstances-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 (flattens) selected hierarchical instances
into their parent module, keeping the design function. Instances are given as hierarchical
paths from `-top` (`top/u_mid1:top/u_mid1/u_bot2`). When an instance's parent is not `-top`,
the parent module is copied as `<parent>_<path>_flattened` and re-linked, so other instances
of the original module stay untouched. Output is one Verilog file (default
`output.flatten.v`) holding the modified top module and its sub-modules. Main class:
`com.eu.miscedautils.verilogparser.FlattenInstances` (jar `lib/verilogparser.jar`).

### Where it ships

Its own bundle, `flatteninstances.tar.gz` (flow `flatteninstances`; release tree
`release_scripts/flatteninstances/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/flatteninstances` running the shell's jar; this guide as `tools/flatteninstances/AGENTS.md`,
examples under `tools/flatteninstances/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: a valid licence file is required at start-up (else exit status 10, no message).
  The licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic`
  (run directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. The work itself
  checks features `REMOVEHIERARCHY` and `FINDDESIGNOBJECTS` (and `REMOVEASSIGNMENTS` with
  `-enable_assignment_merge`/`-remove_unused_nets`): a missing feature is error 6404
  `Failed to checkout LICENSE for the feature : <F>` and the run continues with exit 0.
  (The shipped `README.txt` mentions `EDAUTILS_LICENSE_KEY`; the code does not read it.)
- 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

```
flatteninstances -in <file.v> | -f <filelist>  -top <module>
                 -instances <top/i1:top/i2/i3>  [-out <file>]  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Top module (mandatory, error 1297 if missing) |
| `-instances <p1:p2>` / `-instance` | Colon-separated hierarchical instance paths from `-top` (mandatory, error 1298). Each path must match the whole hierarchical name (Java regex); several matches give warning 1200 |
| `-out <file>` | Output Verilog file (default `output.flatten.v`; parent dirs created) |
| `-hier_delim <c>` | Delimiter used in generated names; first character used (default `_`) |
| `-preserve_nets <n1:n2>` | Nets/pins not to be prefixed with the instance name |
| `-preserve_inst_names` | Keep sub-hierarchy instance names unchanged |
| `-enable_assignment_merge` | Merge the assignments created by flattening |
| `-no_pattern_matching` | Disable pattern-based merging (with `-enable_assignment_merge`) |
| `-remove_unused_nets` | Remove intermediate/unused nets |
| `-rename_nets` / `-print_rename_info` | Shorten net names / print the renames; the top module's ports keep their names |
| `-uniquify_nets` | Uniquify nets to avoid clashes with existing identifiers (not the top module's ports) |
| `-elaborate` | Elaborate the top module before flattening |
| `-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]`, ...) |
| `-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 |
| `-no_braced_expr` | Drop redundant `()` around binary expressions; the ones operator precedence needs are kept (`(a + 1) * 16`) |
| `-help`, `-h` | Print usage and return |

An option that needs a value but has none is error 20108 followed by the usage. Missing
`-in`/`-f` is error 1299.

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 7038 "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.flatten.v` in the current directory).
- An instance of an undefined module (a blackbox) is never flattened: it stays an instance, its
  connections rewritten to the flattened nets.
- Log: `flatteninstances.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** (missing mandatory options,
  top module not found = error 1583, instance not found = warning 3490, parse errors).
  10 = no valid licence file. 1 = `EDAUTILS_ROOT` missing/invalid, or out of memory
  (Fatal Error 3092, JVM halted).
- Message format: `flatteninstances: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; usage lines have no severity or id.
- The run ends with `flatteninstances: Note: <id>: Found N error(s) and M warning(s) ...`.
  This tool prints the summary even with `-nobanner`; it is skipped when usage is printed.

### Examples

Shipped: `examples/middle_instances/` and `examples/simple_and_4/` (`runme.csh` only, no `.bat`):

```
cd $EDAUTILS_ROOT/examples/middle_instances
flatteninstances -in middle_instances.v -top middle_instances -out output.v \
    -instances middle_instances/u_mid1:middle_instances/u_mid2:middle_instances/u_mid3
```

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

```
flatteninstances -in generate_stmt_1.v -top generate_stmt_1 -out output.v \
    -instances generate_stmt_1/IFGEN_FORGEN_1_u_mid -unroll_generate
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, default output and `myEdaUtilsWork/` into the current directory: give each
  parallel run its own working directory (or distinct `-out` and `-l`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` **and** no
  `Could not find instance` warning **and** the `-out` file exists.

### See also

flattenverilog (whole design), removehierarchy, createhierarchy, findinstsornets.
