@h2loop/autosar 1.0.1 → 1.1.0

package/python/ecuc_engine/rte_api.py

@@ -0,0 +1,935 @@
+"""Expected RTE API per SW-C and runnable, derived from the SWC description ARXML (pure model layer).
+
+Everything is found by following references from the SW-COMPONENT-TYPE: ports -> port interfaces -> data
+elements / operations / mode groups / parameters / triggers, the SWC-INTERNAL-BEHAVIOR's runnables and their
+access points, inter-runnable variables, per-instance memory, internal calibration parameters and exclusive
+areas; data types through IMPLEMENTATION-DATA-TYPEs and the behaviour's DATA-TYPE-MAPPING-SETs. No name or
+layout of any particular project is assumed.
+
+Three tiers per API name (AUTOSAR CP R25-11 SWS_RTE, chapter 5.6):
+  allowed    the runnable has the access point the API's "Existence" requirement names (e.g. a dataSendPoint
+             for Rte_Write, SWS_Rte_01280); only these may be called from that runnable
+             (SWS_Rte_CONSTR_09017/09083/... "may only be used by the runnable that contains ...")
+  generated  some runnable of the SW-C is allowed it, so the RTE generator emits it into Rte_<Swc>.h
+  derivable  the port/element (or IRV, parameter, ...) exists with a compatible direction and semantics, so the
+             API could be enabled by adding an access point; calling it now does not compile
+Anything else is not an API of this SW-C.
+
+Each entry carries a full C signature by the SWS_RTE parameter-passing rules (IN primitive by value
+SWS_Rte_01017, IN struct/union by const reference SWS_Rte_01018/07086, IN array as pointer to the base type
+SWS_Rte_05107, OUT by reference SWS_Rte_01019/07082/05108, return values SWS_Rte_07069..07073,
+Rte_Instance first for multiple instantiation), so a header generator can emit Rte_<Swc>.h from this model.
+Matching against an existing generated Rte_<Swc>.h is the separate, optional ``match_header`` step.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from . import paths
+from .xmltree import Node, parse
+
+SWC_TAGS = ("APPLICATION-SW-COMPONENT-TYPE", "SENSOR-ACTUATOR-SW-COMPONENT-TYPE", "SERVICE-SW-COMPONENT-TYPE",
+            "COMPLEX-DEVICE-DRIVER-SW-COMPONENT-TYPE", "ECU-ABSTRACTION-SW-COMPONENT-TYPE",
+            "NV-BLOCK-SW-COMPONENT-TYPE", "SERVICE-PROXY-SW-COMPONENT-TYPE", "PARAMETER-SW-COMPONENT-TYPE")
+MARKERS = (b"SW-COMPONENT-TYPE", b"INTERFACE>", b"DATA-TYPE", b"MODE-DECLARATION-GROUP", b"SW-BASE-TYPE")
+PRIMITIVE_NAMES = {"boolean", "uint8", "uint16", "uint32", "uint64", "sint8", "sint16", "sint32", "sint64",
+                   "float32", "float64", "uint8_least", "uint16_least", "uint32_least", "sint8_least",
+                   "sint16_least", "sint32_least", "Std_ReturnType"}
+
+# API kind -> (signature requirement, existence requirement)
+CITE = {
+    "Write": ("SWS_Rte_01071", "SWS_Rte_01280"), "Send": ("SWS_Rte_01072", "SWS_Rte_01281"),
+    "Switch": ("SWS_Rte_02631", "SWS_Rte_02632"), "Invalidate": ("SWS_Rte_01206", "SWS_Rte_01282"),
+    "Feedback": ("SWS_Rte_01083", "SWS_Rte_01285"), "SwitchAck": ("SWS_Rte_02725", "SWS_Rte_02677"),
+    "Read": ("SWS_Rte_01091", "SWS_Rte_01289"), "DRead": ("SWS_Rte_07394", "SWS_Rte_07395"),
+    "Receive": ("SWS_Rte_01092", "SWS_Rte_01288"), "Call": ("SWS_Rte_01102", "SWS_Rte_01293/01294"),
+    "Result": ("SWS_Rte_01111", "SWS_Rte_01296/01297"), "Pim": ("SWS_Rte_01118", "SWS_Rte_01299"),
+    "CData": ("SWS_Rte_01252", "SWS_Rte_01300"), "Prm": ("SWS_Rte_03928", "SWS_Rte_03929"),
+    "IRead": ("SWS_Rte_03741", "SWS_Rte_01301"), "IReadRef": ("SWS_Rte_04577", "SWS_Rte_04578"),
+    "IWrite": ("SWS_Rte_03744", "SWS_Rte_01302"), "IWriteRef": ("SWS_Rte_05509", "SWS_Rte_05510"),
+    "IInvalidate": ("SWS_Rte_03800", "SWS_Rte_03801"), "IStatus": ("SWS_Rte_02599", "SWS_Rte_02600"),
+    "IrvIRead": ("SWS_Rte_03550", "SWS_Rte_01303"), "IrvIReadRef": ("SWS_Rte_04579", "SWS_Rte_04580"),
+    "IrvIWrite": ("SWS_Rte_03553", "SWS_Rte_01304"), "IrvIWriteRef": ("SWS_Rte_06207", "SWS_Rte_06208"),
+    "IrvRead": ("SWS_Rte_03560", "SWS_Rte_01305"), "IrvWrite": ("SWS_Rte_03565", "SWS_Rte_01306"),
+    "Enter": ("SWS_Rte_01120", "SWS_Rte_01307"), "Exit": ("SWS_Rte_01123", "SWS_Rte_01308"),
+    "Mode": ("SWS_Rte_02628", "SWS_Rte_02629"), "Trigger": ("SWS_Rte_07200", "SWS_Rte_07201"),
+    "IrTrigger": ("SWS_Rte_07203", "SWS_Rte_07204"), "IsUpdated": ("SWS_Rte_07390", "SWS_Rte_07391"),
+}
+# longest first, so "IrvIReadRef" is tried before "IrvIRead" before "IrvRead"
+KINDS = sorted(CITE, key=len, reverse=True)
+PER_RUNNABLE = {"IRead", "IReadRef", "IWrite", "IWriteRef", "IInvalidate", "IStatus", "IrvIRead", "IrvIReadRef",
+                "IrvIWrite", "IrvIWriteRef", "IrvRead", "IrvWrite", "IrTrigger"}
+ROLE = {  # access-point collection -> role name used in reports and suggestions
+    "DATA-SEND-POINTS": "dataSendPoint", "DATA-RECEIVE-POINT-BY-ARGUMENTS": "dataReceivePointByArgument",
+    "DATA-RECEIVE-POINT-BY-VALUES": "dataReceivePointByValue", "DATA-READ-ACCESSS": "dataReadAccess",
+    "DATA-WRITE-ACCESSS": "dataWriteAccess", "SERVER-CALL-POINTS": "serverCallPoint",
+    "ASYNCHRONOUS-SERVER-CALL-RESULT-POINTS": "asynchronousServerCallResultPoint",
+    "MODE-ACCESS-POINTS": "modeAccessPoint", "MODE-SWITCH-POINTS": "modeSwitchPoint",
+    "PARAMETER-ACCESSS": "parameterAccess", "READ-LOCAL-VARIABLES": "readLocalVariable",
+    "WRITTEN-LOCAL-VARIABLES": "writtenLocalVariable", "EXTERNAL-TRIGGERING-POINTS": "externalTriggeringPoint",
+    "INTERNAL-TRIGGERING-POINTS": "internalTriggeringPoint",
+}
+COLLECTION = {v: k for k, v in ROLE.items()}
+INVALIDATING = {"KEEP", "REPLACE", "EXTERNAL-REPLACEMENT"}
+
+
+# ---------------------------------------------------------------- ARXML index
+class ArIndex:
+    """Identifiables of all non-ECUC ARXML that can hold SWC descriptions, interfaces and data types."""
+
+    def __init__(self, root: str, files: Optional[list] = None):
+        self.root = root
+        self.by_path: dict = {}
+        self.path_of: dict = {}
+        self.file_of: dict = {}
+        self.files: list = []
+        for f in sorted(files if files is not None else paths.walk(root, paths.is_arxml).files):
+            try:
+                data = open(f, "rb").read()
+            except OSError:
+                continue
+            if not any(m in data for m in MARKERS):
+                continue
+            try:
+                doc = parse(data)
+            except Exception:  # noqa: BLE001  (malformed file: skipped, other files still indexed)
+                continue
+            self.files.append(f)
+            stack = [(doc, "")]
+            while stack:
+                n, prefix = stack.pop()
+                sn = n.short_name
+                p = f"{prefix}/{sn}" if sn is not None else prefix
+                if sn is not None:
+                    self.by_path.setdefault(p, n)
+                    self.path_of[id(n)] = p
+                    self.file_of[id(n)] = f
+                stack.extend((c, p) for c in reversed(n.children))
+
+    def get(self, path: Optional[str]) -> Optional[Node]:
+        return self.by_path.get(path.strip()) if path else None
+
+    def path(self, n: Node) -> str:
+        return self.path_of.get(id(n), "")
+
+    def where(self, n: Node) -> tuple:
+        return self.file_of.get(id(n)), n.line
+
+    def of_tag(self, *tags) -> list:
+        return [n for p, n in sorted(self.by_path.items()) if n.tag in tags]
+
+
+def _desc(n: Node, tag: str) -> Optional[Node]:
+    for c in n.iter():
+        if c is not n and c.tag == tag:
+            return c
+    return None
+
+
+def _desc_text(n: Node, tag: str) -> Optional[str]:
+    c = _desc(n, tag)
+    return c.text.strip() if c is not None else None
+
+
+def _own(n: Node, coll: str) -> list:
+    """Children of the collection element ``coll`` directly under n (identifiables in an aggregation)."""
+    c = n.child(coll)
+    return list(c.children) if c is not None else []
+
+
+def _ref_ending(n: Node, *suffixes) -> Optional[str]:
+    for c in n.iter():
+        if c is not n and c.tag.endswith(suffixes):
+            t = c.text.strip()
+            if t:
+                return t
+    return None
+
+
+# ---------------------------------------------------------------- types
+@dataclass
+class TypeInfo:
+    name: str
+    kind: str  # primitive | struct | union | array | pointer | unknown
+    path: Optional[str] = None
+    base: Optional[str] = None  # array element C type
+    note: Optional[str] = None
+
+    def to_dict(self):
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+class Types:
+    def __init__(self, ix: ArIndex):
+        self.ix = ix
+        self._maps: dict = {}
+
+    def mapping(self, set_paths: list) -> tuple:
+        key = tuple(set_paths)
+        if key not in self._maps:
+            app, mode = {}, {}
+            sets = [self.ix.get(p) for p in set_paths] if set_paths else self.ix.of_tag("DATA-TYPE-MAPPING-SET")
+            for s in [x for x in sets if x is not None]:
+                for m in _own(s, "DATA-TYPE-MAPS"):
+                    a, i = m.child_text("APPLICATION-DATA-TYPE-REF"), m.child_text("IMPLEMENTATION-DATA-TYPE-REF")
+                    if a and i:
+                        app.setdefault(a, i)
+                for m in _own(s, "MODE-REQUEST-TYPE-MAPS"):
+                    g, i = m.child_text("MODE-GROUP-REF"), m.child_text("IMPLEMENTATION-DATA-TYPE-REF")
+                    if g and i:
+                        mode.setdefault(g, i)
+            self._maps[key] = (app, mode)
+        return self._maps[key]
+
+    def resolve(self, ref: Optional[str], maps: list, depth: int = 0) -> TypeInfo:
+        if not ref:
+            return TypeInfo("void", "unknown", note="no type reference")
+        n = self.ix.get(ref)
+        name = ref.rstrip("/").rsplit("/", 1)[-1]
+        if n is None:
+            return TypeInfo(name, "primitive" if name in PRIMITIVE_NAMES else "unknown", ref,
+                            note=f"type {ref} not found in the project ARXML")
+        if n.tag.startswith("APPLICATION-") and n.tag.endswith("-DATA-TYPE"):
+            impl = self.mapping(maps)[0].get(ref) or (self.mapping([])[0].get(ref) if maps else None)
+            if impl is None:
+                return TypeInfo(name, "unknown", ref, note=f"application data type {name} has no DataTypeMap to an "
+                                "ImplementationDataType (SWS_Rte_07069 needs one)")
+            return self.resolve(impl, maps, depth + 1)
+        cat = (n.child_text("CATEGORY") or "VALUE").upper()
+        if cat == "TYPE_REFERENCE" and depth < 8:  # redefinition: passed like what it redefines (SWS_Rte_07084)
+            inner = self.resolve(_desc_text(n, "IMPLEMENTATION-DATA-TYPE-REF"), maps, depth + 1)
+            return TypeInfo(name, inner.kind, ref, inner.base, inner.note)
+        if cat in ("STRUCTURE", "UNION"):
+            return TypeInfo(name, cat.lower() if cat == "UNION" else "struct", ref)
+        if cat == "ARRAY":
+            el = _desc(n, "IMPLEMENTATION-DATA-TYPE-ELEMENT")
+            base = None
+            if el is not None:
+                r = _desc_text(el, "IMPLEMENTATION-DATA-TYPE-REF")
+                if r:
+                    base = r.rsplit("/", 1)[-1]
+                else:
+                    b = self.ix.get(_desc_text(el, "BASE-TYPE-REF"))
+                    base = (_desc_text(b, "NATIVE-DECLARATION") or b.short_name) if b is not None else None
+            return TypeInfo(name, "array", ref, base)
+        if cat == "DATA_REFERENCE":
+            return TypeInfo(name, "pointer", ref)
+        return TypeInfo(name, "primitive", ref)
+
+    def mode_type(self, group_proto: Optional[Node], maps: list) -> TypeInfo:
+        if group_proto is None:
+            return TypeInfo("uint8", "primitive", note="mode group not found; uint8 assumed")
+        mdg = group_proto.child_text("TYPE-TREF")
+        impl = self.mapping(maps)[1].get(mdg or "") or self.mapping([])[1].get(mdg or "")
+        if impl:
+            t = self.resolve(impl, maps)
+            t.note = None
+            return t
+        return TypeInfo("uint8", "primitive", note=f"no ModeRequestTypeMap for {mdg}; the <mode> type is the "
+                        "ImplementationDataType mapped to the ModeDeclarationGroup (SWS_Rte_02632 description); uint8 assumed")
+
+
+def in_param(t: TypeInfo, name: str = "data") -> str:
+    if t.kind in ("struct", "union"):
+        return f"const {t.name}* {name}"  # SWS_Rte_01018, SWS_Rte_07086
+    if t.kind == "array":
+        return f"const {t.base or t.name}* {name}"  # SWS_Rte_05107, SWS_Rte_07086
+    return f"{t.name} {name}"  # SWS_Rte_01017 (and DATA_REFERENCE: the pointer value itself)
+
+
+def out_param(t: TypeInfo, name: str = "data") -> str:
+    if t.kind == "array":
+        return f"{t.base or t.name}* {name}"  # SWS_Rte_05108
+    return f"{t.name}* {name}"  # SWS_Rte_01019, SWS_Rte_07082, SWS_Rte_07083
+
+
+def ret_of(t: TypeInfo) -> str:
+    if t.kind in ("struct", "union"):
+        return f"const {t.name}*"  # SWS_Rte_07071, SWS_Rte_08300
+    if t.kind == "array":
+        return f"const {t.base or t.name}*"  # SWS_Rte_07072
+    return t.name  # SWS_Rte_07070, SWS_Rte_07073
+
+
+# ---------------------------------------------------------------- model
+@dataclass
+class ApiEntry:
+    name: str
+    api: str
+    ret: str
+    params: list  # [{"name", "type", "dir"}]
+    target: str  # what the API accesses: AUTOSAR path of the data element / operation / IRV / ...
+    port: Optional[str] = None
+    port_path: Optional[str] = None
+    element: Optional[str] = None
+    runnable: Optional[str] = None  # the <re> of per-runnable APIs (IRead, IrvWrite, ...)
+    type: Optional[TypeInfo] = None
+    semantics: Optional[str] = None  # data | event (S/R)
+    access: list = field(default_factory=list)  # [{"runnable", "role", "point"}]
+    any_runnable: bool = False  # Rte_Pim: every runnable of the SW-C
+    condition: Optional[str] = None  # extra configuration the API depends on
+
+    @property
+    def cite(self) -> str:
+        s, e = CITE[self.api]
+        return f"{s} (signature), {e} (existence)"
+
+    @property
+    def signature(self) -> str:
+        ps = ", ".join(p["type"] for p in self.params) or "void"
+        return f"{self.ret} {self.name}({ps})"
+
+    def allowed_for(self, runnable: str) -> bool:
+        return self.any_runnable or any(a["runnable"] == runnable for a in self.access)
+
+    @property
+    def generated(self) -> bool:
+        return self.any_runnable or bool(self.access)
+
+    def to_dict(self, brief: bool = False) -> dict:
+        d = {"name": self.name, "api": self.api, "signature": self.signature, "cite": self.cite, "target": self.target}
+        if not brief:
+            d.update({"ret": self.ret, "params": self.params})
+            for k in ("port", "element", "runnable", "semantics", "condition"):
+                if getattr(self, k) is not None:
+                    d[k] = getattr(self, k)
+            if self.type is not None:
+                d["type"] = self.type.to_dict()
+            d["access"] = self.access
+            d["generated"] = self.generated
+        return d
+
+
+@dataclass
+class Runnable:
+    name: str
+    path: str
+    symbol: str
+    file: str
+    line: int
+    events: list = field(default_factory=list)
+    points: list = field(default_factory=list)  # [{"role", "point", "port", "target"}]
+    concurrent: bool = False
+    signature: str = ""  # the runnable entry point (SWS_Rte_01126 / SWS_Rte_01166 for servers)
+    exclusive_areas: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "path": self.path, "symbol": self.symbol, "at": f"{self.file}:{self.line}",
+                "signature": self.signature, "events": self.events, "accessPoints": self.points,
+                "canBeInvokedConcurrently": self.concurrent}
+
+
+@dataclass
+class SwcModel:
+    name: str
+    path: str
+    tag: str
+    file: str
+    line: int
+    behavior: Optional[str]
+    multiple_instantiation: bool
+    ports: list
+    runnables: list
+    apis: dict  # name -> ApiEntry (every derivable API)
+    types: dict  # type name -> TypeInfo dict (data types used by the SW-C)
+    notes: list = field(default_factory=list)
+    unresolved: list = field(default_factory=list)  # access points whose reference does not resolve
+
+    def runnable(self, name_or_symbol: str) -> Optional[Runnable]:
+        for r in self.runnables:
+            if name_or_symbol in (r.name, r.symbol):
+                return r
+        return None
+
+    def allowed(self, runnable: str) -> list:
+        return [a for a in self.apis.values() if a.allowed_for(runnable)]
+
+    def generated(self) -> list:
+        return [a for a in self.apis.values() if a.generated]
+
+    def classify(self, name: str, runnable: Optional[str]) -> tuple:
+        """-> (status, entry|None, reason). status: OK | NOT-ALLOWED | INVENTED."""
+        e = self.apis.get(name)
+        if e is None:
+            return "INVENTED", None, explain_unknown(self, name)
+        if runnable is None:
+            return ("OK" if e.generated else "NOT-ALLOWED"), e, (
+                "generated for this SW-C" if e.generated else "derivable, but no runnable has the access point")
+        if e.allowed_for(runnable):
+            return "OK", e, f"{runnable} has the access point"
+        others = sorted({a["runnable"] for a in e.access})
+        return "NOT-ALLOWED", e, (f"{name} exists on {self.name} but runnable {runnable} has no "
+                                  f"{needed_role(e)} for it" + (f" (only {', '.join(others)} do)" if others else
+                                                                " (no runnable has one, so it is not generated)"))
+
+    def to_dict(self, runnable: Optional[str] = None) -> dict:
+        d = {"swc": self.name, "path": self.path, "tag": self.tag, "at": f"{self.file}:{self.line}",
+             "behavior": self.behavior, "multipleInstantiation": self.multiple_instantiation, "ports": self.ports,
+             "runnables": [r.to_dict() for r in self.runnables if runnable in (None, r.name, r.symbol)],
+             "counts": {"derivable": len(self.apis), "generated": len(self.generated())}}
+        if runnable:
+            r = self.runnable(runnable)
+            d["allowed"] = [a.to_dict() for a in self.allowed(r.name)] if r else []
+        else:
+            d["allowedByRunnable"] = {r.name: sorted(a.name for a in self.allowed(r.name)) for r in self.runnables}
+            d["apis"] = [a.to_dict() for a in sorted(self.apis.values(), key=lambda a: a.name)]
+        if self.notes:
+            d["notes"] = self.notes
+        if self.unresolved:
+            d["unresolved"] = self.unresolved
+        return d
+
+
+def needed_role(e: ApiEntry) -> str:
+    return {"Write": "dataSendPoint", "Send": "dataSendPoint", "Invalidate": "dataSendPoint",
+            "Feedback": "dataSendPoint", "Read": "dataReceivePointByArgument",
+            "Receive": "dataReceivePointByArgument", "IsUpdated": "dataReceivePointByArgument",
+            "DRead": "dataReceivePointByValue", "IRead": "dataReadAccess", "IReadRef": "dataReadAccess",
+            "IStatus": "dataReadAccess", "IWrite": "dataWriteAccess", "IWriteRef": "dataWriteAccess",
+            "IInvalidate": "dataWriteAccess", "Call": "serverCallPoint",
+            "Result": "asynchronousServerCallResultPoint", "Mode": "modeAccessPoint", "Switch": "modeSwitchPoint",
+            "SwitchAck": "modeSwitchPoint", "Prm": "parameterAccess", "CData": "parameterAccess",
+            "IrvRead": "readLocalVariable", "IrvIRead": "readLocalVariable", "IrvIReadRef": "readLocalVariable",
+            "IrvWrite": "writtenLocalVariable", "IrvIWrite": "writtenLocalVariable",
+            "IrvIWriteRef": "writtenLocalVariable", "Enter": "canEnterExclusiveArea",
+            "Exit": "canEnterExclusiveArea", "Trigger": "externalTriggeringPoint",
+            "IrTrigger": "internalTriggeringPoint"}.get(e.api, "access point")
+
+
+def split_name(name: str) -> tuple:
+    """'Rte_IWrite_Re_Port_El' -> ('IWrite', 'Re_Port_El'); unknown kinds -> (None, rest)."""
+    if not name.startswith("Rte_"):
+        return None, name
+    rest = name[4:]
+    if rest.startswith("Byps_"):
+        rest = rest[5:]
+    for k in KINDS:
+        if rest.startswith(k + "_"):
+            return k, rest[len(k) + 1:]
+    return None, rest
+
+
+def explain_unknown(m: SwcModel, name: str) -> str:
+    kind, rest = split_name(name)
+    if kind is None:
+        return f"{name} is not an RTE API name pattern of SWS_RTE 5.6 (Rte_<Write|Read|Call|...>_...)"
+    if kind in PER_RUNNABLE:
+        re_names = [r.name for r in m.runnables if rest.startswith(r.name + "_") or rest == r.name]
+        if not re_names:
+            return (f"{name}: Rte_{kind} names the runnable first (Rte_{kind}_<re>_...); no runnable of {m.name} "
+                    f"prefixes '{rest}' (runnables: {', '.join(r.name for r in m.runnables)})")
+        rest = rest[len(max(re_names, key=len)) + 1:]
+    if kind in ("Pim", "CData", "Enter", "Exit") or kind.startswith("Irv") or kind == "IrTrigger":
+        return f"{name}: {m.name} declares no {kind} target named '{rest}'"
+    ports = [p for p in m.ports if rest.startswith(p["name"] + "_")]
+    if not ports:
+        return f"{name}: {m.name} has no port that prefixes '{rest}' (ports: {', '.join(p['name'] for p in m.ports)})"
+    p = max(ports, key=lambda x: len(x["name"]))
+    el = rest[len(p["name"]) + 1:]
+    els = [e["name"] for e in p["elements"]]
+    if el not in els:
+        return f"{name}: interface {p['interface']} of port {p['name']} has no element '{el}' (has: {', '.join(els)})"
+    e = next(e for e in p["elements"] if e["name"] == el)
+    return (f"{name}: Rte_{kind} does not apply to {p['direction']}-port {p['name']} element {el} "
+            f"({p['interfaceKind']}{', ' + e['semantics'] + ' semantics' if e.get('semantics') else ''}"
+            f"{'; ' + e['needs'] if e.get('needs') and kind in ('Invalidate', 'IInvalidate', 'IsUpdated') else ''})")
+
+
+class Builder:
+    def __init__(self, ix: ArIndex, types: Types):
+        self.ix, self.t = ix, types
+
+    def rel(self, f: Optional[str]) -> str:
+        if not f:
+            return "?"
+        r = os.path.relpath(f, self.ix.root)
+        return f if r.startswith("..") else r
+
+    def build(self, swc: Node) -> SwcModel:
+        ix = self.ix
+        spath = ix.path(swc)
+        f, line = ix.where(swc)
+        ib = next(iter(_own(swc, "INTERNAL-BEHAVIORS")), None)
+        maps = [r.text.strip() for r in (ib.child("DATA-TYPE-MAPPING-REFS").children if ib is not None and
+                                         ib.child("DATA-TYPE-MAPPING-REFS") is not None else [])]
+        multi = (ib.child_text("SUPPORTS-MULTIPLE-INSTANTIATION") or "").lower() == "true" if ib is not None else False
+        m = SwcModel(swc.short_name, spath, swc.tag, self.rel(f), line, ix.path(ib) if ib is not None else None,
+                     multi, [], [], {}, {})
+        self.m, self.maps = m, maps
+        inst = [{"name": "self", "type": "Rte_Instance self", "dir": "IN"}] if multi else []
+        self.inst = inst
+
+        # ---- ports and everything derivable from them
+        for p in _own(swc, "PORTS"):
+            direction = {"P-PORT-PROTOTYPE": "P", "R-PORT-PROTOTYPE": "R", "PR-PORT-PROTOTYPE": "PR"}.get(p.tag)
+            if direction is None:
+                continue
+            iref = p.child_text("PROVIDED-INTERFACE-TREF") or p.child_text("REQUIRED-INTERFACE-TREF") or \
+                p.child_text("PROVIDED-REQUIRED-INTERFACE-TREF")
+            itf = ix.get(iref)
+            port = {"name": p.short_name, "path": ix.path(p), "direction": direction, "interface": iref,
+                    "interfaceKind": itf.tag if itf is not None else "?", "elements": [],
+                    "at": f"{self.rel(ix.where(p)[0])}:{p.line}"}
+            m.ports.append(port)
+            if itf is None:
+                m.notes.append(f"port {p.short_name}: interface {iref} not found in the project ARXML")
+                continue
+            self.port_apis(p, port, itf, direction)
+
+        # ---- internal behaviour: IRVs, PIM, internal parameters, exclusive areas
+        irvs = {}
+        if ib is not None:
+            for coll, kind in (("EXPLICIT-INTER-RUNNABLE-VARIABLES", "explicit"),
+                               ("IMPLICIT-INTER-RUNNABLE-VARIABLES", "implicit")):
+                for v in _own(ib, coll):
+                    irvs[ix.path(v)] = (v, kind)
+            for pim in _own(ib, "PER-INSTANCE-MEMORYS"):
+                tname = pim.child_text("TYPE") or "void"
+                self.add(ApiEntry(f"Rte_Pim_{pim.short_name}", "Pim", f"{tname}*", list(inst), ix.path(pim),
+                                  type=TypeInfo(tname, "unknown"), any_runnable=True))
+            for pim in _own(ib, "AR-TYPED-PER-INSTANCE-MEMORYS"):
+                t = self.t.resolve(pim.child_text("TYPE-TREF"), maps)
+                self.add(ApiEntry(f"Rte_Pim_{pim.short_name}", "Pim", f"{t.name}*", list(inst), ix.path(pim),
+                                  type=t, any_runnable=True))
+            for coll in ("PER-INSTANCE-PARAMETERS", "SHARED-PARAMETERS"):
+                for prm in _own(ib, coll):
+                    t = self.t.resolve(prm.child_text("TYPE-TREF"), maps)
+                    self.add(ApiEntry(f"Rte_CData_{prm.short_name}", "CData", ret_of(t), list(inst), ix.path(prm),
+                                      element=prm.short_name, type=t))
+            for ea in _own(ib, "EXCLUSIVE-AREAS"):
+                for k in ("Enter", "Exit"):
+                    self.add(ApiEntry(f"Rte_{k}_{ea.short_name}", k, "void", list(inst), ix.path(ea),
+                                      element=ea.short_name))
+
+        # ---- runnables, events and their access points
+        events: dict = {}
+        if ib is not None:
+            for ev in _own(ib, "EVENTS"):
+                tgt = ev.child_text("START-ON-EVENT-REF")
+                if tgt:
+                    d = {"event": ev.short_name, "kind": ev.tag}
+                    if ev.child_text("PERIOD"):
+                        d["period"] = ev.child_text("PERIOD")
+                    trig = _ref_ending(ev, "TARGET-DATA-ELEMENT-REF", "TARGET-PROVIDED-OPERATION-REF",
+                                       "TARGET-MODE-DECLARATION-REF", "TARGET-REQUIRED-OPERATION-REF", "TARGET-TRIGGER-REF")
+                    port_ref = _ref_ending(ev, "PORT-REF")
+                    if trig:
+                        d["target"] = trig
+                    if port_ref:
+                        d["port"] = port_ref.rsplit("/", 1)[-1]
+                    events.setdefault(tgt, []).append(d)
+        for r in (_own(ib, "RUNNABLES") if ib is not None else []):
+            rp = ix.path(r)
+            run = Runnable(r.short_name, rp, r.child_text("SYMBOL") or r.short_name, self.rel(ix.where(r)[0]), r.line,
+                           events.get(rp, []),
+                           concurrent=(r.child_text("CAN-BE-INVOKED-CONCURRENTLY") or "").lower() == "true")
+            run.signature = self.entry_signature(run, inst)
+            m.runnables.append(run)
+            for coll in ROLE:
+                for ap in _own(r, coll):
+                    self.access_point(run, coll, ap, irvs)
+            eas = r.child("CAN-ENTER-EXCLUSIVE-AREA-REFS")
+            for ref in (eas.children if eas is not None else []):
+                ea = ref.text.strip()
+                run.exclusive_areas.append(ea)
+                for k in ("Enter", "Exit"):
+                    e = self.m.apis.get(f"Rte_{k}_{ea.rsplit('/', 1)[-1]}")
+                    if e is not None:
+                        e.access.append({"runnable": run.name, "role": "canEnterExclusiveArea", "point": ea})
+        # per-runnable IRV APIs that exist for every runnable but are allowed only with an access point
+        for run in m.runnables:
+            for vp, (v, kind) in irvs.items():
+                t = self.t.resolve(v.child_text("TYPE-TREF"), maps)
+                self.irv_apis(run.name, v.short_name, vp, t, kind)
+        for r in m.runnables:
+            for pt in r.points:
+                if pt.get("unresolved"):
+                    m.unresolved.append({"runnable": r.name, **pt})
+        for e in m.apis.values():
+            if e.type is not None and e.type.name not in m.types:
+                m.types[e.type.name] = e.type.to_dict()
+        return m
+
+    # -- helpers
+    def add(self, e: ApiEntry) -> ApiEntry:
+        if e.name in self.m.apis:
+            return self.m.apis[e.name]
+        self.m.apis[e.name] = e
+        return e
+
+    def entry_signature(self, run: Runnable, inst: list) -> str:
+        """Runnable entry point: void <symbol>([Rte_Instance]) (SWS_Rte_01126); a server runnable returns
+        Std_ReturnType and takes the operation's arguments (SWS_Rte_01166)."""
+        for ev in run.events:
+            if ev["kind"] == "OPERATION-INVOKED-EVENT":
+                op = self.ix.get(ev.get("target"))
+                if op is not None:
+                    args = [p["type"] for p in self.op_args(op, ("IN", "INOUT", "OUT"))]
+                    ps = ", ".join([x["type"] for x in inst] + args) or "void"
+                    return f"Std_ReturnType {run.symbol}({ps})"
+        return f"void {run.symbol}({'Rte_Instance self' if inst else 'void'})"
+
+    def op_args(self, op: Node, dirs: tuple) -> list:
+        out = []
+        for a in _own(op, "ARGUMENTS"):
+            d = (a.child_text("DIRECTION") or "IN").upper()
+            if d not in dirs:
+                continue
+            t = self.t.resolve(a.child_text("TYPE-TREF"), self.maps)
+            typ = in_param(t, a.short_name) if d == "IN" else out_param(t, a.short_name)
+            out.append({"name": a.short_name, "type": typ, "dir": d})
+        return out
+
+    def port_apis(self, p: Node, port: dict, itf: Node, direction: str):
+        ix, inst, maps = self.ix, self.inst, self.maps
+        pname, ppath = p.short_name, ix.path(p)
+        prov, req = direction in ("P", "PR"), direction in ("R", "PR")
+        kind = itf.tag
+        if kind in ("SENDER-RECEIVER-INTERFACE", "NV-DATA-INTERFACE"):
+            inv = {}
+            for ip in _own(itf, "INVALIDATION-POLICYS"):
+                inv[ip.child_text("DATA-ELEMENT-REF") or ""] = (ip.child_text("HANDLE-INVALID") or "").upper()
+            ack = any(_desc(cs, "TRANSMISSION-ACKNOWLEDGE") is not None for cs in _own(p, "PROVIDED-COM-SPECS"))
+            for el in _own(itf, "DATA-ELEMENTS") + _own(itf, "NV-DATAS"):
+                ep = ix.path(el)
+                t = self.t.resolve(el.child_text("TYPE-TREF"), maps)
+                queued = (_desc_text(el, "SW-IMPL-POLICY") or "").upper() == "QUEUED"
+                sem = "event" if queued else "data"
+                invalid = inv.get(ep, "") in INVALIDATING
+                upd = self.rcv_comspec(p, ep, "ENABLE-UPDATE") == "true"
+                status = any(self.rcv_comspec(p, ep, k) not in (None, "", "0", "false", "none", "NONE")
+                             for k in ("ALIVE-TIMEOUT", "HANDLE-NEVER-RECEIVED", "HANDLE-OUT-OF-RANGE",
+                                       "HANDLE-DATA-STATUS")) or invalid
+                needs = []
+                port["elements"].append({"name": el.short_name, "path": ep, "type": t.name, "semantics": sem})
+                common = dict(port=pname, port_path=ppath, element=el.short_name, type=t, semantics=sem, target=ep)
+                if prov:
+                    if queued:
+                        self.add(ApiEntry(f"Rte_Send_{pname}_{el.short_name}", "Send", "Std_ReturnType",
+                                          inst + [{"name": "data", "type": in_param(t), "dir": "IN"}], **common))
+                    else:
+                        self.add(ApiEntry(f"Rte_Write_{pname}_{el.short_name}", "Write", "Std_ReturnType",
+                                          inst + [{"name": "data", "type": in_param(t), "dir": "IN"}], **common))
+                        if invalid:
+                            self.add(ApiEntry(f"Rte_Invalidate_{pname}_{el.short_name}", "Invalidate",
+                                              "Std_ReturnType", list(inst), condition="InvalidationPolicy", **common))
+                        else:
+                            needs.append("Rte_Invalidate/IInvalidate need an InvalidationPolicy keep/replace")
+                    if ack:
+                        self.add(ApiEntry(f"Rte_Feedback_{pname}_{el.short_name}", "Feedback", "Std_ReturnType",
+                                          list(inst), condition="TransmissionAcknowledgementRequest", **common))
+                if req:
+                    if queued:
+                        self.add(ApiEntry(f"Rte_Receive_{pname}_{el.short_name}", "Receive", "Std_ReturnType",
+                                          inst + [{"name": "data", "type": out_param(t), "dir": "OUT"}], **common))
+                    else:
+                        self.add(ApiEntry(f"Rte_Read_{pname}_{el.short_name}", "Read", "Std_ReturnType",
+                                          inst + [{"name": "data", "type": out_param(t), "dir": "OUT"}], **common))
+                        if t.kind in ("primitive", "unknown", "pointer"):  # SWS_Rte_07395: primitive types only
+                            self.add(ApiEntry(f"Rte_DRead_{pname}_{el.short_name}", "DRead", t.name, list(inst),
+                                              **common))
+                        if upd:
+                            self.add(ApiEntry(f"Rte_IsUpdated_{pname}_{el.short_name}", "IsUpdated", "boolean",
+                                              list(inst), condition="enableUpdate", **common))
+                        else:
+                            needs.append("Rte_IsUpdated needs enableUpdate in the NonqueuedReceiverComSpec")
+                port["elements"][-1]["_flags"] = {"invalid": invalid, "status": status, "queued": queued, "t": t}
+                if needs:
+                    port["elements"][-1]["needs"] = "; ".join(needs)
+        elif kind == "CLIENT-SERVER-INTERFACE":
+            for op in _own(itf, "OPERATIONS"):
+                port["elements"].append({"name": op.short_name, "path": ix.path(op), "kind": "operation"})
+                if req:  # sync signature; the async variant replaces it when an async call point is found
+                    self.add(ApiEntry(f"Rte_Call_{pname}_{op.short_name}", "Call", "Std_ReturnType",
+                                      inst + self.op_args(op, ("IN", "INOUT", "OUT")), ix.path(op), port=pname,
+                                      port_path=ppath, element=op.short_name))
+        elif kind == "MODE-SWITCH-INTERFACE":
+            # the ModeDeclarationGroupPrototype is serialised under its role name <MODE-GROUP>
+            for mg in [c for c in itf.children if c.tag in ("MODE-GROUP", "MODE-DECLARATION-GROUP-PROTOTYPE")]:
+                t = self.t.mode_type(mg, maps)
+                port["elements"].append({"name": mg.short_name, "path": ix.path(mg), "kind": "modeGroup", "type": t.name})
+                common = dict(port=pname, port_path=ppath, element=mg.short_name, type=t, target=ix.path(mg))
+                self.add(ApiEntry(f"Rte_Mode_{pname}_{mg.short_name}", "Mode", t.name, list(inst), **common))
+                if prov:
+                    self.add(ApiEntry(f"Rte_Switch_{pname}_{mg.short_name}", "Switch", "Std_ReturnType",
+                                      inst + [{"name": "mode", "type": f"{t.name} mode", "dir": "IN"}], **common))
+                    if any(_desc(cs, "MODE-SWITCHED-ACK") is not None for cs in _own(p, "PROVIDED-COM-SPECS")):
+                        self.add(ApiEntry(f"Rte_SwitchAck_{pname}_{mg.short_name}", "SwitchAck", "Std_ReturnType",
+                                          list(inst), condition="ModeSwitchedAckRequest", **common))
+        elif kind == "PARAMETER-INTERFACE":
+            for prm in _own(itf, "PARAMETERS"):
+                t = self.t.resolve(prm.child_text("TYPE-TREF"), maps)
+                port["elements"].append({"name": prm.short_name, "path": ix.path(prm), "kind": "parameter", "type": t.name})
+                if req:
+                    self.add(ApiEntry(f"Rte_Prm_{pname}_{prm.short_name}", "Prm", ret_of(t), list(inst), ix.path(prm),
+                                      port=pname, port_path=ppath, element=prm.short_name, type=t))
+        elif kind == "TRIGGER-INTERFACE":
+            for tr in _own(itf, "TRIGGERS"):
+                port["elements"].append({"name": tr.short_name, "path": ix.path(tr), "kind": "trigger"})
+                if prov:
+                    self.add(ApiEntry(f"Rte_Trigger_{pname}_{tr.short_name}", "Trigger", "Std_ReturnType", list(inst),
+                                      ix.path(tr), port=pname, port_path=ppath, element=tr.short_name))
+
+    def rcv_comspec(self, p: Node, elem_path: str, tag: str) -> Optional[str]:
+        for cs in _own(p, "REQUIRED-COM-SPECS"):
+            if (cs.child_text("DATA-ELEMENT-REF") or "") == elem_path:
+                v = cs.child_text(tag)
+                if v is not None:
+                    return v.lower()
+        return None
+
+    def per_runnable_sr(self, run: str, port: dict, el: dict):
+        """Implicit APIs for one runnable / port / element (names carry the runnable)."""
+        f = el.get("_flags")
+        if not f or f["queued"]:
+            return
+        t, inst = f["t"], self.inst
+        pn, en = port["name"], el["name"]
+        common = dict(port=pn, port_path=port["path"], element=en, type=t, semantics="data", target=el["path"],
+                      runnable=run)
+        if port["direction"] in ("R", "PR"):
+            self.add(ApiEntry(f"Rte_IRead_{run}_{pn}_{en}", "IRead", ret_of(t), list(inst), **common))
+            self.add(ApiEntry(f"Rte_IReadRef_{run}_{pn}_{en}", "IReadRef", f"const {t.base or t.name}*"
+                              if t.kind == "array" else f"const {t.name}*", list(inst), **common))
+            if f["status"]:
+                self.add(ApiEntry(f"Rte_IStatus_{run}_{pn}_{en}", "IStatus", "Std_ReturnType", list(inst),
+                                  condition="data element status (aliveTimeout/handleNeverReceived/...)", **common))
+        if port["direction"] in ("P", "PR"):
+            self.add(ApiEntry(f"Rte_IWrite_{run}_{pn}_{en}", "IWrite", "void",
+                              inst + [{"name": "data", "type": in_param(t), "dir": "IN"}], **common))
+            self.add(ApiEntry(f"Rte_IWriteRef_{run}_{pn}_{en}", "IWriteRef", f"{t.base or t.name}*"
+                              if t.kind == "array" else f"{t.name}*", list(inst), **common))
+            if f["invalid"]:
+                self.add(ApiEntry(f"Rte_IInvalidate_{run}_{pn}_{en}", "IInvalidate", "void", list(inst),
+                                  condition="InvalidationPolicy", **common))
+
+    def irv_apis(self, run: str, name: str, vpath: str, t: TypeInfo, kind: str):
+        inst = self.inst
+        common = dict(element=name, type=t, target=vpath, runnable=run)
+        if kind == "explicit":
+            if t.kind in ("struct", "union", "array"):  # complex type signature (SWS_Rte_03560)
+                self.add(ApiEntry(f"Rte_IrvRead_{run}_{name}", "IrvRead", "void",
+                                  inst + [{"name": "data", "type": out_param(t), "dir": "OUT"}], **common))
+            else:
+                self.add(ApiEntry(f"Rte_IrvRead_{run}_{name}", "IrvRead", t.name, list(inst), **common))
+            self.add(ApiEntry(f"Rte_IrvWrite_{run}_{name}", "IrvWrite", "void",
+                              inst + [{"name": "data", "type": in_param(t), "dir": "IN"}], **common))
+        else:
+            self.add(ApiEntry(f"Rte_IrvIRead_{run}_{name}", "IrvIRead", ret_of(t), list(inst), **common))
+            self.add(ApiEntry(f"Rte_IrvIReadRef_{run}_{name}", "IrvIReadRef", f"const {t.base or t.name}*"
+                              if t.kind == "array" else f"const {t.name}*", list(inst), **common))
+            self.add(ApiEntry(f"Rte_IrvIWrite_{run}_{name}", "IrvIWrite", "void",
+                              inst + [{"name": "data", "type": in_param(t), "dir": "IN"}], **common))
+            self.add(ApiEntry(f"Rte_IrvIWriteRef_{run}_{name}", "IrvIWriteRef", f"{t.base or t.name}*"
+                              if t.kind == "array" else f"{t.name}*", list(inst), **common))
+
+    def access_point(self, run: Runnable, coll: str, ap: Node, irvs: dict):
+        ix, m = self.ix, self.m
+        role = ROLE[coll]
+        point = ix.path(ap)
+        rec = {"role": role, "point": point}
+        grant = lambda name: (m.apis[name].access.append({"runnable": run.name, "role": role, "point": point})  # noqa: E731
+                              if name in m.apis else None)
+        if coll in ("READ-LOCAL-VARIABLES", "WRITTEN-LOCAL-VARIABLES"):
+            vref = _ref_ending(ap, "LOCAL-VARIABLE-REF")
+            rec["target"] = vref
+            run.points.append(rec)
+            hit = irvs.get(vref or "")
+            if hit is None:
+                rec["unresolved"] = f"inter-runnable variable {vref} not declared in the behaviour"
+                return
+            v, kind = hit
+            t = self.t.resolve(v.child_text("TYPE-TREF"), self.maps)
+            self.irv_apis(run.name, v.short_name, vref, t, kind)
+            names = (["IrvRead"] if kind == "explicit" else ["IrvIRead", "IrvIReadRef"]) if coll.startswith("READ") else \
+                (["IrvWrite"] if kind == "explicit" else ["IrvIWrite", "IrvIWriteRef"])
+            for k in names:
+                grant(f"Rte_{k}_{run.name}_{v.short_name}")
+            return
+        if coll == "PARAMETER-ACCESSS":
+            local = _ref_ending(ap, "LOCAL-PARAMETER-REF")
+            if local:
+                rec["target"] = local
+                run.points.append(rec)
+                name = f"Rte_CData_{local.rsplit('/', 1)[-1]}"
+                if name not in m.apis:
+                    rec["unresolved"] = f"internal parameter {local} not declared"
+                grant(name)
+                return
+        if coll == "INTERNAL-TRIGGERING-POINTS":
+            rec["target"] = point
+            run.points.append(rec)
+            self.add(ApiEntry(f"Rte_IrTrigger_{run.name}_{ap.short_name}", "IrTrigger", "void", list(self.inst), point,
+                              element=ap.short_name, runnable=run.name))
+            grant(f"Rte_IrTrigger_{run.name}_{ap.short_name}")
+            return
+        if coll == "ASYNCHRONOUS-SERVER-CALL-RESULT-POINTS":
+            call = ix.get(ap.child_text("ASYNCHRONOUS-SERVER-CALL-POINT-REF"))
+            if call is None:
+                rec["unresolved"] = "ASYNCHRONOUS-SERVER-CALL-POINT-REF does not resolve"
+                run.points.append(rec)
+                return
+            ap = call  # the result point inherits port/operation from its call point
+        port_ref = _ref_ending(ap, "PORT-REF", "PORT-PROTOTYPE-REF")
+        tgt = _ref_ending(ap, "TARGET-DATA-PROTOTYPE-REF", "TARGET-REQUIRED-OPERATION-REF", "TARGET-MODE-GROUP-REF",
+                          "TARGET-TRIGGER-REF", "TARGET-DATA-ELEMENT-REF", "TARGET-PROVIDED-OPERATION-REF")
+        rec.update({"port": (port_ref or "").rsplit("/", 1)[-1] or None, "target": tgt})
+        run.points.append(rec)
+        port = next((p for p in m.ports if p["path"] == port_ref), None)
+        if port is None:
+            rec["unresolved"] = f"port {port_ref} is not a port of {m.name}"
+            return
+        el = next((e for e in port["elements"] if e["path"] == tgt), None)
+        if el is None:
+            rec["unresolved"] = f"{tgt} is not an element of {port['interface']}"
+            return
+        pn, en = port["name"], el["name"]
+        if coll in ("DATA-READ-ACCESSS", "DATA-WRITE-ACCESSS"):
+            self.per_runnable_sr(run.name, port, el)
+            kinds = ["IRead", "IReadRef", "IStatus"] if coll == "DATA-READ-ACCESSS" else ["IWrite", "IWriteRef", "IInvalidate"]
+            for k in kinds:
+                grant(f"Rte_{k}_{run.name}_{pn}_{en}")
+            return
+        kinds = {"DATA-SEND-POINTS": ["Write", "Send", "Invalidate", "Feedback"],
+                 "DATA-RECEIVE-POINT-BY-ARGUMENTS": ["Read", "Receive", "IsUpdated"],
+                 "DATA-RECEIVE-POINT-BY-VALUES": ["DRead", "IsUpdated"],
+                 "SERVER-CALL-POINTS": ["Call"], "ASYNCHRONOUS-SERVER-CALL-RESULT-POINTS": ["Result"],
+                 "MODE-ACCESS-POINTS": ["Mode"], "MODE-SWITCH-POINTS": ["Switch", "SwitchAck"],
+                 "PARAMETER-ACCESSS": ["Prm"], "EXTERNAL-TRIGGERING-POINTS": ["Trigger"]}[coll]
+        if coll == "SERVER-CALL-POINTS" and ap.tag == "ASYNCHRONOUS-SERVER-CALL-POINT":
+            op = ix.get(tgt)
+            call = m.apis.get(f"Rte_Call_{pn}_{en}")
+            if call is not None and op is not None:  # async: Call carries IN/INOUT, Result the OUT/INOUT
+                call.params = self.inst + self.op_args(op, ("IN", "INOUT"))
+                call.condition = "asynchronous"
+                self.add(ApiEntry(f"Rte_Result_{pn}_{en}", "Result", "Std_ReturnType",
+                                  self.inst + self.op_args(op, ("INOUT", "OUT")), tgt, port=pn, port_path=port["path"],
+                                  element=en, condition="asynchronous"))
+        for k in kinds:
+            grant(f"Rte_{k}_{pn}_{en}")
+
+
+# ---------------------------------------------------------------- entry points
+def build_all(root: str, ix: Optional[ArIndex] = None) -> list:
+    ix = ix or ArIndex(root)
+    b = Builder(ix, Types(ix))
+    out = []
+    for n in ix.of_tag(*SWC_TAGS):
+        out.append(b.build(n))
+    # derivable per-runnable implicit S/R APIs (names include the runnable): add after runnables are known
+    for m in out:
+        b.m, b.inst = m, ([{"name": "self", "type": "Rte_Instance self", "dir": "IN"}] if m.multiple_instantiation else [])
+        for r in m.runnables:
+            for p in m.ports:
+                for el in p["elements"]:
+                    b.per_runnable_sr(r.name, p, el)
+        for p in m.ports:
+            for el in p["elements"]:
+                el.pop("_flags", None)
+    return out
+
+
+def find_swc(models: list, name: Optional[str]) -> Optional[SwcModel]:
+    if not name:
+        return None
+    for m in models:
+        if name in (m.name, m.path):
+            return m
+    low = name.lower()
+    hits = [m for m in models if m.name.lower() == low]
+    return hits[0] if len(hits) == 1 else None
+
+
+RTE_DECL = re.compile(r"\b(Rte_\w+)\s*\(")
+
+
+def header_entries(files: list) -> dict:
+    """Rte_* macros and function prototypes declared in the given headers -> {name: {form, text, file, line}}."""
+    from .audit import parse_defines, strip_comments
+    out: dict = {}
+    for name, (params, body, f, line) in parse_defines(files).items():
+        if name.startswith("Rte_") and params is not None:
+            out.setdefault(name, {"form": "macro", "text": f"#define {name}({', '.join(params)}) {body}".strip(),
+                                  "file": f, "line": line})
+    for f in files:
+        try:
+            raw = open(f, encoding="utf-8", errors="replace").read()
+        except OSError:
+            continue
+        from .csrc import _blank_preproc
+        text = _blank_preproc(strip_comments(raw))
+        for st in re.finditer(r"[^;{}#]*?\b(Rte_\w+)\s*\([^;{}]*\)\s*;", text):
+            name = st.group(1)
+            ls = text.rfind("\n", 0, st.start(1)) + 1
+            if text[ls:st.start(1)].lstrip().startswith("#") or name in out:
+                continue
+            decl = " ".join(text[st.start():st.end()].split())
+            if re.match(r"^(?:return\b|\(void\))", decl) or "=" in decl.split(name)[0]:
+                continue
+            out[name] = {"form": "function", "text": decl, "file": f, "line": text.count("\n", 0, st.start(1)) + 1}
+    return out
+
+
+def find_header(root: str, swc: str, c_files: Optional[list] = None) -> Optional[str]:
+    want = f"rte_{swc}.h".lower()
+    files = c_files if c_files is not None else paths.walk(root, paths.is_c).files
+    hits = sorted(f for f in files if os.path.basename(f).lower() == want)
+    return hits[0] if hits else None
+
+
+def match_header(m: SwcModel, header: Optional[str], rel=lambda f: f) -> dict:
+    """Optional second step: match each generated API to its declaration/macro in Rte_<Swc>.h."""
+    if not header:
+        return {"header": None, "note": f"no Rte_{m.name}.h in the project; nothing to match"}
+    decl = header_entries([header])
+    gen = {a.name for a in m.generated()}
+    matched = {}
+    for a in sorted(m.apis.values(), key=lambda x: x.name):
+        d = decl.get(a.name)
+        if d:
+            matched[a.name] = {"form": d["form"], "text": d["text"], "at": f"{rel(d['file'])}:{d['line']}"}
+    missing = sorted(gen - set(decl))
+    extra = []
+    for name in sorted(set(decl) - gen):
+        e = m.apis.get(name)
+        extra.append({"name": name, "at": f"{rel(decl[name]['file'])}:{decl[name]['line']}",
+                      "why": "derivable but no runnable has the access point" if e is not None
+                      else explain_unknown(m, name)})
+    symbols = {}
+    try:
+        text = open(header, encoding="utf-8", errors="replace").read()
+    except OSError:
+        text = ""
+    for r in m.runnables:
+        mm = re.search(rf"^[^\n#]*\b{re.escape(r.symbol)}\s*\([^)]*\)\s*;", text, re.M)
+        symbols[r.name] = mm.group(0).strip() if mm else None
+    return {"header": rel(header), "matched": matched, "missing": missing, "extra": extra,
+            "runnablePrototypes": symbols,
+            "counts": {"generatedExpected": len(gen), "declared": len([n for n in decl if n in gen]),
+                       "missing": len(missing), "extra": len(extra)}}
+
+
+def rte_api(root: str, swc: Optional[str] = None, runnable: Optional[str] = None, header: bool = True) -> dict:
+    ix = ArIndex(root)
+    models = build_all(root, ix)
+    rel = lambda f: os.path.relpath(f, root) if not os.path.relpath(f, root).startswith("..") else f  # noqa: E731
+    if swc:
+        m = find_swc(models, swc)
+        if m is None:
+            return {"error": f"no SW-COMPONENT-TYPE {swc!r}; known: {', '.join(x.name for x in models)}"}
+        models = [m]
+        if runnable and m.runnable(runnable) is None:
+            return {"error": f"{m.name} has no runnable {runnable!r}; runnables: {', '.join(r.name for r in m.runnables)}"}
+    cfiles = paths.walk(root, paths.is_c).files if header else []
+    out = []
+    for m in models:
+        d = m.to_dict(runnable)
+        if header:
+            d["header"] = match_header(m, find_header(root, m.name, cfiles), rel)
+        out.append(d)
+    return {"swcs": out, "summary": {"swcs": len(out), "runnables": sum(len(x["runnables"]) for x in out),
+                                     "derivable": sum(x["counts"]["derivable"] for x in out),
+                                     "generated": sum(x["counts"]["generated"] for x in out)}}