# genregisteruvmmodel

> Generate UVM register model from IP-XACT Register File

- Catalog id: `Genregisteruvmmodel`; bundle: `genregisteruvmmodel`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: UVM register model, uvm_reg generator, IP-XACT to UVM, RAL model
- 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/genregisteruvmmodel.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Genregisteruvmmodel (latest file `genregisteruvmmodel-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/genregisteruvmmodel/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/genregisteruvmmodel-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 an IP-XACT register description (a component, memoryMaps or addressBlock XML) or a
Synopsys RALF `.ralf` file or a SystemRDL 2.0 `.rdl` file and writes a UVM register model (UVM RAL SystemVerilog classes)
per memory map / address block. Optionally also writes a UVM register test suite
(`-gentests`) and a Verilog `` `define`` header of base addresses, offsets and field masks
(`-vlogheader`). The IP-XACT revision is taken from the root element's namespace unless
`-v2009` / `-v2022` is given. Main class:
`com.eu.miscedautils.genuvmmodel.GenRegisterUVMModel` (jar `lib/genregistermodel.jar`).

### Where it ships

Its own bundle, `genregisteruvmmodel.tar.gz` (flow `genregisteruvmmodel`; release tree
`release_scripts/genregisteruvmmodel/1.0`), and as a point tool in the **ipxact-shell**,
**baya-shell** and **designplayer-shell** bundles (`bin/genregisteruvmmodel` running the shell's
jar; this guide as `tools/genregisteruvmmodel/AGENTS.md`, examples under
`tools/genregisteruvmmodel/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 `IPXACTREGUVMMODELGEN`. 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).
- No external tools needed to generate. Using the output needs a SystemVerilog simulator
  with UVM (compile the generated files in a package that imports `uvm_pkg`).

### Invocation

```
genregisteruvmmodel -in <file.xml | file.ralf | file.rdl> [-outdir <dir>] [options]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT component/memoryMaps/addressBlock XML, `.ralf` or `.rdl` (SystemRDL) file (mandatory in practice). SystemRDL subset: `addrmap`/`regfile`/`reg`/`field` (named or inline), arrays `n[N]` with `@ offset` and `+= stride`, field `[msb:lsb]` / `[width]`, `sw`/`hw`/`onwrite`/`onread`/`reset`/`desc`/`regwidth`/`accesswidth`/`addressing`/`fieldwidth`/`hdl_path`, `default`, `` `include``. enum/encode, `->`, parameters, signal, counter, interrupts, external, alias, mem and the Perl preprocessor stop the run (exit 2) with `unsupported SystemRDL construct <x> at <file>:<line>`. |
| `-outdir <dir>` | Directory under which the per-map/per-block directories are created (default: current directory) |
| `-v2009` / `-v2022` | Force IP-XACT 1685-2009 / 1685-2022 (default: from the XML namespace, else 2014) |
| `-v2014` | Accepted; no effect (2014 is the fallback) |
| `-bigendian` | Big-endian address block (default little-endian) |
| `-gentests` | Also write `<name>_reg_tests.sv`: reset, reachability, bit bash, backdoor, memory walk/access, shared access, access policy and address-decode sequences (honours `testable`/`testConstraint`) |
| `-vlogheader` | Also write `<block>_reg.vh` with base address, register offsets and field mask/offset `` `define``s |
| `-hdl_path_root <path>` | Backdoor HDL path of the top class (e.g. `tb.dut`); register/field paths come from IP-XACT accessHandles |
| `-ralf_top <name>` | RALF block or system to model (default: last system, else last block) |
| `-ralf_byte_offsets` | Read RALF offsets as byte addresses |
| `-rdl_top <name>` | SystemRDL addrmap to model (default: the last root-level addrmap definition); SystemRDL offsets are byte addresses |
| `-suppress <id1:id2>` | Suppress messages by number (not in `-help`) |
| `-quiet` | Suppress messages after option parsing (not in `-help`) |
| `-nobanner` | Skip banner and closing summary (not in `-help`) |
| `-user <email>` | Recorded for usage tracking only (not in `-help`) |
| `-help` | Print usage and exit (there is no `-h`) |

No arguments prints the usage. An unrecognised option prints
`Error: ...: Unrecognized option : <opt>` followed by the usage.

### Inputs / Outputs

- Reads: the `-in` file.
- Writes, under `-outdir` (directories created as needed), one directory per memory map or
  address block named after it: `<name>/<name>.vh` (the UVM RAL model; for a memory map the
  top class is `mmap_<name>_t`), with `-gentests` `<name>/<name>_reg_tests.sv` (sequence
  `<name>_reg_test_seq`), with `-vlogheader` `<block>/<block>_reg.vh`.
- Log: `GenRegisterUVMModel.log` in the current directory (note the capitalisation;
  override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (unreadable or unsupported
  input returns 0). 10 = licence checkout failed. 1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `GenRegisterUVMModel: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit message number. Usage lines have
  no severity or id.
- The run ends with `GenRegisterUVMModel: Note: <id>: Found N error(s) and M warning(s) ...`;
  this summary is **not printed with `-nobanner`**.

### Examples

Shipped (each directory has `runme.csh`, `runme.bat`; most have a `README.txt`):
`examples/simple_register/` (also holds a pre-generated `blk1/blk1.vh`),
`examples/ral_features_2014/`, `examples/banks/`, `examples/subspace_2009/`, `examples/ralf/`.

```
cd $EDAUTILS_ROOT/examples/simple_register
genregisteruvmmodel -v2009 -in simple_register.xml
cd $EDAUTILS_ROOT/examples/ral_features_2014
genregisteruvmmodel -in ral_features_2014.xml -gentests -vlogheader -hdl_path_root tb.dut
cd $EDAUTILS_ROOT/examples/ralf
genregisteruvmmodel -in ralf_soc.ralf -gentests -outdir soc
```

From the regression suite (`tests.edautilscommandline/tests/genregisteruvmmodel/vlog_header/runme.csh`
via `../runme_common.csh`; `ral_features_2014` and the `nexus_*` cases go through
`../runme_sim.csh`, which also compiles and simulates the model against UVM):

```
genregisteruvmmodel -in vlog_header.xml -v2009 -vlogheader
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log into the current directory and files under `-outdir`: give each parallel
  run its own working directory and output 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** the expected `<name>/<name>.vh` exists.

### See also

genregistercmodel (C model from the same inputs), genregisterdochtml, ipxactreg2verilog,
xls2ipxact.
