# genregisterdochtml

> Generate HTML register documentation from an IP-XACT register definition: address maps, registers, fields and reset values.

- Catalog id: `Genregisterdochtml`; bundle: `genregisterdochtml`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: register documentation, HTML register map, IP-XACT registers, register datasheet
- 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/genregisterdochtml.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Genregisterdochtml (latest file `genregisterdochtml-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/genregisterdochtml/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/genregisterdochtml-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, memoryMap or addressBlock XML) and
writes a self-contained HTML register viewer: `top.html` plus three data scripts
(`blocks.js`, `registers.js`, `fields.js`). The viewer is a single document (no frames, no
fetch/XHR), so it opens from a `file://` URL in any browser; its three tables (address
blocks, registers, bit fields) are virtualised and filterable. Main class:
`com.eu.miscedautils.docgen.GenHTMLDocIPXACT` (jar `lib/docgenerator.jar`).

### Where it ships

Its own bundle, `genregisterdochtml.tar.gz` (flow `genregisterdochtml`; release tree
`release_scripts/genregisterdochtml/1.0`), and as a point tool in the **ipxact-shell** and
**designplayer-shell** bundles (`bin/genregisterdochtml` running the shell's jar; this guide as
`tools/genregisterdochtml/AGENTS.md`, examples under `tools/genregisterdochtml/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 `IPXACTDOCGEN` (the same feature as gendocipxact). 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; any browser displays the output.

### Invocation

```
genregisterdochtml -in <ipxact.xml> [-outdir <dir>] [-v2009 | -v2022] [options]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT component / memoryMap / addressBlock XML (mandatory) |
| `-outdir <dir>` | Directory for `top.html` and the `.js` files (default `.`; created if needed) |
| (none) | Input read as IEEE 1685-2014 |
| `-v2009` | Input is IP-XACT 1685-2009 |
| `-v2022` | Input is IP-XACT 1685-2022 |
| `-suppress <id1:id2>` | Suppress messages by number |
| `-quiet` | Suppress messages after option parsing (not in `-help`) |
| `-nobanner` | Skip the closing summary; the banner is still printed (not in `-help`) |
| `-instmap <file>` | Accepted but not used by the generator: given alone it ends in the "NULL object" error; given with `-in` only a warning is printed (not in `-help`) |
| `-user <email>` | Recorded for usage tracking only (not in `-help`) |
| `-toolprefix <p>` | Accepted but has no effect: the prefix is set before options are parsed |
| `-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` XML.
- Writes, in `-outdir`: `top.html`, `blocks.js`, `registers.js`, `fields.js` (UTF-8).
  These are written even when the input could not be read (then with empty tables).
- Log: `genregisterdochtml.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing `-in`,
  unreadable XML, unsupported element all return 0). 10 = licence checkout failed.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `genregisterdochtml: <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.
- Missing input: `Missing mandatory input- the IP-XACT Register Definition XML or the instance map file ..`
  and `NULL object passed as component definition XML ...`. Unsupported root element:
  `Unsupported IP-XACT Element of type : <class>`.
- On completion: `Wrote B address block(s), R register(s) and F field(s) to <outdir>/top.html`
  (a count of 0 blocks means nothing was read), then
  `genregisterdochtml: Note: <id>: Found N error(s) and M warning(s) ...`; this summary is
  **not printed with `-nobanner`**.

### Examples

Shipped: `examples/i2c/` (`runme.csh`, `runme.bat`, `i2c.xml`):

```
cd $EDAUTILS_ROOT/examples/i2c
genregisterdochtml -v2009 -in i2c.xml        # then open top.html in a browser
```

From the regression suite (`tests.edautilscommandline/tests/genregisterdochtml/i2c/runme.csh`
via `../runme_common.csh`, which compares the log and all four output files to goldens):

```
genregisterdochtml -in i2c.xml -v2009
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- The log goes to the current directory and the viewer to `-outdir` (default the current
  directory): give each parallel run its own working directory or distinct `-outdir`.
- 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 `Wrote ...` line reports at least one
  address block.

### See also

gendocipxact (OpenDocument output), genregistercmodel, genregisteruvmmodel, ipxactreg2xlsreg.
