tan-cli 0.7.0__py3-none-any.whl

tan/planner/zephyr_board.py

@@ -0,0 +1,3510 @@
+# Copyright (c) 2026 Alp Lab AB
+# SPDX-License-Identifier: Apache-2.0
+"""
+`--emit zephyr-board` -- generate the per-core Zephyr board tree
+(`board.yml`, `Kconfig.alp_<board>`, the twister board metadata `.yaml`,
+and -- where the underlying hardware facts already exist in metadata --
+the `_defconfig`, pinctrl `.dtsi`, `Kconfig.defconfig`, and board `.dts`)
+straight from the SoM preset + SoC JSON, instead of hand-authoring them
+under `zephyr/boards/alp/<board>/` (issue #523).
+
+RELOCATED (was alp-sdk `scripts/gen_zephyr_board.py`). Reached as:
+
+    tan generate --target zephyr-board --core <core_id> \\
+        --output build/boards/<board_dir>/
+
+Unlike every other `--emit` mode this one writes a *directory* of files,
+not a single stream -- `tan.planner_emit.render_tree` / `write_tree` handle
+that distinction (as `alp_project.py` did); this module only returns
+``{relative_path: content}`` (paths relative to the board-tree root, e.g.
+``"alp_e1m_aen801_m55_hp/board.yml"``).
+
+Two mechanical changes came with the move, both on failure paths only: the SoM
+preset and the pinmux YAML are read through `tan.planner`'s own loader, so a
+missing preset or an unparseable YAML raises `OrchestratorError` where alp-sdk's
+wrapper called `sys.exit` -- a raise is reportable as a coded envelope, and a
+`SystemExit` inside `tan`'s own process is not. The generated bytes are
+unchanged, pinned by `tests/parity/test_planner_emit_parity.py`.
+
+A third is import-shaped: alp-sdk's `scripts/sentinels.py` has no counterpart
+under `tan/planner/`, so the `is_tbd()` this module calls is spelled as the
+local `_is_tbd` below -- same normalisation, same semantics.
+
+Scope (issue #523, first slice; extended by #655 slice 1 and alp-sdk#1964,
+both hand-ported here as tan-cli#1156):
+
+  - Alif Ensemble (the `aen` family, e.g. E1M-AEN801 m55_hp/m55_he) is
+    fully generated: every file in the hand-authored board tree except
+    `board.cmake` and `Kconfig` (see NOT GENERATED below) is produced
+    here, byte-identical to the committed tree -- proven by alp-sdk's
+    `tests/scripts/test_gen_zephyr_board.py`, whose `HAND_MAINTAINED`
+    exemption set is exactly those two names.
+
+    Its pinctrl `.dtsi` and `.dts` take a THIRD source alongside the SoM
+    preset + SoC JSON: `metadata/e1m_modules/aen/on-module-links.yaml`,
+    the authority for pads that reach no E1M edge pin (BRD_I2C on
+    P7_0/P7_1 and the RV-3028 alarm on P15_0) and for the devices that
+    hang off them.  `metadata/pinmux/aen.yaml` cannot carry those: it is
+    a generated projection of the EDGE pad TSVs, so an on-module pad has
+    no row there by construction.  Same shape, and same reasoning, as
+    `supervisor-links.yaml` below.
+  - Renesas RZ/V2N-family boards (`v2n` / `v2n-m1`, e.g. E1M-V2N101,
+    E1M-V2M101 `m33_sm`) generate the family-agnostic files (`board.yml`,
+    `Kconfig.alp_<board>`, the twister `.yaml`) PLUS the pinctrl `.dtsi`
+    and `_defconfig`, sourced from
+    `metadata/e1m_modules/v2n/supervisor-links.yaml` (#655) -- a
+    hand-authored, family-scoped source for the Renesas-side pin
+    assignments of the on-module GD32G553 supervisor bridge (SCI7
+    Simple-SPI, RIIC8/BRD_I2C, the disabled SCI0 console).
+
+    That source was deliberately NOT placed under
+    `metadata/pinmux/<family>.yaml`, despite that tree already carrying
+    every fact these two files need: `metadata/pinmux/*.yaml` is itself
+    GENERATED DO-NOT-EDIT output of `scripts/gen_pinmux_capability.py`
+    (from the family's TSVs), so it cannot also be a hand-authored
+    generation SOURCE without becoming circular (a generator reading its
+    own generated output as ground truth). `supervisor-links.yaml`
+    instead REFERENCES `metadata/pinmux/v2n.yaml` by
+    (silicon_peripheral, silicon_pad) -- alp-sdk's `scripts/
+    validate_metadata.py` cross-checks every row resolves to exactly one
+    `owner: "renesas"` pad there -- rather than re-declaring pad<->signal
+    authority a second time.
+
+    The board `.dts` is ALSO generated as of #655 slice 2 (alp-sdk
+    `e4f2f60e4`): `emit_zephyr_board()`'s `v2n`/`v2n-m1` branch calls
+    `_v2n_dts()`, which reuses the upstream RZ/V2N SoC devicetree and adds
+    the same on-module GD32G553 supervisor links `_v2n_pinctrl_dtsi()`
+    reads. A SoM preset's `topology.m33_sm.openamp_ipc` (boolean, absent
+    means false) gates the OpenAMP/MHU-B reserved-memory block and the
+    CAN-FD-unavailable analysis -- E1M-V2N101 and E1M-V2M101 both set it
+    (the same RZ/V2N die and MHU-B, #1948); a preset that leaves it false
+    gets neither block. `Kconfig.defconfig` remains
+    the one hand-authored file in this family (no metadata source for it
+    yet).
+
+  NOT GENERATED (any family): `board.cmake` and a bare `Kconfig`.
+  BOTH must be copied across by hand when a generated board tree is
+  used as the board directory -- nothing in the emit, the CLI output,
+  or the JSON envelope says so, which is why they are named here.
+
+  - `board.cmake`.  The hand-authored AEN pair (HP/HE) intentionally
+    carries asymmetric prose -- one board's file hosts the full
+    SETOOLS/J-Link bench-bring-up runbook, the sibling's just points at
+    it -- which is a documentation choice, not a hardware fact, so
+    there is nothing in metadata for it to derive from.
+    Flasher/debugger `board_runner_args()` wiring stays hand-authored
+    until that asymmetry is either resolved (duplicate the full
+    rationale in both) or the prose itself is promoted into a metadata
+    field.  Without it a board has no runner, so `west flash` has
+    nothing to flash with.
+  - `Kconfig` (the bare name, NOT the generated `Kconfig.<board>` /
+    `Kconfig.defconfig`).  It sets
+    `CPU_HAS_CUSTOM_FIXED_SOC_MPU_REGIONS default y`, which
+    `zephyr/CMakeLists.txt` uses to pull in the custom E8 MPU region
+    table (`zephyr/soc-bridge/alif/mpu_regions_e8.c`) via
+    `zephyr_sources_ifdef`.  Zephyr's `hwm_v2.cmake` unconditionally
+    `osource`s a bare `Kconfig` in a board directory whether or not it
+    exists, so it survives regeneration exactly as `board.cmake` does
+    -- and its absence is SILENT: the build succeeds and falls back to
+    Zephyr's generic 2-region FLASH_0/SRAM_0 map, whose whole-flash
+    FLASH_0 region is unsafe on Flow D (production MRAM boot).
+"""
+
+from __future__ import annotations
+
+import re
+import textwrap
+from pathlib import Path
+from typing import Any, NoReturn
+
+# NO module-scope `import json` any more (tan-cli#1162): `_load_soc_spec` was
+# its only user and now reads through `document_guards.read_json_mapping`.
+from tan.core.document_guards import DocumentGuards
+
+from .loader import _load_yaml
+from .project_loader import _resolve_sku
+from .sdk_capability import (
+    AEN_ATOC_RESERVATION,
+    AEN_SOM_POWER_DOMAINS,
+    AEN_ZEPHYR_PERIPHERALS_DTSI,
+    require_capability,
+)
+from .som_metadata import resolve_soc_path
+from .whole_device_alias import is_whole_device_alias
+
+
+def _is_tbd(value: Any) -> bool:
+    """True iff @p value is the `TBD` placeholder sentinel.
+
+    RELOCATED spelling of alp-sdk `scripts/sentinels.py::is_tbd` (alp-sdk
+    #1048), which has no counterpart under `tan/planner/`: it is imported
+    upstream from both `scripts/` and `alp_orchestrate/`, and relocating it
+    would add a module to the hand-port audit for one three-line function.
+    Compares case- and surrounding-whitespace-insensitively (`"tbd"`,
+    `"Tbd"`, `" TBD "` all match) but only on an exact match after that
+    normalisation -- `"TBD_RESERVED"` is a real value, not a placeholder.
+    """
+    return isinstance(value, str) and value.strip().upper() == "TBD"
+
+
+_COPYRIGHT_C = (
+    "/*\n"
+    " * Copyright (c) 2026 Alp Lab AB\n"
+    " * SPDX-License-Identifier: Apache-2.0\n"
+)
+_COPYRIGHT_HASH = (
+    "# Copyright (c) 2026 Alp Lab AB\n"
+    "# SPDX-License-Identifier: Apache-2.0\n"
+)
+
+
+class ZephyrBoardEmitError(ValueError):
+    """Raised when metadata needed for a requested board is missing."""
+
+
+#: The malformed-document register, bound to THIS module's curated class.
+_GUARDS = DocumentGuards(ZephyrBoardEmitError)
+
+
+# ---------------------------------------------------------------------
+# Family-agnostic naming + resolution
+# ---------------------------------------------------------------------
+
+
+def _load_soc_spec(sku_preset: dict[str, Any], metadata_root: Path) -> dict[str, Any]:
+    """The SoC JSON this SoM's `silicon:` ref names, as a mapping.
+
+    RELOCATED divergence from alp-sdk's own `scripts/alp_orchestrate/
+    zephyr_board.py` (tan-cli#1162): upstream still spells the last two
+    lines as an `is_file()` pre-flight plus a bare `json.loads(soc_path.
+    read_text(...))`. Read, parse and shape-check now go through
+    `tan/core/document_guards.py`'s register, for the reasons
+    `read_json_mapping` documents.
+
+    NOT on the `tan build` path, contrary to tan-cli#1162's own body, and
+    established by walking callers rather than assumed: the only caller is
+    `emit_zephyr_board` (this module), reached only through
+    `planner_emit.py:287`, so only from `tan generate --emit zephyr-board`.
+    `loader.py:385` and `secure.py:102` take `_aen_role_slot0_map` and two
+    constants from this module, never this function. The handler that
+    actually catches what this raises is `generate_cmd.py:890`'s
+    `except BaseException` -- coded, not a bare traceback, but naming the
+    exception class instead of the file.
+
+    `no SoC spec at <path>` is preserved byte for byte through `absent=`;
+    the shapes the pre-flight folded into it (a directory, a denied mode, a
+    symlink loop) now say `cannot read`, which is true where it was not.
+    """
+    silicon = sku_preset.get("silicon")
+    if not silicon:
+        raise ZephyrBoardEmitError(f"SoM {sku_preset.get('sku')!r} declares no silicon:")
+    soc_path = resolve_soc_path(silicon, metadata_root)
+    if soc_path is None:
+        raise ZephyrBoardEmitError(f"silicon ref {silicon!r} is not a triple-colon string")
+    return _GUARDS.read_json_mapping(
+        soc_path, what="SoC spec", absent=f"no SoC spec at {soc_path}")
+
+
+def _resolve_variant(sku_preset: dict[str, Any], soc_spec: dict[str, Any]) -> dict[str, Any]:
+    """Resolve the SoM preset's silicon variant against the SoC JSON.
+
+    A DECLARED `silicon_variant:` is authoritative and must name a real
+    `variants[].order_code` -- `docs/porting-new-som.md` says so.  When
+    it names none this raises instead of falling through to the
+    `alp_module_skus` reverse lookup: silently answering with a
+    different variant is how a typo (`...LS0` -> `...LSO`) or an
+    un-published silicon revision emits a whole board tree named after
+    a part number the preset does not declare, carrying the OLD
+    variant's `mram_mb` / DTCM size / board-target name -- exit 0, no
+    diagnostic.  Every other missing fact in this module raises; so
+    does this one.  The reverse lookup stays for presets that declare
+    no variant at all (or `TBD`).
+    """
+    declared = sku_preset.get("silicon_variant")
+    variants = soc_spec.get("variants") or []
+    if declared and not _is_tbd(declared):
+        for v in variants:
+            if v.get("order_code") == declared:
+                return v
+        known = ", ".join(str(v.get("order_code")) for v in variants) or "<none>"
+        raise ZephyrBoardEmitError(
+            f"SoM {sku_preset.get('sku')!r} declares silicon_variant "
+            f"{declared!r}, which is not an order_code in "
+            f"{soc_spec.get('ref')} variants[] ({known}) -- fix the preset, "
+            "or add the variant to the SoC JSON if this is new silicon")
+    sku = sku_preset.get("sku")
+    for v in variants:
+        if sku in (v.get("alp_module_skus") or []):
+            return v
+    raise ZephyrBoardEmitError(
+        f"can't resolve a silicon_variant for {sku_preset.get('sku')!r}")
+
+
+def _find_core(soc_spec: dict[str, Any], core_id: str) -> dict[str, Any]:
+    for c in soc_spec.get("cores", []):
+        if c.get("id") == core_id:
+            return c
+    raise ZephyrBoardEmitError(
+        f"core {core_id!r} not found in {soc_spec.get('ref')} cores[]")
+
+
+def _board_dir_name(sku: str, core_id: str) -> str:
+    """`E1M-AEN801` + `m55_hp` -> `alp_e1m_aen801_m55_hp`."""
+    if not sku.startswith("E1M-"):
+        raise ZephyrBoardEmitError(f"unrecognised SKU prefix: {sku!r}")
+    slug = sku[len("E1M-"):].lower()
+    return f"alp_e1m_{slug}_{core_id}"
+
+
+def _board_naming(
+    sku_preset: dict[str, Any], core_id: str, variant: dict[str, Any], core: dict[str, Any],
+) -> tuple[str, str, str, str]:
+    """Return (dir_name, cluster, variant_tag, basename)."""
+    dir_name = _board_dir_name(sku_preset["sku"], core_id)
+    cluster = core.get("zephyr_cpucluster")
+    if not cluster:
+        raise ZephyrBoardEmitError(
+            f"core {core_id!r} has no zephyr_cpucluster in its SoC spec entry -- "
+            "add one before generating this board (see soc-spec-v1.schema.json)")
+    variant_tag = (variant.get("zephyr_soc_variant") or variant["order_code"]).lower()
+    basename = f"{dir_name}_{variant_tag}_{cluster}"
+    return dir_name, cluster, variant_tag, basename
+
+
+def _topology_entry(sku_preset: dict[str, Any], core_id: str) -> dict[str, Any]:
+    topo = (sku_preset.get("topology") or {}).get(core_id)
+    if not topo:
+        raise ZephyrBoardEmitError(
+            f"SoM {sku_preset.get('sku')!r} has no topology.{core_id} entry")
+    return topo
+
+
+def _generated_banner(
+    style: str, sku: str, soc_json_rel: str, extra_source: str | None = None,
+) -> list[str]:
+    """3-line "auto-generated, do not edit" banner, matching the wording
+    convention `gen_soc_caps.py` uses for `include/alp/soc_caps.h`.
+
+    *extra_source* names an additional generation-authority file beyond the
+    SoM preset + SoC JSON -- the V2N/V2M pinctrl.dtsi/_defconfig read
+    `metadata/e1m_modules/v2n/supervisor-links.yaml` for every pad, PFC
+    triple and I2C address they emit, and a banner that omits it sends a
+    maintainer to two files that carry neither."""
+    c = " *" if style == "c" else "#"
+    sku_rel = f"metadata/e1m_modules/{sku}.yaml"
+    sources = f"{sku_rel} + {soc_json_rel}"
+    if extra_source:
+        sources += f" + {extra_source}"
+    return [
+        f"{c} Auto-generated by `scripts/alp_project.py --emit zephyr-board` from",
+        f"{c} {sources}.",
+        f"{c} DO NOT EDIT BY HAND -- regenerate.",
+    ]
+
+
+def _with_generated_banner(
+    content: str, style: str, sku: str, soc_json_rel: str,
+    extra_source: str | None = None,
+) -> str:
+    """Insert the generated-file banner into *content*.
+
+    - When *content* already opens with the standard Copyright/SPDX
+      header (every AEN file; the V2N-family Kconfig/twister files),
+      the banner is inserted right after the SPDX line, ahead of the
+      file's own prose -- purely additive, no existing line moves or
+      disappears.
+    - When *content* has no header at all (the V2N-family `board.yml`,
+      matching its committed hand-authored original -- see `_board_yml`),
+      the banner is prepended as a leading comment block instead.
+    """
+    lines = content.split("\n")
+    banner = _generated_banner(style, sku, soc_json_rel, extra_source)
+    if style == "c" and len(lines) >= 3 and lines[0] == "/*" and lines[1].startswith(" * Copyright"):
+        lines[3:3] = banner
+        return "\n".join(lines)
+    if style == "hash" and lines and lines[0].startswith("# Copyright"):
+        lines[2:2] = banner
+        return "\n".join(lines)
+    # No pre-existing header: prepend the banner as its own block.
+    return "\n".join(banner) + "\n" + content
+
+
+def _sku_family_slug(sku: str) -> str:
+    """AEN/V2N/V2M -- see `som_metadata._sku_family` (kept independent here, as
+    it was in alp-sdk, so this module carries no import-cycle risk on the fuller
+    SKU-family table; the two must agree, pinned by the test)."""
+    m = re.match(r"^E1M-(AEN|V2N|V2M)", sku)
+    if not m:
+        raise ZephyrBoardEmitError(f"unrecognised SoM SKU pattern: {sku!r}")
+    return {"AEN": "aen", "V2N": "v2n", "V2M": "v2n-m1"}[m.group(1)]
+
+
+# ---------------------------------------------------------------------
+# Family-agnostic files: board.yml, Kconfig.alp_<board>, twister .yaml
+# ---------------------------------------------------------------------
+
+
+def _board_yml(dir_name: str, full_name: str, variant_tag: str, family: str) -> str:
+    # Hand-authored inconsistency across families: AEN's board.yml carries
+    # the copyright header, the V2N-family one doesn't.  Preserved exactly
+    # rather than "fixed", per the byte-equivalence pin -- see the
+    # `--emit zephyr-board` module docstring.
+    header = _COPYRIGHT_HASH if family == "aen" else ""
+    return (
+        header +
+        "board:\n"
+        f"  name: {dir_name}\n"
+        f"  full_name: {full_name}\n"
+        "  vendor: alp\n"
+        "  socs:\n"
+        f"    - name: {variant_tag}\n"
+    )
+
+
+def _kconfig_board(dir_name: str, variant_tag: str, cluster: str) -> str:
+    soc_sym = f"SOC_{variant_tag.upper()}_{cluster.upper()}"
+    board_sym = dir_name.upper()
+    return (
+        _COPYRIGHT_HASH +
+        "\n"
+        f"config BOARD_{board_sym}\n"
+        f"\tselect {soc_sym}\n"
+    )
+
+
+def _aen_dtcm_kib(variant: dict[str, Any], core_id: str) -> int:
+    role = core_id.split("_")[-1].upper()  # "m55_hp" -> "HP"
+    banks = variant.get("sram_banks_kb") or {}
+    for name, size in banks.items():
+        if name.endswith(f"_{role}_DTCM"):
+            return int(size)
+    raise ZephyrBoardEmitError(
+        f"variant {variant.get('order_code')} sram_banks_kb has no *_{role}_DTCM entry")
+
+
+def _twister_yaml(
+    dir_name: str, variant_tag: str, cluster: str, twister_name: str,
+    family: str, sku_preset: dict[str, Any], core_id: str, variant: dict[str, Any],
+) -> str:
+    identifier = f"{dir_name}/{variant_tag}/{cluster}"
+    has_supervisor_mcu = bool((sku_preset.get("on_module") or {}).get("supervisor_mcu"))
+
+    if family == "aen":
+        ram_kib = _aen_dtcm_kib(variant, core_id)
+        flash_kib = round(float(variant["mram_mb"]) * 1024)
+        return (
+            f"identifier: {identifier}\n"
+            f"name: {twister_name}\n"
+            "type: mcu\n"
+            "arch: arm\n"
+            "vendor: alp\n"
+            "toolchain:\n"
+            "  - zephyr\n"
+            "  - gnuarmemb\n"
+            "supported:\n"
+            "  - uart\n"
+            f"ram: {ram_kib}\n"
+            f"flash: {flash_kib}\n"
+        )
+
+    # Non-AEN families: no on-die MRAM/TCM concept surfaced here (the A55
+    # cluster boots Linux from eMMC/xSPI; the M33 board file has no
+    # zephyr,flash of its own), so no ram:/flash:.  supported: lists only
+    # what the board dts leaves `status = "okay"` (audit CM33-14): the GD32
+    # bridge's SCI7 Simple-SPI plus its GPIO chip-select port.  RIIC8
+    # (A55/Linux-exclusive) and the sci0 console UART are disabled, so
+    # i2c/uart are not advertised.  Same PCB, same GD32 bridge on every
+    # current V2N-family SoM (porting-a-new-som "same-PCB families" rule).
+    supported = ["gpio", "spi"] if has_supervisor_mcu else []
+    lines = [
+        f"identifier: {identifier}",
+        f"name: {twister_name}",
+        "type: mcu",
+        "arch: arm",
+        "toolchain:",
+        "  - zephyr",
+        "  - gnuarmemb",
+        "supported:" if supported else "supported: []",
+    ]
+    lines += [f"  - {p}" for p in supported]
+    lines.append("vendor: alp")
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------
+# Alif Ensemble (aen) family -- fully generated
+# ---------------------------------------------------------------------
+
+# Fixed MCUboot flash-partition sizes for the AEN sysbuild profile
+# (MCUboot + a signed application image, swap-using-scratch).  These are
+# an SDK build-policy choice, not a per-chip hardware fact -- every AEN
+# SKU's on-die MRAM is split the same way regardless of total size, so
+# they stay generator constants rather than metadata fields; only the
+# two symmetric image slots derive from the variant's actual MRAM size.
+_AEN_MCUBOOT_KIB = 64
+_AEN_SCRATCH_KIB = 64
+_AEN_STORAGE_KIB = 96
+
+# The SE-owned band at the very TOP of the App MRAM window (alp-sdk#1289).
+#
+# Alif's SETOOLS (`app-gen-toc` / `app-write-mram`) does not place the ATOC
+# application table at a fixed address: it top-anchors the generated package
+# at the App MRAM window end and grows DOWNWARD, sized to the package. There
+# is therefore no compile-time constant to read -- the placement happens at
+# provisioning time, not link time -- so the layout has to reserve a band
+# rather than a specific address.
+#
+# 32 KiB covers the worst case with margin. Three independent figures, all
+# measured/derived against the same window top 0x80580000:
+#
+#   5552 B   observed on the E1M-AEN801 bench 2026-08-08 -- ATOC magic
+#            `ckBS` (0x53426B63) read at 0x8057EA50
+#   13552 B  an E7 SETOOLS transcript in the Alif DFP
+#            (alifsemi/alif_ensemble-cmsis-dfp, docs/Overview.md:193-224):
+#            package at 0x8057cb10
+#   23696 B  worst case computed from SETOOLS' own build/app-package-map.txt
+#            sizing rule -- 2560 B per signed user image + 2880 B fixed
+#            tool-managed + (48 + 32*N) TOC -- at the 8-image maximum. That
+#            rule reproduces the 5552 B observed above exactly.
+#
+# 32768 - 23696 = 9072 B spare at 8 images. UNVERIFIED: no documented
+# maximum TOC entry count could be found, so the 8-image worst case is an
+# assumption, not a specification -- widen this band rather than narrowing
+# it if a larger configuration ever appears.
+#
+# Taken OUT of storage (128 -> 96 + 32) rather than out of the image slots
+# on purpose: `_AEN_MCUBOOT_KIB + _AEN_SCRATCH_KIB + _AEN_STORAGE_KIB +
+# _AEN_ATOC_KIB` still sums to the old 256 KiB, so `image_kib` below is
+# unchanged and no committed AEN board's slot geometry moves.
+_AEN_ATOC_KIB = 32
+
+# Per-role documentation asymmetries in the committed AEN board tree.
+# These are prose choices (which sibling's ITCM comment got the
+# bench-verified annotation), not hardware facts -- like the comment
+# scaffolding in alp_project_emit._emit_dts_overlay / _emit_hw_info_h,
+# they live as generator template text keyed by role rather than as
+# metadata.
+_AEN_BENCH_KNOWN_ITCM = {"hp": False, "he": True}
+
+# Base of the Alif Ensemble on-die App MRAM window.  Family-wide, not
+# per-part: upstream Zephyr declares `mram: flash@80000000` in EVERY
+# Ensemble SoC dtsi (dts/arm/alif/ensemble/ae1c1f4051920ph0.dtsi,
+# ae402fa0e5597le0.dtsi, ae612fa0e5597ls0.dtsi, ae822fa0e5597ls0.dtsi),
+# and E1M-AEN801.yaml's `memory_map:` anchors its `mcuboot` region at the
+# same 0x80000000.  It is the soc-nv-flash child's offset-0 origin, so a
+# SoM whose map disagrees is REFUSED rather than emitted -- see
+# _aen_flash_partitions.
+_AEN_MRAM_BASE = 0x80000000
+
+
+def _aen_part(soc_spec: dict[str, Any]) -> str:
+    """The Ensemble part designator -- `"E8"`, `"E3"`, ... -- from the
+    SoC JSON's required `part` field.
+
+    Was a generator constant hardcoded to E8, which put "Alif Ensemble
+    E8" and `<alif/ensemble_e8_peripherals.dtsi>` into EVERY `E1M-AEN*`
+    board tree regardless of silicon.  `part` is `required` by
+    soc-spec-v1.schema.json, so there is nothing to guess.
+    """
+    part = soc_spec.get("part")
+    if not part or _is_tbd(part):
+        raise ZephyrBoardEmitError(
+            f"SoC spec {soc_spec.get('ref')} declares no usable `part` -- "
+            "the AEN board tree names it in prose and derives the SoC "
+            "peripherals overlay from it")
+    return str(part)
+
+
+def _aen_family_display(soc_spec: dict[str, Any]) -> str:
+    """Vendor-short + family + part, as used in AEN board-tree prose
+    ("Alif Ensemble E8").
+
+    `Alif` is fixed by the code path -- the `aen` family slug IS Alif
+    Ensemble -- because soc_spec's own `vendor:` field spells out the
+    legal name "Alif Semiconductor" for provenance blocks.  `family`
+    ("Ensemble") and `part` ("E8") are read from the SoC JSON, both
+    `required` by the schema.
+    """
+    family = soc_spec.get("family")
+    if not family or _is_tbd(family):
+        raise ZephyrBoardEmitError(
+            f"SoC spec {soc_spec.get('ref')} declares no usable `family`")
+    return f"Alif {family} {_aen_part(soc_spec)}"
+
+
+def _aen_peripherals_dtsi(soc_spec: dict[str, Any], metadata_root: Path) -> str:
+    """The `#include <...>` path of THIS SoC's Zephyr peripherals overlay.
+
+    Read from the SoC JSON's `zephyr_peripherals_dtsi`, never derived
+    from the part name: the overlay declares the SoC's actual peripheral
+    and NPU node set (the E8's includes `ethosu85`; an E3 has 2x U55 and
+    no U85), so including the wrong family's file produces a board that
+    builds and then misbehaves on silicon.  alp-sdk ships exactly one
+    today (`zephyr/dts/alif/ensemble_e8_peripherals.dtsi`), so every
+    other Ensemble part must add its own and declare it here rather than
+    inherit the E8's.
+
+    `zephyr_peripherals_dtsi` is itself a ported requirement (alp-sdk#1352,
+    tan-cli#591) that no released alp-sdk carries yet: an absent value
+    checks `require_capability` FIRST, so a checkout that predates the
+    field raises `SdkTooOldError` naming that, rather than the generic
+    authoring-gap message below, which only fires once the checkout is
+    proven new enough to know the field at all.
+    """
+    dtsi = soc_spec.get("zephyr_peripherals_dtsi")
+    if not dtsi or _is_tbd(dtsi):
+        require_capability(metadata_root, AEN_ZEPHYR_PERIPHERALS_DTSI)
+        raise ZephyrBoardEmitError(
+            f"SoC spec {soc_spec.get('ref')} "
+            f"({_aen_part(soc_spec)}) has no `zephyr_peripherals_dtsi` -- "
+            "the AEN board .dts must include this SoC's own peripherals "
+            "overlay, and alp-sdk ships one only for the E8 "
+            "(zephyr/dts/alif/ensemble_e8_peripherals.dtsi).  Add the "
+            "overlay under zephyr/dts/alif/ and declare it in the SoC "
+            "JSON before generating this board; do NOT fall back to "
+            "another part's file, whose peripheral and NPU node set is "
+            "different silicon")
+    return str(dtsi)
+
+
+def _aen_require_disjoint_slot0(
+    sku: str, sku_preset: "dict[str, Any]",
+    memory_map: "list[dict[str, Any]] | None",
+) -> None:
+    """Refuse a DUAL-M55 AEN SoM that declares no `<role>_slot0` window (#1446).
+
+    `_aen_role_slot0_map` returns None when no role declares one, which drops
+    the caller onto the stock SYMMETRIC layout -- `m55_he` and `m55_hp` slot0
+    at the same address, so flashing one core silently clobbers the other's
+    window. That is the #1069 defect, and it is how E1M-AEN301/401/501/601/701
+    shipped until alp-sdk#1445 gave them explicit maps.
+
+    The half-authored case (one role declares a window, its sibling does not)
+    already raises inside `_aen_role_slot0_map`. This closes the fully
+    unauthored case, which was silent.
+
+    Single-M55 SoMs are unaffected: with no sibling core there is nothing to
+    clobber, so the symmetric layout stays correct for them.
+
+    Costs nothing on the current corpus -- after alp-sdk#1445 every AEN SoM
+    declares disjoint windows, so this never fires today. Its value is the
+    NEXT dual-M55 AEN SoM, which is refused at authoring time instead of
+    discovered by someone flashing one core and losing the other's slot0 on
+    a bench.
+    """
+    if memory_map and any(
+        isinstance(r.get("name"), str) and r["name"].endswith("_slot0")
+        for r in memory_map
+    ):
+        return
+    cores = sku_preset.get("topology") or {}
+    m55 = sorted(c for c in cores if c in ("m55_he", "m55_hp"))
+    if len(m55) < 2:
+        return
+    raise ZephyrBoardEmitError(
+        f"SoM {sku!r} has two M55 cores ({', '.join(m55)}) but its preset "
+        f"declares no per-core `<role>_slot0` region, so both would boot from "
+        f"the SAME MRAM slot0 address -- flashing one core silently corrupts "
+        f"the other's slot0 window (#1069). Declare disjoint `he_slot0` / "
+        f"`hp_slot0` regions in this SoM preset's `memory_map:`; "
+        f"metadata/e1m_modules/E1M-AEN801.yaml is the shape to copy (#1446)."
+    )
+
+
+def _aen_role_slot0_map(
+    memory_map: "list[dict[str, Any]] | None", role: str,
+) -> "dict[str, Any] | None":
+    """Return this role's disjoint-slot0 memory_map entry, or None.
+
+    Dual-M55 AEN SoMs (#1069: both cores boot from the same physical App
+    MRAM) declare a `memory_map:` block in their SoM preset with one region
+    per core named `<role>_slot0` (`accessible_from: [m55_<role>]` only).
+    A SoM with only ONE M55 has no sibling to collide with and keeps the
+    stock symmetric two-slot layout -- see _aen_flash_partitions below.
+
+    #1446: this used to say the stock layout also covered "single-M55
+    aen401/aen601". Both of those are DUAL-M55 -- measured from their own
+    presets, E1M-AEN401 is [m55_he, m55_hp] and E1M-AEN601 is
+    [a32_cluster, m55_he, m55_hp] -- so that sentence was the justification
+    for a silent fallback that put two cores' slot0 at one address, and it
+    is why five shipping SoMs carried a clobbering layout until
+    alp-sdk#1445. `_aen_require_disjoint_slot0` now refuses that state
+    outright; this function keeps returning None only for the genuinely
+    single-M55 case.
+
+    Returning None is only legitimate when NO role declares a slot0
+    window.  A map that declares a SIBLING core's `<role>_slot0` but not
+    this one's is a half-authored map, and answering None for it drops
+    the caller onto the stock symmetric layout, whose `slot0_partition`
+    lands exactly on top of the sibling's declared window -- silently
+    undoing the #1069 disjoint-window fix and re-creating the
+    bench-confirmed corruption it exists to prevent.  So that state
+    RAISES.
+    """
+    if not memory_map:
+        return None
+    suffix = "_slot0"
+    declared_roles = [
+        str(r["name"])[: -len(suffix)]
+        for r in memory_map
+        if isinstance(r.get("name"), str) and r["name"].endswith(suffix)
+    ]
+    if not declared_roles:
+        return None
+    core_id = f"m55_{role}"
+    for region in memory_map:
+        if region.get("name") != f"{role}{suffix}":
+            continue
+        if region.get("accessible_from") != [core_id]:
+            raise ZephyrBoardEmitError(
+                f"AEN memory_map region '{role}{suffix}' must declare "
+                f"accessible_from: [{core_id}] (a disjoint per-core slot0 "
+                f"window is reachable from exactly one core); it declares "
+                f"{region.get('accessible_from')!r}")
+        return region
+    raise ZephyrBoardEmitError(
+        f"AEN memory_map declares a disjoint slot0 window for "
+        f"{sorted(declared_roles)} but none for role {role!r} -- add a "
+        f"'{role}{suffix}' region (accessible_from: [{core_id}]).  "
+        "Falling back to the stock symmetric layout here would place this "
+        "core's slot0_partition on top of the sibling's declared window "
+        "(#1069)")
+
+
+def _aen_check_extents(
+    partitions: "list[tuple[str, int, int]]", total_kib: int, where: str,
+) -> None:
+    """Every emitted partition must fit inside the flash node it is emitted
+    into, and no two may overlap.
+
+    Neither branch used to check this.  The stock branch's
+    `offset != total_kib * 1024` sum assertion is NOT a fits-in-MRAM
+    check -- all five stock sizes derive from `total_kib`, so it is a
+    tautology that can never fire.  The disjoint branch copied `base` /
+    `size_kib` verbatim out of the SoM preset and checked only that each
+    region existed with an integer `base`, so a mis-authored map emitted
+    a `partition@` node outside its own `mram_storage` `reg` -- MCUboot's
+    flash_map and the alif MRAM driver would then compute erase/program
+    addresses past the end of the device.
+    """
+    limit = total_kib * 1024
+    ordered = sorted(partitions, key=lambda p: p[1])
+    prev_label, prev_end = None, 0
+    for label, off, size_kib in ordered:
+        if not isinstance(size_kib, int) or size_kib <= 0:
+            raise ZephyrBoardEmitError(
+                f"{where}: partition {label!r} has a non-positive size "
+                f"({size_kib!r} KiB)")
+        end = off + size_kib * 1024
+        if off < 0 or end > limit:
+            raise ZephyrBoardEmitError(
+                f"{where}: partition {label!r} spans "
+                f"0x{off:x}..0x{end:x} but the mram_storage flash node is "
+                f"only {total_kib} KiB (0x0..0x{limit:x}) -- the partition "
+                "would sit outside the flash device it is declared in")
+        if off < prev_end:
+            raise ZephyrBoardEmitError(
+                f"{where}: partition {label!r} at 0x{off:x} overlaps "
+                f"{prev_label!r}, which ends at 0x{prev_end:x}")
+        prev_label, prev_end = label, end
+
+
+def _aen_check_map_overlaps(
+    memory_map: "list[dict[str, Any]]", mram_base: int, total_kib: int,
+) -> None:
+    """Cross-check the WHOLE declared `memory_map:`, not just the regions
+    this core's partition table happens to name.
+
+    The sibling core's `<role>_slot0` window is not a partition here, so
+    _aen_check_extents cannot see a map that overlaps it; this can.
+    Regions with a non-integer `base` (a `TBD` sentinel) are skipped --
+    they are declarations of intent, not placements. No shipped AEN
+    preset authors one today (#2053 resolved the last holdout,
+    `mram_main`, on all seven), but the skip stays live for any future
+    region or preset that does.
+
+    A region whose resolved extent equals the App MRAM window EXACTLY
+    (the whole-device alias -- `mram_main`, on every AEN preset since
+    #2053 resolved its `base` off the `"TBD"` sentinel) is excluded from
+    the pairwise overlap comparison below -- it deliberately spans the
+    same window `mcuboot` /
+    `he_slot0` / `hp_slot0` / `reserved` / `storage` / `atoc` subdivide,
+    so comparing it against its own partitions would flag every one of
+    them. `whole_device_alias.is_whole_device_alias()` carries the
+    identical "extent == aperture exactly" predicate `classify_region()`
+    and `is_partition_inside_aperture()` (`tan/planner/aperture.py`)
+    already use for this same case --
+    imported by both from one sibling module, whose own docstring
+    records why it stays a separate file, so those two can't drift
+    (alp-sdk#2073). Upstream additionally records that alp-sdk's own
+    `check_atoc_reservation.py` hand-writes this same comparison instead
+    of importing it; tan relocates no counterpart of that gate, so that
+    gap is alp-sdk's alone and the call sites named above are the whole
+    surface here. The exclusion is bounds-checked like every other row
+    and applies to nothing looser than an exact match: a region that
+    merely CONTAINS another without matching the aperture exactly still
+    overlaps and is still refused below; and more than one row matching
+    the aperture exactly is refused outright, not silently allowed to
+    co-exist unchecked against each other.
+    """
+    placed = [
+        (str(r.get("name")), r["base"], int(r["size_kib"]))
+        for r in memory_map
+        if isinstance(r.get("base"), int) and isinstance(r.get("size_kib"), int)
+    ]
+    limit = mram_base + total_kib * 1024
+    aperture = (mram_base, limit)
+    for name, base, size_kib in placed:
+        end = base + size_kib * 1024
+        if base < mram_base or end > limit:
+            raise ZephyrBoardEmitError(
+                f"AEN memory_map region {name!r} spans "
+                f"0x{base:x}..0x{end:x}, outside the {total_kib} KiB App "
+                f"MRAM window 0x{mram_base:x}..0x{limit:x} declared by this "
+                "variant's mram_mb")
+    aliases = [
+        (name, base, size_kib) for name, base, size_kib in placed
+        if is_whole_device_alias((base, base + size_kib * 1024), aperture)
+    ]
+    if len(aliases) > 1:
+        alias_names = ", ".join(repr(name) for name, _b, _s in aliases)
+        raise ZephyrBoardEmitError(
+            f"AEN memory_map declares {len(aliases)} regions ({alias_names}) "
+            f"whose extent equals the {total_kib} KiB App MRAM window "
+            f"0x{mram_base:x}..0x{limit:x} exactly -- only one whole-device "
+            "alias to the App MRAM window is allowed; rename or remove the "
+            "duplicate(s).")
+    overlap_candidates = [row for row in placed if row not in aliases]
+    overlap_candidates.sort(key=lambda r: r[1])
+    for (a_name, a_base, a_kib), (b_name, b_base, _b_kib) in zip(
+            overlap_candidates, overlap_candidates[1:]):
+        a_end = a_base + a_kib * 1024
+        if b_base < a_end:
+            raise ZephyrBoardEmitError(
+                f"AEN memory_map regions {a_name!r} (ends 0x{a_end:x}) and "
+                f"{b_name!r} (starts 0x{b_base:x}) overlap")
+
+
+def _aen_slot0_sizes_display(memory_map: "list[dict[str, Any]]") -> str:
+    """`"HE 2688 KiB + HP 2688 KiB"` -- every declared per-core code slot,
+    in `memory_map:` declaration order.
+
+    The #1069 rationale sentence in the generated `.dts` used to carry
+    the AEN801-only literals "both 2688 KiB code slots fit the 5632 KiB
+    App MRAM alongside the ~2.6 MiB NPU MRAM-model budget" unconditionally,
+    ~100 lines above a partition map derived from this same
+    `memory_map:` -- so any dual-M55 AEN SoM with different slot sizes
+    emitted a board file stating its MRAM budget two contradictory ways,
+    with the prose (the part an engineer sizing an NPU model reads)
+    being the wrong one.  The `~2.6 MiB` figure is a policy number from
+    `zephyr/sysbuild/aen/README.md` that no generator input carries, so
+    it is not interpolated -- the sentence points at the README instead.
+    """
+    suffix = "_slot0"
+    parts = [
+        f"{str(r['name'])[: -len(suffix)].upper()} {r['size_kib']} KiB"
+        for r in memory_map
+        if isinstance(r.get("name"), str) and r["name"].endswith(suffix)
+    ]
+    return " + ".join(parts)
+
+
+def _aen_raise_missing_region(
+    region_name: str, label: str, metadata_root: Path,
+) -> NoReturn:
+    """Raise the right refusal for a missing disjoint-slot0 region.
+
+    `atoc` is a ported requirement (alp-sdk#1289, tan-cli#591) that no
+    released alp-sdk carries yet: checked FIRST, via `require_capability`
+    against the bound checkout's OWN `metadata/quality-tasks-v1.json`
+    registry -- never against the shape of THIS SoM preset's map.  A
+    checkout that doesn't know the concept raises `SdkTooOldError` naming
+    it; only once the checkout is proven new enough does an absent `atoc`
+    region fall through to the generic authoring-gap message below, same as
+    every other region name.
+
+    This used to be a heuristic instead: "every OTHER required region is
+    present and placed, so this preset is a complete pre-#1289 layout" --
+    inferring the checkout's vintage from the shape of one board's map.
+    Imprecise by construction (a hand-edited preset that merely LOOKS
+    pre-#1289-shaped hit the same wording as a genuinely old checkout);
+    `require_capability` answers the real question directly instead.
+    """
+    if region_name == "atoc":
+        require_capability(metadata_root, AEN_ATOC_RESERVATION)
+    raise ZephyrBoardEmitError(
+        f"AEN disjoint-slot0 memory_map is missing an integer-`base` "
+        f"region named {region_name!r} (needed for {label!r}) -- this SoM "
+        "preset's `memory_map:` is incomplete; add the region, or drop the "
+        "per-core `<role>_slot0` windows to fall back to the stock "
+        "symmetric two-slot layout")
+
+
+def _aen_flash_partitions(
+    total_kib: int, metadata_root: Path, role: str | None = None,
+    memory_map: "list[dict[str, Any]] | None" = None,
+) -> "tuple[int, list[tuple[str, int, int]]]":
+    """Return (mram_base, [(label, offset_bytes, size_kib), ...]).
+
+    *metadata_root* is threaded through to `_aen_raise_missing_region`,
+    which needs it to answer "does the bound alp-sdk checkout know about
+    `atoc` at all" before blaming this SoM preset for omitting it
+    (tan-cli#591).
+
+    *mram_base* is the absolute address the emitted `mram_storage`
+    soc-nv-flash child is anchored at, i.e. the origin every returned
+    offset is relative to.  It is returned rather than re-derived by the
+    caller so the DTS node address and the partition offsets can never
+    disagree -- `_aen_dts` used to write the node address as a hardcoded
+    `0x80000000` literal while the offsets came from the metadata base.
+
+    Stock layout (no per-role memory_map entry for *role*): the
+    original symmetric two-slot MCUboot swap-using-scratch map --
+    mcuboot, image-0 (primary/code-partition), image-1 (secondary,
+    OTA), scratch, storage -- unchanged. This now applies only to a
+    genuinely single-M55 AEN SoM that declares no `<role>_slot0`
+    region. E1M-AEN401 and E1M-AEN601 are DUAL-M55 (see
+    `_aen_role_slot0_map` above) and have generated the disjoint-slot0
+    layout below since alp-sdk#1445 -- `_aen_require_disjoint_slot0` refuses
+    to let a dual-M55 SoM fall back to this stock layout at all
+    (alp-sdk#1482, tan-cli#896: docstring-only re-sync, "still what
+    every single-M55 AEN SKU (aen401, aen601) generates" was stale
+    prose, not a behavioural gap -- both SKUs already generated the
+    disjoint layout below).
+
+    Disjoint-slot0 layout (*role*'s `<role>_slot0` memory_map entry is
+    declared, #1069): mcuboot, this role's own slot0 (labelled
+    "image-0" so downstream label maps / the `image_kib` lookup in
+    _aen_dts don't need a second code path), reserved (the ex-scratch
+    headroom, unused -- OTA is deferred since a swap-sized second slot
+    on both cores no longer fits the MRAM budget), storage, atoc. No
+    image-1: this is CONFIG_SINGLE_APPLICATION_SLOT=y (see
+    zephyr/sysbuild/aen/README.md), the only silicon-proven MCUboot
+    mode on this part. The OTHER role's slot0 lives outside this
+    table entirely (a disjoint physical window this board never
+    touches) -- see metadata/e1m_modules/E1M-AEN801.yaml `memory_map:`
+    for the full 6-region physical map.
+
+    BOTH layouts end in `atoc` (alp-sdk#1289) -- the SE-owned band SETOOLS
+    top-anchors the ATOC application table into. It is a declared,
+    named region precisely so no app can mount NVS or a filesystem on
+    top of the boot table: before this, the last region was `storage`
+    in both branches, and on the bench a slot0 app happily erased
+    inside it while the live ATOC sat 0x1EA50 further up the SAME
+    partition. Keep `atoc` last in both paths; see _AEN_ATOC_KIB for
+    the sizing evidence.
+    """
+    slot0_region = _aen_role_slot0_map(memory_map, role) if role else None
+    if slot0_region is not None:
+        by_name = {r["name"]: r for r in memory_map}
+        mcuboot_region = by_name.get("mcuboot")
+        if mcuboot_region is None or not isinstance(mcuboot_region.get("base"), int):
+            raise ZephyrBoardEmitError(
+                "AEN disjoint-slot0 memory_map is missing an integer-`base` "
+                "'mcuboot' region -- its base anchors the soc-nv-flash "
+                "child's offset-0 origin")
+        mram_base = mcuboot_region["base"]
+        if mram_base != _AEN_MRAM_BASE:
+            raise ZephyrBoardEmitError(
+                f"AEN memory_map anchors 'mcuboot' at 0x{mram_base:x}, but "
+                f"the Ensemble App MRAM window starts at "
+                f"0x{_AEN_MRAM_BASE:x} (upstream Zephyr declares `mram: "
+                "flash@80000000` in every ensemble SoC dtsi).  The mcuboot "
+                "base IS the soc-nv-flash child's offset-0 origin, so a map "
+                "that starts elsewhere would place every partition at the "
+                "wrong absolute address")
+        _aen_check_map_overlaps(memory_map, mram_base, total_kib)
+        out: list[tuple[str, int, int]] = []
+        for label, region_name in (
+            ("mcuboot", "mcuboot"),
+            ("image-0", f"{role}_slot0"),
+            ("reserved", "reserved"),
+            ("storage", "storage"),
+            ("atoc", "atoc"),
+        ):
+            region = by_name.get(region_name)
+            if region is None or not isinstance(region.get("base"), int):
+                _aen_raise_missing_region(region_name, label, metadata_root)
+            out.append((label, region["base"] - mram_base, region["size_kib"]))
+        _aen_check_extents(out, total_kib, "AEN disjoint-slot0 memory_map")
+        return mram_base, out
+
+    reserved = (_AEN_MCUBOOT_KIB + _AEN_SCRATCH_KIB + _AEN_STORAGE_KIB
+                + _AEN_ATOC_KIB)
+    remaining = total_kib - reserved
+    if remaining <= 0 or remaining % 2:
+        raise ZephyrBoardEmitError(
+            f"AEN MRAM size {total_kib} KiB doesn't split evenly into two "
+            f"image slots after reserving {reserved} KiB for "
+            "mcuboot/scratch/storage/atoc")
+    image_kib = remaining // 2
+
+    offset = 0
+    out: list[tuple[str, int, int]] = []
+    for label, size_kib in (
+        ("mcuboot", _AEN_MCUBOOT_KIB),
+        ("image-0", image_kib),
+        ("image-1", image_kib),
+        ("image-scratch", _AEN_SCRATCH_KIB),
+        ("storage", _AEN_STORAGE_KIB),
+        # LAST, and must stay last: this is the band SETOOLS top-anchors the
+        # ATOC into (alp-sdk#1289).  The `offset != total_kib * 1024`
+        # assertion below is what keeps it flush against the window top.
+        ("atoc", _AEN_ATOC_KIB),
+    ):
+        out.append((label, offset, size_kib))
+        offset += size_kib * 1024
+    if offset != total_kib * 1024:
+        raise ZephyrBoardEmitError("AEN flash partition arithmetic didn't sum to total")
+    _aen_check_extents(out, total_kib, "AEN stock two-slot layout")
+    return _AEN_MRAM_BASE, out
+
+
+def _aen_console_pinmux_rows(metadata_root: Path) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Return (rx_row, tx_row) for the E1M `UART0` pad from `pinmux/aen.yaml`."""
+    pm = _load_yaml(metadata_root / "pinmux" / "aen.yaml")
+    rows = {r.get("e1m_function"): r for r in (pm.get("pads") or [])
+            if r.get("e1m_function") in ("UART0_TX", "UART0_RX")}
+    if "UART0_RX" not in rows or "UART0_TX" not in rows:
+        raise ZephyrBoardEmitError(
+            "metadata/pinmux/aen.yaml has no UART0_TX/UART0_RX rows for the "
+            "E1M console pad")
+    return rows["UART0_RX"], rows["UART0_TX"]
+
+
+def _pin_macro(row: dict[str, Any]) -> str:
+    return f"PIN_{row['silicon_pad']}__{row['silicon_peripheral']}"
+
+
+def _uart_node_label(row: dict[str, Any]) -> str:
+    m = re.match(r"^([A-Za-z]+\d+)", row["silicon_peripheral"])
+    if not m:
+        raise ZephyrBoardEmitError(
+            "can't derive a UART node label from silicon_peripheral "
+            f"{row['silicon_peripheral']!r}")
+    return m.group(1).lower()
+
+
+# ---------------------------------------------------------------------
+# AEN on-module (non-edge) links: BRD_I2C + its devices, the RTC alarm
+# ---------------------------------------------------------------------
+
+
+def _load_aen_on_module_links(metadata_root: Path) -> dict[str, Any]:
+    """Load + shape-check `metadata/e1m_modules/aen/on-module-links.yaml`.
+
+    The AEN counterpart of `_load_supervisor_links()`, and the ONLY
+    authority for pads that reach no E1M edge pin: `metadata/pinmux/aen.yaml`
+    is a generated projection of the EDGE pad TSVs and carries no row for
+    P7_0 / P7_1 (BRD_I2C) or P15_0 (RTC_ALARM), which run SoC <-> on-module
+    chip and never leave the module.  `e1m_i2c0` (SoC I2C2) is the one
+    exception -- its pads DO have an edge row (it also reaches the EVK
+    carrier's sensor bus), but its DT-node shape lives here too because the
+    SoM's own 24C128 manifest EEPROM sits on the same physical bus (see the
+    `e1m_i2c0` entry's own comment in on-module-links.yaml).  Family-scoped
+    -- one file backs every AEN SKU and both M55 cores.
+    """
+    path = metadata_root / "e1m_modules" / "aen" / "on-module-links.yaml"
+    if not path.is_file():
+        raise ZephyrBoardEmitError(
+            f"no {path} -- the AEN pinctrl.dtsi/.dts emitters need the "
+            "on-module pad + device source (BRD_I2C, e1m_i2c0, the RV-3028 "
+            "alarm)")
+    doc = _load_yaml(path)
+    links = doc.get("on_module_links")
+    if not isinstance(links, dict):
+        raise ZephyrBoardEmitError(f"{path} has no on_module_links: block")
+    for key in ("brd_i2c", "e1m_i2c0", "rtc_alarm"):
+        if key not in links:
+            raise ZephyrBoardEmitError(
+                f"{path} on_module_links: is missing {key!r}")
+    risk = links["rtc_alarm"].get("risk")
+    if risk is not None and not isinstance(risk, dict):
+        raise ZephyrBoardEmitError(
+            f"{path} on_module_links.rtc_alarm.risk must be a map keyed by "
+            "SoC `part` designator (e.g. {\"E8\": \"...\"}), not a bare "
+            "string -- a part-scoped risk note needs the part key (#1988)")
+    bench_validation = links["e1m_i2c0"].get("bench_validation")
+    if bench_validation is not None and not isinstance(bench_validation, dict):
+        raise ZephyrBoardEmitError(
+            f"{path} on_module_links.e1m_i2c0.bench_validation must be a map "
+            "keyed by SoC `part` designator (e.g. {\"E8\": \"...\"}), not a "
+            "bare string -- a part-scoped bench note needs the part key "
+            "(#2046, following #1988's pattern)")
+    return links
+
+
+def _c_comment(text: str, indent: str, width: int = 79) -> list[str]:
+    """Reflow a metadata `evidence:` / `risk:` string into a C block comment.
+
+    Keeps the prose in the YAML (one source per hardware fact) instead of
+    duplicating it as template text here.
+    """
+    body = " ".join(text.split())
+    prefix = f"{indent} * "
+    wrapped = textwrap.wrap(body, width=width - len(prefix)) or [""]
+    return [f"{indent}/*"] + [f"{prefix}{line}".rstrip() for line in wrapped] + [f"{indent} */"]
+
+
+def _dt_property(name: str, value: Any) -> str:
+    """One devicetree property line from a metadata `properties:` entry."""
+    if isinstance(value, bool):
+        if not value:
+            raise ZephyrBoardEmitError(
+                f"on-module-links.yaml property {name!r}: `false` has no "
+                "devicetree meaning -- omit the property instead")
+        return f"{name};"
+    if isinstance(value, int):
+        return f"{name} = <{value}>;"
+    if isinstance(value, str):
+        return f'{name} = "{value}";'
+    raise ZephyrBoardEmitError(
+        f"on-module-links.yaml property {name!r}: unsupported value type "
+        f"{type(value).__name__}")
+
+
+def _aen_i2c_device_nodes(
+    bus: dict[str, Any], links: dict[str, Any], indent: str = "\t",
+) -> list[str]:
+    """The `&i2c0` child nodes for the on-module devices, from metadata.
+
+    Only devices the metadata actually lists get a node -- the DNP=1 OPTIGA
+    Trust M is absent from `devices:` for exactly that reason, so it can
+    never be emitted as a phantom node.
+    """
+    lines: list[str] = []
+    for dev in bus.get("devices") or []:
+        lines.append("")
+        if dev.get("evidence"):
+            lines += _c_comment(dev["evidence"], indent)
+        lines.append(f"{indent}{dev['node_label']}: {dev['node_name']} {{")
+        lines.append(f'{indent}\tcompatible = "{dev["compatible"]}";')
+        lines.append(f"{indent}\treg = <{dev['address_7bit']:#04x}>;")
+        for name, value in (dev.get("properties") or {}).items():
+            lines.append(f"{indent}\t{_dt_property(name, value)}")
+        int_link = dev.get("int_gpio_link")
+        if int_link:
+            alarm = links[int_link]
+            flag = "GPIO_ACTIVE_LOW" if alarm.get("active_low") else "GPIO_ACTIVE_HIGH"
+            lines.append(
+                f"{indent}\tint-gpios = <&{alarm['gpio_node']} "
+                f"{alarm['gpio_pin']} {flag}>;")
+        lines.append(f"{indent}}};")
+    return lines
+
+
+def _aen_pinctrl_dtsi(
+    role: str, sku_display: str, rx_row: dict[str, Any], tx_row: dict[str, Any],
+    family_display: str, links: dict[str, Any], part: str,
+) -> str:
+    other_role = "he" if role == "hp" else "hp"
+    rx_macro, tx_macro = _pin_macro(rx_row), _pin_macro(tx_row)
+    uart_node = _uart_node_label(rx_row)
+
+    if role == "hp":
+        confirm_block = (
+            f" * (In an {other_role.upper()}+{role.upper()} AMP image the two cores share this single physical console;\n"
+            " * during bring-up each core is flashed/run independently.)  Confirmed against\n"
+            " * the SoM netlist + metadata/e1m_modules/aen/from-alif.tsv.\n"
+        )
+    else:
+        confirm_block = (
+            " * Confirmed against the SoM netlist + metadata/e1m_modules/aen/from-alif.tsv\n"
+            f" * (rows {tx_row['e1m_pad']} = {tx_row['e1m_function']} = "
+            f"{tx_row['silicon_peripheral']}/{tx_row['silicon_pad']}, "
+            f"{rx_row['e1m_pad']} = {rx_row['e1m_function']} = "
+            f"{rx_row['silicon_peripheral']}/{rx_row['silicon_pad']}).\n"
+        )
+
+    return (
+        _COPYRIGHT_C +
+        " *\n"
+        f" * {sku_display} ({family_display}) Cortex-M55-{role.upper()} carrier pin control.\n"
+        " *\n"
+        " * Console: the E1M edge \"UART0\" maps to Alif "
+        f"{uart_node.upper()} ({rx_row['silicon_pad']} RX_A / "
+        f"{tx_row['silicon_pad']} TX_A) on\n"
+        " * the AEN module PCB; the Alp E1M-EVK carrier wires its USB-UART console to it.\n"
+        + confirm_block +
+        " *\n"
+        " *\n"
+        " * BRD_I2C (SoC I2C0, function C) is wired here too: it is an ON-MODULE bus\n"
+        " * carrying SoM-resident parts (RTC + temperature sensor), present on every\n"
+        " * board built from this SoM -- not a per-app choice, so it belongs in the\n"
+        " * board layer rather than in each consumer's overlay.  Pads, macros and pad\n"
+        " * config come from metadata/e1m_modules/aen/on-module-links.yaml.\n"
+        " *\n"
+        " * SoC I2C2 (function C, portable alp-i2c0) is wired here too, for the same\n"
+        " * reason: the SoM's own 24C128 manifest EEPROM is bridge/DNP-selected onto\n"
+        " * it, so every board built from this SoM needs the controller enabled --\n"
+        " * even though the same pads also carry the EVK carrier's sensor bus once\n"
+        " * they leave the module (docs/bring-up-aen.md Sec 5.1).\n"
+        " *\n"
+        " * Remaining GPIO / SPI / Ethernet pin groups are added alongside their\n"
+        " * drivers (the alp-sdk Alif peripheral drivers).\n"
+        " */\n"
+        "\n"
+        "#include <zephyr/dt-bindings/pinctrl/alif-ensemble-pinctrl.h>\n"
+        "\n"
+        "&pinctrl {\n"
+        f"\tpinctrl_{uart_node}: pinctrl_{uart_node} {{\n"
+        "\t\tgroup0 {\n"
+        f"\t\t\tpinmux = <{rx_macro}>;\n"
+        "\t\t\tinput-enable;\n"
+        "\t\t};\n"
+        "\n"
+        "\t\tgroup1 {\n"
+        f"\t\t\tpinmux = <{tx_macro}>;\n"
+        "\t\t};\n"
+        "\t};\n"
+        "\n"
+        + _aen_i2c_pinctrl_group(links) +
+        "\n"
+        + _aen_e1m_i2c0_pinctrl_group(links, part) +
+        "};\n"
+    )
+
+
+def _aen_i2c_pinctrl_group(links: dict[str, Any]) -> str:
+    """The BRD_I2C pinctrl group (+ the RTC alarm pad), from metadata.
+
+    The alarm pad rides in THIS group rather than one of its own because
+    `snps,designware-gpio` (the lpgpio controller's binding) has no
+    `pinctrl-0` property: on Alif the pad input buffer is a PADCTRL bit only
+    pinctrl can set, gpio_dw drives direction in the controller and never
+    touches the pad, so an un-referenced group would simply never be applied
+    and the alarm line would read 0 forever.  Same pattern as P2_6 (the
+    CC3501E READY input) riding in `pinctrl_spi1`.
+    """
+    bus = links["brd_i2c"]
+    alarm = links["rtc_alarm"]
+    sda = _pin_by_peripheral(bus["pins"], "I2C0_SDA_C")
+    scl = _pin_by_peripheral(bus["pins"], "I2C0_SCL_C")
+    return (
+        "\t/*\n"
+        f"\t * {sda['net'].rsplit('_', 1)[0]} = SoC {bus['peripheral']} function C: "
+        f"{sda['silicon_pad']} {sda['net'].rsplit('_', 1)[-1]} / "
+        f"{scl['silicon_pad']} {scl['net'].rsplit('_', 1)[-1]},\n"
+        "\t * the on-module housekeeping bus (see the board .dts for the parts on it).\n"
+        "\t *\n"
+        "\t * BOTH pins get input-enable, in one group -- Alif's own DFP sets\n"
+        f"\t * PADCTRL_READ_ENABLE on {sda['silicon_pad']} AND {scl['silicon_pad']}.  "
+        "With it on SDA only, the\n"
+        "\t * i2c_dw controller cannot SENSE SCL (clock-stretch detect / arbitration)\n"
+        "\t * and NACKs every address for a reason that looks electrical but is not.\n"
+        "\t *\n"
+        "\t * bias-pull-up is DSC=1, a REAL pull-up: pinctrl_soc.h's field comment\n"
+        "\t * (soc/alif/ensemble/pinctrl_soc.h:24) and its ALIF_PINCTRL_BIAS_CFG()\n"
+        "\t * macro (:44-48) both map bias-pull-up -> DSC=1 unconditionally -- there\n"
+        "\t * is NO inversion between the devicetree property and the DSC field, on\n"
+        "\t * this bus or the e1m_i2c0 one below (#2046 corrected that group's\n"
+        "\t * comment, which used to claim the opposite).  Do NOT copy the\n"
+        "\t * I2C2/EEPROM overlay's bias-pull-down: DSC=2 is a pull-DOWN, harmless\n"
+        "\t * there only because that bus has external carrier pull-ups (R137/R144).\n"
+        "\t * This net has NO external pull-up at all, so a pull-down would park both\n"
+        "\t * lines low and look like a busy bus.\n"
+        "\t *\n"
+        "\t * drive-open-drain is deliberately NOT set, so bit 23 [DRV] stays 0 =\n"
+        "\t * PUSH-PULL: the pad actively drives the high phase instead of relying on\n"
+        "\t * a pull-up this net does not have.  input-schmitt-enable + max\n"
+        "\t * drive-strength/slew-rate cover the resulting slow edges.  Bench-proven\n"
+        "\t * 2026-09-05 on E1M-AEN801 2626-R2: every non-response is a clean rc=-5\n"
+        "\t * (-EIO) NACK, zero -ETIMEDOUT, zero \"User Abort\".\n"
+        "\t */\n"
+        f"\t{bus['pinctrl_group_label']}: {bus['pinctrl_group_label']} {{\n"
+        "\t\tgroup0 {\n"
+        f"\t\t\tpinmux = <{_pin_macro(sda)}>, <{_pin_macro(scl)}>;\n"
+        "\t\t\tinput-enable;\n"
+        "\t\t\tbias-pull-up;\n"
+        "\t\t\tinput-schmitt-enable;\n"
+        "\t\t\tdrive-strength = <12>;\n"
+        "\t\t\tslew-rate = \"fast\";\n"
+        "\t\t};\n"
+        "\n"
+        "\t\t/*\n"
+        f"\t\t * {alarm['net']}: the RV-3028 /INT line on {alarm['silicon_pad']} "
+        f"({alarm['gpio_node']} bit {alarm['gpio_pin']}).\n"
+        "\t\t * Muxed + input-enabled here because snps,designware-gpio has no\n"
+        "\t\t * pinctrl-0 of its own (see this function's docstring); without it the\n"
+        "\t\t * pad input buffer stays off and the alarm reads 0 forever.\n"
+        "\t\t */\n"
+        "\t\tgroup1 {\n"
+        f"\t\t\tpinmux = <{_pin_macro(alarm)}>;\n"
+        "\t\t\tinput-enable;\n"
+        "\t\t};\n"
+        "\t};\n"
+    )
+
+
+def _aen_e1m_i2c0_pinctrl_group(links: dict[str, Any], part: str) -> str:
+    """The `e1m_i2c0` (SoC I2C2) pinctrl group, from metadata.
+
+    Unlike `_aen_i2c_pinctrl_group()` this bus carries NO alarm-style
+    passenger pad and gets NO device child nodes in `_aen_e1m_i2c0_dts()`
+    below (its only genuinely on-module device, the 24C128 EEPROM, is
+    addressed by 7-bit address over the bus, not a DT device node -- see
+    the `e1m_i2c0` entry's own comment in on-module-links.yaml).
+
+    `bias-pull-down` here is intentional and matches Alif's own reference
+    I2C pinctrl (metadata says why).  `part` (the Ensemble part designator
+    this board tree is for, e.g. "E8") picks which of on_module_links'
+    `e1m_i2c0.bench_validation` map's citations -- if any -- this comment
+    carries: the only bench run on record is against the E8, and #2046
+    found that citation being emitted unqualified into every OTHER AEN
+    part's board tree (E3 included) as the same class of leak #1988 fixed
+    for `rtc_alarm.risk`.  Unlike that fix, a part with no entry here does
+    NOT get silence -- #2046 is explicit that the citation must not be
+    silently dropped, only qualified, because the emitted PAD VALUE
+    (bias-pull-down) is unchanged and still correct for every part.
+    """
+    bus = links["e1m_i2c0"]
+    sda = _pin_by_peripheral(bus["pins"], "I2C2_SDA_C")
+    scl = _pin_by_peripheral(bus["pins"], "I2C2_SCL_C")
+    bench = (bus.get("bench_validation") or {})
+    this_part_bench = bench.get(part)
+    if this_part_bench:
+        bench_text = f"input-enable + bias-pull-down: {this_part_bench}"
+    else:
+        e8_bench = bench.get("E8", "")
+        bench_text = (
+            "input-enable + bias-pull-down: bench-validated ONLY on the E8 "
+            f"-- {e8_bench} This board tree is for the {part}; that bench "
+            f"run has NOT been independently repeated on the {part}'s own "
+            "silicon (#2046, following the #1988 per-part-evidence "
+            "pattern).  The config below is still what this board tree "
+            "emits -- on_module_links.yaml is one file for every AEN SKU "
+            f"and no {part}-specific bench run exists yet to confirm or "
+            "override it -- but that silence is not proof either way."
+        )
+    # Reflowed to house-style comment width (metadata prose has no line
+    # breaks of its own to preserve, unlike the hand-wrapped paragraphs
+    # below) -- the raw bench_validation string can run well past 79
+    # columns unwrapped, same reason _c_comment() exists for evidence/risk
+    # strings elsewhere in this file.
+    bench_lines = [line + "\n" for line in _c_comment(bench_text, "\t")[1:-1]]
+    return (
+        "\t/*\n"
+        f"\t * e1m_i2c0 = SoC {bus['peripheral']} function C: {sda['silicon_pad']} SDA / "
+        f"{scl['silicon_pad']} SCL,\n"
+        "\t * portable alp-i2c0 (E1M edge bus 0 -- ALP_E1M_I2C0 /\n"
+        "\t * EVK_I2C_BUS_SENSORS).  Carries the SoM's own 24C128 manifest EEPROM;\n"
+        "\t * the same pads also reach the EVK carrier's sensor bus once they leave\n"
+        "\t * the module (docs/bring-up-aen.md Sec 5.1 -- two separate buses).\n"
+        "\t *\n"
+        + "".join(bench_lines) +
+        "\t *\n"
+        "\t * bias-pull-down really is a pull-down (DSC=2), and bias-pull-up really\n"
+        "\t * would be a pull-up (DSC=1) -- pinctrl_soc.h does NOT invert the two.\n"
+        "\t * Its ALIF_PINCTRL_BIAS_CFG() macro (soc/alif/ensemble/pinctrl_soc.h:44-48)\n"
+        "\t * maps bias-pull-up -> DSC=1 and bias-pull-down -> DSC=2 unconditionally,\n"
+        "\t * exactly as the field's own comment at :24 describes.  An earlier version\n"
+        "\t * of this comment (and of examples/aen/aen-eeprom-manifest's overlay) blamed\n"
+        "\t * bias-pull-up's reported dead bus on that encoding \"reading inverted vs\n"
+        "\t * the Alif pad hardware\" -- pinctrl_soc.h has no such inversion, so that\n"
+        "\t * explanation is RETRACTED (#2046), and the dead-bus report it was invented\n"
+        "\t * to explain is UNCONFIRMED, not disproven: nobody has re-run bias-pull-up\n"
+        "\t * here in a controlled bench trial since.  What IS established, matching\n"
+        "\t * the BRD_I2C group's own reasoning above: this bus, unlike BRD_I2C, has\n"
+        "\t * the EVK carrier's R137/R144 pull-ups stuffed, so a real internal\n"
+        "\t * pull-down is harmless -- the strong external pull-up dominates a weak\n"
+        "\t * internal one -- which is why bias-pull-down is bench-proven correct as\n"
+        "\t * emitted.  Do NOT change it to bias-pull-up on the strength of either\n"
+        "\t * reading; that needs a fresh register-level bench comparison, not a theory.\n"
+        "\t */\n"
+        f"\t{bus['pinctrl_group_label']}: {bus['pinctrl_group_label']} {{\n"
+        "\t\tgroup0 {\n"
+        # SCL, SDA -- matches the bench-validated overlay's own pinmux
+        # order verbatim (examples/aen/aen-i2c2-eeprom-regcheck and
+        # aen-eeprom-manifest), not the SDA-first order the BRD_I2C group
+        # above happens to use.
+        f"\t\t\tpinmux = <{_pin_macro(scl)}>, <{_pin_macro(sda)}>;\n"
+        "\t\t\tinput-enable;\n"
+        "\t\t\tbias-pull-down;\n"
+        "\t\t};\n"
+        "\t};\n"
+    )
+
+
+def _aen_brd_i2c_dts(links: dict[str, Any], part: str) -> list[str]:
+    """`&i2c0` (BRD_I2C) + its on-module device nodes, `&lpgpio`, and the
+    aliases that make all three reachable portably.
+
+    Board layer, not a per-app overlay and not the SoC peripherals dtsi:
+    these parts are soldered on the E1M-AEN SoM, so every app built for this
+    board should get them for free -- while
+    `zephyr/dts/alif/ensemble_e8_peripherals.dtsi` describes the E8 DIE, which
+    every AEN SKU shares whether or not it carries these chips.
+
+    *part* (the SoC JSON's `part`, e.g. ``"E8"``, ``"E3"``) gates the
+    alarm-node risk comment below -- see that block for why.
+
+    RELOCATED divergence, RETIRED (alp-sdk#1988 / tan-cli#493): this used to
+    gate on a hardcoded ``if part == "E8"`` against a plain-string
+    `on_module_links.rtc_alarm.risk` (tan's own independent fix for the same
+    hazard `_aen_brd_i2c_dts` names -- an E8-only DFP warning bleeding into
+    an E3/E4/E6 board tree). alp-sdk's own fix for the same issue landed
+    later and reshapes the metadata field itself into a per-part map
+    (``risk: {E8: "..."}``) rather than gating in code -- ported here to
+    match: an unstated part gets no paragraph, and any future DFP that
+    confirms the same quirk is added to the map, not to a code branch.
+    """
+    bus = links["brd_i2c"]
+    alarm = links["rtc_alarm"]
+    sda = _pin_by_peripheral(bus["pins"], "I2C0_SDA_C")
+    scl = _pin_by_peripheral(bus["pins"], "I2C0_SCL_C")
+    devices = bus.get("devices") or []
+
+    lines = [
+        "/*",
+        f" * BRD_I2C -- the on-module housekeeping bus: SoC {bus['peripheral']} in its function-C",
+        f" * muxing ({sda['silicon_pad']} SDA / {scl['silicon_pad']} SCL), NOT the slave-only LPI2C0 it was",
+        " * believed to be before #1848.  Driven by UPSTREAM",
+        ' * Zephyr i2c_dw ("snps,designware-i2c"), ADR 0017 Tier-1 -- no vendored code.',
+        " *",
+        " * ISOLATED: R93/R94 (the 0-ohm bridge to the I2C2/EEPROM segment) are DNP, so",
+        " * the 24C128 manifest EEPROM is NOT on this bus -- it stays on i2c2.  The",
+        " * OPTIGA Trust M (IC1, @0x30) is DNP=1 on this batch and so has NO node here;",
+        " * its silence is a negative control, not a fault.",
+        " *",
+        " * Both device drivers are upstream and Kconfig `default y` on their own",
+        " * DT_HAS_*_ENABLED, so an app needs only CONFIG_RTC / CONFIG_SENSOR in its",
+        " * prj.conf -- the board layer deliberately forces neither.",
+        " */",
+        f"&{bus['dt_label']} {{",
+        '\tstatus = "okay";',
+        f"\tpinctrl-0 = <&{bus['pinctrl_group_label']}>;",
+        '\tpinctrl-names = "default";',
+        f"\tclock-frequency = <{bus['clock_frequency_macro']}>;",
+    ]
+    lines += _aen_i2c_device_nodes(bus, links)
+    lines += ["};", ""]
+
+    lines += [
+        "/*",
+        f" * {alarm['gpio_node']} -- needed so the RV-3028 alarm on {alarm['silicon_pad']} "
+        f"({alarm['net']}, bit {alarm['gpio_pin']} =>",
+        f" * IRQ {alarm['gpio_irq']}) is usable as an interrupt source.  Active LOW,",
+        " * open-drain, pulled up on-module by R98 (100k to +1V8, FITTED).  The pad",
+        " * itself is muxed in the pinctrl dtsi's BRD_I2C group (that binding has no",
+        " * pinctrl-0 of its own).",
+    ]
+    # The port-15 control-register warning, straight from the metadata's own
+    # per-part `risk:` map (alp-sdk#1988) -- evidenced only against this
+    # board's own SoC part's DFP: on-module-links.yaml's `risk:` names only
+    # "The AE822 DFP" -- the E8 part's datasheet -- so a family-scoped
+    # emission bled E8 register-layout guidance into an E1M-AEN301 (E3)
+    # board tree (tan-cli#493's
+    # test_a_non_e8_aen_sku_includes_its_own_peripherals_overlay caught it).
+    # A part with no entry in the map gets no paragraph: an unstated DFP
+    # citation is not evidence for this silicon.
+    risk_text = (alarm.get("risk") or {}).get(part)
+    if risk_text:
+        lines += [" *"]
+        lines += _c_comment(risk_text, "")[1:-1]
+    lines += [
+        " */",
+        f"&{alarm['gpio_node']} {{",
+        '\tstatus = "okay";',
+        "};",
+        "",
+    ]
+
+    alias_lines = [f"\t\t{bus['alias']} = &{bus['dt_label']};"]
+    for dev in devices:
+        if dev.get("alias"):
+            alias_lines.append(f"\t\t{dev['alias']} = &{dev['node_label']};")
+    lines += [
+        "/*",
+        " * Portable aliases.  The bus alias is what alp_i2c_open(.bus_id = N)",
+        " * resolves (src/backends/i2c/zephyr_drv.c -> DT_ALIAS(alp_i2cN)), matching",
+        " * the on-module EEPROM's own convention on i2c2; the device aliases let an",
+        " * example say DT_ALIAS(rtc) / DT_ALIAS(alp_temp0) instead of hardcoding",
+        " * this board's node labels.",
+        " */",
+        "/ {",
+        "\taliases {",
+        *alias_lines,
+        "\t};",
+        "};",
+        "",
+    ]
+    return lines
+
+
+def _aen_e1m_i2c0_dts(links: dict[str, Any]) -> list[str]:
+    """`&i2c2` (e1m_i2c0, portable alp-i2c0) + its bus alias.
+
+    No device child nodes (see `_aen_e1m_i2c0_pinctrl_group()`'s
+    docstring): the only genuinely on-module part on this bus, the 24C128
+    manifest EEPROM, is addressed by 7-bit address over the bus rather
+    than a DT device node, the same way
+    examples/aen/aen-i2c2-eeprom-regcheck and
+    examples/aen/aen-eeprom-manifest already open it.  The EVK carrier's
+    sensor/IO-expander/INA236 parts that also ride this bus once it
+    leaves the module are the EVK board layer's concern, not this SoM
+    board layer's.
+    """
+    bus = links["e1m_i2c0"]
+    sda = _pin_by_peripheral(bus["pins"], "I2C2_SDA_C")
+    scl = _pin_by_peripheral(bus["pins"], "I2C2_SCL_C")
+
+    return [
+        "/*",
+        f" * e1m_i2c0 -- SoC {bus['peripheral']} in its function-C muxing "
+        f"({sda['silicon_pad']} SDA / {scl['silicon_pad']} SCL), portable",
+        f" * {bus['alias']} (E1M edge bus 0).  Carries the SoM's own 24C128 manifest",
+        " * EEPROM; the same physical bus also reaches the EVK carrier's sensor bus",
+        " * once the pads leave the module (docs/bring-up-aen.md Sec 5.1).  Driven by",
+        ' * UPSTREAM Zephyr i2c_dw ("snps,designware-i2c"), ADR 0017 Tier-1 -- no',
+        " * vendored code.",
+        " */",
+        f"&{bus['dt_label']} {{",
+        '\tstatus = "okay";',
+        f"\tpinctrl-0 = <&{bus['pinctrl_group_label']}>;",
+        '\tpinctrl-names = "default";',
+        f"\tclock-frequency = <{bus['clock_frequency_macro']}>;",
+        "};",
+        "",
+        "/*",
+        " * Portable alias for e1m_i2c0.  alp_i2c_open(.bus_id = ALP_E1M_I2C0)",
+        " * resolves this via src/backends/i2c/zephyr_drv.c -> DT_ALIAS(alp_i2c0);",
+        " * matches the EEPROM manifest reader's own",
+        " * CONFIG_ALP_SDK_HW_INFO_EEPROM_I2C_BUS_ID=0 convention.",
+        " */",
+        "/ {",
+        "\taliases {",
+        f"\t\t{bus['alias']} = &{bus['dt_label']};",
+        "\t};",
+        "};",
+        "",
+    ]
+
+
+def _aen_ethos_u(soc_spec: dict[str, Any]) -> tuple[str, str] | None:
+    """The Arm Ethos-U accelerator this SoC's silicon carries, as
+    ``(accelerator_config_kconfig, dt_node_label)`` -- or ``None`` when the
+    SoC has no NPU.
+
+    A SoC carrying more than one Ethos-U variant (the E8 has 2x U55 + 1x U85)
+    builds the core driver for its MOST capable NPU -- the U85 -- because the
+    upstream Arm Ethos-U driver compiles exactly one accelerator config per
+    image (``ETHOS_U_NPU_CONFIG`` is a Kconfig ``choice``).  Vela targets must
+    match (``--accelerator-config ethos-u85-256`` for the U85 case).
+
+    Used only to flip the (already-declared, disabled) NPU DT node to
+    ``status="okay"`` on the generated silicon board -- harmless on its own
+    (``CONFIG_ETHOS_U`` is ``default n``, so no driver binds until an inference
+    app selects it via ``ALP_SDK_INFERENCE_BACKEND_ETHOS_U_AEN``).
+    """
+    caps = soc_spec.get("capabilities") or {}
+    if (caps.get("ethos_u85_count") or 0) > 0:
+        return ("ETHOS_U85_256", "ethosu85")
+    if (caps.get("ethos_u55_count") or 0) > 0:
+        return ("ETHOS_U55_256", "ethosu55")
+    return None
+
+
+def _aen_defconfig(
+    uart_node: str, rx_row: dict[str, Any], tx_row: dict[str, Any],
+    slot0_base: int,
+) -> str:
+    # CONFIG_USE_DT_CODE_PARTITION is the Kconfig half of the very
+    # `zephyr,code-partition = &slot0_partition;` chosen that _aen_dts()
+    # (below) lays down for every board this function serves -- the two are
+    # emitted as a pair, from the same MRAM partition map, so the board can
+    # never carry the DT fact without the Kconfig that honours it.  Without
+    # it Zephyr leaves FLASH_LOAD_OFFSET at 0 and the image links at the MRAM
+    # base 0x80000000, on top of the boot partition: the reset vector comes
+    # out 0x8000xxxx, which `alif_flash` rejects ("unrecognised reset vector
+    # ... expected a slot0-XIP image") and which faults if it is written
+    # anyway.  Set here, in the board layer, rather than in each app's
+    # prj.conf, because the link offset is a property of THIS BOARD's flash
+    # map, not of any app -- so it reaches every consumer of the board
+    # equally (plain `west build`, twister, the board.yaml planner, `tan`).
+    # It is also where upstream Zephyr boards with a fixed bootloader slot
+    # set it (`grep -l USE_DT_CODE_PARTITION=y zephyr/boards/**/*_defconfig`).
+    #
+    # A Flow C ITCM RAM-run deliberately undoes it (a board defconfig is the
+    # lowest-precedence Kconfig layer): `scripts/bench/aen/aen-flowc-itcm.conf`
+    # + `aen-flowc-itcm.overlay`.  MCUboot's own image is unaffected -- it
+    # re-points the chosen at &boot_partition via mcuboot's app.overlay.
+    return (
+        _COPYRIGHT_HASH +
+        "\n"
+        "CONFIG_ARM_MPU=y\n"
+        "CONFIG_HW_STACK_PROTECTION=y\n"
+        "\n"
+        "# Link the image into the board's `zephyr,code-partition`\n"
+        f"# (slot0_partition, MRAM 0x{slot0_base:08x}) instead of the MRAM base --\n"
+        "# without it the reset vector lands at 0x8000xxxx and no AEN flash\n"
+        "# flow accepts the image.  Flow C (ITCM RAM-run) overrides it via\n"
+        "# scripts/bench/aen/aen-flowc-itcm.conf.\n"
+        "CONFIG_USE_DT_CODE_PARTITION=y\n"
+        "\n"
+        # Silicon pads read from metadata/pinmux/aen.yaml, exactly as the
+        # sibling .dts and -pinctrl.dtsi do -- they used to be the string
+        # literal "P3_4/P3_5", the AEN801 console pads, on every SKU.
+        f"# Console: Alif {uart_node.upper()} (E1M edge \"UART0\", "
+        f"{rx_row['silicon_pad']}/{tx_row['silicon_pad']}) "
+        "-- NS16550-class UART.\n"
+        "CONFIG_SERIAL=y\n"
+        "CONFIG_CONSOLE=y\n"
+        "CONFIG_UART_CONSOLE=y\n"
+        "CONFIG_UART_INTERRUPT_DRIVEN=y\n"
+        "CONFIG_UART_NS16550=y\n"
+    )
+
+
+# Board-level LOG_MODE default for every AEN board (alp-sdk issue #1373,
+# ported from alp-sdk#1407). Emitted into the generated `Kconfig.defconfig`;
+# the two hand-authored AEN board trees (e1m_aen401_m55_hp, e1m_aen601_m55_hp)
+# carry a byte-identical copy on the alp-sdk side, kept in step by that repo's
+# own `tests/scripts/test_gen_zephyr_board.py`.
+#
+# WHY: Zephyr's own `choice LOG_MODE` default is LOG_MODE_DEFERRED
+# (subsys/logging/Kconfig.mode), which no AEN board ever set or unset -- it
+# is inherited. Deferred mode hands every record to the LOG_PROCESS_THREAD
+# (CONFIG_LOG_PROCESS_THREAD is `default y`), and CONFIG_LOG_PRINTK is
+# `default y if PRINTK`, so printk() -- including the Alp SDK boot banner --
+# is deferred with it. The AEN bench procedure deliberately runs apps whose
+# main() never yields (`for (;;) { k_busy_wait(1000); }`) because an idling
+# M55 makes the Secure Enclave gate the DAP and the SE-UART together. A
+# main() that never yields never lets the log thread run: with
+# CONFIG_LOG_PROCESS_THREAD_CUSTOM_PRIORITY=n (the default) log_core.c runs
+# that thread at K_LOWEST_APPLICATION_THREAD_PRIO (= CONFIG_NUM_PREEMPT_
+# PRIORITIES - 1), strictly below main's CONFIG_MAIN_THREAD_PRIORITY=0, and
+# time-slicing rotates only among READY threads of EQUAL priority -- so a
+# busy-looping main() at 0 starves it outright and a healthy, fault-free
+# board emits ZERO bytes. Measured on E1M-AEN801 silicon: PC inside
+# `z_impl_k_busy_wait`, IPSR = 000 (NoException), CFSR @ 0xE000ED28 =
+# 00000000, zero UART bytes in a 15 s capture; the same source with
+# LOG_MODE_MINIMAL prints the banner and both LOG_INF lines. LOG_MODE_MINIMAL
+# formats and writes in the calling context, so it cannot be starved by a
+# non-yielding main().
+#
+# WHY A CHOICE `default` AND NOT `CONFIG_LOG_MODE_MINIMAL=y` IN THE BOARD
+# `_defconfig`: the `_defconfig` form assigns the symbol unconditionally,
+# including on the 47 `CONFIG_LOG=n` fragments under examples/aen/, where
+# the choice is invisible. Zephyr's scripts/kconfig/kconfig.py then runs
+# check_assigned_choice_values() and prints "The choice symbol
+# LOG_MODE_MINIMAL ... was selected (set =y), but no symbol ended up as the
+# choice selection" on every one of those builds. A Kconfig.defconfig
+# default is inert when LOG=n. Precedence is unchanged either way:
+# Kconfig.zephyr sources the board's Kconfig.defconfig ahead of subsys/
+# Kconfig precisely so board defaults outrank upstream ones, and an app that
+# wants the deferred backend pipeline still overrides this with
+# CONFIG_LOG_MODE_DEFERRED=y in its own prj.conf.
+_AEN_LOG_MODE_DEFAULT = (
+    "# Logging: default to LOG_MODE_MINIMAL, not Zephyr's inherited\n"
+    "# LOG_MODE_DEFERRED.  Deferred mode needs CONFIG_LOG_PROCESS_THREAD to run,\n"
+    "# and the AEN bench procedure runs apps whose main() never yields (a\n"
+    "# non-yielding busy loop is what keeps the Secure Enclave from gating the\n"
+    "# DAP and the SE-UART -- see docs/debugging-aen.md section 4).  A\n"
+    "# non-yielding main() starves the log thread, and because CONFIG_LOG_PRINTK\n"
+    "# routes printk() through the same queue the Alp SDK banner disappears too:\n"
+    "# a running, fault-free board prints ZERO bytes.  Measured on E1M-AEN801\n"
+    "# silicon (issue #1373) -- PC inside z_impl_k_busy_wait, IPSR = 000,\n"
+    "# CFSR @ 0xE000ED28 = 00000000, and no UART output at all.  Minimal mode\n"
+    "# formats in the calling context, so the same app prints.  An app that\n"
+    "# wants the deferred pipeline (backends, runtime filtering, timestamps)\n"
+    "# overrides this with CONFIG_LOG_MODE_DEFERRED=y in its prj.conf.\n"
+    "choice LOG_MODE\n"
+    "\tdefault LOG_MODE_MINIMAL\n"
+    "endchoice\n"
+    "\n"
+)
+
+
+def _aen_kconfig_defconfig(dir_name: str, role: str, part: str) -> str:
+    board_sym = dir_name.upper()
+    role_u = role.upper()
+    # NUM_IRQS=480 is an Ensemble-FAMILY constant, not a per-part one:
+    # upstream Zephyr defaults it to 480 for every RTSS cluster it ships
+    # (soc/alif/ensemble/{e1c,e4,e6,e8}/Kconfig.defconfig.*_rtss_{hp,he}).
+    # The part designator in the sentence is NOT -- it used to be the
+    # literal "E8" on every E1M-AEN* board.
+    return (
+        _COPYRIGHT_HASH +
+        "\n"
+        f"if BOARD_{board_sym}\n"
+        "\n"
+        f"# The Ensemble {part} RTSS-{role_u} has CONFIG_NUM_IRQS=480, so the ARMv8-M vector table is\n"
+        "# (16 + 480) * 4 = 1984 bytes and the hardware VTOR must be 2 KiB (0x800) aligned.\n"
+        "# For an MCUboot chain-loaded image the linker therefore places _vector_table at\n"
+        "# slot_base + 0x800, but Zephyr hard-defaults the MCUboot header (ROM_START_OFFSET,\n"
+        "# which is also imgtool --header-size) to 0x200 under BOOTLOADER_MCUBOOT and makes\n"
+        "# it non-promptable. MCUboot then jumps to slot_base + 0x200 (header end) and reads\n"
+        "# a garbage SP/PC from the 0x600 padding gap -> instant HardFault -> reset/reboot\n"
+        "# loop, never reaching the app. Bump the header reservation to match the vector\n"
+        "# alignment so the jump target == _vector_table. (Affects only chain-loaded images;\n"
+        "# MCUboot itself builds with BOOTLOADER_MCUBOOT=n.)\n"
+        "config ROM_START_OFFSET\n"
+        "\tdefault 0x800 if BOOTLOADER_MCUBOOT\n"
+        "\n"
+        "# alp-sdk's own chips/tmp112/tmp112.c defines tmp112_init(), and upstream\n"
+        "# Zephyr's zephyr/drivers/sensor/ti/tmp112/tmp112.c defines the SAME symbol\n"
+        "# for the SAME part.  The two only collide at LINK time, and only when an\n"
+        "# app pulls in both -- which CONFIG_SENSOR=y does for free on this board,\n"
+        "# because the ti,tmp112 devicetree node below auto-selects upstream's\n"
+        "# driver regardless of whether the app uses it (#2043).  Board-scope the\n"
+        "# fix instead of leaving every app to rediscover it: default the upstream\n"
+        "# driver OFF here.  This is not a permanent no -- Kconfig.zephyr sources a\n"
+        "# board's Kconfig.defconfig ahead of subsys/Kconfig (see the LOG_MODE\n"
+        "# comment below for the same precedence fact), so this default only\n"
+        "# supplies a value when nothing else assigns the symbol.  An app that\n"
+        "# genuinely wants the upstream driver is therefore expected to win by\n"
+        "# setting CONFIG_TMP112=y explicitly in its own prj.conf -- ordinary\n"
+        "# Kconfig behaviour for a user assignment versus a `default` -- and that\n"
+        "# is exactly why examples/aen/aen-temp-sensor sets it by name.\n"
+        "#\n"
+        "# CONFIRMED ON THE REAL BOARD TARGET, not just by mechanism.  `west build\n"
+        "# -p always -b alp_e1m_aen801_m55_he/ae822fa0e5597ls0/rtss_he\n"
+        "# examples/aen/aen-temp-sensor` links\n"
+        "# zephyr/drivers/sensor/ti/tmp112/libdrivers__sensor__ti__tmp112.a (step\n"
+        "# 139/148), and the resolved .config carries CONFIG_TMP112=y,\n"
+        "# CONFIG_SENSOR=y and CONFIG_DT_HAS_TI_TMP112_ENABLED=y with this board's\n"
+        "# `default n` in force -- the explicit CONFIG_TMP112=y in\n"
+        "# examples/aen/aen-temp-sensor/prj.conf really does win, on silicon-\n"
+        "# targeted Kconfig, not only in theory.  If that build ever fails on\n"
+        "# CONFIG_TMP112, this derivation is what needs revisiting, not the\n"
+        "# build.\n"
+        "config TMP112\n"
+        "\tdefault n\n"
+        "\n"
+        + _AEN_LOG_MODE_DEFAULT +
+        f"endif # BOARD_{board_sym}\n"
+    )
+
+
+#: Per-device state -> the singular ("is ...") / plural ("are ...") verb
+#: phrase both `_aen_ospi_device_clause()` and `_aen_ospi_population_clause()`
+#: read, so the two forms can't drift apart (alp-sdk#2062 review round 4).
+_AEN_OSPI_STATE_PHRASE = {
+    "populated": "populated",
+    "not_populated": "not populated",
+    "optional": "BOM-optional, not assumed populated",
+}
+
+#: Why this SDK's AEN board never uses the OSPI0 NOR/HyperRAM for XIP boot,
+#: EVEN when a preset populates (or might populate) them -- alp-sdk#2062
+#: review round 3: "OSPI_XIP_SER does not exist on this die" is a true, cited
+#: fact (Alif `soc_features.h` `SOC_FEAT_OSPI_HAS_XIP_SER 0` for AE822), but it
+#: is NOT proof XIP is impossible on this silicon -- Alif's own
+#: `ospi_psram_xip.c` compiles `ospi_control_xip_ss()` out under that same
+#: guard and STILL calls `aes_enable_xip()`; `flash_ospi_alif.c` documents
+#: AE822 doing XiP "through a single FIFO location". The real reasons this
+#: driver stack never attempts it: hal_alif's OWN `alif_hal_ospi_xip_enable()`
+#: unconditionally targets the absent `XIP_SER` register (a bus fault, not a
+#: graceful no-op), and `flash_ospi_alif.c`'s `flash_driver_api` -- read/
+#: read_jedec_id/sfdp_read, bench-verified on E1M-AEN803's fitted NOR -- never
+#: calls it either (#915) -- so there is no in-tree driver path that would use
+#: OSPI0 for XIP today regardless of population. Never follow the die-level
+#: fact alone with a "so" -- always cite this instead.
+_AEN_OSPI_XIP_GAP = (
+    "hal_alif's alif_hal_ospi_xip_enable() targets the XIP_SER register, "
+    "absent on this die, and flash_ospi_alif.c's flash_driver_api never "
+    "calls it -- #915")
+
+
+def _aen_ospi_device_state(
+        dev: "dict[str, Any] | None") -> tuple[str, "str | None"]:
+    """(state, chip-or-None) for one `on_module` OSPI-family device dict
+    (`ospi_memories.ospi0` or `hyperram`).  *dev* is `None` when the block
+    itself is ABSENT from the preset -- the schema only requires
+    `on_module.silicon`, so omitting `ospi_memories:`/`hyperram:` entirely
+    is valid, a different fact from a declared-but-empty block (alp-sdk#2062
+    review round 4: the old code collapsed both to `{}` via `... or {}`,
+    so an undeclared device hit the `assembled` default same as a
+    declared one with the key merely omitted, and got printed as
+    "populated"). `state` is `"absent"` for that case; callers must leave
+    an absent device out of the clause text entirely.
+
+    For a DECLARED block, `state` is one of `"populated"`, `"not_populated"`,
+    `"optional"` (alp-sdk#2062 review round 2 -- `assembled` is a TRI-STATE
+    field, not a bool: `"optional"` is Python-truthy, so a naive
+    `bool(dev.get("assembled"))` printed "populated" for the AEN301-701
+    SKUs' genuinely-unresolved BOM question; a MISSING `assembled` key on a
+    DECLARED device means populated per the schema default `true` (see the
+    bug that default itself caused, documented at `metadata/e1m_modules/
+    E1M-AEN801.yaml`'s own `hyperram:` comment), not "not populated"). `chip`
+    is `None` when the field is `TBD`/absent so callers never print a
+    placeholder part name -- `_is_tbd()` is this module's own relocated
+    spelling of the helper `alp_orchestrate` uses for the same job."""
+    if dev is None:
+        return "absent", None
+    chip = dev.get("chip")
+    if not chip or _is_tbd(chip):
+        chip = None
+    assembled = dev.get("assembled", True)
+    if assembled == "optional":
+        return "optional", chip
+    return ("populated" if assembled else "not_populated"), chip
+
+
+def _aen_ospi_device_clause(label: str, state: str, chip: "str | None") -> str:
+    """One device's own clause, e.g. `"OSPI0 NOR (IS25WX256-JHLE) is
+    populated"` / `"HyperRAM is not populated"` / `"OSPI0 NOR is
+    BOM-optional, not assumed populated"`.  Never called with `state ==
+    "absent"` -- callers exclude an absent device before reaching here."""
+    named = f"{label} ({chip})" if chip else label
+    return f"{named} is {_AEN_OSPI_STATE_PHRASE[state]}"
+
+
+def _aen_ospi_population_clause(
+        sku_preset: dict[str, Any]) -> tuple[str, str, int]:
+    """Return `(clause, category, populated_count)` describing the SoM
+    preset's own OSPI0 NOR + HyperRAM population, read from `on_module.
+    ospi_memories.ospi0` / `on_module.hyperram` rather than a hardcoded
+    claim (alp-sdk#2062: this used to hardcode Macronix/Winbond as
+    "BOM-optional and NOT populated on the current batch" for every AEN SKU
+    alike -- both the board-header banner and the MRAM-partition-map comment
+    now call THIS one function, so they cannot disagree with each other or
+    with the real preset the way a board emitted for a from-scratch
+    "populated" preset showed they could: the old banner said populated,
+    the old partition-map comment still said "not populated on this
+    batch" two paragraphs later in the SAME file).
+
+    An ABSENT device block (see `_aen_ospi_device_state()`) is left out of
+    *clause* entirely -- it is never named "not populated", since there is
+    no declared device to describe.
+
+    `category` is `"populated"` if either device is definitely populated,
+    `"optional"` if neither is definite but at least one MIGHT be
+    (`assembled: "optional"`), else `"not_populated"` (every declared
+    device is `assembled: false`, and an absent block contributes
+    nothing).  `populated_count` is how many of the (present) devices are
+    definitely `"populated"` -- callers need it for singular/plural
+    agreement when exactly one of two declared devices is populated."""
+    on_module = sku_preset.get("on_module") or {}
+    ospi_memories = on_module.get("ospi_memories")
+    ospi0 = ospi_memories.get("ospi0") if ospi_memories else None
+    hyperram = on_module.get("hyperram")
+    nor_state, nor_chip = _aen_ospi_device_state(ospi0)
+    ram_state, ram_chip = _aen_ospi_device_state(hyperram)
+
+    devices = [(label, state, chip) for label, state, chip in (
+        ("OSPI0 NOR", nor_state, nor_chip), ("HyperRAM", ram_state, ram_chip))
+        if state != "absent"]
+    populated_count = sum(1 for _, state, _ in devices if state == "populated")
+
+    if not devices:
+        return ("no OSPI0 NOR or HyperRAM is declared on this SoM preset",
+                "not_populated", 0)
+
+    states = {state for _, state, _ in devices}
+    if "populated" in states:
+        category = "populated"
+    elif "optional" in states:
+        category = "optional"
+    else:
+        category = "not_populated"
+
+    if len(devices) == 2 and devices[0][1] == devices[1][1]:
+        (nor_label, state, nchip), (ram_label, _, rchip) = devices
+        nor_named = f"{nor_label} ({nchip})" if nchip else nor_label
+        ram_named = f"{ram_label} ({rchip})" if rchip else ram_label
+        clause = f"{nor_named} + {ram_named} are {_AEN_OSPI_STATE_PHRASE[state]}"
+    else:
+        clause = "; ".join(_aen_ospi_device_clause(label, state, chip)
+                           for label, state, chip in devices)
+    return clause, category, populated_count
+
+
+def _aen_ospi_storage_banner_lines(sku_preset: dict[str, Any]) -> list[str]:
+    """Describe the SoM's OSPI0 NOR + HyperRAM for the board-header banner
+    -- see `_aen_ospi_population_clause()`, the shared source this and the
+    MRAM-partition-map comment both read, and `_AEN_OSPI_XIP_GAP` for why
+    a populated (or possibly-populated) device still never sees XIP boot
+    here."""
+    clause, category, populated_count = _aen_ospi_population_clause(sku_preset)
+    if category == "populated":
+        # Singular/plural: "neither" only holds when BOTH declared devices
+        # are actually populated (alp-sdk#2062 review round 4) -- a mixed
+        # preset (one populated, one not/absent) gets the singular form.
+        who = "neither is" if populated_count == 2 else "the populated device is not"
+        tail = f"{clause}; {who} used for XIP boot here ({_AEN_OSPI_XIP_GAP});"
+    elif category == "optional":
+        tail = (f"{clause}, so no external XIP / flash device is assumed -- "
+                f"even if fitted, the same gap applies ({_AEN_OSPI_XIP_GAP});")
+    else:
+        tail = f"{clause}, so there is no external XIP / flash device;"
+    wrapped = textwrap.wrap(tail, width=68, break_on_hyphens=False)
+    return [
+        " *   - runs boot + storage from on-die MRAM only.  The SoM's",
+        *(f" *     {line}" for line in wrapped),
+    ]
+
+
+def _aen_mram_only_comment_lines(sku_preset: dict[str, Any], tail: str) -> list[str]:
+    """The MRAM partition-map comment's own "why MRAM-only" sentence,
+    from the same `_aen_ospi_population_clause()` the banner reads
+    (alp-sdk#2062 review round 2: this used to hardcode "the SoM OSPI NOR +
+    HyperRAM are not populated on this batch" unconditionally, so a preset
+    that DOES populate them got a board tree contradicting its own banner
+    two paragraphs up). *tail* is the caller's own ending clause (what lives
+    in MRAM as a result); MRAM-only itself holds regardless of population
+    -- see `_AEN_OSPI_XIP_GAP`; the die-level XIP_SER absence alone does
+    NOT imply it (round 3)."""
+    clause, category, _populated_count = _aen_ospi_population_clause(sku_preset)
+    if category == "populated":
+        sentence = (f"MRAM-only regardless: {clause}; {_AEN_OSPI_XIP_GAP} "
+                    f"(see the banner above), so {tail}")
+    elif category == "optional":
+        sentence = (f"MRAM-only: {clause}; even if fitted, the same gap "
+                    f"applies ({_AEN_OSPI_XIP_GAP}, see the banner above), "
+                    f"so {tail}")
+    else:
+        sentence = f"MRAM-only: {clause}, so {tail}"
+    return [f" * {line}" for line in textwrap.wrap(sentence, width=76, break_on_hyphens=False)]
+
+
+def _aen_dts(
+    sku: str, sku_preset: dict[str, Any], core_id: str, soc_spec: dict[str, Any],
+    variant: dict[str, Any],
+    dir_name: str, basename: str, rx_row: dict[str, Any], tx_row: dict[str, Any],
+    metadata_root: Path, links: dict[str, Any],
+    ethos_u: tuple[str, str] | None = None,
+    memory_map: "list[dict[str, Any]] | None" = None,
+    power_domains: "dict[str, Any] | None" = None,
+    wired_pads: "list[dict[str, Any]] | None" = None,
+) -> str:
+    role = core_id.split("_")[-1]                     # "hp" / "he"
+    role_u = role.upper()
+    other_role = "he" if role == "hp" else "hp"
+    other_role_u = other_role.upper()
+    other_core_id = f"m55_{other_role}"
+
+    core = _find_core(soc_spec, core_id)
+    other_core = _find_core(soc_spec, other_core_id)
+
+    itcm_base, dtcm_base = core["itcm_global_base"], core["dtcm_global_base"]
+    other_itcm, other_dtcm = other_core["itcm_global_base"], other_core["dtcm_global_base"]
+
+    display_variant = variant["order_code"]
+    slug = sku[len("E1M-"):].lower()
+    compatible = f"alp,e1m-{slug}-m55-{role}"
+    model = f"Alp {sku} Cortex-M55 {role_u} carrier"
+    uart_node = _uart_node_label(rx_row)
+
+    part = _aen_part(soc_spec)
+    family_display = _aen_family_display(soc_spec)
+    peripherals_dtsi = _aen_peripherals_dtsi(soc_spec, metadata_root)
+
+    total_kib = round(float(variant["mram_mb"]) * 1024)
+    mram_base, partitions = _aen_flash_partitions(
+        total_kib, metadata_root, role, memory_map)
+    image_kib = dict((label, size) for label, _off, size in partitions)["image-0"]
+    disjoint_slot0 = _aen_role_slot0_map(memory_map, role) is not None
+
+    bench_known = _AEN_BENCH_KNOWN_ITCM[role]
+    itcm_known_suffix = "  (also bench-known)" if bench_known else ""
+
+    lines: list[str] = []
+    lines += [
+        "/*",
+        " * Copyright (c) 2026 Alp Lab AB",
+        " * SPDX-License-Identifier: Apache-2.0",
+        " *",
+        f" * {sku} ({family_display}, {display_variant}) Cortex-M55-{role_u} carrier,",
+        " * for the Alp E1M-EVK.",
+        " *",
+        f" * Reuses the upstream Alif {part} SoC + RTSS-{role_u} cluster devicetree and:",
+        " *   - retargets the console from the DevKit's UART2 to the E1M carrier console",
+        f" *     (Alif {uart_node.upper()}, {rx_row['silicon_pad']}/{tx_row['silicon_pad']} -- the E1M edge \"UART0\");",
+        *_aen_ospi_storage_banner_lines(sku_preset),
+        " *   - lays down a production MCUboot partition map in MRAM.",
+    ]
+    if disjoint_slot0:
+        lines += [
+            " *",
+            f" * NOTE (AMP, #1069): {role_u}'s slot0 lives in its OWN disjoint MRAM window,",
+            f" * physically separate from {other_role_u}'s -- both cores' images can be",
+            " * resident in MRAM at once (see the partition map below and",
+            f" * metadata/e1m_modules/{sku}.yaml `memory_map:`).  OTA is DEFERRED",
+            " * (CONFIG_SINGLE_APPLICATION_SLOT=y, no secondary/scratch slot): the",
+            f" * per-core code slots ({_aen_slot0_sizes_display(memory_map)}) share the",
+            f" * {total_kib} KiB App MRAM with boot, storage and the NPU MRAM-model",
+            " * budget -- see zephyr/sysbuild/aen/README.md for the sizing rationale.",
+        ]
+    elif role == "hp":
+        lines += [
+            " *",
+            " * NOTE (AMP): this per-core board takes the full MRAM view for single-image",
+            f" * bring-up (one core flashed/run at a time).  An {other_role_u}+{role_u} co-resident AMP image",
+            " * partitions MRAM between the two cores at the system-integration layer",
+            " * (sysbuild); see docs/heterogeneous-builds.md.",
+        ]
+    lines += [
+        " *",
+        f" * Inter-core IPC (the APSS<->RTSS-{role_u} MHUv2 doorbell pair) + the remaining",
+        " * on-module peripheral buses (GPIO / SPI / Ethernet) are added alongside the",
+        " * alp-sdk Alif peripheral drivers; this base wires boot, console and the",
+        " * on-module BRD_I2C housekeeping bus (RTC + temperature sensor, below).",
+        " */",
+        "",
+        "/dts-v1/;",
+        "",
+        f"#include <alif/ensemble/{display_variant.lower()}.dtsi>",
+        f"#include <alif/ensemble/common/ensemble_rtss_{role}.dtsi>",
+        f"#include <{peripherals_dtsi}>",
+        "#include <zephyr/dt-bindings/gpio/gpio.h>",
+        "#include <zephyr/dt-bindings/i2c/i2c.h>",
+        f'#include "{dir_name}-pinctrl.dtsi"',
+        "",
+        "/ {",
+        f'\tmodel = "{model}";',
+        f'\tcompatible = "{compatible}";',
+        "",
+        "\tchosen {",
+        "\t\tzephyr,flash = &mram_storage;",
+        "\t\t/*",
+        "\t\t * MCUboot's flash_map_extended.c derives FLASH_DEVICE_BASE /",
+        "\t\t * FLASH_DEVICE_ID from zephyr,flash-controller (the controller",
+        "\t\t * node, NOT the soc-nv-flash child) -- mirrors the fork's",
+        "\t\t * e1.dtsi chosen.  Without it MCUboot's flash_map fails to link.",
+        "\t\t */",
+        "\t\tzephyr,flash-controller = &mram;",
+        "\t\tzephyr,sram = &dtcm;",
+        f"\t\tzephyr,console = &{uart_node};",
+        f"\t\tzephyr,shell-uart = &{uart_node};",
+        "\t\tzephyr,code-partition = &slot0_partition;",
+        "\t};",
+        "};",
+        "",
+        "/*",
+        " * ITCM/DTCM global_base -- central CPU-local -> system-bus address translation.",
+        " *",
+        " * hal_alif's soc_memory_map.h local_to_global() translates a CPU-local TCM",
+        " * pointer into the address other bus masters (the Ethos-U NPU AXI master, the",
+        " * SD/DMA controllers) must be programmed with, by reading",
+        " * DT_PROP(DT_NODELABEL(itcm|dtcm), global_base).  Upstream Zephyr's",
+        f" * arm,itcm/arm,dtcm bindings (ensemble_rtss_{role}.dtsi, included above) declare no",
+        " * such property, so re-`compatible` the nodes onto the alp-sdk",
+        " * alif,itcm/alif,dtcm bindings (zephyr/dts/bindings/memory-controllers/), which",
+        " * require global_base.  Done here in the per-core board (not a per-example",
+        f" * overlay) so every {role_u} app on this board inherits the same translation.",
+        " *",
+        " * Values transcribed from the Apache-2.0 zephyr_alif fork",
+        f" * dts/arm/alif/ensemble/common/ensemble_rtss_{role}.dtsi:",
+        f" *   itcm global_base = {hex(itcm_base)}{itcm_known_suffix}",
+        f" *   dtcm global_base = {hex(dtcm_base)}",
+        f" * These are the RTSS-{role_u} global TCM aliases; the RTSS-{other_role_u} core uses a different",
+        f" * window ({hex(other_itcm)} / {hex(other_dtcm)}), set in the _{other_role} board dts.",
+        " */",
+        "&itcm {",
+        f'\t/* fork ensemble_rtss_{role}.dtsi: itcm compatible = "alif,itcm" */',
+        '\tcompatible = "alif,itcm";',
+        f"\t/* fork ensemble_rtss_{role}.dtsi: itcm global_base = <{hex(itcm_base)}> */",
+        f"\tglobal_base = <{hex(itcm_base)}>;",
+        "};",
+        "",
+        "&dtcm {",
+        f'\t/* fork ensemble_rtss_{role}.dtsi: dtcm compatible = "alif,dtcm" */',
+        '\tcompatible = "alif,dtcm";',
+        f"\t/* fork ensemble_rtss_{role}.dtsi: dtcm global_base = <{hex(dtcm_base)}> */",
+        f"\tglobal_base = <{hex(dtcm_base)}>;",
+        "};",
+        "",
+        "/*",
+        " * On-die MRAM as a real flash controller (ADR 0017 Tier-2).",
+        " *",
+        f" * Upstream Zephyr's {part} SoC dtsi exposes the MRAM only as a memory region",
+        f' * (`mram: flash@{mram_base:x}`, compatible "zephyr,memory-region","soc-nv-flash"):',
+        " * XIP-readable but with NO flash driver, so FLASH_HAS_DRIVER_ENABLED stays",
+        " * unset and MCUboot's flash_map has nothing to read/write slot0 with.",
+        " *",
+        " * We retarget the upstream `&mram` node into the fork's flash-controller",
+        " * hierarchy WITHOUT editing upstream zephyr/: override `&mram`'s compatible to",
+        ' * the controller compatible "alif,mram-flash-controller" (which the in-tree',
+        " * flash_mram_alif driver binds, setting FLASH_HAS_DRIVER_ENABLED), and add a",
+        " * `mram_storage` soc-nv-flash child carrying the program/erase geometry the",
+        " * driver reads (DT_NODELABEL(mram_storage): erase-block-size / write-block-size",
+        " * / reg).  This mirrors the fork e1.dtsi node structure exactly (controller",
+        f" * `mram_flash@{mram_base:x}` + `mram_storage@{mram_base:x}` soc-nv-flash child); the only",
+        " * difference is we reuse the upstream `mram` nodelabel as the controller rather",
+        " * than declaring a fresh `mram_flash` node, since upstream owns the node.",
+    ]
+    partitions_total_kib = sum(size for _label, _off, size in partitions)
+    if disjoint_slot0:
+        lines += [
+            " *",
+            f" * MRAM partition map (this {role_u} core's {partitions_total_kib} KiB view of the",
+            f" * {total_kib} KiB App MRAM) for the sysbuild/aen MCUboot profile (MCUboot + a",
+            " * signed application image, CONFIG_SINGLE_APPLICATION_SLOT=y -- no OTA/swap",
+            " * slot, deferred per #1069).  Offsets are relative to the soc-nv-flash child",
+            f" * base (MRAM 0x{mram_base:x}).  {other_role_u}'s disjoint slot0 window is NOT a",
+            " * partition in this table (it's outside this core's own view); see",
+            f" * metadata/e1m_modules/{sku}.yaml `memory_map:` for the full physical map:",
+            " *",
+        ]
+    else:
+        if role == "hp":
+            lines += [
+                f" * Kept byte-for-byte identical to the {other_role_u}-sibling board so a future HE+HP AMP",
+                " * sysbuild sees one MRAM partition map.",
+            ]
+        lines += [
+            " *",
+            f" * MRAM partition map ({total_kib} KiB total) for the sysbuild/aen MCUboot profile",
+            " * (MCUboot + a signed application image, swap-using-scratch).  Offsets are",
+            f" * relative to the soc-nv-flash child base (MRAM 0x{mram_base:x}):",
+            " *",
+        ]
+    labels_display = {
+        "mcuboot": "mcuboot ",
+        "image-0": "image-0 ",
+        "image-1": "image-1 ",
+        "image-scratch": "scratch ",
+        "reserved": "reserved",
+        "storage": "storage ",
+        "atoc": "atoc    ",
+    }
+    trailers = {
+        "image-0": "   (primary slot, code-partition)",
+        "image-1": "   (secondary slot for OTA)",
+        "reserved": "   (ex-scratch; unused, OTA deferred)",
+        "storage": "    (settings / NVS)",
+        "atoc": "    (SE-owned: SETOOLS top-anchors the ATOC here -- do NOT write, #1289)",
+    }
+    for label, off, size in partitions:
+        lines.append(
+            f" *   {labels_display[label]} 0x{off:06x}  {size} KiB{trailers.get(label, '')}"
+        )
+    if disjoint_slot0:
+        lines += [
+            f" *                      = {partitions_total_kib} KiB (of {total_kib} KiB App MRAM total)",
+            " *",
+            *_aen_mram_only_comment_lines(
+                sku_preset,
+                "boot, this core's own slot0, reserved headroom, and "
+                "storage all live in MRAM."),
+            " */",
+        ]
+    else:
+        lines += [
+            f" *                      = {total_kib} KiB",
+            " *",
+            *_aen_mram_only_comment_lines(
+                sku_preset,
+                "all of boot, both image slots, scratch, and storage live "
+                "in MRAM."),
+            " */",
+        ]
+    lines += [
+        "&mram {",
+        '\tcompatible = "alif,mram-flash-controller";',
+        "\t#address-cells = <1>;",
+        "\t#size-cells = <1>;",
+        "\t/*",
+        "\t * Drop the upstream memory-region properties: this node is no longer a",
+        '\t * "zephyr,memory-region" (it is a flash controller now), and the',
+        "\t * controller addresses its soc-nv-flash child by absolute `reg`, not via",
+        "\t * `ranges`.  flash-controller.yaml / base.yaml declare neither property,",
+        "\t * so they must be removed or DT binding-check fails.",
+        "\t */",
+        "\t/delete-property/ zephyr,memory-region;",
+        "\t/delete-property/ ranges;",
+        "",
+        # Node address + `reg` base come from the SAME `mram_base` the
+        # partition offsets above are relative to -- they used to be a
+        # hardcoded 0x80000000 literal while the offsets were computed from
+        # the metadata-declared `mcuboot` base, an invariant documented only
+        # in an error string and never enforced.
+        f"\tmram_storage: mram_storage@{mram_base:x} {{",
+        '\t\tcompatible = "soc-nv-flash";',
+        f"\t\treg = <{hex(mram_base)} DT_SIZE_K({total_kib})>;",
+        "\t\terase-block-size = <1024>;",
+        "\t\twrite-block-size = <16>;",
+        "",
+        "\t\tpartitions {",
+        '\t\t\tcompatible = "fixed-partitions";',
+        "\t\t\t#address-cells = <1>;",
+        "\t\t\t#size-cells = <1>;",
+        "",
+    ]
+
+    partition_node_labels = {
+        "mcuboot": "boot_partition",
+        "image-0": "slot0_partition",
+        "image-1": "slot1_partition",
+        "image-scratch": "scratch_partition",
+        "reserved": "reserved_partition",
+        "storage": "storage_partition",
+        "atoc": "atoc_partition",
+    }
+    partition_dt_labels = {
+        "mcuboot": "mcuboot",
+        "image-0": "image-0",
+        "image-1": "image-1",
+        "image-scratch": "image-scratch",
+        "reserved": "reserved",
+        "storage": "storage",
+        "atoc": "atoc",
+    }
+    for i, (label, off, size) in enumerate(partitions):
+        node = partition_node_labels[label]
+        dt_label = partition_dt_labels[label]
+        lines += [
+            f"\t\t\t{node}: partition@{off:x} {{",
+            f'\t\t\t\tlabel = "{dt_label}";',
+            f"\t\t\t\treg = <{hex(off)} DT_SIZE_K({size})>;",
+            "\t\t\t};",
+        ]
+        if i != len(partitions) - 1:
+            lines.append("")
+
+    lines += [
+        "\t\t};",
+        "\t};",
+        "};",
+        "",
+        f"/* Carrier console: Alif {uart_node.upper()} on {rx_row['silicon_pad']} (RX) / "
+        f"{tx_row['silicon_pad']} (TX), 115200 8N1. */",
+        f"&{uart_node} {{",
+        '\tstatus = "okay";',
+        f"\tpinctrl-0 = <&pinctrl_{uart_node}>;",
+        '\tpinctrl-names = "default";',
+        "\tcurrent-speed = <115200>;",
+        "};",
+        "",
+    ]
+    lines += _aen_brd_i2c_dts(links, part)
+    lines += _aen_e1m_i2c0_dts(links)
+    if power_domains:
+        lines += _aen_som_power_dts(sku_preset, power_domains, links, wired_pads or [])
+
+    if ethos_u is not None:
+        _accel, node = ethos_u
+        # Enable the Arm Ethos-U NPU node this SoC carries.  The full node
+        # (reg/interrupts/compatible/secure-enable) is already declared
+        # status="disabled" in this SoC's peripherals dtsi (the
+        # `zephyr_peripherals_dtsi` included above -- e.g.
+        # zephyr/dts/alif/ensemble_e8_peripherals.dtsi for the E8); a silicon
+        # board just flips it on.  Harmless -- CONFIG_ETHOS_U is `default n`,
+        # so no driver binds until an inference app pulls it in via
+        # ALP_SDK_INFERENCE_BACKEND_ETHOS_U_AEN (select ETHOS_U if
+        # DT_HAS_ARM_ETHOS_U_ENABLED).  A native_sim build uses the native_sim
+        # board (no such node) and so stays on the tflite-micro stub kernel.
+        lines += [
+            f"/* Arm Ethos-U NPU: enable the {node} node declared in the SoC "
+            "peripherals dtsi (see ALP_SDK_INFERENCE_BACKEND_ETHOS_U_AEN). */",
+            f"&{node} {{",
+            '\tstatus = "okay";',
+            "};",
+            "",
+        ]
+    return "\n".join(lines)
+
+
+def _load_aen_wired_lpgpio_pads(metadata_root: Path) -> list[dict[str, Any]]:
+    """`wired_lpgpio_pads:` of on-module-links.yaml: LPGPIO pads the module wires
+    to an on-module chip without a power-domain control (the OSPI INTn / RESETn
+    nets).  `check_som_power_domains.py` pins each to its TSV row."""
+    doc = _load_yaml(metadata_root / "e1m_modules" / "aen" / "on-module-links.yaml")
+    pads = doc.get("wired_lpgpio_pads") or []
+    for p in pads:
+        if not re.fullmatch(r"P15_[0-7]", str(p.get("silicon_pad", ""))):
+            raise ZephyrBoardEmitError(
+                f"wired_lpgpio_pads entry {p.get('signal')!r}: silicon_pad "
+                f"{p.get('silicon_pad')!r} is not an LPGPIO pad P15_0..P15_7")
+    return pads
+
+
+def _load_aen_power_domains(metadata_root: Path) -> dict[str, Any]:
+    """Load + shape-check `power_domains:` of
+    `metadata/e1m_modules/aen/on-module-links.yaml` (v2, alp-sdk#2784).
+
+    The JSON schema (`on-module-links-v2.schema.json`) pins the shape in
+    `validate_metadata.py`; this refuses only what the emitter itself cannot
+    work without, so a hand-made `--metadata-root` copy fails loudly instead
+    of emitting a board with no SoM power node.
+    """
+    path = metadata_root / "e1m_modules" / "aen" / "on-module-links.yaml"
+    doc = _load_yaml(path)
+    if doc.get("schemaVersion") != "on-module-links-v2":
+        # tan-side (tan-cli#591 pattern): a bound checkout that predates
+        # alp-sdk#2784 is an SDK floor, not this file's authoring gap.
+        require_capability(metadata_root, AEN_SOM_POWER_DOMAINS)
+        raise ZephyrBoardEmitError(
+            f"{path} schemaVersion is {doc.get('schemaVersion')!r}, expected "
+            "'on-module-links-v2' (the `power_domains:` block, alp-sdk#2784)")
+    domains = doc.get("power_domains")
+    if not isinstance(domains, dict) or not domains:
+        raise ZephyrBoardEmitError(f"{path} has no power_domains: block")
+    return domains
+
+
+def _aen_power_domain_presence(
+        domain: dict[str, Any], on_module: dict[str, Any],
+) -> "tuple[str, str | None] | None":
+    """`(state, chip)` for a power domain on THIS SoM preset, or `None` when
+    the domain is absent.  `state` is `"populated"` or `"optional"`.
+
+    Presence is never assumed from the family: it is read from the SKU's own
+    `on_module` block (`presence.on_module_key`, a dotted path).  A string
+    value (`wifi_ble: cc3501e`) is present unless it is a TBD placeholder; a
+    block with the tri-state `assembled:` follows that field via
+    `_aen_ospi_device_state()` (false -> absent, "optional" -> BOM variant).
+    `presence.family_invariant` is for the one domain no SKU preset describes.
+    """
+    presence = domain["presence"]
+    if presence.get("family_invariant"):
+        return "populated", domain.get("chip")
+    node: Any = on_module
+    for part in presence["on_module_key"].split("."):
+        node = node.get(part) if isinstance(node, dict) else None
+    if node is None:
+        return None
+    if isinstance(node, dict):
+        state, chip = _aen_ospi_device_state(node)
+        if state == "not_populated":
+            return None
+        return state, chip or domain.get("chip")
+    if not node or _is_tbd(node):
+        return None
+    return "populated", str(node)
+
+
+#: `alp,stop-hold` strength order: the weakest control decides.
+_AEN_STOP_HOLD_RANK = {"no": 0, "unproven": 1, "yes": 2}
+
+#: Control role -> the DT gpio property name `alp,som-power-domain` uses.
+_AEN_POWER_ROLE_PROP = {
+    "reset": "reset-gpios",
+    "rail_enable": "enable-gpios",
+    "powerdown": "powerdown-gpios",
+    "enable": "enable-gpios",
+    "wake_in": "wake-gpios",
+}
+
+
+def _aen_som_power_dts(
+        sku_preset: dict[str, Any], domains: dict[str, Any],
+        links: dict[str, Any], wired_pads: list[dict[str, Any]],
+) -> list[str]:
+    """The `alp,som-power` node: one `alp,som-power-domain` child per domain
+    this SKU actually carries (alp-sdk#2784, metadata-only -- nothing in the
+    SDK drives these pads yet).
+
+    Pad, polarity and action facts come from `power_domains:` in
+    on-module-links.yaml; whether the domain exists on this SKU comes from the
+    SKU's own `on_module:` block (`_aen_power_domain_presence()`).
+    """
+    on_module = sku_preset.get("on_module") or {}
+    device_labels = {
+        d["node_label"]
+        for d in (links["brd_i2c"].get("devices") or []) if d.get("node_label")}
+    children: list[str] = []
+    for name, dom in domains.items():
+        found = _aen_power_domain_presence(dom, on_module)
+        if found is None:
+            continue
+        state, chip = found
+        label = dom.get("device_label")
+        if label and label not in device_labels:
+            raise ZephyrBoardEmitError(
+                f"power_domains.{name}.device_label {label!r} is not a "
+                "node_label under on_module_links.brd_i2c.devices")
+        action = dom["default_action"]
+        actions = dom["actions"]
+        if action not in actions:
+            raise ZephyrBoardEmitError(
+                f"power_domains.{name}.default_action {action!r} is not in "
+                "its actions:")
+        by_signal = {c["signal"]: c for c in dom["controls"]}
+        # The hold level that matters is the default action's own pad; a
+        # command-only action falls back to the domain's pads (weakest wins).
+        ctl = by_signal.get(actions[action].get("control", ""))
+        held = ([ctl] if ctl else
+                [c for c in dom["controls"] if c["direction"] == "out"])
+        stop_hold = (min((c["holds_through_stop"] for c in held),
+                         key=_AEN_STOP_HOLD_RANK.__getitem__)
+                     if held else "none")
+        node = name.replace("_", "-")
+        child = [""]
+        child += _c_comment(dom["evidence"], "\t\t")
+        child += [f"\t\tsom_pd_{name}: {node} {{",
+                  '\t\t\tcompatible = "alp,som-power-domain";',
+                  f'\t\t\talp,role = "{name}";']
+        seen_props: set[str] = set()
+        for c in dom["controls"]:
+            prop = _AEN_POWER_ROLE_PROP[c["role"]]
+            if prop in seen_props:
+                raise ZephyrBoardEmitError(
+                    f"power_domains.{name}: two controls map to {prop}")
+            seen_props.add(prop)
+            flag = ("GPIO_ACTIVE_LOW" if c["polarity"] == "active_low"
+                    else "GPIO_ACTIVE_HIGH")
+            child.append(
+                f"\t\t\t{prop} = <&{c['gpio_node']} {c['gpio_pin']} {flag}>;"
+                f" /* {c['signal']} {c['silicon_pad']} */")
+        if dom.get("secondary_rtc"):
+            child.append("\t\t\talp,primary-rtc;")
+        if label:
+            child.append(f"\t\t\talp,device = <&{label}>;")
+        if chip:
+            child.append(f'\t\t\talp,chip = "{chip}";')
+        child += [
+            f'\t\t\talp,default-action = "{action}";',
+            "\t\t\talp,default-modes = "
+            + ", ".join(f'"{m}"' for m in dom["default_modes"]) + ";",
+            f'\t\t\talp,stop-hold = "{stop_hold}";',
+            f'\t\t\talp,restore = "{dom["restore"]["method"]}";']
+        if actions.get("rail_off", {}).get("opt_in"):
+            child.append("\t\t\talp,rail-off-opt-in;")
+        if state == "optional":
+            child.append("\t\t\talp,bom-optional;")
+        deps = sorted({d["kind"] for d in dom.get("dependents") or []})
+        if deps:
+            child.append("\t\t\talp,dependents = "
+                         + ", ".join(f'"{d}"' for d in deps) + ";")
+        child.append("\t\t};")
+        children += child
+
+    # Every output control pad the layer drives, muxed and pad-configured by the
+    # `alp,som-power` node's own pinctrl-0 state.  Pad config is input-enable +
+    # schmitt (0x23 with the default 4 mA drive on the LP pads: the value the
+    # bench-proven CC3501E bring-up writes by hand) so the output driver is on
+    # and the pad can be read back.  Port 15 is the LPGPIO island.  The group sets
+    # mux / pad configuration only, never direction or level (those are GPIO-port
+    # state), so applying it to a pad whose domain is KEEP_ALIVE changes nothing.
+    pads: list[tuple[int, int]] = []
+    for name, dom in domains.items():
+        if _aen_power_domain_presence(dom, on_module) is None:
+            continue
+        for c in dom["controls"]:
+            m = re.fullmatch(r"P(\d+)_(\d)", c["silicon_pad"])
+            if c["direction"] != "out" or m is None:
+                continue
+            pad = (int(m.group(1)), int(m.group(2)))
+            if pad not in pads:
+                pads.append(pad)
+    pads.sort()
+    pinmux = ", ".join(
+        f"<PIN_P{port}_{pin}__{'LPGPIO' if port == 15 else 'GPIO'}>"
+        for port, pin in pads)
+
+    # LPGPIO pads the module wires without a domain control, so a wake-pad
+    # claim is per board (src/backends/power/som_power.c reads this property).
+    wired_line = []
+    if wired_pads:
+        cells = " ".join(str(int(p["silicon_pad"][4:])) for p in wired_pads)
+        wired_line = [
+            "\t\t/* SoM-wired LPGPIO pads without a domain node (alif-ospi.tsv):",
+            "\t\t * " + ", ".join(f"{p['signal']} {p['silicon_pad']}" for p in wired_pads) + ".",
+            "\t\t * Never an application wake pad. */",
+            f"\t\talp,wired-lpgpio-pads = <{cells}>;"]
+
+    lines = [
+        "/*",
+        " * SoM power domains (alp-sdk#2784): which on-module chips this SKU carries,",
+        " * the SoC pads that gate them, and the default quiesce action per domain.",
+        " * Presence follows this SKU's `on_module` block; pads, polarity and actions",
+        " * come from `power_domains:` in metadata/e1m_modules/aen/on-module-links.yaml.",
+        " * The SoM power layer (src/backends/power/som_power.c) reads this node and",
+        " * applies its pinctrl-0 state before it first drives a pad.  `alp,stop-hold` is",
+        " * \"unproven\" for every LPGPIO (P15_n) pad until the STOP bench shows the output",
+        " * holds.",
+        " */",
+        "&pinctrl {",
+        "\tpinctrl_som_power: pinctrl_som_power {",
+        "\t\tgroup0 {",
+        f"\t\t\tpinmux = {pinmux};",
+        "\t\t\tinput-enable;",
+        "\t\t\tinput-schmitt-enable;",
+        "\t\t};",
+        "\t};",
+        "};",
+        "",
+        "/ {",
+        "\tsom_power: som-power {",
+        '\t\tcompatible = "alp,som-power";',
+        "\t\tpinctrl-0 = <&pinctrl_som_power>;",
+        '\t\tpinctrl-names = "default";',
+        *wired_line,
+        *children,
+        "\t};",
+        "};",
+        "",
+    ]
+    return lines
+
+
+# ---------------------------------------------------------------------
+# V2N-family files: pinctrl.dtsi, _defconfig (#655)
+# ---------------------------------------------------------------------
+
+
+def _load_supervisor_links_doc(metadata_root: Path) -> dict[str, Any]:
+    """Load `metadata/e1m_modules/v2n/supervisor-links.yaml` as a whole doc.
+
+    Family-scoped (see the module docstring): this one file backs both the
+    `v2n` and `v2n-m1` families' pinctrl.dtsi / _defconfig, so it is not
+    looked up per-SoM the way `_aen_console_pinmux_rows()` reads
+    `pinmux/aen.yaml`.
+    """
+    path = metadata_root / "e1m_modules" / "v2n" / "supervisor-links.yaml"
+    if not path.is_file():
+        raise ZephyrBoardEmitError(
+            f"no {path} -- the V2N/V2M pinctrl.dtsi/_defconfig emitters need "
+            "the on-module GD32G553 supervisor pin-wiring source (#655)")
+    return _load_yaml(path)
+
+
+def _v2n_declared_families(metadata_root: Path) -> list[str]:
+    """The `families:` list `supervisor-links.yaml` declares it backs.
+
+    Load-bearing: `emit_zephyr_board()`'s V2N/V2M branch gates on this list
+    instead of a hardcoded `("v2n", "v2n-m1")` tuple, so dropping a family
+    here (e.g. removing `v2n-m1`) actually stops that family's
+    pinctrl.dtsi/_defconfig from being generated rather than silently
+    continuing on a stale local constant nothing else reads.
+    """
+    doc = _load_supervisor_links_doc(metadata_root)
+    families = doc.get("families")
+    if not isinstance(families, list) or not families:
+        raise ZephyrBoardEmitError(
+            "metadata/e1m_modules/v2n/supervisor-links.yaml has no "
+            "non-empty families: list")
+    return families
+
+
+def _load_supervisor_links(metadata_root: Path) -> dict[str, Any]:
+    """Load + shape-check the `supervisor_links:` block of
+    `metadata/e1m_modules/v2n/supervisor-links.yaml`."""
+    doc = _load_supervisor_links_doc(metadata_root)
+    links = doc.get("supervisor_links")
+    if not isinstance(links, dict):
+        raise ZephyrBoardEmitError(
+            "metadata/e1m_modules/v2n/supervisor-links.yaml has no "
+            "supervisor_links: block")
+    for key in ("console", "gd32_spi", "brd_i2c"):
+        if key not in links:
+            raise ZephyrBoardEmitError(
+                "metadata/e1m_modules/v2n/supervisor-links.yaml "
+                f"supervisor_links: is missing {key!r}")
+    return links
+
+
+def _pin_by_peripheral(pins: list[dict[str, Any]], peripheral: str) -> dict[str, Any]:
+    for p in pins:
+        if p.get("silicon_peripheral") == peripheral:
+            return p
+    raise ZephyrBoardEmitError(
+        f"no {peripheral!r} row in this link's pins[] "
+        "(supervisor-links.yaml / on-module-links.yaml)")
+
+
+def _rzv_pinmux(row: dict[str, Any]) -> str:
+    return f"RZV_PINMUX({row['pfc_port']}, {row['pfc_pin']}, {row['pfc_func']})"
+
+
+#: RZ/V2N PFC alternate-function role -> mnemonic suffix for the gd32_spi
+#: link's `silicon_peripheral` roles ("GD32_SPI.MOSI" -> "MOSI", etc.).
+#: SCLK is the one exception to a literal pass-through: the RZ/V2N PFC
+#: table names that alternate function "SCK", not "SCLK".
+_V2N_SPI_ROLE_MNEMONIC = {"MOSI": "MOSI", "MISO": "MISO", "SCLK": "SCK"}
+
+
+def _v2n_sci_channel(dt_label: str) -> str:
+    """`"sci7"` -> `"7"` -- the SCI channel digit `gd32_spi.dt_label`
+    encodes, used to build the PFC alternate-function mnemonics
+    (`TXD7_MOSI7`, `RXD7_MISO7`, `SCK7`) instead of hardcoding them."""
+    m = re.match(r"^sci([0-9]+)$", dt_label)
+    if not m:
+        raise ZephyrBoardEmitError(
+            f"gd32_spi.dt_label {dt_label!r} is not sci<N> -- can't derive "
+            "the RZ/V2N PFC alternate-function mnemonics from it")
+    return m.group(1)
+
+
+def _v2n_spi_pfc_mnemonic(row: dict[str, Any], channel: str) -> str:
+    """RZ/V2N PFC alternate-function mnemonic for a `gd32_spi` pin row,
+    e.g. (`silicon_peripheral="GD32_SPI.MOSI"`, channel `"7"`) -> `"MOSI7"`.
+    """
+    role = row["silicon_peripheral"].rsplit(".", 1)[-1]
+    return f"{_V2N_SPI_ROLE_MNEMONIC[role]}{channel}"
+
+
+def _v2n_assignable_m33(
+    metadata_root: Path, soc_spec: dict[str, Any],
+) -> list[tuple[str, dict[str, Any], list[tuple[dict[str, Any], tuple[str, int, int]]]]]:
+    """(instance, entry, [(row, (port, pin, func))]) for every `assignable:`
+    instance of core-ownership.yaml that carries an `m33:` devicetree block --
+    the peripherals the CM33 board tree declares `disabled`, left for a
+    project's `--emit dts-overlay` / `zephyr-conf` to enable (board.yaml
+    `ownership:`).  The PFC function codes are the SoC JSON's
+    `linux_dt[soc_instance].pinmux` -- one silicon-fact source for both cores."""
+    from .ownership import instance_pfc
+    path = metadata_root / "e1m_modules" / "v2n" / "core-ownership.yaml"
+    if not path.is_file():
+        return []
+    out = []
+    for inst, e in sorted((_load_yaml(path).get("assignable") or {}).items()):
+        if "m33" not in e:
+            continue
+        rows = instance_pfc(soc_spec, e)
+        for r, pfc in rows:
+            if pfc is None:
+                raise ZephyrBoardEmitError(
+                    f"core-ownership.yaml assignable.{inst} has an m33: block but the SoC "
+                    f"linux_dt.{e.get('soc_instance')}.pinmux has no function code for "
+                    f"{r['peripheral']}")
+        out.append((inst, e, rows))
+    return out
+
+
+def _v2n_assignable_pinctrl(assignable: list) -> str:
+    """`&pinctrl { ... };` groups for the assignable instances (empty when
+    none).  Pins are the rows' own pfc_* triples -- no literals here."""
+    out = ""
+    for inst, e, rows in assignable:
+        pc = e["m33"]["pinctrl"]
+        pins = "".join(
+            ("\t\t\tpinmux = " if i == 0 else "\t\t\t\t ")
+            + f"<RZV_PINMUX({port}, {pin}, {func})>{';' if i == len(rows) - 1 else ','} "
+            f"/* {r['peripheral']} {r['pad']} */\n"
+            for i, (r, (port, pin, func)) in enumerate(rows))
+        out += (
+            "\n&pinctrl {\n"
+            f"\t/* {inst}: pad group for the CM33 when a project assigns it (board.yaml\n"
+            "\t * `ownership:`); unreferenced while the node stays disabled. */\n"
+            f"\t{pc['group_label']}: {pc['node']} {{\n"
+            f"\t\t{pc['child_node']} {{\n"
+            f"{pins}"
+            "\t\t};\n\t};\n};\n")
+    return out
+
+
+def _v2n_assignable_dts(assignable: list) -> list[str]:
+    """Board-dts lines declaring each assignable node `disabled` with its
+    pinctrl group; the owning project's overlay flips it to `okay`."""
+    lines: list[str] = []
+    for inst, e, _rows in assignable:
+        m = e["m33"]
+        lines += [
+            "/*",
+            f" * {inst} (assignable, metadata/e1m_modules/v2n/core-ownership.yaml): disabled on",
+            " * the board; a project that assigns it to m33 enables it in its own overlay.",
+            " */",
+            f"&{m['dt_label']} {{",
+            f"\tpinctrl-0 = <&{m['pinctrl']['group_label']}>;",
+            '\tpinctrl-names = "default";',
+            '\tstatus = "disabled";',
+            "};",
+            "",
+        ]
+    return lines
+
+
+def _v2n_pinctrl_dtsi(links: dict[str, Any], assignable: list = ()) -> str:
+    """`<board>-pinctrl.dtsi` for a V2N/V2M `m33_sm` board.
+
+    Prose (the GD32 SPI block comment, the console/BRD_I2C one-liners)
+    lives here as template text, matching `_aen_pinctrl_dtsi()`'s pattern;
+    the pad numbers, PFC (port, pin, func) triples, DT node/group/child
+    names, and the GD32 I2C address all come from
+    `metadata/e1m_modules/v2n/supervisor-links.yaml`.
+    """
+    console = links["console"]
+    gd32_spi = links["gd32_spi"]
+    brd_i2c = links["brd_i2c"]
+
+    txd0 = _pin_by_peripheral(console["pins"], "UART0_TXD0")
+    rxd0 = _pin_by_peripheral(console["pins"], "UART0_RXD0")
+    mosi = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.MOSI")
+    miso = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.MISO")
+    sclk = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.SCLK")
+    sda = _pin_by_peripheral(brd_i2c["pins"], "RIIC8_SDA8")
+    scl = _pin_by_peripheral(brd_i2c["pins"], "RIIC8_SCL8")
+    cs0 = gd32_spi["gpio_chip_select"]
+
+    # PFC alternate-function mnemonics + the console's own TXD0 reference,
+    # derived from metadata (gd32_spi.dt_label's channel digit +
+    # silicon_peripheral) rather than hardcoded, so a pfc_func or channel
+    # change can't silently desync this prose from the RZV_PINMUX(...)
+    # triples it documents.
+    spi_channel = _v2n_sci_channel(gd32_spi["dt_label"])
+    mosi_mnem = f"TXD{spi_channel}_{_v2n_spi_pfc_mnemonic(mosi, spi_channel)}"
+    miso_mnem = f"RXD{spi_channel}_{_v2n_spi_pfc_mnemonic(miso, spi_channel)}"
+    sclk_mnem = _v2n_spi_pfc_mnemonic(sclk, spi_channel)
+    console_mnem = txd0["silicon_peripheral"].split("_", 1)[1]
+
+    return (
+        _COPYRIGHT_C +
+        " */\n"
+        "\n"
+        "#include <zephyr/dt-bindings/gpio/gpio.h>\n"
+        "#include <zephyr/dt-bindings/pinctrl/renesas/pinctrl-rzv2n.h>\n"
+        "\n"
+        "&pinctrl {\n"
+        f"\t/* {console['peripheral']} console: {txd0['silicon_pad']} TXD / "
+        f"{rxd0['silicon_pad']} RXD */\n"
+        f"\t{console['pinctrl_group_label']}: {console['pinctrl_node']} {{\n"
+        f"\t\t{console['pinctrl_child_node']} {{\n"
+        f"\t\t\tpinmux = <{_rzv_pinmux(txd0)}>, /* TXD */\n"
+        f"\t\t\t\t <{_rzv_pinmux(rxd0)}>; /* RXD */\n"
+        "\t\t\t/* RXD resets Hi-Z with no pull: a floating RXD0 raises sci0 eri.\n"
+        "\t\t\t * Renesas' own RSCI UART pin groups always carry bias-pull-up\n"
+        "\t\t\t * (audit CM33-01/IO-01/CM33-M3).  Whole group; a pull-up on TXD is\n"
+        "\t\t\t * harmless. */\n"
+        "\t\t\tbias-pull-up;\n"
+        "\t\t};\n"
+        "\t};\n"
+        "\n"
+        "\t/*\n"
+        f"\t * GD32G553 SPI fast path on SCI channel {spi_channel} (clock-synchronous Simple-SPI).\n"
+        f"\t * Per the RZ/V2N PFC (Table 1.2-3): {mosi['silicon_pad']} = {mosi_mnem} (func{mosi['pfc_func']}), "
+        f"{miso['silicon_pad']} =\n"
+        f"\t * {miso_mnem} (func{miso['pfc_func']}), {sclk['silicon_pad']} = {sclk_mnem} (func{sclk['pfc_func']}).  Calibrated against the known-good\n"
+        f"\t * console pin {txd0['silicon_pad']} = {console_mnem} (func{txd0['pfc_func']}) and the P52 TXD1/SCK0/DE0/CTS0N column run.\n"
+        "\t *\n"
+        f"\t * {cs0['silicon_pad']} (SS{spi_channel}) is deliberately NOT muxed here: master Simple-SPI has no\n"
+        f"\t * hardware slave-select, so {cs0['silicon_pad']} is driven as a GPIO chip-select "
+        f"({cs0['gpio_node']} pin {cs0['gpio_pin']};\n"
+        "\t * see cs-gpios in the board dts).  Leaving it out keeps it in GPIO mode.\n"
+        "\t */\n"
+        f"\t{gd32_spi['pinctrl_group_label']}: {gd32_spi['pinctrl_node']} {{\n"
+        f"\t\t{gd32_spi['pinctrl_child_node']} {{\n"
+        f"\t\t\tpinmux = <{_rzv_pinmux(mosi)}>, /* {mosi_mnem.split('_', 1)[1]} {mosi['silicon_pad']} */\n"
+        f"\t\t\t\t <{_rzv_pinmux(miso)}>, /* {miso_mnem.split('_', 1)[1]} {miso['silicon_pad']} */\n"
+        f"\t\t\t\t <{_rzv_pinmux(sclk)}>; /* {sclk_mnem}  {sclk['silicon_pad']} */\n"
+        "\t\t};\n"
+        "\t};\n"
+        "\n"
+        f"\t/* BRD_I2C ({brd_i2c['peripheral']}): on-module GD32G553 I2C slave @ "
+        f"0x{brd_i2c['peer_address_7bit']:02x} */\n"
+        f"\t{brd_i2c['pinctrl_group_label']}: {brd_i2c['pinctrl_node']} {{\n"
+        f"\t\t{brd_i2c['pinctrl_child_node']} {{\n"
+        f"\t\t\tpinmux = <{_rzv_pinmux(sda)}>, /* SDA {sda['silicon_pad']} */\n"
+        f"\t\t\t\t <{_rzv_pinmux(scl)}>; /* SCL {scl['silicon_pad']} */\n"
+        "\t\t};\n"
+        "\t};\n"
+        "};\n"
+    ) + _v2n_assignable_pinctrl(assignable)
+
+
+def _v2n_defconfig(links: dict[str, Any], soc_spec: dict[str, Any]) -> str:
+    """`<board>_defconfig` for a V2N/V2M `m33_sm` board.
+
+    `CONFIG_XIP=n` has no supervisor-link source -- it's a documented V2N/
+    V2M family constant (the CM33 image always runs from RAM on this
+    family), kept as a literal here rather than invented metadata. The
+    console-disable prose and the CONFIG_* symbol names are template text
+    (matching `_aen_defconfig()`'s pattern); which block gets emitted is
+    still gated on the metadata's own `status:` per link, so a
+    supervisor-links.yaml edit that (incorrectly) re-enables the console or
+    disables the GD32 bridge fails loudly here instead of silently drifting
+    the committed `_defconfig`.
+    """
+    rc_a55, _, rc_size = _ram_console(soc_spec)
+    win_base = _openamp_carveout(soc_spec)["cm33_ns_base"]
+    console = links["console"]
+    gd32_spi = links["gd32_spi"]
+    brd_i2c = links["brd_i2c"]
+    if console.get("status") != "disabled":
+        raise ZephyrBoardEmitError(
+            "supervisor-links.yaml console link must stay status: disabled "
+            "for this _defconfig template -- its floating-RX fault (see "
+            "the console pins' evidence: strings) is why the CM33 serial "
+            "console is off; re-enabling it needs a matching _defconfig "
+            "rewrite, not just a metadata flip")
+    if gd32_spi.get("status") != "enabled":
+        raise ZephyrBoardEmitError(
+            "supervisor-links.yaml gd32_spi link must stay status: enabled "
+            "for this _defconfig template to turn on CONFIG_SPI")
+    if brd_i2c.get("status") != "disabled":
+        raise ZephyrBoardEmitError(
+            "supervisor-links.yaml brd_i2c link must stay status: disabled "
+            "-- RIIC8/BRD_I2C is Cortex-A55/Linux-exclusive, so this "
+            "_defconfig template does NOT turn on CONFIG_I2C for it; "
+            "re-enabling it needs a matching _defconfig rewrite, not just "
+            "a metadata flip")
+    return (
+        _COPYRIGHT_HASH +
+        "\n"
+        "CONFIG_XIP=n\n"
+        "\n"
+        "# CM33 serial console (sci0 = EVK \"Pmod USB-UART\") DISABLED on this board:\n"
+        "# the only console is the A55's; sci0 is not wired as a CM33 console here, and\n"
+        "# opening it faults on the floating RX (sci0 eri -> Zephyr fatal -> hang before\n"
+        "# main()).  Re-enable UART_CONSOLE (and sci0 in the dts) only with a Pmod\n"
+        "# attached AND once Linux cannot gate the rsci_0_* clocks (audit CM33-05).\n"
+        "CONFIG_SERIAL=y\n"
+        "CONFIG_UART_CONSOLE=n\n"
+        "\n"
+        "# Enabling sci0 also needs CONFIG_UART_INTERRUPT_DRIVEN=y: the FSP always\n"
+        "# enables the rxi/eri IRQs, and the Zephyr driver only IRQ_CONNECTs them\n"
+        "# under it -- otherwise an unhandled NVIC line goes fatal.  Not set here:\n"
+        "# with sci0 disabled it resolves to n and Kconfig warns.\n"
+        "\n"
+        "# RAM console: the CM33 has no UART and no SWD yet, so printk lands in a\n"
+        f"# fixed buffer (zephyr,ram-console node in the dts, inside the {win_base:#x}\n"
+        "# window Linux reserves) that the A55 reads post-mortem via /dev/mem at\n"
+        f"# {rc_a55:#x}.  CONFIG_CONSOLE=y only pulls the RAM console in; with\n"
+        "# UART_CONSOLE=n nothing touches sci0.  Size must equal the dts node's reg.\n"
+        "CONFIG_CONSOLE=y\n"
+        "CONFIG_RAM_CONSOLE=y\n"
+        f"CONFIG_RAM_CONSOLE_BUFFER_SIZE={rc_size}\n"
+        "# With CONFIG_LOG=y, printk is routed into the logging core by default\n"
+        "# (LOG_PRINTK), and no CM33 log backend reaches this buffer, so it would\n"
+        "# stay empty.  Keep printk direct to the RAM console.\n"
+        "CONFIG_LOG_PRINTK=n\n"
+        "\n"
+        "# On-module GD32G553 supervisor bridge transport.  SPI only: RIIC8/\n"
+        "# BRD_I2C is Cortex-A55/Linux-exclusive, so no CONFIG_I2C here.\n"
+        "CONFIG_SPI=y\n"
+    )
+
+
+def _v2n_part_display(order_code: str) -> tuple[str, str]:
+    """Split an RZ/V2N `silicon_variant` order code into the board `.dts`
+    header's part display (`"R9A09G056N44GBG"` -> `"R9A09G056-N44"`, the
+    package suffix dropped and a hyphen inserted before the variant code)
+    and the upstream Zephyr SoC dtsi include path both n44 and n48gbg
+    variants share (`"arm/renesas/rz/rzv/r9a09g056.dtsi"`).  Raises rather
+    than guessing if a future RZ/V2N part doesn't fit this
+    base+variant+package shape -- see the no-inventing-values rule.
+    """
+    m = re.match(r"^(R9A09G056)(N[0-9]+)([A-Z]+)$", order_code)
+    if not m:
+        raise ZephyrBoardEmitError(
+            f"silicon_variant order_code {order_code!r} doesn't match the "
+            "RZ/V2N R9A09G056<variant><pkg> shape the board .dts header "
+            "and #include path expect")
+    base, variant_code, _pkg = m.groups()
+    return f"{base}-{variant_code}", f"arm/renesas/rz/rzv/{base.lower()}.dtsi"
+
+
+_V2N_OPENAMP_TAIL: tuple[str, ...] = (
+    '',
+    '/*',
+    ' * No &canfd node here (alp-sdk#1146): CAN-FD cannot be enabled on this',
+    ' * core at the pinned Zephyr v4.4.1 / hal_renesas 06282060fa, and what is',
+    ' * missing is vendor data this tree does not carry -- not lines nobody has',
+    ' * got round to writing.  Upstream DOES ship the driver',
+    ' * (drivers/can/can_renesas_rz_canfd.c) and both bindings',
+    ' * (dts/bindings/can/renesas,rz-canfd.yaml + renesas,rz-canfd-global.yaml),',
+    ' * and src/backends/can/zephyr_drv.c already binds any DT_ALIAS(alp_canN),',
+    ' * so this is an enablement gap and not a missing backend.  Four things',
+    ' * block the enablement:',
+    ' *',
+    ' *   1. No FSP CAN-FD module for RZ/V.  CONFIG_CAN_RENESAS_RZ_CANFD',
+    ' *      selects USE_RZ_FSP_CANFD (Zephyr drivers/can/Kconfig.renesas_rz),',
+    ' *      which compiles fsp/src/${SOC_SERIES_PREFIX}/r_canfd/r_canfd.c',
+    ' *      (hal_renesas drivers/rz/CMakeLists.txt).  hal_renesas carries that',
+    ' *      module for RZ/G only: fsp/src/rzg/r_canfd/ and',
+    ' *      fsp/inc/instances/rzg/r_canfd.h exist, the rzv counterparts do',
+    ' *      not.  Setting the symbol under SOC_SERIES_RZV2N is a CMake',
+    " *      configure error on a missing source file, and the driver's",
+    ' *      #include "r_canfd.h" does not resolve on the rzv include path.',
+    ' *',
+    ' *   2. No CAN-FD node in the SoC devicetree.  arm/renesas/rz/rzv/',
+    ' *      r9a09g056.dtsi declares none -- no label to reference, no reg and',
+    ' *      no interrupts to inherit.  The only RZ SoC dtsi that carries them',
+    " *      is RZ/G3S's r9a08g045.dtsi (canfd-global@400c0000, global",
+    ' *      interrupts 373 and 374, per-channel 375..380).  DO NOT COPY THOSE',
+    ' *      NUMBERS: different SoC, different vector map, different base.  On',
+    ' *      THIS part the CAN-FD register base is 0x42440000 -- hal_renesas',
+    ' *      .../Include/R9A09G056N/iodefines/canfd_iodefine.h, R_CANFD_BASE.',
+    " *      The `(@ 0x400B0000)` in that same file's R_CANFD struct",
+    " *      doc-comment is a template annotation, not this SoC's base; it is",
+    ' *      the second trap in one header.',
+    ' *',
+    " *   3. No static NVIC vector exists to write.  RZ/V2N's CM33 gives CAN-FD",
+    " *      no dedicated vector at all: bsp_irq_id.h's IRQn_Type enum has zero",
+    ' *      CANFD entries, and all 20 CAN-FD sources live in the separate',
+    ' *      IRQSELn_Type enum (354..373 -- per-channel err/rec/trx, plus',
+    ' *      CANFD_INTRCANGERR_IRQSELn 366 and CANFD_INTRCANGRECC_IRQSELn 367',
+    ' *      for the global controller).  Reaching the NVIC means routing an',
+    ' *      IRQSEL source onto one of the selectable slots',
+    ' *      SEL0_IRQn..SEL126_IRQn (NVIC 353..479) at run time, through',
+    " *      R_BSP_SelectIrqSet() (bsp/mcu/all/bsp_mcu_api.h).  Upstream's dtsi",
+    ' *      hands those slots out itself (adc0 = 403 = SEL50, gpt0 = 406..408',
+    ' *      = SEL53..55, on up to 453) and both CAN-FD bindings require',
+    ' *      `interrupts`, so choosing slots here means inventing an allocation',
+    ' *      that collides with whatever upstream picks when it adds the nodes.',
+    ' *',
+    ' *   4. No PFC function index for the pads.  The module bonds out two of',
+    " *      the SoC's six controllers -- CANFD2 (CTX2 = P84, CRX2 = P85) and",
+    ' *      CANFD3 (CTX3 = P86, CRX3 = P87), per',
+    ' *      metadata/e1m_modules/v2n/renesas-peripheral-map.tsv -- but',
+    ' *      metadata/pinmux/v2n.yaml carries pad <-> signal only, with no',
+    ' *      alternate-function number.  RZV_PINMUX() needs one, and it comes',
+    " *      from the RZ/V2N hardware manual's PFC table (the same source",
+    ' *      sci7_spi_pins above cites), not from this tree.',
+    ' *',
+    ' * What IS already in place, so a future port does not re-derive it: the',
+    ' * clock path.  RZ_CLOCK_CANFD(ch) exists',
+    ' * (dt-bindings/clock/renesas_rzv_clock.h) and',
+    ' * clock_control_renesas_rz_cpg.c already maps RZ_IP_CANFD onto',
+    ' * R_BSP_MODULE_START(FSP_IP_CANFD, ch); the rzv2n bsp_feature.h declares',
+    ' * 6 channels, CAN-FD support and 96 RX message buffers for this part.',
+    ' *',
+    " * Carrier note: the TCAN1044 transceivers' standby line is NOT a Renesas",
+    ' * pad.  CAN_STBY belongs to the GD32 IO-MCU on PB13',
+    ' * (metadata/pinmux/v2n.yaml, metadata/e1m_modules/v2n/gd32-io-mcu-map.tsv),',
+    ' * so taking the transceivers out of standby is a bridge GPIO call, not a',
+    ' * pinctrl entry.',
+    ' *',
+    ' * Until those clear, <alp/can.h> on this core returns ALP_ERR_NOT_READY',
+    ' * from src/backends/can/zephyr_drv.c -- the alp-canN aliases resolve to',
+    ' * nothing.',
+    ' */',
+    '',
+    '/*',
+    ' * OpenAMP / RPMsg carve-out for the M33-SM <-> A55-Linux link (alp-sdk #683,',
+    ' * Path B Phase 1).  Addresses are the Renesas RZ/V Multi-OS Package memory',
+    " * map, NOT the paper `ipc:` carve-out in this project's board.yaml.  The two",
+    ' * are different regions by construction, not by omission: `resolve_carve_outs()`',
+    " * (scripts/alp_orchestrate/carveout.py) allocates board.yaml's `ipc:` entry",
+    ' * from `ocram_low` (512 KiB, non-cacheable -- the only region it can reach',
+    ' * from both `a55_cluster` and `m33_sm`; metadata/socs/renesas/rzv2n/n44.json)',
+    ' * purely because the resolver needs *some* region and that is the only',
+    ' * candidate -- nothing in this firmware reads or writes the address it',
+    ' * resolves to.  The real transport uses the hand-authored DDR window below',
+    " * instead, sized from this responder's OpenAMP resource table (512 rpmsg",
+    " * buffers x 512 B x 2 vrings -- m33_sm/src/resource_table.h's",
+    ' * RSC_TABLE_NUM_RPMSG_BUFF).  That sizing happens to consume the whole of',
+    ' * `ocram_low` when expressed as `carve_out_kb` in board.yaml (both examples',
+    ' * on this SoM request 512, i.e. all 512 KiB of `ocram_low`) -- harmless',
+    ' * today because nothing consumes the resolved address, but it means a',
+    ' * second `ipc:` entry on this SoM has no ocram_low headroom left to land',
+    ' * in.  Whether the fix is teaching the resolver about this DDR window, or',
+    ' * shrinking the paper `carve_out_kb` values to leave ocram_low headroom, is',
+    ' * an open sizing question for whoever picks it up next -- it is not settled',
+    ' * by #683, which is about bench-validating the real `/dev/rpmsg` transport,',
+    ' * not this address reconciliation.',
+    ' *',
+    ' * CORRECTED (alp-sdk #683, address root-cause fix): this region used to be',
+    ' * quoted at the RZ/V2L CM33-NS offset (0x62f00000, i.e. A55 - 0x20000000),',
+    ' * which is the V2N xSPI-NOR secure window on THIS SoC -- writes there never',
+    ' * reach DRAM.  The authoritative V2N map (Renesas FSP',
+    ' * drivers/rz/fsp/src/rzv/bsp/mcu/rzv2n/bsp_slave_address.h, confirmed by',
+    " * this board's upstream ddr node) is CM33-secure 0x80000000 / CM33-NS",
+    ' * 0x90000000 / A55 0x40000000, a 256 MiB window, i.e. A55 phys = CM33-NS -',
+    ' * 0x50000000.  Of that window only A55 0x48000000..0x4FFFFFFF is real,',
+    ' * populated NS RAM (0x40000000..0x47FFFFFF reads back 0xFF) -- the base',
+    ' * below is chosen so the whole carve-out (0x4F700000..0x4FFFFFFF) sits',
+    ' * entirely inside that populated range, right up against its top.  The',
+    ' * rsctbl/vring/shm regions below are all quoted in the CM33 view, matching',
+    " * upstream's openamp_linux_zephyr sample; see resource_table.h for the",
+    ' * CM33->A55 translation macro this same fix corrected.',
+    ' *',
+    ' * mbox1 is hand-authored: unlike the RZ/V2L SoC dtsi (r9a07g054.dtsi, which',
+    ' * ships mbox1/mbox3/mbox4/mbox5), the upstream RZ/V2N SoC dtsi',
+    ' * (r9a09g056.dtsi) has no MHU node at all yet -- added here at board level',
+    ' * per the "board .dts stays hand-authored for the v2n family"',
+    ' * (scripts/gen_zephyr_board.py) rather than editing the vendored SoC dtsi.',
+    ' *',
+    ' * RESOLVED (alp-sdk #683 Phase 2): RZ/V2N\'s MHU hardware is the newer "MHU-B"',
+    ' * variant (hal_renesas drivers/rz/fsp/src/rzv/bsp/mcu/rzv2n/bsp_mhu_b.h) with',
+    ' * only channels {5, 11, 17, 23} valid (BSP_FEATURE_MHU_B_NS_VALID_CHANNEL_MASK)',
+    ' * and a non-linear per-channel register/IRQ pairing -- NOT the plain linear MHU',
+    " * that Zephyr's mbox_renesas_rz_mhu.c + FSP r_mhu_ns.c implement (that pair does",
+    ' * not compile for rzv2n). This node now uses the vendored MHU-B port instead',
+    ' * (compatible `renesas,rz-mhu-b-mbox`, driver',
+    ' * zephyr/drivers/mbox/mbox_renesas_rz_mhu_b.c, FSP module',
+    " * zephyr/drivers/mbox/r_mhu_b_ns/r_mhu_b_ns.c -- see that file's header for the",
+    ' * register-semantic notes and the "FLAG FOR REVIEW" send_type caveat, and',
+    " * mbox_renesas_rz_mhu_b.c's header for the bounded #697 verification status:",
+    ' * init/attach and A55->M33 receive are silicon-proven, mbox_send() M33->A55',
+    ' * is unexercised and does not reach the A55 on this topology).',
+    " * `channel = <5>` is the lowest MHU-B-valid channel.  Per bsp_mhu_b.h's",
+    ' * R_BSP_MHU_B_NS_REG_PAIR_BODY, channel 5 sends via R_MHU_NS36 (base',
+    ' * 0x50480480) and receives via R_MHU_NS8 (base 0x50480100) -- `reg` below',
+    ' * documents the send register only (the driver resolves both from the',
+    ' * pair-body table by channel number, not from this property; the binding',
+    ' * schema requires `reg` regardless).  `interrupts = <293 2>` is',
+    ' * MHU_MSG5_NS_IRQn (bsp_irq_id.h), which r_mhu_b_ns.c matches against',
+    " * bsp_mhu_b.h's R_BSP_MHU_B_NS_SEND_TYPE_RSP_BODY to derive send_type = RSP",
+    ' * for this instance.',
+    ' */',
+    '/ {',
+    '\treserved-memory {',
+    '\t\t#address-cells = <1>;',
+    '\t\t#size-cells = <1>;',
+    '\t\tranges;',
+    '',
+    '\t\t/* Whole OpenAMP region as one reservation to save MPU entries',
+    "\t\t * (matches the vendor sample's rationale). */",
+    '\t\topenamp_shm: memory@@carveout.hex@ {',
+    '\t\t\tcompatible = "zephyr,memory-region";',
+    '\t\t\treg = <@carveout.addr@ @carveout.size@>;',
+    '\t\t\tzephyr,memory-region = "openamp_memory";',
+    '\t\t\tzephyr,memory-attr = <DT_MEM_ARM(ATTR_MPU_IO)>;',
+    '\t\t};',
+    '\t};',
+    '',
+    '\t/* CM33-NS view minus A55 view of the OpenAMP reservation (from metadata) */',
+    '\tzephyr,user {',
+    '\t\talp,cm33-ns-to-a55-offset = <@carveout.offset@>;',
+    '\t};',
+    '',
+    '\tchosen {',
+    '\t\t/* The A55 master (DRIVER role) allocates every rpmsg buffer from',
+    '\t\t * vring_shm1 (@vring-shm1.a55@ A55 / @vring-shm1.addr@ CM33-NS) -- the',
+    '\t\t * "mst-alloc = vring-shm1" contract in the backend REFERENCE.  The',
+    "\t\t * M33's descriptor-translation window MUST cover that pool, so it",
+    '\t\t * points at vring_shm1, not vring_shm0 (whose window ends exactly at',
+    '\t\t * @vring-shm0.end@, leaving every buffer outside it).  Silicon-root-caused',
+    '\t\t * alongside the vring-DA fix (#683/#697 bench, 2026-07-11). */',
+    '\t\tzephyr,ipc_shm = &vring_shm1;',
+    '\t\tzephyr,ipc = &mbox_consumer;',
+    '\t};',
+    '',
+    '\trsctbl: memory@@rsctbl.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@rsctbl.addr@ @rsctbl.size@>;',
+    '\t};',
+    '',
+    "\t/* Widened from the RZ/V2L layout's 8-byte mhu1_shm (@ +0x1008) to a",
+    '\t * full 4 KiB region immediately after rsctbl, so it lines up with the',
+    "\t * A55/kernel-overlay side's @mhu-shm.a55hex@.mhu-shm node 1:1 (alp-sdk #683",
+    '\t * address fix). */',
+    '\tmhu1_shm: memory@@mhu-shm.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@mhu-shm.addr@ @mhu-shm.size@>;',
+    '\t};',
+    '',
+    '\tvring_ctrl0: memory@@vring-ctl0.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@vring-ctl0.addr@ @vring-ctl0.size@>;',
+    '\t};',
+    '',
+    '\tvring_ctrl1: memory@@vring-ctl1.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@vring-ctl1.addr@ @vring-ctl1.size@>;',
+    '\t};',
+    '',
+    '\tvring_shm0: memory@@vring-shm0.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@vring-shm0.addr@ @vring-shm0.size@>;',
+    '\t};',
+    '',
+    '\t/* The rpmsg buffer pool: the A55 master allocates from here, so this is',
+    "\t * the M33's zephyr,ipc_shm window (see the chosen node above).",
+    '\t * vring_shm0 is kept reserved so the region layout still matches the A55',
+    "\t * kernel overlay's 6 nodes 1:1. */",
+    '\tvring_shm1: memory@@vring-shm1.hex@ {',
+    '\t\tcompatible = "mmio-sram";',
+    '\t\treg = <@vring-shm1.addr@ @vring-shm1.size@>;',
+    '\t};',
+    '',
+    '\tmbox_consumer: mbox-consumer {',
+    '\t\tcompatible = "vnd,mbox-consumer";',
+    '\t\tmboxes = <&mbox1 1>, <&mbox1 0>;',
+    '\t\tmbox-names = "tx", "rx";',
+    '\t};',
+    '',
+    '\tsoc {',
+    '\t\t/* CA55_0 <-> CM33 -- see the MHU-B note above. */',
+    '\t\tmbox1: mhu@50480480 {',
+    '\t\t\tcompatible = "renesas,rz-mhu-b-mbox";',
+    '\t\t\tchannel = <5>;',
+    '\t\t\treg = <0x50480480 0x20>; /* R_MHU_NS36 (send reg) -- see the MHU-B note above */',
+    '\t\t\ttx-mask = <0x00000002>; /* Channel 1 is for TX */',
+    '\t\t\trx-mask = <0x00000001>; /* Channel 0 is for RX */',
+    '\t\t\tchannels-count = <2>;',
+    '\t\t\tinterrupts = <293 2>; /* MHU_MSG5_NS_IRQn, bsp_irq_id.h -- verified against the vendor header */',
+    '\t\t\tinterrupt-names = "mhuns";',
+    '\t\t\t#mbox-cells = <1>;',
+    '\t\t\tshared-memory = <&mhu1_shm>;',
+    '\t\t\tstatus = "okay";',
+    '\t\t};',
+    '\t};',
+    '};',
+)
+
+
+def _openamp_carveout(soc_spec: dict[str, Any]) -> dict[str, Any]:
+    """The SoC spec's `openamp_carveout` block, refused with a coded error
+    naming the first missing field -- never a bare `KeyError` out of `tan
+    generate --target zephyr-board` against an alp-sdk that predates the
+    block (alp-sdk#2685, the floor this change raises tan to)."""
+    where = f"SoC spec {soc_spec.get('ref')} `openamp_carveout`"
+    c = soc_spec.get("openamp_carveout")
+    if not isinstance(c, dict) or not c:
+        raise ZephyrBoardEmitError(
+            f"{where} is missing -- the V2N/V2M board emits the OpenAMP window "
+            "and the CM33 RAM console from it (needs alp-sdk b04bb0f7a or newer)")
+
+    def need(block: dict[str, Any], name: str, path: str) -> Any:
+        if not isinstance(block, dict) or block.get(name) is None:
+            raise ZephyrBoardEmitError(
+                f"{where} has no `{path}{name}` field")
+        return block[name]
+
+    for f in ("cm33_ns_base", "a55_base", "size"):
+        need(c, f, "")
+    regions = need(c, "regions", "")
+    if not isinstance(regions, dict):
+        raise ZephyrBoardEmitError(f"{where} `regions` is not a mapping")
+    for name, r in regions.items():
+        for f in ("offset", "size"):
+            need(r, f, f"regions.{name}.")
+    rc = need(c, "ram_console", "")
+    for f in ("offset", "size"):
+        need(rc, f, "ram_console.")
+    return c
+
+
+def _openamp_subst(tail: tuple[str, ...], soc_spec: dict[str, Any]) -> list[str]:
+    """Fill the OpenAMP window tokens from the SoC's `openamp_carveout`
+    (metadata/socs/**.json; the one declaration the Linux DT, the backend
+    header and scripts/check_amp_window.py also read).  Tokens:
+    `@carveout.{addr,hex,size}@` for the whole reservation and, per name in
+    `regions`, `@<name>.{addr,hex,size,end,a55,a55hex}@` -- addr/hex/end in
+    the CM33-NS view, a55/a55hex in the A55 view."""
+    c = _openamp_carveout(soc_spec)
+    base, a55 = c["cm33_ns_base"], c["a55_base"]
+    tok = {
+        "@carveout.addr@": f"{base:#x}",
+        "@carveout.hex@": f"{base:x}",
+        "@carveout.size@": f"{c['size']:#x}",
+        "@carveout.offset@": f"{base - a55:#x}",
+    }
+    for name, r in c["regions"].items():
+        off, size = r["offset"], r["size"]
+        tok.update({
+            f"@{name}.addr@": f"{base + off:#x}",
+            f"@{name}.hex@": f"{base + off:x}",
+            f"@{name}.size@": f"{size:#x}",
+            f"@{name}.end@": f"{base + off + size:#x}",
+            f"@{name}.a55@": f"{a55 + off:#x}",
+            f"@{name}.a55hex@": f"{a55 + off:x}",
+        })
+    out = []
+    for line in tail:
+        for k, v in tok.items():
+            line = line.replace(k, v)
+        out.append(line)
+    return out
+
+
+def _ram_console(soc_spec: dict[str, Any]) -> tuple[int, int, int]:
+    """(A55 address, CM33-NS address, size) of the CM33 RAM console, from the
+    SoC's `openamp_carveout.ram_console` (the one declaration; the dts node,
+    CONFIG_RAM_CONSOLE_BUFFER_SIZE and scripts/gen_amp_window.py all read it)."""
+    c = _openamp_carveout(soc_spec)
+    off = c["ram_console"]["offset"]
+    return c["a55_base"] + off, c["cm33_ns_base"] + off, c["ram_console"]["size"]
+
+
+def _v2n_dts(
+    sku: str, dir_name: str, soc_spec: dict[str, Any], variant: dict[str, Any],
+    sku_preset: dict[str, Any], links: dict[str, Any],
+    assignable: list = (),
+) -> str:
+    """Board `.dts` for a V2N/V2M `m33_sm` board (#655 slice 2).
+
+    Reuses the upstream RZ/V2N SoC devicetree; adds the on-module GD32G553
+    supervisor links from `supervisor-links.yaml` (the same source
+    `_v2n_pinctrl_dtsi()` reads).  Only SoMs whose
+    `topology.m33_sm.openamp_ipc` preset field is true also get the
+    OpenAMP/MHU-B reserved-memory block and the CAN-FD-unavailable
+    analysis (alp-sdk #683/#1146) -- E1M-V2M101 does not carry either
+    block in the currently-committed tree, so this generator reproduces
+    that gap rather than "fixing" it; the byte-identity pin
+    (`tests/scripts/test_gen_zephyr_board.py`) is against what is
+    committed today, not against what a more "complete" V2M101 board
+    would look like.
+    """
+    slug = sku[len("E1M-"):].lower()
+    compatible = f"alp,e1m-{slug}-m33-sm"
+    model = f"Alp {sku} Cortex-M33 system manager"
+
+    part_display, soc_dtsi_include = _v2n_part_display(variant["order_code"])
+    family = soc_spec.get("family")
+    if not family or _is_tbd(family):
+        raise ZephyrBoardEmitError(f"SoC spec {soc_spec.get('ref')} declares no usable `family`")
+    family_display = f"{family} {part_display}"
+    if (sku_preset.get("on_module") or {}).get("npu") == "deepx_dxm1":
+        family_display += " + DEEPX DX-M1"
+
+    console = links["console"]
+    gd32_spi = links["gd32_spi"]
+    brd_i2c = links["brd_i2c"]
+    wdt = _find_core(soc_spec, "m33_sm").get("watchdog") or {}
+    if not wdt:
+        raise ZephyrBoardEmitError(
+            f"SoC spec {soc_spec.get('ref')} core m33_sm declares no `watchdog` "
+            "block (base/size/counting_clock_hz) -- the V2N/V2M board emits the "
+            "CM33 watchdog node and the alp-wdt0 alias from it")
+    wdt_base = wdt["base"]
+    txd0 = _pin_by_peripheral(console["pins"], "UART0_TXD0")
+    rxd0 = _pin_by_peripheral(console["pins"], "UART0_RXD0")
+    mosi = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.MOSI")
+    miso = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.MISO")
+    sclk = _pin_by_peripheral(gd32_spi["pins"], "GD32_SPI.SCLK")
+    sda = _pin_by_peripheral(brd_i2c["pins"], "RIIC8_SDA8")
+    scl = _pin_by_peripheral(brd_i2c["pins"], "RIIC8_SCL8")
+    cs0 = gd32_spi["gpio_chip_select"]
+    pads = links.get("gd32_pads")  # optional: GD32 SWD + ATTN pads (alp,gd32-pads)
+    peer_addr = brd_i2c["peer_address_7bit"]
+    ch = _v2n_sci_channel(gd32_spi["dt_label"])  # "7"
+
+    has_openamp = bool(
+        (sku_preset.get("topology") or {}).get("m33_sm", {}).get("openamp_ipc"))
+    rc_a55, rc_addr, rc_size = _ram_console(soc_spec)
+    carveout = _openamp_carveout(soc_spec)
+    win_base, win_size = carveout["cm33_ns_base"], carveout["size"]
+
+    lines: list[str] = [
+        "/*",
+        " * Copyright (c) 2026 Alp Lab AB",
+        " * SPDX-License-Identifier: Apache-2.0",
+        " *",
+        f" * {sku} ({family_display}) Cortex-M33 system-manager.",
+        " *",
+        " * Reuses the upstream RZ/V2N SoC devicetree + the EVK SCI_UART0 console and",
+        " * adds the on-module GD32G553 supervisor links:",
+        f" *   - SCI{ch} Simple-SPI (alias {gd32_spi['alias']}): {mosi['silicon_pad']} MOSI{ch} / "
+        f"{miso['silicon_pad']} MISO{ch} / {sclk['silicon_pad']} SCK{ch} +",
+        f" *     {cs0['silicon_pad']} GPIO chip-select (master SCI-SPI has no hardware slave-select)",
+        f" *   - RIIC8 / BRD_I2C: {sda['silicon_pad']} SDA / {scl['silicon_pad']} SCL "
+        f"(GD32 slave @ 0x{peer_addr:02x}) -- Cortex-A55/Linux-exclusive,",
+        " *     NOT wired on this board: no alias, &i2c8 stays disabled below.",
+        " *",
+        " * The on-module silicon is the n44 variant; Zephyr only models the n48gbg",
+        " * SoC, which is devicetree-identical for the M33 + SPI/I2C peripherals",
+        " * (the n44/n48 delta is GPU/ISP/crypto fusing only).",
+        " */",
+        "",
+        "/dts-v1/;",
+        "",
+        "#include <zephyr/dt-bindings/i2c/i2c.h>",
+        "#include <zephyr/dt-bindings/gpio/gpio.h>",
+    ]
+    if has_openamp:
+        lines.append("#include <zephyr/dt-bindings/memory-attr/memory-attr-arm.h>")
+    lines += [
+        f"#include <{soc_dtsi_include}>",
+        f'#include "{dir_name}-pinctrl.dtsi"',
+        "",
+        "/ {",
+        f'\tmodel = "{model}";',
+        f'\tcompatible = "{compatible}";',
+        "",
+        "\tchosen {",
+        "\t\tzephyr,sram = &sram;",
+        "\t\tzephyr,ram-console = &ram_console;",
+        "\t\t/*",
+        "\t\t * No CM33 serial console on this board.  The only console is the",
+        "\t\t * A55's (Linux, on the shared debug UART); sci0 here is the EVK",
+        '\t\t * "Pmod USB-UART", which is NOT wired as a CM33 console on the SoM.',
+        "\t\t * Bringing it up enables RX on a floating RXD, whose receive-error",
+        "\t\t * interrupt (sci0 eri = NVIC 114) escalates to a Zephyr fatal",
+        "\t\t * (arch_system_halt) and hangs the CM33 before main() ever runs.",
+        "\t\t * Leave the UART console unset (sci0 is disabled below); only the",
+        "\t\t * RAM console is chosen.  Re-add zephyr,console/zephyr,shell-uart and",
+        "\t\t * re-enable sci0 only when a Pmod USB-UART is attached.",
+        "\t\t */",
+        "\t};",
+        "",
+        "\taliases {",
+        f"\t\t{gd32_spi['alias']} = &gd32_spi;",
+        "\t\talp-wdt0 = &wdt0;",
+        "\t};",
+        "",
+        "\tsram: memory@8003000 {",
+        '\t\tcompatible = "mmio-sram";',
+        "\t\treg = <0x08003000 0xfbfff>;",
+        "\t};",
+        "",
+        "\t/*",
+        f"\t * RAM console buffer (audit CM33-M2): {rc_size // 1024} KiB at CM33-NS {rc_addr:#x} (A55",
+        f"\t * view {rc_a55:#x}), from the SoC's openamp_carveout.ram_console: inside the",
+        f"\t * {win_size // 1048576} MiB {win_base:#x} window Linux reserves no-map and clear of every",
+        "\t * region listed there (rsctbl with the liveness beacon in its top 16",
+        "\t * bytes, mhu-shm, the vring control and buffer areas).",
+        "\t */",
+        f"\tram_console: memory@{rc_addr:x} {{",
+        '\t\tcompatible = "zephyr,memory-region";',
+        '\t\tzephyr,memory-region = "RAM_CONSOLE";',
+        f"\t\treg = <{rc_addr:#x} {rc_size:#x}>;",
+        "\t};",
+        "",
+        "\t/*",
+        "\t * alp pin map for alp_spi/alp_gpio id resolution.  alp_spi_open(cs_pin_id=N)",
+        "\t * resolves its chip-select gpio_dt_spec from gpios[N] of this node (see the",
+        "\t * SPI backend's alp_z_gpio_resolve()).  Index 0 = the GD32 SPI chip-select",
+        f"\t * on {cs0['silicon_pad']}, matching the example's cs_pin_id = 0.",
+    ]
+    lines += [
+        "\t */",
+        "\talp_pins: alp-pins {",
+        '\t\tcompatible = "alp,pin-array";',
+        f"\t\tgpios = <&{cs0['gpio_node']} {cs0['gpio_pin']} GPIO_ACTIVE_LOW>;",
+        "\t};",
+    ]
+    if pads:
+
+        def pol(pad: dict[str, Any]) -> str:
+            return "GPIO_ACTIVE_LOW" if pad["active_low"] else "GPIO_ACTIVE_HIGH"
+
+        def spec(role: str) -> str:
+            pad = pads[role]
+            return f"<&{pad['gpio_node']} {pad['gpio_pin']} {pol(pad)}>"
+
+        lines += [
+            "",
+            "\t/*",
+            "\t * The GD32 control pads outside the SPI link (protocol v0.15, section 3.17).",
+            "\t * A DEDICATED node, deliberately not entries of alp_pins above (whose index 0",
+            "\t * is the GD32 SPI chip-select): resolved only through the INTERNAL pad opener",
+            "\t * (the portable alp_gpio_open() refuses GD32G553_PAD_ID_*).  All four are plain GPIO, inputs out of",
+            "\t * reset.  swclk and attn are the SAME pad (P71 = GD32 PA14): the host drives it",
+            "\t * only inside an SWD session, with GD32_NRST asserted first, and otherwise uses",
+            "\t * it as the bridge ATTN input with a rising-edge IRQ.  nrst is open-drain on the",
+            "\t * board; the Renesas GPIO driver has no open-drain mode, so the SWD driver",
+            "\t * emulates it (low = assert, input = release) and never drives the pad high.",
+            "\t */",
+            "\tgd32_pads: gd32-pads {",
+            '\t\tcompatible = "alp,gd32-pads";',
+            f"\t\tswdio-gpios = {spec('swdio')};",
+            f"\t\tswclk-gpios = {spec('swclk')};",
+            f"\t\tnrst-gpios = {spec('nrst')};",
+            f"\t\tattn-gpios = {spec('attn')};",
+            "\t};",
+        ]
+    lines += [
+        "};",
+        "",
+        "/*",
+        f' * {console["dt_label"]} = EVK "Pmod USB-UART" console.  DISABLED on this board: it is not wired',
+        " * as a CM33 console here, and opening it (RX enabled on a floating RXD) faults",
+        " * the CM33 in its receive-error ISR (sci0 eri / NVIC 114) -> Zephyr fatal ->",
+        " * arch_system_halt, before the app runs.  Keep pinctrl for easy re-enable.",
+        " */",
+        f"&{console['dt_label']} {{",
+        f"\tpinctrl-0 = <&{console['pinctrl_group_label']}>;",
+        '\tpinctrl-names = "default";',
+        '\tstatus = "disabled";',
+        "",
+        "\tuart0: uart {",
+        "\t\tcurrent-speed = <115200>;",
+        '\t\tstatus = "disabled";',
+        "\t};",
+        "};",
+        "",
+        "/*",
+        f" * GD32 supervisor SPI fast path -- SCI channel {ch} in clock-synchronous",
+        ' * "Simple SPI" mode (sci7@42802800, compatible renesas,rz-sci-b).  The board',
+        f" * wires the GD32 to {mosi['silicon_pad']}/{miso['silicon_pad']}/{sclk['silicon_pad']}/{cs0['silicon_pad']}, "
+        f"which per the RZ/V2N PFC (Table 1.2-3) are",
+        f" * MOSI{ch}/MISO{ch}/SCK{ch}/SS{ch} = SCI channel {ch} -- NOT the dedicated SPI_B IP.  The sci{ch}",
+        " * parent (from the SoC dtsi) already supplies reg, channel = <7> and the fixed",
+        " * CM33 vectors (eri=156, rxi=157, txi=158, tei=159); here we enable it, point it",
+        " * at the SCI7 SPI pins, and attach the SPI child.",
+        " *",
+        " * Master Simple-SPI has NO hardware slave-select (the FSP sets CCR0.SSE only in",
+        f" * slave mode), so the GD32 chip-select on {cs0['silicon_pad']} is driven as a GPIO via cs-gpios",
+        f" * ({cs0['gpio_node']} pin {cs0['gpio_pin']}) -- the GD32's PA8 CS-EXTI needs per-transaction framing.",
+        " */",
+        f"&{gd32_spi['dt_label']} {{",
+        f"\tpinctrl-0 = <&{gd32_spi['pinctrl_group_label']}>;",
+        '\tpinctrl-names = "default";',
+        '\tstatus = "okay";',
+        "",
+        "\tgd32_spi: spi {",
+        '\t\tcompatible = "renesas,rz-sci-b-spi";',
+        "\t\t#address-cells = <1>;",
+        "\t\t#size-cells = <0>;",
+        f"\t\tcs-gpios = <&{cs0['gpio_node']} {cs0['gpio_pin']} GPIO_ACTIVE_LOW>;",
+        '\t\tstatus = "okay";',
+        "\t};",
+        "};",
+        "",
+        f"&{cs0['gpio_node']} {{",
+        '\tstatus = "okay";',
+        "};",
+        "",
+    ]
+    if pads and pads["attn"].get("tint_slot") is not None and pads["swdio"]["gpio_node"] == cs0["gpio_node"]:
+        raise SystemExit("gd32_pads.attn.tint_slot set but the pads block is skipped (swdio shares CS0's gpio node)")
+    if pads and pads["swdio"]["gpio_node"] != cs0["gpio_node"]:
+        tint = pads["attn"].get("tint_slot")
+        if tint is not None:
+            if pads["attn"]["gpio_node"] != pads["swdio"]["gpio_node"]:
+                raise SystemExit("gd32_pads.attn.tint_slot needs attn on the swdio gpio node")
+            lines += [
+                "/*",
+                " * ATTN (P71) interrupt: the RZ GPIO driver routes a pin to a TINT slot through",
+                " * the port's `irqs`; without it alp_gpio_irq_enable() has no route and the",
+                " * supervisor stays on the staging-gap fallback.  The slot is a shared ICU",
+                " * resource, claimed here for the CM33 (supervisor-links.yaml gd32_pads.attn).",
+                " */",
+                f"&tint{tint} {{",
+                '\tstatus = "okay";',
+                "};",
+                "",
+            ]
+        lines += [f"&{pads['swdio']['gpio_node']} {{", '\tstatus = "okay";']
+        if tint is not None:
+            lines.append(f"\tirqs = <&tint{tint} {pads['attn']['gpio_pin']}>;")
+        lines += ["};", ""]
+    lines += [
+        "/*",
+        f" * {brd_i2c['peripheral']} / BRD_I2C is Cortex-A55/Linux-exclusive",
+        " * (metadata/e1m_modules/v2n/core-ownership.yaml) -- the CM33 must never",
+        " * master it, so this node stays disabled and carries no alias (no",
+        " * alp_i2c_open() bus_id resolves to it on this board).  The pinctrl group",
+        f" * ({brd_i2c['pinctrl_group_label']} in {dir_name}-pinctrl.dtsi) is kept for",
+        " * reference only -- an unreferenced group claims no pin.",
+        " */",
+        f"&{brd_i2c['dt_label']} {{",
+        '\tstatus = "disabled";',
+        "};",
+        "",
+    ] + _v2n_assignable_dts(assignable) + [
+        "/*",
+        f" * wdt0 = the Cortex-M33's own watchdog (base {wdt_base} and counting clock",
+        " * from the SoC spec's m33_sm `watchdog` block; hal_renesas R9A09G056N",
+        " * wdt_iodefine.h R_WDT0_BASE).  The upstream SoC devicetree",
+        " * (arm/renesas/rz/rzv/r9a09g056.dtsi) declares no watchdog, and upstream's",
+        " * `renesas,rz-wdt` driver cannot bind RZ/V2N, so the node uses the alp-sdk",
+        " * driver zephyr/drivers/watchdog/wdt_renesas_rzv.c (compatible",
+        " * `renesas,rzv-wdt`; alp-sdk#2660).  DISABLED by default: an expiry resets the",
+        " * WHOLE SoM, not just the M33, so a product opts in with `&wdt0 { status =",
+        ' * "okay"; };`.  <alp/wdt.h> then reaches it through alias alp-wdt0.  Enabling it',
+        " * also needs the CPG module clocks held for the CM33 (renesas,cm33-owned-clocks,",
+        " * docs/bench/rzv-wdt0-cm33.md).  clock-freq is the WDT0 counting clock",
+        " * (WDT_0_clk_loco, 24 MHz Main OSC; RZ/V2N hardware manual Table 4.4-2).",
+        " */",
+        "&{/soc} {",
+        f"\twdt0: watchdog@{wdt_base[2:]} {{",
+        '\t\tcompatible = "renesas,rzv-wdt";',
+        f"\t\treg = <{wdt_base} {wdt['size']}>;",
+        f"\t\tclock-freq = <{wdt['counting_clock_hz']}>;",
+        '\t\tstatus = "disabled";',
+        "\t};",
+        "};",
+    ]
+    if has_openamp:
+        lines += _openamp_subst(_V2N_OPENAMP_TAIL, soc_spec)
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------
+# Top-level entry point
+# ---------------------------------------------------------------------
+
+
+def emit_zephyr_board(
+    sku: str, core_id: str, metadata_root: Path,
+) -> dict[str, str]:
+    """Return {relative_path: content} for the requested SoM+core's board tree.
+
+    *relative_path* is rooted at the board directory (e.g.
+    ``"alp_e1m_aen801_m55_hp/board.yml"``) so the caller can write the
+    result straight under a `--board-root`-style output directory.
+    """
+    sku_preset = _resolve_sku(sku, metadata_root)
+    soc_spec = _load_soc_spec(sku_preset, metadata_root)
+    variant = _resolve_variant(sku_preset, soc_spec)
+    core = _find_core(soc_spec, core_id)
+    dir_name, cluster, variant_tag, basename = _board_naming(
+        sku_preset, core_id, variant, core)
+    topo = _topology_entry(sku_preset, core_id)
+    full_name = topo.get("zephyr_full_name")
+    if not full_name:
+        raise ZephyrBoardEmitError(
+            f"topology.{core_id}.zephyr_full_name is required for "
+            f"--emit zephyr-board (SoM {sku!r}); add it to "
+            f"metadata/e1m_modules/{sku}.yaml")
+    twister_name = topo.get("zephyr_twister_name") or full_name
+    family = _sku_family_slug(sku)
+
+    files: dict[str, str] = {
+        f"{dir_name}/board.yml": _board_yml(dir_name, full_name, variant_tag, family),
+        f"{dir_name}/Kconfig.{dir_name}": _kconfig_board(dir_name, variant_tag, cluster),
+        f"{dir_name}/{basename}.yaml": _twister_yaml(
+            dir_name, variant_tag, cluster, twister_name, family,
+            sku_preset, core_id, variant),
+    }
+
+    # relpath -> the extra generation-authority file its banner must name.
+    banner_extra_source: dict[str, str] = {}
+    if family == "aen":
+        rx_row, tx_row = _aen_console_pinmux_rows(metadata_root)
+        role = core_id.split("_")[-1]
+        uart_node = _uart_node_label(rx_row)
+        memory_map = sku_preset.get("memory_map")
+        _aen_require_disjoint_slot0(sku, sku_preset, memory_map)
+        # This role's own disjoint slot0 base (#1069), falling back to the
+        # stock symmetric-layout address (the App MRAM base + the mcuboot
+        # partition, same for every single-M55 AEN SKU and for AEN801
+        # boards with no memory_map override) when this SoM declares no
+        # per-role `<role>_slot0` region -- see _aen_role_slot0_map /
+        # _aen_flash_partitions.
+        slot0_region = _aen_role_slot0_map(memory_map, role)
+        slot0_base = (slot0_region["base"] if slot0_region
+                      else _AEN_MRAM_BASE + _AEN_MCUBOOT_KIB * 1024)
+        # The on-module (non-edge) pad + device source: BRD_I2C's P7_0/P7_1 and
+        # the RV-3028 alarm on P15_0 reach no E1M edge pin, so metadata/pinmux/
+        # aen.yaml (an edge-pad projection) has no row for them -- see
+        # _load_aen_on_module_links().
+        on_module_links = _load_aen_on_module_links(metadata_root)
+        aen_pinctrl_relpath = f"{dir_name}/{dir_name}-pinctrl.dtsi"
+        aen_dts_relpath = f"{dir_name}/{basename}.dts"
+        files[aen_pinctrl_relpath] = _aen_pinctrl_dtsi(
+            role, sku, rx_row, tx_row, _aen_family_display(soc_spec),
+            on_module_links, _aen_part(soc_spec))
+        files[f"{dir_name}/{basename}_defconfig"] = _aen_defconfig(
+            uart_node, rx_row, tx_row, slot0_base)
+        files[f"{dir_name}/Kconfig.defconfig"] = _aen_kconfig_defconfig(
+            dir_name, role, _aen_part(soc_spec))
+        files[aen_dts_relpath] = _aen_dts(
+            sku, sku_preset, core_id, soc_spec, variant, dir_name, basename,
+            rx_row, tx_row, metadata_root, on_module_links,
+            _aen_ethos_u(soc_spec), memory_map,
+            _load_aen_power_domains(metadata_root),
+            _load_aen_wired_lpgpio_pads(metadata_root))
+        banner_extra_source.update(dict.fromkeys(
+            (aen_pinctrl_relpath, aen_dts_relpath),
+            "metadata/e1m_modules/aen/on-module-links.yaml"))
+    elif family in _v2n_declared_families(metadata_root):
+        # `Kconfig.defconfig` stays hand-authored in this slice (it does
+        # not exist in the V2N/V2M board directories); the board `.dts`
+        # does not -- #655 slice 2 closed that gap (alp-sdk e4f2f60e4).
+        # Which families this branch covers is read from
+        # metadata/e1m_modules/v2n/supervisor-links.yaml's own
+        # `families:` list, not a local constant -- dropping `v2n-m1`
+        # there stops V2M emission without a code change.
+        supervisor_links = _load_supervisor_links(metadata_root)
+        v2n_pinctrl_relpath = f"{dir_name}/{dir_name}-pinctrl.dtsi"
+        v2n_defconfig_relpath = f"{dir_name}/{basename}_defconfig"
+        v2n_dts_relpath = f"{dir_name}/{basename}.dts"
+        assignable = _v2n_assignable_m33(metadata_root, soc_spec)
+        files[v2n_pinctrl_relpath] = _v2n_pinctrl_dtsi(supervisor_links, assignable)
+        files[v2n_defconfig_relpath] = _v2n_defconfig(supervisor_links, soc_spec)
+        files[v2n_dts_relpath] = _v2n_dts(
+            sku, dir_name, soc_spec, variant, sku_preset, supervisor_links,
+            assignable)
+        # None of the three files carries a single pad, PFC triple or I2C
+        # address from sku_rel/soc_json_rel below -- every one of those
+        # facts comes from supervisor-links.yaml, so its path is threaded
+        # into all three files' banners too (below), not just the
+        # family-agnostic ones.
+        banner_extra_source.update(dict.fromkeys(
+            (v2n_pinctrl_relpath, v2n_defconfig_relpath, v2n_dts_relpath),
+            "metadata/e1m_modules/v2n/supervisor-links.yaml"))
+
+    # `_load_soc_spec()` above already raised ZephyrBoardEmitError if
+    # `sku_preset["silicon"]` didn't resolve, so `soc_path` can't be None
+    # here -- but that's a dependency on call order, not a guarantee this
+    # function itself enforces, so don't drop the None-guard idiom.
+    soc_path = resolve_soc_path(sku_preset["silicon"], metadata_root)
+    if soc_path is None:
+        raise ZephyrBoardEmitError(
+            f"silicon ref {sku_preset['silicon']!r} is not a triple-colon string")
+    soc_json_rel = f"metadata/{soc_path.relative_to(metadata_root).as_posix()}"
+    for relpath in list(files):
+        style = "c" if relpath.endswith((".dts", "-pinctrl.dtsi")) else "hash"
+        extra_source = banner_extra_source.get(relpath)
+        files[relpath] = _with_generated_banner(
+            files[relpath], style, sku, soc_json_rel, extra_source)
+
+    return files