# flattenverilog

> Flatten all RTL hierarchies in a module

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

## Downloads

- EDAUtils download site: https://edautils.ai/download/Flattenverilog (latest file `flattenverilog-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/flattenverilog/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/flattenverilog-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 flattens the module given with `-top`: every
sub-module instance is ungrouped into the top (all levels by default), with generated names
joined by the hierarchy delimiter. Optionally merges the assignments created by flattening and
removes unused nets. Output is a single Verilog file (default `output.flatten.v`) holding only
the flattened top module. Main class: `com.eu.miscedautils.verilogparser.FlattenVerilog`
(jar `lib/verilogparser.jar`).

### Where it ships

Its own bundle, `flattenverilog.tar.gz` (flow `flattenverilog`; release tree
`release_scripts/flattenverilog/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/flattenverilog` running the shell's jar; this guide as `tools/flattenverilog/AGENTS.md`,
examples under `tools/flattenverilog/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 flattening
  checks feature `REMOVEHIERARCHY` (and `REMOVEASSIGNMENTS` with `-enable_assignment_merge`
  or `-remove_unused_nets`); a missing feature is error 6404
  `Failed to checkout LICENSE for the feature : <F>` and the run continues with exit 0.
  Feature `FLATTENVERILOG` exists in the licence but is not checked by this class.
- 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

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

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Module to flatten (mandatory, error 1300 if missing) |
| `-out <file>` | Output Verilog file (default `output.flatten.v`; parent dirs created) |
| `-hier_delim <c>` | Delimiter for generated names; first character used (default `_`) |
| `-no_hier` | Ungroup only the first level of instances instead of all levels |
| `-stop_at_leaf` | Do not flatten leaf modules (modules without instances) |
| `-exclude_modules <m1:m2>` | Instances of these modules are not flattened |
| `-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 intermediate assignments created by flattening |
| `-no_pattern_matching_in_assignment_merge` | Disable pattern-based merging |
| `-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 |
| `-no_braced_expr` | Drop redundant `()` around binary expressions; the ones operator precedence needs are kept (`(a + 1) * 16`) |
| `-help`, `-h` | Print usage and return |

A value option without a value is error 20204 followed by the usage. Missing `-in`/`-f` is
error 1303. The usage text describes `-enable_assignment_merge` as "disables merging"; the
code enables merging.

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 7039 "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) containing
  only the flattened top module.
- An instance of an undefined module (a blackbox) is never flattened: it stays an instance, its
  connections rewritten to the flattened nets.
- Log: `flattenverilog.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 1598, parse errors). 10 = no valid licence file.
  1 = `EDAUTILS_ROOT` missing/invalid, or out of memory (Fatal Error 3092, JVM halted).
- Message format: `flattenverilog: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; usage lines have no severity or id.
- The run ends with `flattenverilog: 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/simple_and_3/`, `examples/delimeter_dot/` (both with `runme.csh`/`.bat`)
and `examples/i2c_rtl/` (`runme.csh`, `files.txt`, `rtl/`). `delimeter_dot/` and `i2c_rtl/`
also ship a previous `flattened.v` and `flattenverilog.log`, and `delimeter_dot/runme.sh`
calls a hard-coded Windows path; use `runme.csh`.

```
cd $EDAUTILS_ROOT/examples/i2c_rtl
flattenverilog -f files.txt -top i2c -no_braced_expr -out flattened.v \
    -no_pattern_matching_in_assignment_merge -v95
```

From the regression suite (reference:
`tests.edautilscommandline/tests/flattenverilog/exclude_module/runme.csh` via
`../runme_common.csh`, which appends `-out flattened.v -no_pattern_matching_in_assignment_merge`):

```
flattenverilog -in exclude_module.v -top exclude_module -out flattened.v \
    -exclude_modules bottom1 -no_pattern_matching_in_assignment_merge
```

### 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`).
- Large designs: raise the heap with `JAVA_FLAGS=-Xmx<n>g`.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` **and** the `-out`
  file exists.

### See also

flatteninstances (selected instances), removehierarchy, removeassignments, createhierarchy.
