tan-cli 0.7.0__py3-none-any.whl

tan/planner/link_target.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`diagnostics.link:` -- the image link target (tan-cli#1350, ADR-0026).
+
+`link: itcm` turns a board.yaml into an AEN Flow C image: linked into the
+M55-HE ITCM (base 0x0, global window 0x58000000) for `tan flash --ram`, which
+loads the ELF there and reads `ram_console_buf`.  Without it the only route
+was hand-copying alp-sdk's `scripts/bench/aen/aen-flowc-itcm.{conf,overlay}`
+into the app.
+
+The planner owns the retarget (ADR-0026): it renders the same two halves the
+bench pair carries -- the Kconfig half and the devicetree half, BOTH required
+(the conf alone still links into MRAM, the overlay alone leaves
+`CONFIG_FLASH_LOAD_OFFSET` at the slot0 offset) -- as two extra per-slice
+config artefacts layered AFTER the slice's `alp.conf`.
+
+Pure: no IO, no SDK read.  HE-only by design: the knob retargets the M55-HE
+slice only, and is refused when the project has no M55-HE app of its own (an
+M55-HP-only project included), on any SKU but AEN801/AEN803, with a sysbuild
+(`boot:`) project, and with an explicit `linux`/`none` console.
+
+`console: uart` is accepted (tan-cli#1374).  The #1374 bench (e1m-aen-evk-02,
+AEN803, 2026-10-07) ran a UART5 shell RAM-run with ONLY `zephyr,flash = &itcm;`,
+the code-partition delete, `CONFIG_USE_DT_CODE_PARTITION=n` and
+`CONFIG_FLASH_LOAD_OFFSET=0x0` hand-added -- no `CONFIG_DCACHE=n`, so the
+D-cache stayed at its board default.  A `uart` image therefore gets exactly
+that retarget.  The D-cache hang recorded by #1350 concerns the RAM-console
+path, which still gets `CONFIG_DCACHE=n` and the 16 KiB buffer (`ram`/`auto`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import BoardProject, OrchestratorError, Slice
+from .secure import emit_sysbuild_conf, emit_tfm_sysbuild_conf
+
+UNSUPPORTED_CODE = "build.link-itcm-unsupported"
+CONSOLE_CONFLICT_CODE = "build.link-itcm-console-conflict"
+
+#: Build-dir file names of the two extra artefacts (siblings of `alp.conf`).
+CONF_NAME = "alp-link-itcm.conf"
+OVERLAY_NAME = "alp-link-itcm.overlay"
+
+_HE_CORE_ID = "m55_he"
+#: The SKUs the Flow C ITCM retarget is proven on (E8: AEN801 / AEN803, bench
+#: 2026-07..10). Other Alif Ensemble SKUs have different ITCM maps / SoC
+#: variants and are refused until someone proves them.
+_PROVEN_SKUS = ("E1M-AEN801", "E1M-AEN803")
+#: The schema enum already rejects anything else; the checks below that read
+#: the value defensively exist for hand-built projects that skip the schema.
+_LINK_VALUES = ("auto", "itcm")
+#: `diagnostics.console:` values a Flow C image accepts: the RAM console (the
+#: default; read over SWD) or the board UART (a RAM-run shell, tan-cli#1374).
+#: `alp` is kconfig's own alias of `uart` (`kconfig._CONSOLE_ALIASES`), so it is
+#: the UART console here too and emits exactly the `uart` bytes (tan-cli#1419).
+_CONSOLE_VALUES = ("auto", "ram", "uart", "alp")
+
+
+class LinkTargetError(OrchestratorError):
+    """A `diagnostics.link:` refusal carrying its tan issue code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _console(diagnostics: dict[str, Any] | None) -> str:
+    return str((diagnostics or {}).get("console") or "auto").strip().lower()
+
+
+def uses_ram_console(diagnostics: dict[str, Any] | None) -> bool:
+    """Whether an ITCM image uses the RAM console (`auto` is promoted to it):
+    True for `auto`/`ram`, False for `uart`, its alias `alp`, and anything else."""
+    return _console(diagnostics) in ("auto", "ram")
+
+
+def link_target(diagnostics: dict[str, Any] | None) -> str:
+    """The `diagnostics.link:` value (`auto` when unset). The `.strip().lower()`
+    is defensive only: the schema enum is lowercase, exact."""
+    raw = (diagnostics or {}).get("link")
+    return "auto" if raw is None else str(raw).strip().lower()
+
+
+def is_itcm_link(diagnostics: dict[str, Any] | None) -> bool:
+    return link_target(diagnostics) == "itcm"
+
+
+def applies_to(diagnostics: dict[str, Any] | None, slice_: Slice) -> bool:
+    """Whether `link: itcm` retargets THIS slice: the Zephyr M55-HE only.
+
+    The knob is project-wide in board.yaml, but a Flow C image is one core's
+    ITCM image: the other slices of the project (the AEN stock M55-HP shim,
+    the A32 Linux image) build exactly as without it.
+    """
+    return (is_itcm_link(diagnostics) and slice_.os == "zephyr"
+            and slice_.core_id == _HE_CORE_ID)
+
+
+def check_link_target(project: BoardProject) -> None:
+    """Refuse `link: itcm` anywhere but an AEN project with an M55-HE app.
+
+    Raises `LinkTargetError`; returns None for `auto`/unset.
+    """
+    target = link_target(project.diagnostics)
+    if target == "auto":
+        return
+    if target not in _LINK_VALUES:
+        raise LinkTargetError(
+            UNSUPPORTED_CODE,
+            f"diagnostics.link: '{target}' is not one of "
+            f"{', '.join(_LINK_VALUES)}.")
+    if project.sku not in _PROVEN_SKUS:
+        raise LinkTargetError(
+            UNSUPPORTED_CODE,
+            f"diagnostics.link: itcm is proven on the Alif Ensemble E8 "
+            f"M55-HE ({', '.join(_PROVEN_SKUS)}); {project.sku} is not "
+            f"supported. Remove `diagnostics.link:` for this SoM.")
+    declared = (project.raw.get("cores") or {}) if isinstance(
+        project.raw, dict) else {}
+    he_decl = declared.get(_HE_CORE_ID)
+    he = project.cores.get(_HE_CORE_ID)
+    if (not isinstance(he_decl, dict) or not he_decl.get("app")
+            or he is None or he.os != "zephyr"):
+        others = sorted(
+            c for c, d in declared.items()
+            if c != _HE_CORE_ID and isinstance(d, dict) and d.get("app"))
+        hint = (f" The project's own app is on {', '.join(others)}; the "
+                f"M55-HP has a separate ITCM window (0x50000000) and is not "
+                f"supported -- move the app to `cores.{_HE_CORE_ID}`."
+                if others else "")
+        raise LinkTargetError(
+            UNSUPPORTED_CODE,
+            f"diagnostics.link: itcm links the M55-HE ITCM image, but "
+            f"`cores.{_HE_CORE_ID}` has no `os: zephyr` app of its own."
+            f"{hint}")
+    if emit_sysbuild_conf(project) or emit_tfm_sysbuild_conf(project):
+        raise LinkTargetError(
+            UNSUPPORTED_CODE,
+            "diagnostics.link: itcm cannot be combined with a sysbuild "
+            "project (`boot:` / `ota:` / TF-M) -- a RAM-run image has no "
+            "MCUboot slot.")
+    console = _console(project.diagnostics)
+    if console not in _CONSOLE_VALUES:
+        raise LinkTargetError(
+            CONSOLE_CONFLICT_CODE,
+            f"diagnostics.link: itcm supports the RAM console or the board "
+            f"UART, but diagnostics.console is '{console}'. Use "
+            f"`console: ram` (or leave it `auto`) to read the RAM console "
+            f"buffer, or `console: uart` for a RAM-run UART shell.")
+
+
+def apply_link_target(project: BoardProject) -> None:
+    """`check_link_target`, then mark the retargeted slice (`Slice.link_target`)
+    so the manifest/flash recipe can refuse an MRAM write of it."""
+    check_link_target(project)
+    for sl in project.cores.values():
+        if applies_to(project.diagnostics, sl):
+            sl.link_target = "itcm"
+
+
+#: Floor for the Flow C RAM-console buffer (bytes).
+ITCM_RAM_CONSOLE_MIN_SIZE = 16384
+
+
+def itcm_conf(ram_console: bool = True, *, app_ram_console_size: int = 0) -> str:
+    """Kconfig half of the retarget (+ the bench-proven RAM-run settings).
+
+    The retarget lines are always emitted.  The bench-proven RAM-console
+    settings (`CONFIG_DCACHE=n`, the buffer size) only when `ram_console`
+    (`console: ram`/`auto`); a `console: uart` image leaves both as the board
+    defaults them.
+
+    `app_ram_console_size` is the `CONFIG_RAM_CONSOLE_BUFFER_SIZE` the app's own
+    `prj.conf` sets (0 when none): this conf is layered AFTER it, so a bare
+    16384 would shrink a larger app-set buffer and wrap its console
+    (tan-cli#1401). The size is max(16384, app value).
+    """
+    size = max(ITCM_RAM_CONSOLE_MIN_SIZE, app_ram_console_size)
+    retarget = (
+        "# Flow C (AEN M55-HE ITCM RAM-run) link retarget -- board.yaml\n"
+        "# `diagnostics.link: itcm`.  NOT for an image you will flash to MRAM:\n"
+        "# it links at 0x0.  Kconfig half; the devicetree half is\n"
+        f"# {OVERLAY_NAME} -- BOTH are required.\n"
+        "#\n"
+        "# Stop deriving the link offset from the DT code-partition and force\n"
+        "# the ITCM base (undoes the AEN board defconfig's slot0 default and a\n"
+        "# literal CONFIG_FLASH_LOAD_OFFSET an app may hard-code).\n"
+        "CONFIG_USE_DT_CODE_PARTITION=n\n"
+        "CONFIG_FLASH_LOAD_OFFSET=0x0\n"
+    )
+    if not ram_console:
+        return retarget
+    return retarget + (
+        "# The E8 D-cache maintenance loop hangs on this silicon.\n"
+        "CONFIG_DCACHE=n\n"
+        "# ram_console_out() WRAPS: a buffer smaller than the app's output\n"
+        "# reads back as two interleaved points in the run.\n"
+        f"CONFIG_RAM_CONSOLE_BUFFER_SIZE={size}\n"
+    )
+
+
+def itcm_overlay() -> str:
+    """Devicetree half: retarget the ROM region to ITCM."""
+    return (
+        "/*\n"
+        " * Flow C (AEN M55-HE ITCM RAM-run) devicetree retarget -- board.yaml\n"
+        " * `diagnostics.link: itcm`.  Moves zephyr,flash to the ITCM and drops\n"
+        " * the code-partition so the image links at 0x0.  Kconfig half:\n"
+        f" * {CONF_NAME} -- BOTH are required.  NOT for an MRAM-flashed image.\n"
+        " */\n"
+        "\n"
+        "/ {\n"
+        "\tchosen {\n"
+        "\t\t/* path-ref form: the pointer form makes FLASH_SIZE=0 and\n"
+        "\t\t * overflows the link */\n"
+        "\t\tzephyr,flash = &itcm;\n"
+        "\t\t/delete-property/ zephyr,code-partition;\n"
+        "\t};\n"
+        "};\n"
+    )
+
+
+def extra_config_artefacts(project: BoardProject,
+                           slice_: Slice) -> list[tuple[str, str]]:
+    """`(name, contents)` of the extra per-slice artefacts, in layer order.
+
+    Empty unless `link: itcm` and this is the Zephyr M55-HE slice.
+    """
+    if not applies_to(project.diagnostics, slice_):
+        return []
+    # Lazy: kconfig imports this module (the shared reader of the app's prj.conf).
+    from .kconfig import _app_ram_console_size  # noqa: PLC0415
+
+    ram_console = uses_ram_console(project.diagnostics)
+    app_size = _app_ram_console_size(project, slice_) if ram_console else 0
+    return [(CONF_NAME, itcm_conf(ram_console, app_ram_console_size=app_size)),
+            (OVERLAY_NAME, itcm_overlay())]

tan/planner/linux_ownership.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Linux devicetree fragment for per-product core ownership (RZ/V2N family).
+
+ONE renderer for two callers: `scripts/gen_linux_ownership_dt.py` (the
+committed SoM-default fragment) and `--emit linux-ownership-dts` (the
+per-project fragment from the project's resolved `ownership:`).  Inputs are
+read, never restated: the family core-ownership.yaml, its
+supervisor-links.yaml and the SoC JSON `linux_dt` block (`project.soc_spec`).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .models import OrchestratorError
+from .ownership import instance_pfc, load_ownership_doc, ownership_doc_rel, resolve_ownership
+
+# The V2N SoM-default source; a project passes its own family's via render(src=).
+SRC = "metadata/e1m_modules/v2n/core-ownership.yaml"
+
+
+class GenError(OrchestratorError):
+    pass
+
+
+def load_supervisor_links(metadata_root: Path, family_dir: Optional[str]) -> dict:
+    """The family's enabled/disabled supervisor links (V2M shares V2N's)."""
+    for fam in (family_dir, "v2n" if (family_dir or "").startswith("v2n") else None):
+        if fam:
+            p = metadata_root / "e1m_modules" / fam / "supervisor-links.yaml"
+            if p.is_file():
+                return yaml.safe_load(p.read_text(encoding="utf-8"))["supervisor_links"]
+    return {}
+
+
+def emit_linux_ownership_dts(project) -> str:
+    """The Linux ownership fragment for this project's resolved ownership,
+    or a comment-only stub when the SoM family has no `assignable:` block."""
+    from .loader import _sku_family_dir
+    root, fam = project.effective_metadata_root(), _sku_family_dir(project.sku)
+    doc = load_ownership_doc(root, fam)
+    if not doc or not doc.get("assignable"):
+        return "/* No assignable core ownership for this SoM family; nothing to emit. */\n"
+    return render(doc, project.soc_spec, load_supervisor_links(root, fam), project.ownership,
+                  src=ownership_doc_rel(root, fam))[0]
+
+
+def cm33_clocks(doc: dict, soc: dict, links: dict, own: dict[str, str]) -> list[str]:
+    """CPG clock names to keep on for the CM33: enabled supervisor links +
+    CM33-owned assignable instances (a hw_blocked instance is never enabled)."""
+    linux_dt = soc.get("linux_dt") or {}
+    by_label = {v["label"]: v for v in linux_dt.values() if v.get("cpg_clocks")}
+    clocks: list[str] = []
+
+    def add(names: list[str]) -> None:
+        clocks.extend(n for n in names if n not in clocks)
+
+    for name, link in sorted(links.items()):
+        if link.get("status") != "enabled":
+            continue
+        ent = by_label.get(link["dt_label"])
+        if ent is None:
+            raise GenError(f"supervisor link {name}: no cpg_clocks for &{link['dt_label']} in "
+                           f"soc linux_dt")
+        add(ent["cpg_clocks"])
+    for inst, e in sorted(doc["assignable"].items()):
+        if own[inst] == "m33" and not e.get("hw_blocked"):
+            ent = linux_dt.get(e.get("soc_instance")) or {}
+            if not ent.get("cpg_clocks"):
+                raise GenError(f"assignable.{inst}: owned by m33 but linux_dt.{e.get('soc_instance')} "
+                               "has no cpg_clocks")
+            add(ent["cpg_clocks"])
+    return clocks
+
+
+def _can_channels(doc: dict, soc: dict, own: dict[str, str]) -> tuple[dict[int, int], set[int], str]:
+    """({E1M CAN bus id: SoC channel} for every a55-owned, non-hw_blocked bus,
+    {bus ids Linux ENABLES (`linux_enable`)}, shared controller label)."""
+    linux_dt = soc.get("linux_dt") or {}
+    cans: dict[int, int] = {}
+    enabled: set[int] = set()
+    label = ""
+    for inst, e in doc["assignable"].items():
+        m = re.fullmatch(r"e1m_can(\d+)", inst)
+        ld = linux_dt.get(e.get("soc_instance")) or {}
+        if m and ld.get("channel") is not None and own[inst] == "a55" and not e.get("hw_blocked"):
+            bus = int(m.group(1))
+            cans[bus], label = ld["channel"], ld["label"]
+            # `render` only sets the node okay when linux_enable AND every pad has
+            # a PFC code (a GAP leaves the node at the vendor status).
+            if e.get("linux_enable") and all(p is not None for _, p in instance_pfc(soc, e)):
+                enabled.add(bus)
+    return cans, enabled, label
+
+
+def can_netdev_map(doc: dict, soc: dict, own: dict[str, str]) -> list[str]:
+    """Linux netdev per E1M CAN bus id (index = N of `e1m_canN`), "" = none.
+
+    rcar_canfd names netdevs `can0..` in probe order of the ENABLED channels
+    (ascending channel), and exposes no channel id at runtime (#2352), so the
+    name is the rank of the instance's SoC channel among the channels Linux
+    enables -- i.e. the `linux_enable` ones, the only nodes `render` sets to
+    "okay" (same rule as every other peripheral here).  `render` forces every
+    OTHER channel node disabled, so rank == enabled order by construction.
+    Buses that are not enabled map to "": alp_can_open fails closed."""
+    cans, enabled, _ = _can_channels(doc, soc, own)
+    if not cans:
+        return []
+    ranked = sorted(cans[b] for b in enabled)
+    return [f"can{ranked.index(cans[b])}" if b in enabled else "" for b in range(max(cans) + 1)]
+
+
+def _group(inst: str) -> tuple[str, str]:
+    return f"{inst}_pins", inst.replace("_", "-")
+
+
+def render(doc: dict, soc: dict, links: dict,
+           ownership: Optional[dict[str, str]] = None,
+           src: str = SRC) -> tuple[str, set[str]]:
+    """(dtsi text, node labels it references).  `src` = the family's
+    core-ownership.yaml path, quoted in the output."""
+    own = ownership or resolve_ownership(doc)
+    linux_dt = soc.get("linux_dt") or {}
+    pins: list[str] = []
+    nodes: list[str] = []
+    labels: set[str] = set()
+    for inst, e in sorted(doc["assignable"].items()):
+        ld = linux_dt.get(e.get("soc_instance"))
+        if ld is None:
+            raise GenError(f"assignable.{inst}: soc_instance {e.get('soc_instance')!r} "
+                           f"is not a key of soc linux_dt")
+        label = ld["label"]
+        head = f"/* {inst} ({e['soc_instance']}, &{label}): "
+        if e.get("hw_blocked"):
+            nodes.append(f"{head}left disabled -- hardware-blocked on every core:\n"
+                         f" * {e['hw_blocked']['reason']} */")
+            continue
+        if own[inst] != "a55":
+            labels.add(label)
+            nodes.append(f"{head}owned by {own[inst]}; Linux must not claim it. */\n"
+                         f"&{label} {{\n\tstatus = \"disabled\";\n}};")
+            continue
+        if e.get("linux_enable") and not e.get("linux_evidence"):
+            raise GenError(f"assignable.{inst}: linux_enable needs linux_evidence")
+        if not e.get("linux_enable"):
+            nodes.append(f"{head}owned by a55; left at the vendor status (no `linux_enable` in\n"
+                         f" * {src} -- Linux enablement is not bench-evidenced). */")
+            continue
+        rows = instance_pfc(soc, e)
+        gaps = [r["peripheral"] for r, p in rows if p is None]
+        if gaps:
+            nodes.append(f"{head}GAP -- no PFC function code in the SoC JSON\n"
+                         f" * linux_dt.{e['soc_instance']}.pinmux for {gaps}; node left as the vendor\n"
+                         " * dtsi has it (disabled).  Not guessed. */")
+            continue
+        grp_label, grp_node = _group(inst)
+        body = "".join(
+            ("\t\tpinmux = " if i == 0 else "\t\t\t ")
+            + f"<RZV2N_PORT_PINMUX({port[-1]}, {pin}, {func})>{';' if i == len(rows) - 1 else ','}"
+            f" /* {r['pad']} = {r['peripheral']} */\n"
+            for i, (r, (port, pin, func)) in enumerate(rows))
+        pins.append(f"\t{grp_label}: {grp_node} {{\n{body}\t}};\n")
+        labels.add(label)
+        chan = ld.get("channel")
+        node = (f"{head}owned by a55. */\n&{label} {{\n"
+                f"\tpinctrl-0 = <&{grp_label}>;\n\tpinctrl-names = \"default\";\n"
+                f"\tstatus = \"okay\";\n")
+        if chan is not None:
+            node += f"\n\tchannel{chan} {{\n\t\tstatus = \"okay\";\n\t}};\n"
+            labels.add(f"{label}/channel{chan}")
+        nodes.append(node + "};")
+    out = (
+        "/*\n"
+        " * GENERATED (scripts/gen_linux_ownership_dt.py, or `--emit linux-ownership-dts`\n"
+        f" * for a project) from {src}\n"
+        " * and the SoC JSON linux_dt block -- DO NOT EDIT BY HAND.\n"
+        " *\n"
+        " * Per-product core ownership on the A55 side: each assignable resource\n"
+        " * the SoM default gives to Linux is enabled here with pinctrl built from\n"
+        " * the metadata; resources owned by the Cortex-M33 or hardware-blocked\n"
+        " * are explicitly disabled.  Regenerate after editing either source.\n"
+        " */\n\n")
+    if pins:
+        out += "&pinctrl {\n" + "\n".join(pins) + "};\n\n"
+    out += "\n\n".join(nodes) + "\n"
+    names = ", ".join(f'"{c}"' for c in cm33_clocks(doc, soc, links, own))
+    out += ("\n/*\n * Module clocks the Cortex-M33 uses (enabled supervisor links + CM33-owned\n"
+            " * assignable instances): the CPG driver keeps them, and their bus-stop gates,\n"
+            " * on through clk_disable_unused (0001-clk-renesas-rzv2h-cpg-cm33-owned-clocks).\n"
+            " */\n"
+            f"&cpg {{\n\trenesas,cm33-owned-clocks = {names};\n}};\n")
+    labels.add("cpg")
+    nd = can_netdev_map(doc, soc, own)
+    if nd:
+        cans, enabled, clabel = _can_channels(doc, soc, own)
+        on = {cans[b] for b in enabled}
+        off = [c for c in range(int((soc.get("peripherals") or {}).get("can_fd", 0)))
+               if c not in on]
+        if off:
+            body = "\n".join(f'\tchannel{c} {{\n\t\tstatus = "disabled";\n\t}};\n' for c in off)
+            out += ("\n/*\n * Every CAN-FD channel Linux does not enable is disabled explicitly: rcar_canfd\n"
+                    " * numbers netdevs by probe order of the ENABLED channels, so the netdev map\n"
+                    " * below holds only if no other channel is enabled; an empty entry =\n"
+                    " * no netdev for that bus (#2352).\n */\n"
+                    f"&{clabel} {{\n{body}}};\n")
+            labels.update(f"{clabel}/channel{c}" for c in off)
+        names = ", ".join(f'"{n}"' for n in nd)
+        out += ("\n/*\n * Linux netdev per E1M CAN bus id (index = N of E1M_X_CANN): rcar_canfd numbers\n"
+                " * netdevs by probe order, not by channel, so the SDK's SocketCAN backend reads\n"
+                " * this instead of assuming can<N> (#2352).\n */\n"
+                f"/ {{\n\talp,e1m-can-netdev = {names};\n}};\n")
+    return out, labels