# vhdltbgen

> VHDL testbench generator with random test vectors

- Catalog id: `Vhdltbgen`; bundle: `vhdltbgen`; latest version 20261018
- Documentation page: https://edautils.com/VHDLTBGen.html
- Keywords: VHDL testbench generator, random test vectors, testbench skeleton
- 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/vhdltbgen.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Vhdltbgen (latest file `vhdltbgen-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/vhdltbgen/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/vhdltbgen-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

Run: `gentbvhdl -help`

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

Reads VHDL, finds the entity given with `-top`, and writes a self-running testbench for it:
an entity `tb_<top>` with architecture `arch` that declares a signal per port, instantiates the
DUT as `entity work.<top>`, toggles the clocks given with `-clk`, drives the resets given with
`-rst`, drives every other input from a random vector, and ends the simulation with
`assert FALSE report "End of simulation" severity FAILURE`. Alongside the testbench (default
`tb.vhd`) it writes ModelSim and NCSim compile scripts. The command is `gentbvhdl`; the bundle is
named `vhdltbgen`. Main class: `com.eu.miscedautils.gentbvhdl.GenerateVHDLTestBench`
(jar `lib/testbenchgenerators.jar`).

### Where it ships

Its own bundle, `vhdltbgen.tar.gz` (flow `vhdltbgen`; release tree
`release_scripts/vhdltbgen/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/gentbvhdl` running the shell's jar; this guide as `tools/vhdltbgen/AGENTS.md`, examples
under `tools/vhdltbgen/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/`, `lib/` and
  `vhdl_pkgs/`, the precompiled STD/IEEE libraries read through `vhdl_pkgs/qtmap.ini`,
  `qtmap.win.ini` on Windows). 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 `VHDLTESTBENCH`, checked first. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. No valid licence or no feature: error 56404
  `Failed to checkout LICENSE for the feature : VHDLTESTBENCH`, the summary line, then exit
  status 10. (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).
- No external tools needed to generate; ModelSim or NCSim is needed to run the scripts it writes.

### Invocation

```
gentbvhdl -in <file.vhd> | -filelist <list>  -top <entity>  [-out <file>]
          [-clk "<name>[@<half period>[{<port>:<port>}]]" ...]  [-rst "<name>[{<v>@<delay>:...}]" ...]
          [-max_sim_time <ns> | -max_sim_cycles <clk>@<n>]  [-flatten_ports]  [options]
```

This tool has its own option parser; the shared Verilog-reader options (`-f`, `+incdir+`,
`-l`, `-v95`, `-dbg` ...) are **not** accepted. Options:

| Option | Meaning |
|---|---|
| `-in <file>` | VHDL input (wildcards expanded unless `-nowildcard`) |
| `-filelist <file>` | File listing VHDL files, one per line, any order; requires `-top`; not together with `-in` |
| `-top <entity>` | Entity to test (case-insensitive). Without it the input is only compiled and no testbench is written |
| `-out <file>` | Testbench file (default `tb.vhd`) |
| `-clk "<name>@<n>{p1:p2}"` | Clock (repeatable). Toggles every `<n>` ns, so `<n>` is the **half** period (default 5). A non-integer `<n>` is error 56213 and 10 is used. The `{p1:p2}` list is parsed but, from source, does not change the output |
| `-rst "<name>{v@d:v@d}"` | Reset (repeatable). Each `v@d` sets value `v` after a further `d` ns |
| `-max_sim_time <ns>` | End the simulation at `<ns>` |
| `-max_sim_cycles <clk>@<n>` | End after `<n>` x the `-clk` number of `<clk>` ns, i.e. `<n>` half periods |
| `-flatten_ports` | Needed when the entity has ports of user-defined types (multi-dimensional arrays, records): a `<top>_wrapper` entity with flattened ports is built and the testbench targets it |
| `-work <lib>` | Logical work library (default `work`) |
| `-mapfile <file>` | Library map, lines `logical=physical` (default `qtmap.ini`; read if present, always rewritten) |
| `-compile` | Requires `-in` (else error 54730); otherwise no effect in the current code |
| `-excludefilelist <file>` | Accepted; its effect is not confirmed from source |
| `-nowildcard`, `-quiet`, `-nobanner`, `-suppress <id1:id2>`, `-user <email>` | As in the other tools |
| `-help` | Print usage and return (`-h` is not accepted) |

With neither end option the simulation ends at 500 ns. `-in` with `-filelist` is error 54732;
`-filelist` without `-top` is error 54733; no `-in`/`-filelist` prints the usage only. The usage
says `-top` may name an already compiled entity, but from source every run needs `-in` or
`-filelist`. An unknown option is error 57028 "Unrecognized option" followed by the usage, exit 0.

### Inputs / Outputs

- Reads: the VHDL from `-in` / `-filelist`, the `-mapfile` if it exists, and
  `$EDAUTILS_ROOT/vhdl_pkgs/`. The README strongly recommends an input holding only the entity:
  architectures and packages that do not analyse cleanly produce errors.
- Writes, all in the current directory except the testbench: the `-out` file;
  `modelsim_compile.csh` / `.bat` (`vcom -work work -93 ...`, `vsim -c -lib work tb_<top>`);
  `ncsim_compile.csh` / `.bat`, `cds.lib`, `hdl.var`; the `-mapfile` (`qtmap.ini`, e.g.
  `work=myEdaUtilsWork`); the work library directory (`myEdaUtilsWork/` by default); and
  `edautils.file.list` (the `-in` files, removed on exit).
- Log: `GenTBVHDL.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (top not found = error 50861,
  top is not an entity = 50875, parse errors, unrecognised option). 10 = licence checkout
  failed. 1 = `EDAUTILS_ROOT` missing, or out of memory (Fatal Error 53092, JVM halted).
- Message format: `GenTBVHDL: <Severity>: <id>: <text>`; the printed id is 50000 + the source
  number, and `-suppress` takes the printed id. Usage lines have no severity or id.
- The run ends with `GenTBVHDL: Note: 53250: Found N error(s) and M warning(s) ...`, printed even
  with `-nobanner`, but not after an early return (usage, option conflicts, top not found).

### Examples

Shipped: `examples/design/` (`runme.csh`, `runme.bat`, `design.vhd`; possibly a `qtmap.ini`,
which the tool rewrites anyway):

```
cd $EDAUTILS_ROOT/examples/design
gentbvhdl -in design.vhd -top design -clk "clk1@8{in1:in2}" -clk CLK2 -rst rst1 \
    -rst "rst2{1@5:0@50:1@200}" -out tb.vhd
```

The bundle self-test (`vhdltbgen_example`) runs that `runme.csh` with `</dev/null` and requires
`Found 0 error(s)` in `GenTBVHDL.log`.

From the regression suite (reference: `tests.edautilscommandline/tests/vhdltbgen/multiplefiles`
and `simtime_cycles`), which also compares the ModelSim/NCSim scripts, `cds.lib` and `hdl.var`:

```
gentbvhdl -filelist infile.list -top top -out tb.vhd
gentbvhdl -in clock_and_reset.vhd -top clock_and_reset -clk "clk1@8{in1:in2}" -clk CLK2 \
    -rst rst1 -out tb.vhd -max_sim_time 400 -max_sim_cycles clk1@40
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Quote `-clk`/`-rst` values: `{`, `}` and `@` must reach the tool unexpanded.
- The compile scripts, `cds.lib`, `hdl.var`, `qtmap.ini` and the work library always go to the
  current directory, whatever `-out` says: 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 `-out`
  file exists.

### See also

vlogtbgen (the Verilog counterpart), genwrappervhdl (the `-flatten_ports` wrapper), parsevhdl.
