@h2loop/autosar 0.1.2 → 1.1.0

package/python/ecuc_engine/codegen/emit.py

@@ -0,0 +1,395 @@
+"""The shared BSW emitter: one ModuleOutput per module, rendered into the standard file set.
+
+File placement follows each parameter's effective config class for the module's
+IMPLEMENTATION-CONFIG-VARIANT (from the param defs' VALUE-CONFIG-CLASSES):
+  PRE-COMPILE / PUBLISHED-INFORMATION scalars -> #defines in <Mip>_Cfg.h
+  tables whose fields are all pre-compile     -> <Mip>_Cfg.c      (SWS_BSW_00103 Table 5.1)
+  tables with a link-time field               -> <Mip>_Lcfg.c     (SWS_BSW_00013)
+  tables with a post-build field              -> <Mip>_PBcfg.c    (SWS_BSW_00015)
+Everything generic is driven by the defs: scalars of singleton containers become macros, every
+symbolicNameValue parameter a TPS_ECUC_02108 symbol, every multiplicity-n container a const table.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .. import ENGINE_VERSION
+from .. import defs as D
+from . import cwriter as W
+from .model import CLASS_FILE, CLASS_RANK, CgModel, Container, ModuleCfg, snake
+
+
+@dataclass
+class Ctx:
+    cg: CgModel
+    headers: dict  # project header basename -> path (static code, excluding the output dir)
+    bindings: dict
+    binding_name: Optional[str]
+    release: tuple
+    sources: list = field(default_factory=list)  # project .c/.h files (static + in-house), for SchM scans
+    generating: set = field(default_factory=set)  # module names generated in this run
+    available: set = field(default_factory=set)  # header basenames reachable by the build (incl. the output dir)
+
+    def xsym(self, c: Container, here: ModuleCfg, used: set) -> str:
+        """Symbol of a container for use in module `here`: the TPS_ECUC_02108 name when its provider header
+        (<Mip>_Cfg.h) is generated now or already exists, else the configured value (named in a comment)."""
+        sym = self.cg.symbol(c)
+        if c.module is here:
+            return sym
+        if c.module.name in self.generating or f"{c.module.mip}_Cfg.h" in self.available:
+            used.add(c.module.mip)
+            return sym
+        from ..values import parse_int
+        v = parse_int(self.cg.symbol_value(c) or "")
+        return f"{W.c_uint(v)} /* {sym} */" if v is not None else sym
+
+
+class ModuleOutput:
+    def __init__(self, ctx: Ctx, mc: ModuleCfg):
+        self.ctx = ctx
+        self.mc = mc
+        self.mip = mc.mip
+        self.MIP = mc.MIP
+        self.groups: list = []  # (title, [define lines])
+        self.types: list = []
+        self.hdecls: list = []
+        self.h_includes: list = []
+        self.tables: dict = {}  # rank -> [text]
+        self.c_externs: dict = {}  # rank -> [text]
+        self.c_includes: list = []
+        self.used_mips: set = set()
+        self.defined: set = set()
+        self.notes: list = []
+        self.extra_files: dict = {}  # name -> text (module-specific additional files)
+        self.symbols: list = []  # (name, value, container path)
+
+    # ---------- collection ----------
+    def group(self, title: str, defs: list):
+        lines = []
+        for d in defs:
+            name = d[0]
+            if name in self.defined:
+                self.notes.append(f"duplicate #define {name} suppressed ({title})")
+                continue
+            self.defined.add(name)
+            lines.append(W.define(*d))
+        if lines:
+            self.groups.append((title, lines))
+
+    def table(self, rank: int, text: str, externs: Optional[list] = None):
+        rank = max(rank, 1)
+        self.tables.setdefault(rank, []).append(text)
+        for e in externs or []:
+            lst = self.c_externs.setdefault(rank, [])
+            if e not in lst:
+                lst.append(e)
+
+    def include(self, h: str):
+        if h not in self.c_includes:
+            self.c_includes.append(h)
+
+    # ---------- rendering ----------
+    def digest(self) -> str:
+        h = hashlib.sha256(ENGINE_VERSION.encode())
+        for f in sorted({f.file for c in self.mc.containers for f in c.frags} | {self.mc.elem.file}):
+            h.update(self.ctx.cg.p.files[f].data)
+        for f in sorted(self.ctx.cg.defs.files):
+            h.update(f.rsplit("/", 1)[-1].encode())
+        return "sha256:" + h.hexdigest()[:16]
+
+    def _banner(self, name: str) -> str:
+        return W.banner(name, self.mc.name, self.mc.variant, self.ctx.release, self.ctx.cg.rel_files(self.mc),
+                        self._digest)
+
+    def render(self) -> dict:
+        self._digest = self.digest()
+        out = {}
+        hname = f"{self.mip}_Cfg.h"
+        g = W.guard(hname)
+        parts = [self._banner(hname), "", f"#ifndef {g}", f"#define {g}", ""]
+        for inc in self.h_includes:
+            parts.append(f'#include "{inc}"')
+        maj, mnr, rev = self.ctx.release
+        sw = [int(x) if x.isdigit() else 0 for x in ENGINE_VERSION.split("-")[0].split(".")][:3]
+        ver = [(f"{self.MIP}_CFG_AR_RELEASE_MAJOR_VERSION", f"{maj}u"),
+               (f"{self.MIP}_CFG_AR_RELEASE_MINOR_VERSION", f"{mnr}u"),
+               (f"{self.MIP}_CFG_AR_RELEASE_REVISION_VERSION", f"{rev}u"),
+               (f"{self.MIP}_CFG_SW_MAJOR_VERSION", f"{sw[0]}u"),
+               (f"{self.MIP}_CFG_SW_MINOR_VERSION", f"{sw[1]}u"),
+               (f"{self.MIP}_CFG_SW_PATCH_VERSION", f"{sw[2]}u")]
+        parts += ["", "/* Published information of this generated configuration (SWS_BSW_00059) */"]
+        parts += [W.define(n, v) for n, v in ver]
+        for title, lines in self.groups:
+            parts += ["", f"/* {title} */", *lines]
+        if self.types:
+            parts += ["", "/* Generated configuration types (one struct per multiplicity-n container def) */"]
+            parts += self.types
+        if self.hdecls:
+            parts += ["", *self.hdecls]
+        parts += ["", f"#endif /* {g} */", ""]
+        out[hname] = "\n".join(parts)
+        for rank in sorted(self.tables):
+            fname = f"{self.mip}_{CLASS_FILE[rank]}"
+            if fname in out:  # PUBLISHED-INFORMATION and PRE-COMPILE share <Mip>_Cfg.c
+                continue
+            ranks = [r for r in self.tables if CLASS_FILE[r] == CLASS_FILE[rank]]
+            body = []
+            externs = []
+            for r in sorted(ranks):
+                body += self.tables[r]
+                externs += [e for e in self.c_externs.get(r, []) if e not in externs]
+            incs = list(self.c_includes) or [f"{self.mip}_Cfg.h"]
+            for m in sorted(self.used_mips - {self.mip}):
+                h = f"{m}_Cfg.h"
+                if h not in incs:
+                    incs.append(h)
+            text = [self._banner(fname), ""]
+            text += [f'#include "{i}"' for i in incs]
+            text += ["", self._version_check(), ""]
+            if externs:
+                text += ["/* Objects owned by other modules / the application, referenced by this configuration */",
+                         *externs, ""]
+            text += [W.memmap(self.mip, "\n\n".join(body)), ""]
+            out[fname] = "\n".join(text)
+        out.update(self.extra_files)
+        return out
+
+    def _version_check(self) -> str:
+        M = self.MIP
+        return "\n".join([
+            f"/* SWS_BSW_00036: the static code ({self.mip}.h) and this configuration must use the same AUTOSAR release */",
+            f"#if defined({M}_AR_RELEASE_MAJOR_VERSION) && defined({M}_AR_RELEASE_MINOR_VERSION)",
+            f"#if ({M}_AR_RELEASE_MAJOR_VERSION != {M}_CFG_AR_RELEASE_MAJOR_VERSION) || "
+            f"({M}_AR_RELEASE_MINOR_VERSION != {M}_CFG_AR_RELEASE_MINOR_VERSION)",
+            f'#error "{self.mip}: AUTOSAR release of the generated configuration does not match {self.mip}.h"',
+            "#endif",
+            "#endif",
+        ])
+
+
+# ======================================================================================
+# Generic emission, driven only by the param defs
+# ======================================================================================
+
+def strip_prefix(mip: str, name: str) -> str:
+    return name[len(mip):] if name.lower().startswith(mip.lower()) and len(name) > len(mip) else name
+
+
+def scalar_macros(cg: CgModel, mo: ModuleOutput):
+    """PRE-COMPILE / PUBLISHED-INFORMATION params of singleton containers -> #define <MIP>_<PARAM>."""
+    mc = mo.mc
+    names: dict = {}
+    for c in mc.containers:
+        if cg.is_multi(c) or c.defn is None:
+            continue
+        lines = []
+        for pd_path in c.defn.params:
+            d = cg.defs.get(pd_path)
+            if d is None or d.upper != 1 or cg.eff_class(mc, d) > CLASS_RANK["PRE-COMPILE"]:
+                continue
+            raw = c.text(d.name)
+            if raw is None:
+                raw = d.default
+            if raw is None:
+                continue
+            base = f"{mo.MIP}_{snake(strip_prefix(mo.mip, d.name))}"
+            if base in names and names[base] != c.path:
+                base = f"{mo.MIP}_{snake(strip_prefix(mo.mip, c.def_name))}_{snake(strip_prefix(mo.mip, d.name))}"
+            names[base] = c.path
+            lines.append((base, W.macro_value(d, raw)))
+            if d.kind == "ENUMERATION":
+                enum_literals(mo, d)
+        mo.group(f"Pre-compile parameters of {c.def_name} ({c.path})", lines)
+
+
+def enum_literals(mo: ModuleOutput, d: D.DefNode):
+    """Guarded values for module-prefixed enum literals used in #if comparisons (def literal order)."""
+    lits = [x for x in d.literals if x.upper().startswith(mo.MIP + "_")]
+    if not lits or len(lits) != len(d.literals):
+        return
+    key = f"__enum__{d.path}"
+    if key in mo.defined:
+        return
+    mo.defined.add(key)
+    lines = [f"#ifndef {lit}\n" + W.define(lit, W.c_uint(i)) + "\n#endif" for i, lit in enumerate(d.literals)]
+    mo.groups.append((f"Literals of {d.name} (def literal order; the static code may predefine them)", lines))
+
+
+def symbolic_names(cg: CgModel, mo: ModuleOutput):
+    """TPS_ECUC_02108 / SWS_BSW_00200 symbols for every symbolicNameValue parameter of the module."""
+    by_def: dict = {}
+    for c in mo.mc.containers:
+        d = cg.symbolic_param(c)
+        if d is None:
+            continue
+        v = c.text(d.name)
+        if v is None:
+            continue
+        by_def.setdefault(c.def_name, []).append((c, d, v))
+    for dname, items in by_def.items():
+        lines = []
+        items = sorted(items, key=lambda t: (cg.sorted_instances(mo.mc, dname).index(t[0])))
+        for c, d, v in items:
+            sym = cg.symbol(c)
+            val = W.macro_value(d, v)
+            lines.append((sym, val))
+            mo.symbols.append((sym, val, c.path))
+        mo.group(f"Symbolic names of {dname} (TPS_ECUC_02108, {items[0][1].name})", lines)
+
+
+# ---------- generic tables ----------
+
+@dataclass
+class Field:
+    name: str
+    ctype: str
+    steps: list  # sub-container def names to the owner of the param
+    d: Optional[D.DefNode] = None  # param/ref def
+    choice: Optional[D.DefNode] = None  # for the choice selector field
+    parent: bool = False
+
+
+def _fields(cg: CgModel, cdef: D.DefNode, prefix: str = "", steps: Optional[list] = None, depth: int = 0) -> list:
+    steps = steps or []
+    out: list = []
+    skipped: list = []
+    for p in cdef.params + cdef.refs:
+        d = cg.defs.get(p)
+        if d is None:
+            continue
+        if d.upper != 1:
+            if d.kind == "ENUMERATION" and 0 < len(d.literals) <= 32:
+                out.append(Field(prefix + d.name + "Mask", "uint32", steps, d))  # set of literals as a bitmask
+            else:
+                skipped.append(f"{d.name} (multi-valued)")
+            continue
+        if D.is_ref_kind(d.kind or ""):
+            if d.kind not in ("REFERENCE", "SYMBOLIC-NAME-REFERENCE", "CHOICE-REFERENCE"):
+                skipped.append(f"{d.name} ({d.kind.lower()})")
+                continue
+            out.append(Field(prefix + d.name, "uint16", steps, d))
+            continue
+        ct = W.param_ctype(d)
+        if ct is None:
+            skipped.append(f"{d.name} ({d.kind.lower()})")
+            continue
+        out.append(Field(prefix + d.name, ct, steps, d))
+    if depth < 4:
+        for sp in cdef.containers:
+            sd = cg.defs.get(sp)
+            if sd is None or sd.upper != 1:
+                continue  # multiplicity-n sub-containers get their own table
+            if sd.tag == D.CHOICE_TAG:
+                out.append(Field(prefix + sd.name, "uint8", steps + [sd.name], choice=sd))
+                for bp in sd.containers:
+                    bd = cg.defs.get(bp)
+                    if bd is not None:
+                        f2 = _fields(cg, bd, f"{prefix}{sd.name}_{bd.name}_", steps + [sd.name, bd.name], depth + 1)
+                        out += f2
+                continue
+            out += _fields(cg, sd, f"{prefix}{sd.name}_", steps + [sd.name], depth + 1)
+    return out
+
+
+def _owner(c: Optional[Container], steps: list) -> Optional[Container]:
+    for s in steps:
+        if c is None:
+            return None
+        subs = c.sub(s)
+        c = subs[0] if subs else None
+    return c
+
+
+def _value(cg: CgModel, mo: ModuleOutput, row: Container, f: Field) -> tuple:
+    if f.parent:
+        p = row.parent
+        while p is not None and not cg.is_multi(p):
+            p = p.parent
+        return (W.c_uint(cg.index_of(p)) if p is not None else "0u", p.name if p is not None else "")
+    owner = _owner(row, f.steps)
+    if f.choice is not None:
+        if owner is None or not owner.children:
+            return ("0xFFu", "no choice")
+        br = owner.children[0]
+        names = [x.rsplit("/", 1)[-1] for x in f.choice.containers]
+        return (W.c_uint(names.index(br.def_name)) if br.def_name in names else "0xFFu", br.def_name)
+    d = f.d
+    if D.is_ref_kind(d.kind or ""):
+        t = cg.target(owner.value(d.name)) if owner is not None else None
+        if t is None:
+            return ("0xFFFFu", "no reference")
+        sym = cg.symbol(t)
+        if sym is not None:
+            return (mo.ctx.xsym(t, mo.mc, mo.used_mips), "")
+        if cg.is_multi(t):
+            return (W.c_uint(cg.index_of(t)), t.name)
+        return ("0u", t.name)
+    if d.upper != 1:  # multi-valued enumeration -> bitmask of def literal indices
+        lits = [pv.value for pv in owner.values(d.name)] if owner is not None else []
+        mask = 0
+        for x in lits:
+            if x in d.literals:
+                mask |= 1 << d.literals.index(x)
+        return (W.c_uint(mask, hexa=True), "|".join(lits))
+    raw = owner.text(d.name) if owner is not None else None
+    return W.table_value(d, raw)
+
+
+def generic_tables(cg: CgModel, mo: ModuleOutput, skip: set):
+    """One const struct array per multiplicity-n container def (plus singleton structs for non-PC scalars)."""
+    mc = mo.mc
+    seen: list = []
+    for c in mc.containers:
+        if c.def_name in skip or c.defn is None or c.def_name in seen:
+            continue
+        if c.defn.upper == 1 and not _has_dynamic(cg, mc, c):
+            continue
+        if c.defn.upper == 1 and cg.is_multi(c):
+            continue  # flattened into its multi ancestor's row
+        seen.append(c.def_name)
+    for dname in seen:
+        rows = cg.sorted_instances(mc, dname)
+        cdef = rows[0].defn
+        fields = _fields(cg, cdef)
+        if rows[0].parent is not None and cg.is_multi(rows[0].parent):
+            fields = [Field("Parent", "uint16", [], parent=True)] + fields
+        if not fields:
+            continue
+        tname = f"{mo.mip}_Cfg{dname}Type"
+        oname = f"{mo.mip}_Cfg{dname}"
+        rank = max([cg.eff_class(mc, f.d) for f in fields if f.d is not None] + [cg.eff_class(mc, cdef), 1])
+        mo.types.append("typedef struct {\n" + "\n".join(f"  {f.ctype} {f.name};" for f in fields) +
+                        f"\n}} {tname};")
+        lines = []
+        for r in rows:
+            vals = []
+            notes = []
+            for f in fields:
+                v, n = _value(cg, mo, r, f)
+                vals.append(v)
+            sym = cg.symbol(r)
+            lines.append(W.initializer(vals, sym or r.name))
+        multi = cdef.upper != 1 or len(rows) > 1
+        cnt = f"{mo.MIP}_CFG_NUM_{snake(strip_prefix(mo.mip, dname))}"
+        if multi:
+            mo.group(f"Size of {oname}[]", [(cnt, W.c_uint(len(rows)))])
+            decl = f"CONST({tname}, {mo.MIP}_CONST) {oname}[{cnt}]"
+            body = f"{decl} = {{\n" + ",\n".join(lines) + "\n};"
+        else:
+            decl = f"CONST({tname}, {mo.MIP}_CONST) {oname}"
+            body = f"{decl} =\n" + lines[0].strip() + ";"
+        mo.hdecls.append(f"extern {decl};")
+        names = ", ".join(f.name for f in fields)
+        mo.table(rank, f"/* {dname}: {len(rows)} row(s), fields {names} */\n{body}")
+
+
+def _has_dynamic(cg: CgModel, mc: ModuleCfg, c: Container) -> bool:
+    """A singleton container holding link-time/post-build scalars needs a const object, not macros."""
+    for p in c.defn.params:
+        d = cg.defs.get(p)
+        if d is not None and d.upper == 1 and W.param_ctype(d) and cg.eff_class(mc, d) > CLASS_RANK["PRE-COMPILE"]:
+            if c.text(d.name) is not None:
+                return True
+    return False

package/python/ecuc_engine/codegen/handles.py

@@ -0,0 +1,89 @@
+"""Deterministic handle-ID assignment for symbolicNameValue parameters, written back in place.
+
+TPS_ECUC_02107: values of symbolicNameValue parameters that the configuration editor or module
+generator assigns are stored in the ECUC XML. TPS_ECUC_02108 turns them into the
+`<Mip>Conf_<ContainerDef>_<ContainerValue>` #defines.
+
+Algorithm (stable by construction):
+  * values already in the ECUC are kept as they are (so regeneration never renumbers a handle that
+    code or another ECU already uses), duplicates among them are reported, not "fixed";
+  * containers without a value get the lowest free integers >= max(def MIN, 0), in document order;
+  * the scope is one container def within one module (the symbol namespace of TPS_ECUC_02108).
+Only INTEGER parameters are assigned. A missing STRING symbolic value is reported.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..values import parse_int
+from .model import CgModel, ModuleCfg
+
+
+def plan(cg: CgModel, modules: list) -> dict:
+    """-> {"assign": [{path, param, value, def}], "errors": [...], "notes": [...]}"""
+    out: dict = {"assign": [], "errors": [], "notes": []}
+    for name in modules:
+        mc = cg.module(name)
+        if mc is None:
+            continue
+        _plan_module(cg, mc, out)
+    return out
+
+
+def _plan_module(cg: CgModel, mc: ModuleCfg, out: dict):
+    seen_defs: list = []
+    for c in mc.containers:
+        if c.def_name not in seen_defs:
+            seen_defs.append(c.def_name)
+    for dname in seen_defs:
+        insts = cg.instances(mc, dname)
+        d = cg.symbolic_param(insts[0])
+        if d is None:
+            continue
+        if d.kind != "INTEGER":
+            for c in insts:
+                if c.text(d.name) in (None, ""):
+                    out["notes"].append(f"{c.path}: {d.name} (symbolic {d.kind}) has no value and cannot be "
+                                        "auto-assigned; its symbol is not generated")
+            continue
+        lo = max(parse_int(d.min) if d.min else 0, 0)
+        hi: Optional[int] = parse_int(d.max) if d.max else None
+        used: dict = {}
+        missing = []
+        for c in insts:
+            v = parse_int(c.text(d.name) or "")
+            if v is None:
+                missing.append(c)
+                continue
+            if v in used:
+                out["errors"].append(f"{d.name}={v} is used by both {used[v]} and {c.path} "
+                                     f"(handle IDs must be unique per module, TPS_ECUC_02108)")
+            used.setdefault(v, c.path)
+        nxt = lo
+        for c in missing:
+            while nxt in used:
+                nxt += 1
+            if hi is not None and nxt > hi:
+                out["errors"].append(f"{c.path}: no free {d.name} left in [{lo}..{hi}]")
+                break
+            used[nxt] = c.path
+            out["assign"].append({"path": c.path, "param": d.name, "value": nxt, "def": d.path})
+            if not d.with_auto:
+                out["notes"].append(f"{c.path}: assigned {d.name}={nxt}; the def has no withAuto, so check that "
+                                    "the number carries no hardware meaning")
+            nxt += 1
+
+
+def apply(project, assignments: list, write: bool) -> dict:
+    """Write the assigned values into the ECUC ARXML in place (TPS_ECUC_02107) via the engine's editor.
+
+    write=False patches only the in-memory model (dry run), so the generated code still uses them.
+    """
+    if not assignments:
+        return {"written": False, "changes": []}
+    from ..edit import edit
+    ops = [{"op": "set", "path": a["path"], "param": a["param"], "value": a["value"]} for a in assignments]
+    res = edit(project, ops, dry_run=not write, run_validate=False)
+    if not res.get("ok"):
+        raise RuntimeError(f"handle-ID write-back failed: {res.get('error')}")
+    return {"written": bool(res.get("written")), "changes": res.get("changes", [])}

package/python/ecuc_engine/codegen/mcal/tc4d.json

@@ -0,0 +1,60 @@
+{
+  "silicon": "tc4d",
+  "title": "Infineon AURIX TC4Dx: Port pad configuration (register level)",
+  "status": "skeleton",
+  "statusNote": "Only public AURIX TC4Dx user manual data is in this file. It is enough to compute the GPIO direction / level / MODE=0 (GPIO) pad settings of a pin whose port and pin number are given in the project pin map. It is NOT a replacement for the Infineon MCAL: alternate-function MODE numbers per pin and mode literal, pad driver/level defaults, access-protection handling and the MCAL's own Port_ConfigType layout come from Infineon's vendor param defs (VSMD) / BSWMD and MCAL static code, which are under NDA and not used here.",
+  "sources": [
+    {"id": "UM", "doc": "AURIX TC4Dx user manual v1.1 (2025-06-26), public", "file": "tc4d/docs/infineon-infineon-aurix-tc4dx-um-v1.1-public-en_us.pdf-usermanual-en.pdf"}
+  ],
+  "registers": {
+    "GPIO":   {"offset": "0x300", "stride": "0x10", "cite": "UM 47.4.2 Table 2432 (p. 8609) and 47.4.30 PADCFGp_GPIO (p. 8632-8633)"},
+    "DRVCFG": {"offset": "0x304", "stride": "0x10", "cite": "UM 47.4.2 Table 2432 (p. 8610) and 47.4.31 PADCFGp_DRVCFG (p. 8633-8637)"}
+  },
+  "fields": {
+    "DIR":  {"reg": "DRVCFG", "lsb": 0,  "width": 1, "cite": "UM p. 8634: 0B IN, 1B OUT"},
+    "OD":   {"reg": "DRVCFG", "lsb": 1,  "width": 1, "cite": "UM p. 8634: 0B push-pull, 1B open drain"},
+    "MODE": {"reg": "DRVCFG", "lsb": 4,  "width": 4, "cite": "UM p. 8634: output: 0 = GPIO, n = alternate output function n; input: 0 tristate, 1 pull-down, 2 pull-up, 3 tristate"},
+    "PD":   {"reg": "DRVCFG", "lsb": 8,  "width": 3, "cite": "UM p. 8635: pad driver strength / edge"},
+    "PL":   {"reg": "DRVCFG", "lsb": 12, "width": 3, "cite": "UM p. 8636: input level (AL / TTL)"},
+    "SET":  {"reg": "GPIO",   "lsb": 2,  "width": 1, "cite": "UM p. 8633: write 1 drives the pin high (OUT is read-only)"},
+    "CLR":  {"reg": "GPIO",   "lsb": 3,  "width": 1, "cite": "UM p. 8633: write 1 drives the pin low"}
+  },
+  "direction": {"PORT_PIN_IN": {"DIR": 0}, "PORT_PIN_OUT": {"DIR": 1}},
+  "level": {"PORT_PIN_LEVEL_HIGH": {"SET": 1}, "PORT_PIN_LEVEL_LOW": {"CLR": 1}},
+  "modes": {
+    "PORT_PIN_MODE_DIO": {"MODE": 0, "cite": "UM p. 8634: MODE 0 = GPIO (output) / tristate (input)"}
+  },
+  "modesNote": "Every other PortPinMode needs the alternate-function number of that pin (MODE = 1..15). Per-pin ALT numbers are listed in the TC4Dx data sheet pin tables, but the mapping from the vendor's PortPinMode literals to them is defined by Infineon's VSMD (NDA). Give them per pin in the project pin map ('modes': {'PORT_PIN_MODE_CAN': 2}).",
+  "ports": {
+    "P00": {"base": "0xF003A000", "pins": "0-15"},
+    "P01": {"base": "0xF003A400", "pins": "0-15"},
+    "P02": {"base": "0xF003A800", "pins": "0-15"},
+    "P03": {"base": "0xF003AC00", "pins": "0-15"},
+    "P04": {"base": "0xF003B000", "pins": "0-9"},
+    "P10": {"base": "0xF003C800", "pins": "0-11,13-15"},
+    "P13": {"base": "0xF003D400", "pins": "0-15"},
+    "P14": {"base": "0xF003D800", "pins": "0-15"},
+    "P15": {"base": "0xF003DC00", "pins": "0-8,10-15"},
+    "P16": {"base": "0xF003E000", "pins": "0-14"},
+    "P20": {"base": "0xF003F000", "pins": "0-3,6-14"},
+    "P21": {"base": "0xF003F400", "pins": "0-7"},
+    "P22": {"base": "0xF003F800", "pins": "0-11"},
+    "P23": {"base": "0xF003FC00", "pins": "0-7"},
+    "P25": {"base": "0xF0040400", "pins": "1"},
+    "P30": {"base": "0xF0041800", "pins": "0-15"},
+    "P31": {"base": "0xF0041C00", "pins": "6-7"},
+    "P32": {"base": "0xF0042000", "pins": "2,4-7"},
+    "P33": {"base": "0xF0042400", "pins": "0-15"},
+    "P34": {"base": "0xF0042800", "pins": "1-5"},
+    "P35": {"base": "0xF0042C00", "pins": "0-5"},
+    "P40": {"base": "0xF0044000", "pins": "0-14"}
+  },
+  "portsCite": "UM 47.8 Table 2448 'Registers address space - Pn' (p. 8650); available slices from Table 2446 'Port implementation in TC4DxAA-step' (p. 8645-8646)",
+  "needsVendorData": [
+    "Infineon MCAL Port/Dio vendor param defs (VSMD) and BSWMD: vendor PortPin parameters (driver strength, pad level, input select, alternate-function literals) and their config classes",
+    "the MCAL static code's Port_ConfigType / Dio config layout (what Port_Init actually consumes); without it only the register image below can be generated",
+    "per-pin alternate-function numbers for each PortPinMode literal (data sheet pin tables + the VSMD literal mapping)",
+    "write sequencing under the pad access protection (PADCFGp_ACCEN, ACCGRPy_*, PROTSE/Safety ENDINIT; UM 47.4.x) that the MCAL performs",
+    "PortPinId / DioChannelId encoding used by the Infineon MCAL (port*16+pin or otherwise); the project pin map gives port and pin explicitly instead"
+  ]
+}