# vhdl2systemc

> Convert VHDL RTL to SystemC keeping the original structure and signal names for correlation and co-simulation.

- Catalog id: `Vhdl2systemc`; bundle: `vhdl2systemc`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: VHDL to SystemC, RTL to SystemC, SystemC generator, HDL conversion
- 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/vhdl2systemc.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Vhdl2systemc (latest file `vhdl2systemc-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/vhdl2systemc/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/vhdl2systemc-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.

Translates a VHDL design, starting at one entity (`-top`), into SystemC C++. The entity is
first converted to intermediate Verilog (`<outdir>/verilog/<top>.v`); with `-gentb` a
Verilog testbench (`<outdir>/verilog/tb.v`, module `testbench`) is generated and becomes the
SystemC top. The Verilog is re-parsed, elaborated (unless `-noelab`) and written as
`<module>.hxx` / `<module>.cxx` files plus `main_sc.cxx` under `-outdir`, and a `Makefile`
in the current directory builds `bin/test.exe` against a SystemC installation.
Main class: `com.eu.miscedautils.vhdl2systemc.vhdl2systemc` (jar `lib/vhdl2systemc.jar`).

### Where it ships

Its own bundle, `vhdl2systemc.tar.gz` (flow `vhdl2systemc`; release tree
`release_scripts/vhdl2systemc/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/vhdl2systemc` running the shell's jar; this guide as `tools/vhdl2systemc/AGENTS.md`,
examples under `tools/vhdl2systemc/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 `bin/vhdl2systemc.bat` does 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`).
- Licence feature `VHDL2SYSTEMC` (the SystemC writer also checks `VERILOG2SYSTEMC`; if that
  one is missing the failure message is printed and no module files are written, exit 0).
  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
  `VHDL2SYSTEMC`: 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`.
- To build/run the generated code (not needed for translation): g++, GNU make and a SystemC
  installation. The generated `Makefile` uses `SYSTEMC_ROOT ?= /software/systemc` and
  `SYSTEMC_HOME ?= $(SYSTEMC_ROOT)`; set `SYSTEMC_ROOT` in the environment.

### Invocation

```
vhdl2systemc -in <file.vhd> | -filelist <list>  -top <entity>  [-outdir <dir>]  [options]
```

| Option | Meaning |
|---|---|
| `-in <file>` | VHDL input file (not together with `-filelist`); extra bare file names after it are accepted |
| `-filelist <list>` | File listing VHDL files; sorted internally before analysis |
| `-excludefilelist <list>` | Files to exclude from processing |
| `-top <entity>` | Top entity (mandatory; missing -> usage printed, nothing written) |
| `-outdir <dir>` | Output directory for the C++ files (default `outdir`) |
| `-gentb` | Generate a Verilog testbench and make it the SystemC top |
| `-generic NAME=VALUE` | Integer value for a top generic that has no default (repeatable) |
| `-nogenericeval` | Do not evaluate generics |
| `-nouniquify` | Do not uniquify entities/modules by parameter values |
| `-noelab` | Do not elaborate the design |
| `-two_value_logic` | Use two-value logic types (faster simulation) |
| `-write_driver_monitor` | Also write `driver_<top>` / `monitor_<top>` `.hxx`/`.cxx` |
| `-analyze` | Analyse `-in` only |
| `-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 |

vhdl2systemc has its own option parser (not the shared Verilog/VHDL one; no `-l`). An
unknown option before `-in` is Error 7050 "Unrecognized option" followed by the usage; a
malformed `-generic` is Error 7051. An option given last without its value ends in an
internal exception message.

### Inputs / Outputs

- Reads: the VHDL file(s), `./qtmap.ini` (or `-mapfile`) if present,
  `$EDAUTILS_ROOT/vhdl_pkgs/`.
- Writes: `<outdir>/verilog/<top>.v` (intermediate Verilog) and, with `-gentb`,
  `<outdir>/verilog/tb.v`; `<outdir>/<module>.hxx|.cxx`, `<outdir>/main_sc.cxx`; `Makefile`
  in the **current directory** (overwritten); the map file `./qtmap.ini` (rewritten); the
  work library directory (`myEdaUtilsWork/` unless mapped elsewhere).
- Log: `vhdl2systemc.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (conflicting options, top
  not found, parse errors all return 0). 10 = licence checkout failed.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `vhdl2systemc: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`, `Programming Error`; `<id>` is a 5-digit message number.
  Usage lines have no severity or id. Top entity missing: Error 863 "Top design unit '<top>'
  is not found in th RTL file ...". Message 51818 is always suppressed.
- The run ends with `vhdl2systemc: Note: <id>: Found N error(s) and M warning(s) ...`.
  On a normal finish this summary is **not printed with `-nobanner`**; the early-exit
  error paths (top not found, parse failure) print it regardless.

### Examples

Shipped: `examples/simple_and/` (`runme.csh`, `runme.bat`, `simple_and.vhd`,
`infile.list`):

```
cd $EDAUTILS_ROOT/examples/simple_and
vhdl2systemc -filelist infile.list -top simple_and -outdir tmpdir -gentb
```

From the regression suite (reference: `tests.edautilscommandline/tests/vhdl2systemc/lsq/runme.csh`
via `../runme_common.csh`, which needs SystemC -- the case is skipped when it is missing):

```
vhdl2systemc -filelist infile.list -top lsq -outdir tmpdir -gentb \
    -generic FIFO_DEPTH=4 -generic DATA_SIZE=32 -generic ADDRESS_SIZE=32 -generic TAIL_SIZE=2 \
    -generic PORT_COUNT=1 -generic STORE_MAX=4 -generic LOAD_MAX=4
make
./bin/test.exe > sim.out
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `Makefile`, `qtmap.ini`, the work directory and the default `outdir/` 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)` (do not use
  `-nobanner` if you rely on that line) **and** `<outdir>/main_sc.cxx` exists. Proving the
  output compiles needs `make` with a SystemC installation.
- A package used by the design must be analysed first: list its file before the design
  file in `-filelist`.

### See also

verilog2systemc, vhdl2verilog, vlogtbgen (gentbvlog), parsevhdl.
