# vhdl2ipxact

> Generate IP-XACT component from VHDL entity

- Catalog id: `Vhdl2Ipxact`; bundle: `vhdl2ipxact`; latest version 20261018
- Documentation page: https://edautils.com/vhdl2ipxact.html
- Keywords: VHDL to IP-XACT, IP-XACT component generator, IEEE 1685, IP packaging
- 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/vhdl2ipxact.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Vhdl2Ipxact (latest file `vhdl2ipxact-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/vhdl2ipxact/
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/vhdl2ipxact/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/vhdl2ipxact-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 an IP-XACT `component` description of one entity (`-top`):
its generics become parameters/model parameters and its ports become model ports. The
schema is IEEE 1685-2009 by default, 2014 with `-v2014`, 2022 with `-v2022`. Output is one
XML file (default `component.xml`). Main class:
`com.eu.miscedautils.vhdl2ipxact.Entity2IPXACTComponent` (jar `lib/vhdl2ipxact.jar`).

### Where it ships

Its own bundle, `vhdl2ipxact.tar.gz` (flow `vhdl2ipxact`; release tree
`release_scripts/vhdl2ipxact/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell**
and **designplayer-shell** bundles (`bin/vhdl2ipxact` running the shell's jar; this guide as
`tools/vhdl2ipxact/AGENTS.md`, examples under `tools/vhdl2ipxact/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/vhdl2ipxact.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 `VHDL2IPXACT`. 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`. The `EDAUTILS_IPXACT_SEARCH_PATH*` variables are not read by this
  tool's code path.
- No external tools needed.

### Invocation

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

| Option | Meaning |
|---|---|
| `-in <file>` | VHDL input file (not together with `-filelist`) |
| `-filelist <list>` | File listing VHDL files, one per line, optionally `library=file` (a line without a library goes to `work`, whatever `-work` says); needs `-top`. Despite the log's "sorted order", a package listed after a unit that uses it fails on a clean work library (e.g. Error 54700 undefined symbol) -- list dependencies first |
| `-excludefilelist <list>` | Files to exclude from processing |
| `-top <entity>` | Entity to describe. Without it the input is only analysed |
| `-out <file>` | Output IP-XACT file (default `component.xml`) |
| `-v2014` / `-v2022` | Write IP-XACT 1685-2014 / 1685-2022 instead of 1685-2009 |
| `-vlnv V/L/N/V` | Vendor/library/name/version, `/`- or `:`-separated (default `edautils.com/Lib/<entity>/1.0`) |
| `-noparameval` | Do not evaluate generics/parameters |
| `-fileset_all` | List every input file in the fileSet, in input order, not only the files the entity needs (see "Component contents") |
| `-analyze` | Analyse `-in` (e.g. a package into `-work`); with `-top` it still converts |
| `-work <lib>` | Work library name (default `work`) |
| `-mapfile <ini>` | Logical=physical library map (default `qtmap.ini` in the run directory) |
| `-nowildcard` | No wildcard expansion of file names |
| `-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 |

vhdl2ipxact has its own option parser (case-sensitive; no `-l`). An unrecognised option is
Error 7049 "Unrecognized option" followed by the usage. 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: the `-out` file (default `./component.xml`); the map file `./qtmap.ini`
  (rewritten on each run that gets past option checks); the work library directory
  (`myEdaUtilsWork/` unless the map file maps the work library elsewhere).
- Log: `vhdl2ipxact.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

#### Component contents

- **fileSet `fs-vhdlwrapper`**: the files the entity needs, collected from the analysed design --
  the entity's file, its architectures' files (they may be other files), the packages, package
  bodies and contexts named by their `use`/`context` clauses, and the entities they instantiate,
  to any depth -- in dependency order (each file after what it uses), so the list is also a
  compile order. `std` and `ieee` are the simulator's and are left out. Each file's
  `logicalName` is the library it was compiled into (`-work`, or `library=` in `-filelist`).
  Only units analysed in this run are followed: a package that exists only as a compiled library
  is not reopened (reopening elaborates and can report errors that are not the component's).
  `-fileset_all` lists every `-in`/`-filelist` file instead. `fileType` is `vhdlSource-93`
  (1685-2014/2022) or `vhdlSource` (1685-2009). Paths are relative to the `-out` file's directory.
- **Generics -> parameters**, `parameterId` = generic name, `resolve="user"`. 1685-2014/2022 values
  are SystemVerilog, translated from VHDL: `true`/`false` -> 1/0 (type `bit`); `std_logic`/`bit` ->
  `bit`; `std_logic_vector`/`bit_vector`/`signed`/`unsigned` -> `bit` with `vectors` (`x"A5"` ->
  `8'hA5`, `"0101"` -> `4'b0101`, `(others => '0')` -> `'0`); `integer`/`natural`/`positive` ->
  `int` (`longint` beyond 32 bits), `16#1F#` -> `'h1F`, an `integer range a to b` constraint ->
  `minimum`/`maximum`; `real` -> `real`; `string` -> `string`; any other type (`time`, enumerations)
  -> `string` holding the VHDL text (`"10 ns"`). Operators map (`mod` -> `%`, `/=` -> `!=`, `and` ->
  `&&` ...) and generic names keep their declared spelling. A default with no SystemVerilog form
  that does not evaluate (function call, attribute, concatenation) becomes a string, Warning
  12331. A generic without a default gets a placeholder value, Warning 12330. 1685-2009 keeps
  literal values with `format` `long`/`bool`/`bitString` (+`bitStringLength`)/`float`/`string`;
  an expression kept by `-noparameval` gets no format. Model parameters (1685-2009) carry
  `id`/`resolve="user"` and the VHDL type mark as `dataType`.
- **Ports**: vector bounds are SystemVerilog expressions over the generics (1685-2014/2022);
  a bound that cannot be translated is evaluated, else kept as VHDL text with a Warning. 1685-2009
  writes evaluated numbers. `buffer` ports are `out`; `linkage` is `inout`. The `wireTypeDef` names
  the VHDL type and, when found, the package `use` clause that declares it.
- **1685-2014/2022**: the view is `VHDL` (it used to be named `Verilog`) and refers to a
  `componentInstantiation` `vhdl_implementation`: language `vhdl`, `libraryName`, `moduleName` =
  entity, `architectureName` = the entity's architecture analysed in this run (else the most
  recent compiled one), a `moduleParameter` per generic bound to its component parameter, and a
  `fileSetRef`. 1685-2009: the view `vhdlwrapper` names the fileSet.

### 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: `vhdl2ipxact: <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. Option errors: 4734 (`-analyze` without `-in`), 4735
  (`-in` and `-filelist`), 4736 (`-filelist` without `-top`). Top is not an entity: Error
  5557. Bad `-vlnv`: Warning 4293 / 4294.
- The run ends with `vhdl2ipxact: Note: <id>: Found N error(s) and M warning(s) ...`,
  printed **even with `-nobanner`** (not printed after Error 862 "Top design unit ... is not
  found").
- `-help` output golden: `tests.edautilscommandline/tests/vhdl2ipxact/help_msg/vhdl2ipxact.log.gld`.

### Examples

Shipped (`runme.csh`; the `runme.bat` files call `java com.eu.miscedautils.vhdl2ipxact.Entity2IPXACTComponent`
directly instead of the launcher, so they need `CLASSPATH` from `setup_env.bat`):

```
cd $EDAUTILS_ROOT/examples/simpletest_with_generics
vhdl2ipxact -in simpletest_with_generics.vhd -out simpletest_with_generics.xml -top simpletest_with_generics

cd $EDAUTILS_ROOT/examples/multilib_package      # package analysed into its own library first
vhdl2ipxact -analyze -in myconstpack.vhd -work mylib
vhdl2ipxact -analyze -in multilib_package.vhd -work work -top multilib_package -out multilib_package.xml
```

From the regression suite (reference:
`tests.edautilscommandline/tests/vhdl2ipxact/sort_inputs/runme.csh`):

```
vhdl2ipxact -filelist infile.list -work mylib -top sort_inputs -out sort_inputs.xml
vhdl2ipxact -filelist sources.list -top top -v2014 -out fileset_closure.xml   # fileSet closure, generic translation
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `qtmap.ini`, the work directory and the default output into the current
  directory: give each parallel run its own working directory. Multi-step flows (analyse a
  package, then convert) must share that directory, since the library map links the steps.
- 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. Also check that the component name in the XML is the requested
  `-top`: when `-top` does not match any entity, the lookup can fall through to the last
  analysed design unit instead of reporting Error 862.

### See also

verilog2ipxact, ipxact2vhdl, validateipxact, parsevhdl.
