# genregistercmodel

> Generate C model from IP-XACT Register definition

- Catalog id: `Genregistercmodel`; bundle: `genregistercmodel`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: C header generator, register C model, IP-XACT registers, firmware header
- 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/genregistercmodel.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Genregistercmodel (latest file `genregistercmodel-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/genregistercmodel/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/genregistercmodel-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, memoryMap or addressBlock
file; an IP-XACT design with `-design`; a Synopsys RALF `.ralf` file or a SystemRDL 2.0 `.rdl` file) and writes a C
register model: per address block a structure header, a register/bit-field header, a mask
header and an initialiser `.c`, plus a shared `common/common.h`, per-memory-map address-map
headers and, with `-gentests`, register self-tests in C. The IP-XACT revision is taken from
the root element's namespace unless `-v2009` / `-v2022` is given. Main class:
`com.eu.miscedautils.gencmodel.GenRegisterCModel` (jar `lib/genregistermodel.jar`).

### Where it ships

Its own bundle, `genregistercmodel.tar.gz` (flow `genregistercmodel`; release tree
`release_scripts/genregistercmodel/1.0`), and as a point tool in the **ipxact-shell**,
**baya-shell** and **designplayer-shell** bundles (`bin/genregistercmodel` running the shell's
jar; this guide as `tools/genregistercmodel/AGENTS.md`, examples under
`tools/genregistercmodel/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 `IPXACTREGCMODELGEN`. 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_IPXACT_SEARCH_PATH` and `EDAUTILS_IPXACT_SEARCH_PATH_{COMPONENTS,BUS_DEFINITIONS,ABSTRACTION_DEFINITIONS,DESIGNS}`
  (colon-separated directories read by the IP-XACT loaders).
- No external tools needed to generate. A C compiler is needed only to use the output.

### Invocation

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

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT component/memoryMaps/memoryMap/addressBlock XML, a design XML (with `-design`), a `.ralf` or an `.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 for the generated files (default: current directory) |
| `-v2009` / `-v2022` | Force IP-XACT 1685-2009 / 1685-2022 (default: from the XML namespace, else 2014) |
| `-blks <b1:b2>` | Generate only these address blocks (component/memory-map input) |
| `-design` | Input is an IP-XACT design; instantiated components are found via `-search_path` |
| `-search_path <p1:p2>` | Where the design's component XMLs are found (default `.`) |
| `-addressmap <file>` | Base-address overrides, one `inst1/mmap1/blk1=0x1024` per line |
| `-regprefix <s>` / `-regsuffix <s>` | Register name prefix/suffix (address-block input) |
| `-baseaddress <0x..>` | Base address for an address-block input |
| `-reg_value_accssor <name>` | Accessor for the register value (default `value`) |
| `-reg_field_accssor <name>` | Accessor for the bit-field struct (default `Fields`) |
| `-reg_size <n>` | Default register size (integer; not in `-help`) |
| `-bitunit <n>` | Bits per address unit (default 8) |
| `-nomask` | Do not write the `_mask.h` file |
| `-bigendian` | Big-endian block: bit-fields most significant first; `common.h` refuses the other byte order |
| `-gentests` | Also write `<block>_test.c` / `<block>_test.h` register self-tests |
| `-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 |
| `-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; with `-design`, component XMLs under `-search_path`;
  the `-addressmap` file.
- Writes, under `-outdir` (created if needed): `common/common.h`; per address block a
  directory `<block>/` (nested under the component / memory-map name for component and
  design inputs, e.g. `i2c/registers/`) holding `<block>.h`, `<block>.c`, `<block>_regs.h`
  (prefix/suffix applied) and `<block>_mask.h` (not with `-nomask`); with `-gentests` also
  `<block>_test.c` / `<block>_test.h`. For a component, `<component>/<map>/<map>_address_map.h`.
  Some inputs also produce a top-level `main.c` (seen for design inputs in the regression goldens).
- Log: `GenRegisterCModel.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 input, bad
  `-bitunit`/`-reg_size`/`-baseaddress`, unsupported element all return 0).
  10 = licence checkout failed. 1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `GenRegisterCModel: <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.
- With no errors the tool prints `Use the switch -fpermissive to compile the generated file(s) with GNU g++ compiler ...`.
- The run ends with `GenRegisterCModel: 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/`, `examples/c_features_2014/` (with `ram_test.c`),
`examples/banks/`, `examples/subspace/`, `examples/ralf/`.

```
cd $EDAUTILS_ROOT/examples/simple_register
genregistercmodel -v2009 -in simple_register.xml
cd $EDAUTILS_ROOT/examples/c_features_2014
genregistercmodel -in c_features_2014.xml -outdir csrc -gentests
cd $EDAUTILS_ROOT/examples/ralf
genregistercmodel -in ralf_soc.ralf -outdir csrc_soc -gentests
```

From the regression suite (`tests.edautilscommandline/tests/genregistercmodel/design_2014/runme.csh`;
simple cases go through `../runme_common.csh`, which also runs `gcc -c` on the result):

```
genregistercmodel -in design_2014.xml -outdir csrc -design -search_path ./complib
genregistercmodel -in addressblk_override_cmdline.xml -outdir . \
    -regprefix uart_ -regsuffix _inst -baseaddress 0x00ff -v2009
```

### 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 `<block>/<block>.h` exists.
  Compile check used by the regression: `gcc -c <out>/<blk>/<blk>.c -I<out>/common -I<out>/<blk>`.

### See also

genregisteruvmmodel (UVM RAL from the same inputs), genregisterdochtml, ipxactreg2verilog,
xls2ipxact.
