# ipxact2tlm

> Generate a SystemC TLM-2.0 model skeleton from an IP-XACT component: registers, memory maps and bus interfaces as TLM sockets.

- Catalog id: `Ipxact2tlm`; bundle: `ipxact2tlm`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT to TLM, SystemC TLM generator, TLM-2.0, virtual platform, 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/ipxact2tlm.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Ipxact2tlm (latest file `ipxact2tlm-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/ipxact2tlm/
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/ipxact2tlm/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/ipxact2tlm-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 one IP-XACT component XML (1685-2009 by default, 1685-2014 with `-v2014`, 1685-2022 with
`-v2022`) and writes a SystemC/TLM-2.0 model of it: `<outdir>/<component>.hxx` and
`<outdir>/<component>.cxx` (one SystemC port per IP-XACT port, a typed read/write pair per
transactional port, one storage vector per address block, one TLM-2.0 loosely-timed socket
per transaction-carrying bus interface -- see "Bus interfaces" below). With `-genregmodel` it also writes
the C register model under the same directory. Main class:
`com.eu.miscedautils.ipxact2tlm.GenTLMModel` (jar `lib/ipxact2tlm.jar`).
Note the tool prefix is **`GenTLMModel`**, not `ipxact2tlm`: the log is `GenTLMModel.log`.

### Where it ships

Its own bundle, `ipxact2tlm.tar.gz` (flow `ipxact2tlm`; release tree
`release_scripts/ipxact2tlm/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell** and
**designplayer-shell** bundles (`bin/ipxact2tlm` running the shell's jar; this guide as
`tools/ipxact2tlm/AGENTS.md`, examples under `tools/ipxact2tlm/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` and prepends `bin/` to `PATH`.
- Licence feature `IPXACT2TLM`. 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` (colon-separated directories): when set, the IP-XACT loader
  loads every IP-XACT file found there on first use.
- Generating needs nothing else. Compiling the result needs a C++17 compiler and SystemC
  (the shipped `examples/tlm_systemc/Makefile` targets Accellera SystemC 3.0.1).

### Invocation

```
ipxact2tlm -in <component.xml> [-outdir <dir>] [-v2014 | -v2022] [-genregmodel [-nomask]]
           [-nobanner] [-quiet] [-suppress <id1:id2>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT component XML (mandatory) |
| `-outdir <dir>` | Output directory (default `syscdir`; created with parents if missing) |
| `-v2014` / `-v2022` | Input is IP-XACT 1685-2014 / 1685-2022 (default 1685-2009; `-v2022` wins if both) |
| `-genregmodel` | Also generate the C register/memory model into `<outdir>` |
| `-nomask` | No bit-masking in the C register model (only with `-genregmodel`) |
| `-nobanner` | No completion summary (the banner is still printed) |
| `-quiet` | Silence every later message (log included); errors are then not counted |
| `-suppress <id1:id2>` | Colon-separated message numbers to suppress |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and exit |

An unrecognised option prints "Unrecognized option : <opt>" and the usage (exit 0). No
arguments prints the usage.

### Inputs / Outputs

- Reads: the `-in` component XML, plus any abstraction definitions it names that are found
  (see "Bus interfaces"). If the file does not parse as the selected revision:
  error "No IP-XACT 2009 Component could be read from '<f>', check the file and the IP-XACT
  revision switch ..." (2014/2022 variants analogous).
- Writes: `<outdir>/<name>.hxx` and `<outdir>/<name>.cxx` (`<name>` = component name made a
  C identifier). With `-genregmodel`: the C model (e.g. `common/common.h`,
  `<comp>/<memoryMap>/<memoryMap>.c/.h`, `<memoryMap>_mask.h`) under `<outdir>`.
  If `<outdir>` cannot be created the folder name is blanked and the files are written as
  `/<name>.hxx` (filesystem root), which normally fails: make sure `<outdir>` is creatable.
- Not modelled (per the shipped example README): subspace maps, register fields and access
  types, byte enables / streaming on the sockets, non-literal vector bounds.
- Log: `GenTLMModel.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Bus interfaces (TLM-2.0 sockets)

Every `<busInterface>` is handled the same way in all three revisions:

| Interface mode | Emitted |
|---|---|
| `master` (2009/2014), `initiator` (2022), `mirroredSlave`, `mirroredTarget` | `tlm_utils::simple_initiator_socket< <comp>, BUSWIDTH > <ifname>;` |
| `slave` (2009/2014), `target` (2022), `mirroredMaster`, `mirroredInitiator` | `tlm_utils::simple_target_socket< <comp>, BUSWIDTH > <ifname>;` with `<ifname>_b_transport` and `<ifname>_transport_dbg` registered in the constructor |
| `monitor`, `system`, `mirroredSystem` | no socket, a comment |
| any mode whose busType or abstractionType name contains reset / rst / clock / clk / interrupt / irq / intproc | no socket, a comment: its signals are the mapped physical ports, already emitted as `sc_in`/`sc_out` |

- The socket member is named after the interface (made a C identifier); if that collides
  with a port or parameter name it becomes `<ifname>_socket`. The SystemC object name is the
  member name.
- A target socket's `b_transport` decodes the byte address into the memory map its
  `<memoryMapRef>` names: a transfer wholly inside one address block reads/writes that
  block's storage and answers `TLM_OK_RESPONSE`; anything else answers
  `TLM_ADDRESS_ERROR_RESPONSE`; a byte-enable pointer answers
  `TLM_BYTE_ENABLE_ERROR_RESPONSE`, a streaming width below the length
  `TLM_BURST_ERROR_RESPONSE`. Every path sets the response status. `transport_dbg` does the
  same decode and returns the byte count (0 on error). No memory map, or one with no modelled
  address block: every address answers `TLM_ADDRESS_ERROR_RESPONSE` (WARNING 56771 for the
  latter). Blocks of a serial bank are laid end to end from the bank base. Data is host
  byte order (the TLM-2.0 generic payload convention); addresses are bytes.
- **BUSWIDTH**, first that applies: (1) the widest `width`/`busWidth` of an `isData` port in
  the abstraction definition the interface names; (2) the widest component port that a
  data logical port maps to (the abstraction definition's `isData` ports, or logical names
  containing `DATA` when it was not found); (3) 32, with WARNING 56770 saying which of the
  two was missing. A bound initiator and target must agree on BUSWIDTH, so this is checked
  by the C++ compiler when you bind.
- Abstraction definitions are searched (recursively, plain XML, any revision) in the
  directory of the `-in` file and in the colon-separated directories of
  `EDAUTILS_IPXACT_SEARCH_PATH_ABSTRACTION_DEFINITIONS` and `EDAUTILS_IPXACT_SEARCH_PATH`.
- `<portMaps>` are written into the header as a logical -> physical table per interface
  (`//     PWDATA -> s_data[7:0]`), never as binding code: at LT the transaction travels
  through the socket.
- An unbound socket is a SystemC elaboration error (`E109 complete binding failed`): a
  harness must bind every socket of the generated module.

### Exit status and messages

- 0 on a clean run. **1 if any error was reported** during generation (checked after the
  completion summary), and 1 when arguments were given but `-in` is missing (error "No input
  IP-XACT file given, -in <ip-xact Component file> is mandatory ..."). 10 = licence
  checkout failed. An unrecognised option exits 0. With `-quiet` errors are not counted,
  so the exit is 0.
- Message format: `GenTLMModel: <Severity>: <id>: <text>`; `<id>` is a 5-digit number.
- Bus interface warnings: `56770` (socket BUSWIDTH defaulted to 32, with the reason) and
  `56771` (a target's `<memoryMapRef>` names a map with no modelled address block).
- The run ends with `GenTLMModel: Note: <id>: Found N error(s) and M warning(s) ...`
  unless `-nobanner`.

### Examples

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

```
cd $EDAUTILS_ROOT/examples/ipxact2tlmsystemc
ipxact2tlm -in dma_regmodel.xml -outdir syscsrc -genregmodel
```

Shipped: `examples/tlm_systemc/` (`README.txt`, `Makefile`, `sc_main.cxx`, `timers.xml`,
`pv/` stubs) -- generates `syscsrc/timers.hxx/.cxx` with
`ipxact2tlm -in timers.xml -outdir syscsrc`, then `make` compiles and runs it against SystemC;
the harness binds a CPU initiator to the `APB_Slave` target socket and does a b_transport
register round trip and an unmapped-address check.

From the regression suite (reference: `tests.edautilscommandline/tests/ipxact2tlm/dma_regmodel/runme.csh`
via `../runme_common.csh`, which also syntax-checks every generated `.cxx` with g++ when
SystemC is installed, and links and runs the case's `sc_main.cxx` when it has one --
`busif2014`, `busif2022`, `rgu`, `dma` drive the generated sockets with b_transport):

```
ipxact2tlm -in dma_regmodel.xml -outdir syscsrc -genregmodel
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log (and default `syscdir/`) into the current directory: give each parallel run
  its own working directory (or distinct `-outdir` and `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** `GenTLMModel.log` contains `Found 0 error(s)` (do not
  use `-nobanner`/`-quiet` if you rely on it) **and** `<outdir>/<name>.hxx/.cxx` exist.
  Compile the `.cxx` (`g++ -std=c++17 -fsyntax-only -I$SYSTEMC_HOME/include -I<outdir>`) for a
  real check; the read/write stubs return `TLM_OK_RESPONSE` and need your behaviour filled in
  (the socket `b_transport`s are complete register/memory models).
- Windows: `bin/ipxact2tlm.bat` does not set `CLASSPATH`; it relies on `setup_env.bat`.

### See also

genregistercmodel, genregisteruvmmodel, ipxact2verilog, validateipxact, ipxact-shell.
