# verilog2ipxact

> Generate IP-XACT Component from Verilog module with ports and parameters

- Catalog id: `Verilog2Ipxact`; bundle: `verilog2ipxact`; latest version 20261018
- Documentation page: https://edautils.com/verilog2ipxact.html
- Keywords: Verilog 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/verilog2ipxact.md

## Downloads

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

Parses Verilog/SystemVerilog, finds the top module and writes its IP-XACT view: by default an
IP-XACT **component** (ports, parameters/model parameters, file sets); with `-design`, an IP-XACT
**design** of the top module's instances plus an ipxact-shell Tcl script that rebuilds it.
Output revision is IEEE 1685-2009 by default, 1685-2014 with `-v2014`, 1685-2022 with `-v2022`.
Main class: `com.eu.miscedautils.verilog2ipxact.verilog2ipxact` (jar `lib/verilog2ipxact.jar`).

### Where it ships

Its own bundle, `verilog2ipxact.tar.gz` (flow `verilog2ipxact`; release tree
`release_scripts/verilog2ipxact/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell**
and **designplayer-shell** bundles (`bin/verilog2ipxact` running the shell's jar; this guide as
`tools/verilog2ipxact/AGENTS.md`, examples under `tools/verilog2ipxact/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=$EDAUTILS_ROOT/lib/verilog2ipxact.jar`
  and prepends `bin/` to `PATH`.
- Licence: **two** features, `VERILOG2IPXACTCOMP` and `VERILOG2IPXACTDES`, both checked on every run
  (component mode too, and before `-help` is looked at). Either one missing, or no valid licence
  file: Error "Failed to checkout LICENSE for the feature : <name>", **exit status 11** (most other
  tools use 10). The licence file is
  searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory),
  `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. (`README.txt` says `EDAUTILS_LICENSE_KEY`;
  that is stale -- the variable is `EDAUTILS_LICENSE_FILE`.)
- No XSD schemas or XSL files are read (output is written through compiled JAXB bindings), so the
  bundle ships neither `bin/schemas` nor `bin/xsl`.
- 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) for big designs),
  `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` (map file for `-dump`/`-restore`, default `libmap.ini`).
  `-design` reads existing component XMLs through `-search_path`; the IP-XACT loaders also read
  the `EDAUTILS_IPXACT_SEARCH_PATH*` variables.
- No external tools needed.

### Invocation

```
verilog2ipxact -in <file.v> | -f <files.list>  -top <module>  [-out <file.xml>]
               [-v2014 | -v2022] [-design [-search_path <p1:p2>]] [-vlnv <V/L/N/V>]
               [-v95] [-nowildcard] [+incdir+<d1>+<d2>] [+define+<M1>+<M2>=<val>]
               [-noparameval] [-nobanner] [-quiet] [-suppress <id1:id2>]
```

Tool options:

| Option | Meaning |
|---|---|
| `-top <module>` | Top module to convert (mandatory; without it only the usage is printed) |
| `-out <file>` | Output XML (default `output.ipxact.xml`) |
| `-v2014` / `-v2022` | Output revision 1685-2014 / 1685-2022 (default **1685-2009**; if both, 2022 wins) |
| `-design` | Write an IP-XACT design instead of a component (see Outputs) |
| `-search_path <p1:p2>` | Colon-separated directories searched for sub-module component XMLs with `-design` (default `.`) |
| `-vlnv <V/L/N/V>` | Component VLNV, `/`- or `:`-separated (default `edautils.com/complib/<top>/1.0`). Warns if not 4 fields or if the name differs from the module |
| `-noparameval` | Do not evaluate parameter expressions |
| `-fileset_all` | List every input file in the fileSet, in input order, not only the files the top module needs (see "Component contents") |
| `-toolprefix <name>` | Name printed in the banner only (log name and message prefix stay `verilog2ipxact`) |
| `-help`, `-h` | Print the usage and return |

Verilog front-end options (shared with the other Verilog tools):

| Option | Meaning |
|---|---|
| `-in <file>` | One Verilog file; wildcard-expanded unless `-nowildcard` |
| `-f <file>` | File list (one file per line; `+incdir+`/`+define+` lines allowed); repeatable. `-in` wins if both are given |
| `-excludefilelist <file>` | Files to drop from the input list |
| `-v95` | Parse as Verilog-95/2001 (SystemVerilog keywords off); default is SystemVerilog |
| `-nowildcard` | No wildcard expansion of `-in` |
| `+incdir+<d1>+<d2>` | Include search paths (environment variables expanded) |
| `+define+<M>[=<v>]+...` | Predefine macros |
| `-nokeywords <k1:k2>` | Words not to treat as keywords (the suite uses `-nokeywords do`) |
| `-blackbox` | Create black boxes for undefined modules |
| `-declare_wires_for_undefined_obects` | Declare wires for undeclared objects (spelling as in the code) |
| `-l <file>` / `-la <file>` | Log file name / append to it |
| `-nobanner` | No banner and no completion summary |
| `-quiet` | Silence every later message (log included); errors are then not counted |
| `-suppress <id1:id2>` | Colon-separated message numbers to suppress |
| `-dump`, `-restore <units>`, `-work <lib>`, `-mapfile <file>` | Save/load precompiled design units |
| `-encryption_key`, `-encryption_algorithm`, `-private_key_file`, `-public_key_file` | Encrypted-source options |
| `-dbg` | Parser debug tracing |
| `-user <email>` | Usage-tracking user id |

The usage text also lists `-sort` and `-nopreprocess`; **neither is accepted** on the command
line. An unrecognised word logs Error "Unrecognized option : <word>" and the run stops with no
usage and no summary (exit 0). Missing `-in`/`-f` prints the usage after
the banner.

### Inputs / Outputs

- Reads: the Verilog sources, include files; with `-design`, component XMLs under `-search_path`.
- Component mode writes the component XML to `-out`.
- `-design` writes **two** files: the design XML to `-out`, and the ipxact-shell Tcl script
  `commands.ipxact.design.tcl` (fixed name, current directory). Sub-modules with no component in
  the search path are converted from their Verilog, with Warning "Could not find the IP-XACT
  Component definition for '<m>' in the search path, converting Verilog module definition into
  IP-XACT Component ...". The log line "Creating ip-xact Tcl command in file <out>" names the
  XML, not the Tcl file.
- Also creates the directory `myEdaUtilsWork/` in the current directory (Verilog work library),
  even when nothing is dumped.
- Log: `verilog2ipxact.log` in the current directory (override with `-l`/`-la` or `EDAUTILS_LOG_FILE`).

#### Component contents

- **fileSet `fs-verilogwrapper`**: the files the top module needs, collected from the parsed
  design rather than copied from the file list -- the top module's file, the file of every module
  and UDP it instantiates (through generate blocks too, to any depth), the files of the packages
  they import, and the files they `` `include`` (marked `isIncludeFile`). Testbenches and modules
  the top does not use stay out; `-fileset_all` lists every input file instead. Files are in the
  order of the input list; includes follow. Each `+incdir+` directory is a fileSet `dependency`,
  each `+define+NAME=VALUE` a `define` on every source file. `fileType` follows the extension
  (`.sv`/`.svh` systemVerilogSource, otherwise verilogSource). Paths are relative to the `-out`
  file's directory (absolute if on another root). Verilog has no libraries, so no `logicalName`.
- **Parameters**: every module parameter (localparams are not), `resolve="user"`,
  `parameterId` = the parameter name. 1685-2014/2022 `type` comes from the declared type (`int`,
  `longint`, `string`, `real`, `bit`/`logic` with a range -> `bit` with `vectors`), else from the
  value (`int`, or `longint` beyond 32 bits; string and real literals). 1685-2009 `format` is
  `long`/`string`/`float` for literals and absent for an expression it cannot evaluate. The
  parser holds integers in 32 bits: a 64-bit literal is truncated (Error 53112).
- **Ports**: every packed dimension is a `vector` (outermost first); unpacked dimensions are
  1685-2014/2022 `arrays` (`[N]` is `[0:N-1]`). A bound that does not evaluate keeps its
  expression in 1685-2014/2022 (Warning) -- 1685-2009 writes 0. A `ref` or interface port is
  written as `inout` with Warning 12320-12322.
- **1685-2014/2022**: a `componentInstantiation` `verilog_implementation` (language `verilog`, or
  `systemverilog` for a `.sv` top file; `moduleName`; one `moduleParameter` per parameter whose
  value is the component parameter's ID, so a configured value reaches the module; `fileSetRef`),
  and the view `Verilog` refers to it. 1685-2009: the view `verilogwrapper` names the fileSet,
  language `Verilog`/`SystemVerilog`.
- A `-vlnv` that is not four fields falls back to `edautils.com/complib/<top>/1.0` (Warning).
- The parser does not accept `import pkg::*;` in an ANSI module header (Error 55638); import in
  the module body instead.

### Exit status and messages

- 0 on every normal return, **including failures** (parse errors, top not found, unrecognised
  option, internal exceptions). 11 = licence checkout failed. 1 = out of memory, or
  `EDAUTILS_ROOT` missing/invalid (launcher).
- Message format: `verilog2ipxact: <Severity>: <id>: <text>`, severity one of `Error`,
  `Programming Error`, `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit number.
- Key messages: `Creating ip-xact component <out> ...`, `created ip-xact <out> ...`,
  Error `Could not find the top module '<m>' ...`. The run ends with
  `Found N error(s) and M warning(s) ...` (not with `-nobanner`).
- Parse errors in the Verilog are counted but do not stop the run; check the error count.

### Examples

Shipped: `examples/i2c/` and `examples/i2c_2022/` (the i2c RTL, `files.txt`, `runme.csh`,
`runme.bat`; `i2c/i2c.vhd` is not used):

```
cd $EDAUTILS_ROOT/examples/i2c
verilog2ipxact -f files.txt -out i2c.xml -top i2c -v95
cd $EDAUTILS_ROOT/examples/i2c_2022
verilog2ipxact -f files.txt -out i2c_2022.xml -top i2c -v95 -v2022
```

From the regression suite (reference: `tests.edautilscommandline/tests/verilog2ipxact/`; 12 cases,
golden `<case>.xml.gld`; `help_msg` compares `verilog2ipxact -help` against `verilog2ipxact.log.gld`):

```
verilog2ipxact -nowildcard -in simple_and_2022.v -out simple_and_2022.xml -top simple_and -v2022
verilog2ipxact -nowildcard -f infile.list -out l2_cache_processor_interface.xml -top l2_cache_processor_interface +incdir+src
verilog2ipxact -nowildcard -nokeywords do -f files.txt -out design2014.xml -top i2c -design -v2014
verilog2ipxact -nowildcard -f files.f -top top +incdir+inc +define+MODE=2 -v2014 -out fileset_closure.xml   # fileSet closure
verilog2ipxact -nowildcard -f files.f -top top +incdir+inc +define+MODE=2 -fileset_all -v2022 -out fileset_all_2022.xml
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `myEdaUtilsWork/`, the default output and (with `-design`)
  `commands.ipxact.design.tcl` into the current directory: give each parallel run its own
  working directory.
- About 40 s per IP (JVM start plus parse). When a flow needs many components, generate them once
  and reuse them rather than re-running per case.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `created ip-xact` and `Found 0 error(s)`
  (do not use `-nobanner`/`-quiet` if you rely on these) **and** the `-out` file exists.

### See also

ipxact2verilog (the reverse), vhdl2ipxact, validateipxact, ipxact-shell (sources
`commands.ipxact.design.tcl`).
