# genwrappervhdl

> Generate VHDL wrapper on top of Verilog module or VHDL entity

- Catalog id: `Genwrappervhdl`; bundle: `genwrappervhdl`; latest version 20261018
- Documentation page: https://edautils.com/RTLUtils.html
- Keywords: VHDL wrapper generator, mixed language wrapper, VHDL on Verilog, entity wrapper
- 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/genwrappervhdl.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Genwrappervhdl (latest file `genwrappervhdl-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/genwrappervhdl/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/genwrappervhdl-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 VHDL design and writes a wrapper entity + architecture around one entity (`-top`).
The wrapper (default name `<top>_wrapper`, always lower-cased) repeats the top's generics and
ports and instantiates the top. Multi-dimensional array ports are flattened by default
(`-no_flatten` keeps them). With `-aroundverilog` the wrapper is meant to sit around a
Verilog module whose entity was produced by `verilog2vhdl -only_entity`; the bundle ships
that `verilog2vhdl` launcher for this purpose. Output is one VHDL file.
Main classes (jar `lib/genwrapper.jar`, which also contains the VHDL and Verilog parsers and
the verilog2vhdl converter):

- `bin/genwrappervhdl`: `com.eu.miscedautils.genwrapper.vhdl.GenWrapperVHDL`
- `bin/verilog2vhdl`: `com.eu.miscedautils.verilog2vhdl.verilog2vhdl`

### Where it ships

Its own bundle, `genwrappervhdl.tar.gz` (flow `genwrappervhdl`; release tree
`release_scripts/genwrappervhdl/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/genwrappervhdl`, `bin/verilog2vhdl` running the shell's jar; this guide as
`tools/genwrappervhdl/AGENTS.md`, examples under `tools/genwrappervhdl/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`.
  On Windows the `.bat` launchers do not set `CLASSPATH`; run `setup_env.bat` first.
- VHDL standard packages: `$EDAUTILS_ROOT/vhdl_pkgs/` (added to the bundle at release build
  time). The tool reads `$EDAUTILS_ROOT/vhdl_pkgs/qtmap.ini` (`qtmap.win.ini` on Windows;
  `qtmap2019.ini` when `EDAUTILS_VHDL_LIBSET=2019`); if it is missing, Error 3643
  "Failed to read VHDL precompiled library map file".
- Licence features: `VHDLWRAPPERGEN` (genwrappervhdl), `VERILOG2VHDL` (verilog2vhdl). 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),
  `EDAUTILS_VHDL_LIBSET` (`2019` selects the IEEE 1076-2019 package set).
- No external tools needed.

### Invocation

#### genwrappervhdl

```
genwrappervhdl -in <file.vhd> | -filelist <list>  -top <entity>  [-out <file>]  [options]
```

| Option | Meaning |
|---|---|
| `-in <file>` | VHDL input file (not together with `-filelist`) |
| `-filelist <list>` | File listing VHDL files; sorted internally before analysis (needs `-top`) |
| `-excludefilelist <list>` | Files to exclude from processing |
| `-top <entity>` | Entity to wrap. Without it the input is only analysed and nothing is written |
| `-out <file>` | Output VHDL file (default `<wrapper name>.vhd`) |
| `-wrapper <name>` | Wrapper entity name (default `<top>_wrapper`; lower-cased) |
| `-aroundverilog` | Build the wrapper as a "VHDL around Verilog module" wrapper |
| `-no_flatten` | Keep multi-dimensional array ports as they are |
| `-nogenericeval` | Do not evaluate generics (keeps port ranges symbolic) |
| `-analyze` | Analyse `-in` only (e.g. a package file before the top entity) |
| `-work <lib>` | Work library name (default `work`) |
| `-mapfile <ini>` | Logical=physical library map (default `qtmap.ini` in the run directory) |
| `-suppress <id1:id2>` | Suppress the colon-separated message numbers |
| `-quiet`, `-nobanner` | No console messages / no banner |
| `-user <email>` | User id for usage registration |
| `-help` | Print usage and exit |

Options other than `-no_flatten`, `-wrapper` and `-user` are matched case-insensitively.
genwrappervhdl does not use the shared Verilog/VHDL option parser. An unknown option prints
the usage and exits 0 **without** any error message. An option given as the last argument
without its value ends in an internal exception message.

#### verilog2vhdl

Same converter, options and behaviour as in the verilog2vhdl bundle (see that bundle's
AGENTS.md): Verilog (`-in`/`-f`) + `-top <module>` in, VHDL (`-out`, default
`output.v2vh.vhd`) out, log `verilog2vhdl.log`. In this bundle it is used with
`-only_entity` to make the entity that `genwrappervhdl -aroundverilog` wraps.

### Inputs / Outputs

- Reads: the VHDL file(s) from `-in` / `-filelist`, the library map (`-mapfile`, default
  `./qtmap.ini`, if present) and `$EDAUTILS_ROOT/vhdl_pkgs/`.
- Writes: the wrapper file (`-out`, default `<top>_wrapper.vhd`, in the current directory),
  the analysed design units under the work library directory (`myEdaUtilsWork/` unless the
  map file maps the work library elsewhere) and the map file (`./qtmap.ini` by default,
  rewritten on every run that finds the top).
- Log: `GenWrapperVHDL.log` (genwrappervhdl) / `verilog2vhdl.log` (verilog2vhdl) in the
  current directory (override with `EDAUTILS_LOG_FILE`; genwrappervhdl has no `-l`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (conflicting options, top
  entity not found, parse errors all return 0). 10 = licence checkout failed.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `GenWrapperVHDL: <Severity>: <id>: <text>` (`verilog2vhdl: ...` for the
  converter), severity one of `Error`, `Fatal Error`, `Warning`, `Note`,
  `Programming Error`; `<id>` is a 5-digit message number. Usage lines have no severity/id.
- Errors from option checks: 4724 (`-analyze` without `-in`), 4725 (`-in` and `-filelist`
  together), 4726 (`-filelist` without `-top`); top missing: Error 859 "Top design unit
  '<top>' is not found in th RTL file ..." (the run then ends without the summary line).
- A run that writes the wrapper ends with `GenWrapperVHDL: Note: <id>: Found N error(s) and
  M warning(s) ...`; genwrappervhdl prints it **even with `-nobanner`**. An analyse-only
  run (no `-top`) ends without it.

### Examples

Shipped (`runme.csh` only, no `.bat`):

```
cd $EDAUTILS_ROOT/examples/vhdlaroundvhdl/record_type
genwrappervhdl -top record_type -in record_type.vhd -out record_type_wrapper.vhd

cd $EDAUTILS_ROOT/examples/vhdlaroundverilog/simple_test      # has qtmap.ini: work=myvhdlwork
verilog2vhdl -only_entity -top simple_test -in simple_test.v -out simple_test_e.vhd
genwrappervhdl -top simple_test -in simple_test_e.vhd -out simple_test_wrapper.vhd \
    -no_flatten -aroundverilog
```

Also `examples/vhdlaroundvhdl/simple_array_2d_2/` (ships a pre-analysed `myvhdlwork/`).

From the regression suite (reference:
`tests.edautilscommandline/tests/genwrapper/vhdlinvhdl/record_type/runme.csh` and
`tests.edautilscommandline/tests/genwrapper/veriloginvhdl/simple_test/runme.csh`, each via
`../runme_common.csh`):

```
genwrappervhdl -top record_type -in record_type.vhd -out record_type_wrapper.vhd
verilog2vhdl -only_entity -nowildcard -top simple_test -in simple_test.v -out simple_test.vhd
genwrappervhdl -top simple_test -in simple_test.vhd -out simple_test_wrapper.vhd -aroundverilog
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `qtmap.ini`, the work library directory and the default output into the
  current directory: give each parallel run its own working directory.
- 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
  output file exists.
- The usage text calls the list switch "-fileist" in one line; the accepted switch is
  `-filelist`.
- (2026-10-03) The wrapper no longer writes `use work.<entity>.all;` (an entity is not a package);
  with `-aroundverilog` it now prints the component declaration of the wrapped module.

### See also

genwrapperverilog, verilog2vhdl, vhdl2verilog, parsevhdl.
