@h2loop/autosar 1.0.1 → 1.2.0

package/python/ecuc_engine/codegen/emit.py

@@ -0,0 +1,463 @@
+"""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)
+    out_headers: dict = field(default_factory=dict)  # headers of other generators (e.g. the RTE) in the project's output dir
+
+    def module_release(self, mip: str) -> tuple:
+        """AUTOSAR release the module's generated configuration is built for: the published information of its
+        static code (<MIP>_AR_RELEASE_*_VERSION in <Mip>.h, SWS_BSW_00059), which SWS_BSW_00036-style checks compare
+        against; the ECUC schema release only when the project has no such header."""
+        f = self.headers.get(f"{mip}.h")
+        rel = published_release(f, mip.upper()) if f else None
+        return rel or self.release
+
+    def header_text(self, name: str) -> Optional[str]:
+        """Text of a project header or of another generator's header in the output dir (None if absent)."""
+        f = self.headers.get(name) or self.out_headers.get(name)
+        if not f:
+            return None
+        try:
+            with open(f, errors="replace") as fh:
+                return fh.read()
+        except OSError:
+            return None
+
+    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
+
+
+def published_release(path: str, MIP: str) -> Optional[tuple]:
+    """(major, minor, revision) from <MIP>_AR_RELEASE_{MAJOR,MINOR,REVISION}_VERSION in a header, if defined."""
+    import re
+    try:
+        with open(path, errors="replace") as fh:
+            t = fh.read()
+    except OSError:
+        return None
+    v = []
+    for k in ("MAJOR", "MINOR", "REVISION"):
+        m = re.search(rf"#\s*define\s+{re.escape(MIP)}_AR_RELEASE_{k}_VERSION\s+\(?(\d+)", t)
+        v.append(int(m.group(1)) if m else None)
+    if v[0] is None or v[1] is None:
+        return None
+    return (v[0], v[1], v[2] or 0)
+
+
+class ModuleOutput:
+    def __init__(self, ctx: Ctx, mc: ModuleCfg):
+        self.ctx = ctx
+        self.mc = mc
+        self.mip = mc.mip
+        self.MIP = mc.MIP
+        self.release = ctx.module_release(mc.mip)
+        self.vars: dict = {}  # rank -> [(section, text)]: RAM objects (e.g. I-PDU buffers) next to the tables
+        self.errors: list = []  # configuration the static-code binding cannot represent (generation fails)
+        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 var(self, rank: int, section: str, text: str):
+        """A RAM object owned by the configuration (e.g. a buffer the const tables point to)."""
+        rank = max(rank, 1)
+        self.vars.setdefault(rank, []).append((section, text))
+        self.tables.setdefault(rank, [])
+
+    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.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.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, ""]
+            sections: dict = {}
+            for r in sorted(ranks):
+                for sec, v in self.vars.get(r, []):
+                    sections.setdefault(sec, []).append(v)
+            for sec in sorted(sections):
+                text += [W.memmap(self.mip, "\n".join(sections[sec]), sec), ""]
+            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_literal_values(literals: list) -> list:
+    """C values of enumeration literals used in #if comparisons.
+
+    When every literal is <common stem><decimal number> with distinct numbers (NVM_API_CONFIG_CLASS_1..3), the
+    number in the name is the value: the name states the ordinal (SWS_NvM_00560..00562 API configuration class
+    1/2/3), so #if (X >= X_2) keeps its meaning and no literal is 0. Otherwise the def literal order is used (the
+    ECUC def lists literals alphabetically, so that order carries no meaning beyond being stable).
+    """
+    import re
+    m = [re.fullmatch(r"(.*?)(\d+)", x) for x in literals]
+    if all(m) and len({x.group(1) for x in m}) == 1 and len({int(x.group(2)) for x in m}) == len(literals):
+        return [int(x.group(2)) for x in m]
+    return list(range(len(literals)))
+
+
+def enum_literals(mo: ModuleOutput, d: D.DefNode):
+    """Guarded values for module-prefixed enum literals used in #if comparisons (see enum_literal_values)."""
+    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)
+    vals = enum_literal_values(d.literals)
+    lines = [f"#ifndef {lit}\n" + W.define(lit, W.c_uint(v)) + "\n#endif" for v, lit in zip(vals, d.literals)]
+    mo.groups.append((f"Literals of {d.name} (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,176 @@
+"""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.
+
+Static-code layout (layout()): a static code that indexes its tables by handle (e.g. a Com whose
+signal table holds the Tx signals at 0..nTx-1 and the Rx signals after them) declares that order in
+its binding ("handleLayout"). When the configured values break it (a Tx signal added after the Rx
+ones), the generator renumbers that handle param, keeping the relative order inside each row set,
+but only for withAuto params (the def says the configuration tool computes the value); otherwise the
+mismatch is an error for the integrator.
+"""
+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 layout(cg: CgModel, modules: list, selected: dict) -> dict:
+    """-> {"assign": [...], "errors": [...], "notes": [...]} renumbering handles to each binding's handleLayout."""
+    from .binding import Eval
+    out: dict = {"assign": [], "errors": [], "notes": []}
+    for name in modules:
+        mb, mc = selected.get(name), cg.module(name)
+        if not mb or mc is None:
+            continue
+        ev = Eval(cg, mc)
+        for hl in mb.get("handleLayout", []):
+            rows: list = []
+            for st in hl["sets"]:
+                rows += [r for r in ev.rows("@" + st, mb.get("sets", {})) if r not in rows]
+            insts = cg.instances(mc, mb["sets"][hl["sets"][0]]["rows"])
+            rows += [r for r in cg.sorted_instances(mc, insts[0].def_name) if r not in rows] if insts else []
+            if not rows:
+                continue
+            d = cg.symbolic_param(rows[0])
+            changes = [(r, i) for i, r in enumerate(rows) if parse_int(r.text(d.name) or "") != i]
+            if not changes:
+                continue
+            what = f"{d.name}: the {mb.get('_binding')} static code indexes its tables by handle in the order " \
+                   f"{' then '.join(hl['sets'])}"
+            if not d.with_auto:
+                out["errors"].append(f"{what}; {len(changes)} value(s) break that order and the def has no withAuto, "
+                                     f"so they are not renumbered (first: {changes[0][0].path}={changes[0][0].text(d.name)})")
+                continue
+            for r, i in changes:
+                out["assign"].append({"path": r.path, "param": d.name, "value": i, "def": d.path})
+            out["notes"].append(f"{what}; renumbered {len(changes)} {d.name} value(s) (withAuto, TPS_ECUC_02107), "
+                                f"e.g. {changes[0][0].name}: {changes[0][0].text(d.name)} -> {changes[0][1]}")
+    return out
+
+
+def apply(project, assignments: list, write: bool) -> dict:
+    """Write the assigned values into the ECUC ARXML in place (TPS_ECUC_02107).
+
+    Values that replace an existing VALUE are patched in one pass per file (only the VALUE text bytes change,
+    so a renumbering of thousands of handles stays linear); new values go through the engine's editor, which
+    places the element per the schema. write=False patches only the in-memory model (dry run), so the
+    generated code still uses them.
+    """
+    if not assignments:
+        return {"written": False, "changes": []}
+    import difflib
+    import os
+    from ..xmltree import escape
+    by_path = {}
+    for e in _elems(project):
+        by_path.setdefault(e.path, []).append(e)
+    patches: dict = {}
+    rest = []
+    for a in assignments:
+        hits = [(e, pv) for e in by_path.get(a["path"], []) for pv in e.params if pv.name == a["param"]]
+        vn = hits[0][1].value_node if len(hits) == 1 else None
+        if vn is None or vn.cstart is None or vn.tag != "VALUE":
+            rest.append(a)
+            continue
+        patches.setdefault(hits[0][0].file, []).append((vn.cstart, vn.cend, escape(str(a["value"])).encode()))
+    changes = []
+    for f in sorted(patches):
+        before = project.files[f].data
+        after = bytearray(before)
+        for start, end, repl in sorted(patches[f], reverse=True):
+            after[start:end] = repl
+        after = bytes(after)
+        project.reload(f, after)
+        rel = project.rel(f)
+        a_, b_ = before.decode("utf-8", "replace").splitlines(True), after.decode("utf-8", "replace").splitlines(True)
+        changes.append({"file": rel, "diff": "".join(difflib.unified_diff(a_, b_, f"a/{rel}", f"b/{rel}", n=1))})
+        if write:
+            tmp = f + ".ecuc-tmp"
+            with open(tmp, "wb") as fh:
+                fh.write(after)
+            os.replace(tmp, f)
+    written = bool(patches) and write
+    if rest:
+        from ..edit import edit
+        ops = [{"op": "set", "path": a["path"], "param": a["param"], "value": a["value"]} for a in rest]
+        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')}")
+        written = written or bool(res.get("written"))
+        changes += res.get("changes", [])
+    return {"written": written, "changes": changes}
+
+
+def _elems(project):
+    stack = list(project.modules)
+    while stack:
+        e = stack.pop()
+        yield e
+        stack.extend(e.children)