# gendocipxact

> Generate IP documentation (HTML/ODT) from an IP-XACT component: ports, parameters, bus interfaces, memory maps and registers.

- Catalog id: `Gendocipxact`; bundle: `gendocipxact`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: IP-XACT documentation, register documentation, IP datasheet generator, IEEE 1685
- 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/gendocipxact.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Gendocipxact (latest file `gendocipxact-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/gendocipxact/
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/gendocipxact/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/gendocipxact-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 component XML (or a memoryMaps document) and writes an OpenDocument text
file (`.odt`) describing it: ports, parameters, bus interfaces, memory maps, registers and
bit fields, filled into an ODT template. Input revision is IP-XACT 1685-2014 by default;
`-v2009` / `-v2022` select the other revisions (no auto-detection). Main class:
`com.eu.miscedautils.docgen.GenDocIPXACT` (jar `lib/docgenerator.jar`).

### Where it ships

Its own bundle, `gendocipxact.tar.gz` (flow `gendocipxact`; release tree
`release_scripts/gendocipxact/1.0`), and as a point tool in the **ipxact-shell** and
**designplayer-shell** bundles (`bin/gendocipxact` running the shell's jar; this guide as
`tools/gendocipxact/AGENTS.md`, examples under `tools/gendocipxact/examples/`).

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`, with `-Djava.awt.headless=true`). 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`.
- The default templates are read from `$EDAUTILS_ROOT/lib/hdldocgen.odt` (component input)
  and `$EDAUTILS_ROOT/lib/memorymap.odt` (memoryMaps input); both ship in `lib/`.
- Licence feature `IPXACTDOCGEN`. 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 (an ODT viewer such as LibreOffice to read the result).

### Invocation

```
gendocipxact -in <component.xml> [-out <file.odt>] [-v2009 | -v2022] [options]
```

The tool parses its own options (it does not use the shared Verilog option reader):

| Option | Meaning |
|---|---|
| `-in <file.xml>` | IP-XACT component or memoryMaps XML (required; not checked up front, see below) |
| `-out <file.odt>` | Output document (default `output.edautils.odt`) |
| `-v2009` | Input is IP-XACT 1685-2009 |
| `-v2022` | Input is IP-XACT 1685-2022 (default without either switch: 1685-2014) |
| `-template <file.odt>` | ODT template to fill instead of the one in `$EDAUTILS_ROOT/lib` (not in `-help`) |
| `-suppress <id1:id2>` | Suppress messages by number |
| `-quiet` | Do not print log messages |
| `-nobanner` | Skip the completion summary |
| `-user <email>` | User id recorded by usage tracking (not in `-help`) |
| `-toolprefix <p>` | Parsed but has no effect (the prefix is set before parsing; not in `-help`) |
| `-help` | Print usage and exit (`-h` is not recognised) |

No arguments prints the usage. An unrecognised option is an error (7009 "Unrecognized
option") followed by the usage.

### Inputs / Outputs

- Reads: the `-in` XML; the ODT template.
- Writes: the `-out` document in the current directory unless a path is given.
- Log: `gendocipxact.log` in the current directory (override with `EDAUTILS_LOG_FILE` or
  `EDAUTILS_APPEND_LOG_FILE`; this tool has no `-l` option). Every console line is also
  written to the log.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing `-in` gives
  Error 1168 "NULL object passed as component definition XML" and Fatal 5768 "Failed to
  process", then exit 0). 10 = licence checkout failed. 1 = `EDAUTILS_ROOT` missing/invalid.
- The licence is checked before the tool prefix is set, so licence-failure lines carry the
  prefix `DesignPlayer` and go to `DesignPlayer.log`.
- Message format: `gendocipxact: <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.
- A save failure (e.g. output open elsewhere) is Error 6189.
- The run ends with `gendocipxact: 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
gendocipxact -in i2c.xml -v2009          # writes output.edautils.odt
```

From the regression suite (reference:
`tests.edautilscommandline/tests/gendocipxact/i2c_2014/runme.csh` via `../runme_common.csh`):

```
gendocipxact -in i2c_2014.xml
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and default output into the current directory: give each parallel run its
  own working directory (or a distinct `-out` and `EDAUTILS_LOG_FILE`).
- 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 `-out` file exists.

### See also

genregisterdochtml (HTML register view of the same input), gendocverilog, genregistercmodel,
genregisteruvmmodel.
