# vlogtbgen

> Verilog testbench generator with random test vectors

- Catalog id: `Vlogtbgen`; bundle: `vlogtbgen`; latest version 20261018
- Documentation page: https://edautils.com/VlogTBGen.html
- Keywords: Verilog testbench generator, random test vectors, testbench skeleton, SystemVerilog testbench
- 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/vlogtbgen.md

## Downloads

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

Run: `gentbvlog -help`

## How an agent runs it

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

Reads a Verilog/SystemVerilog design and writes a self-running testbench for the module given
with `-top`: a `module testbench` that declares a `bench_<port>` reg/wire per DUT port,
instantiates the DUT, toggles the clocks given with `-clk`, drives the resets given with
`-rst`, drives every other input from a `$random` register, `$monitor`s the inputs and stops
with `$finish`. Output is a single Verilog file (default `tb.v`). The command is `gentbvlog`;
the bundle is named `vlogtbgen`. Main class: `com.eu.miscedautils.gentbvlog.GenTBVlog`
(jar `lib/testbenchgenerators.jar`).

### Where it ships

Its own bundle, `vlogtbgen.tar.gz` (flow `vlogtbgen`; release tree
`release_scripts/vlogtbgen/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/gentbvlog` running the shell's jar; this guide as `tools/vlogtbgen/AGENTS.md`, examples
under `tools/vlogtbgen/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 `VERILOGTESTBENCH`, 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 : VERILOGTESTBENCH`, 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),
  `EDAUTILS_LIBRARY_MAP_FILE` (default for `-mapfile`, used with `-dump`/`-restore`).
- No external tools needed to generate; a Verilog simulator is needed to run the testbench.

### Invocation

```
gentbvlog -in <file.v> | -f <filelist>  -top <module>  [-out <file>]
          [-clk "<name>[@<half period>[{<port>:<port>}]]" ...]  [-rst "<name>[{<v>@<delay>:...}]" ...]
          [-max_sim_time <n> | -max_sim_cycles <clk>@<n>]  [-flatten_ports]  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | DUT module (mandatory; missing -> usage only, no error, exit 0) |
| `-out <file>` | Testbench file (default `tb.v`) |
| `-clk "<name>@<n>{p1:p2}"` | Clock (repeatable). `bench_<name>` starts at 0 and toggles every `<n>` time units, so `<n>` is the **half** period (default 5). A non-integer `<n>` is error 56214 and 10 is used. The `{p1:p2}` port list is parsed but, from source, does not change the output |
| `-rst "<name>{v@d:v@d}"` | Reset (repeatable). Each `v@d` becomes `#d bench_<name> = 1'bv;` in one `initial` block, so delays are relative to the previous step. Without a waveform: `#10 bench_<name> = 1'b0;` |
| `-max_sim_time <n>` | `initial #<n> $finish;` |
| `-max_sim_cycles <clk>@<n>` | `$finish` after `<n>` x the `-clk` number of `<clk>`, i.e. `<n>` half periods. If `<clk>` is not a `-clk` and no `-max_sim_time` is given, no `$finish` is written at all |
| `-flatten_ports` | Needed when the top has multi-dimensional ports: a `<top>_wrapper` with flattened ports is built and the testbench targets it |
| `-help`, `-h` | Print usage and return |

With neither `-max_sim_time` nor `-max_sim_cycles` the testbench finishes at `#500`; with both,
two `$finish` blocks are written and the earlier wins. An unknown option is error 57029
"Unrecognized option" followed by the usage, exit 0. The `README.txt` calls the `-clk` number
the period; the code and the usage text treat it as the half period.

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>`.

### Inputs / Outputs

- Reads: the Verilog files from `-in` / `-f` and their `` `include`` files. The DUT must have
  at least one input port (else error 53151 "No input port found in the specified top module").
- Writes: the `-out` file only: a header, the design's `` `timescale`` if it has one, and
  `module testbench`. Whether the `-flatten_ports` wrapper module itself is written anywhere is
  not confirmed from source.
- Log: `GenTBVerilog.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 not found = error 53202,
  parse errors, unrecognised option). 10 = licence checkout failed. 1 = `EDAUTILS_ROOT`
  missing, or out of memory (Fatal Error 53092, JVM halted).
- Message format: `GenTBVerilog: <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 `GenTBVerilog: Note: 53250: Found N error(s) and M warning(s) ...`. This
  summary is **not printed with `-nobanner`**, nor after an early return (usage, top not found).

### Examples

Shipped: `examples/multiple_clk_rst/` (`runme.csh`, `runme.bat`, `reset_waveforms.v`) and
`examples/test_with_param/` (`runme.csh`, `runme.bat`, `test_with_param.v`):

```
cd $EDAUTILS_ROOT/examples/multiple_clk_rst
gentbvlog -in reset_waveforms.v -top reset_waveforms -out tb.v \
    -clk "clk1@8{in1:in2}" -clk clk2 -rst rst1 -rst "rst2{1@5:0@50:1@150}"
cd $EDAUTILS_ROOT/examples/test_with_param
gentbvlog -in test_with_param.v -top test_with_param -out tb.v
```

The bundle self-test (`vlogtbgen_example`) runs both with `</dev/null` and requires
`Found 0 error(s)` in each `GenTBVerilog.log`.

From the regression suite (reference: `tests.edautilscommandline/tests/vlogtbgen/simtime_cycles`
and `include_header`):

```
gentbvlog -in simtime_cycles.v -top simtime_cycles -out tb.v -clk "clk1@8{in1:in2}" -clk clk2 \
    -rst rst1 -rst rst2 -max_sim_cycles clk1@40 -max_sim_time 700
gentbvlog -in include_header.v +incdir+include1+include2 -top include_header -out tb.v
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Quote `-clk`/`-rst` values: `{`, `}` and `@` must reach the tool unexpanded.
- Writes the log, `tb.v` 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)` (do not use
  `-nobanner` if you rely on that line) **and** the `-out` file exists.

### See also

vhdltbgen (the VHDL counterpart), genwrapperverilog (the `-flatten_ports` wrapper), parseverilog.
