tan-cli 0.7.0__py3-none-any.whl

tan/planner/paths.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem roots for the planner package -- the bottom leaf.
+
+`REPO`, `METADATA_ROOT`, and the schema paths. A near-dependency-free leaf so
+any sibling -- topology, the loader, the carve-out / partition resolvers -- can
+import a path root directly instead of reaching back into the package __init__
+(which would cycle). Extracting these is the #285 paths seam that lets
+topology.py drop its lazy `BOARD_SCHEMA` import.
+
+RELOCATED (was alp-sdk `scripts/alp_orchestrate/paths.py`): the roots used to be
+derived from this file's own location -- three parents up landed on the SDK
+checkout. Inside `tan` that walk lands on the `tan` package, so the root is now
+an explicit binding resolved by `tan.planner_root.sdk_root()`, which raises if
+the package was imported before a root was bound. `REPO` still means *the
+alp-sdk checkout*, never tan's own tree: `metadata/**`, `firmware/`,
+`zephyr/sysbuild/` and the git commit all come from the SDK (ADR-0017 -- the
+generators relocated, the facts did not).
+"""
+
+from __future__ import annotations
+
+from tan.planner_root import sdk_root
+
+# Evaluated at import time, and deliberately so: siblings take
+# `metadata_root: Path = METADATA_ROOT` as a *default argument*, which binds
+# here too. `sdk_root()` raising on an unbound import is what keeps that from
+# becoming a silently-wrong metadata tree.
+REPO = sdk_root()
+METADATA_ROOT = REPO / "metadata"
+BOARD_SCHEMA = METADATA_ROOT / "schemas" / "board.schema.json"
+BOARD_PRESET_SCHEMA = METADATA_ROOT / "schemas" / "board-preset.schema.json"

tan/planner/plain_slice.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The `system-manifest.yaml` a `board.yaml`-less Zephyr build writes (tan-cli#1370).
+
+`tan build --board <zephyr-board-target>` has no `board.yaml` for the planner to
+project a manifest from. This builds the same document the planner would have
+written for ONE slice -- same schema, same `flash_method`/`flash_args` (composed
+by the planner's own `_slice_flash_recipe`, not re-spelled here) -- from the SoM
+preset whose `topology.<core>.board` names the target.
+
+The planner core id (`m55_he`) is NOT the Zephyr cpucluster (`rtss_he`) the board
+qualifier ends in: it comes from the preset's topology key, so no core name is
+spelled in this module. An unknown target (`native_sim`, a non-Alp board) still
+gets a one-slice manifest, with no SoC facts to carry.
+
+Imports of the planner are local: the planner freezes its SDK root at import
+time, so callers must `bind_sdk_root` first.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+#: A manifest slice linked below the SoC flash base runs from RAM only.
+RAM_RUN_ONLY = "ram_run_only"
+#: The flash_args a RAM-run-only slice keeps: the wrong-board preflight pair.
+_RAM_RUN_KEYS = ("expect_dpidr", "jlink_device")
+
+
+def _find_preset(board: str, metadata_root: Path) -> tuple[dict, str] | None:
+    from .loader import _load_yaml
+
+    for path in sorted((metadata_root / "e1m_modules").glob("*.yaml")):
+        try:
+            preset = _load_yaml(path)
+        except Exception:  # noqa: BLE001 -- an unreadable preset is not THIS target's
+            continue
+        for core_id, topo in sorted((preset.get("topology") or {}).items()):
+            if isinstance(topo, dict) and topo.get("board") == board:
+                return preset, str(core_id)
+    return None
+
+
+def plain_core_id(board: str, metadata_root: Path) -> str | None:
+    """The planner core id of the SoM topology entry that names `board`."""
+    found = _find_preset(board, metadata_root)
+    return found[1] if found else None
+
+
+def plain_system_manifest(
+    board: str, metadata_root: Path | None, *, fallback_core_id: str, elf_path: str | None = None
+) -> str:
+    """The manifest YAML for one plain Zephyr slice, status `pending`.
+
+    `elf_path`, when it points at an ELF whose lowest load address is below the
+    SoC's `soc_flash_base`, marks the slice `ram_run_only`."""
+    import yaml
+
+    from tan.core.elf_load import lowest_load_address
+
+    from .loader import (
+        _enforce_flow_d_preflight_pair, _jlink_flash_device_declared, _load_json, _resolve_flow_d_preflight,
+        _resolve_jlink_flash_device, _resolve_slot0_load_address,
+        _resolve_variant_debug, _silicon_to_soc_path, _slice_from_resolved)
+    from .models import Slice
+    from .validate import _enforce_os_matches_core_class
+    from .orchestrator import _slice_flash_recipe
+
+    found = _find_preset(board, metadata_root) if metadata_root is not None else None
+    hw_info: dict[str, Any] = dict.fromkeys(
+        ("sku", "som_hw_rev", "board_name", "board_hw_rev", "silicon"))
+    hw_info["sku"] = ""
+    flash_base: int | None = None
+    if found is None:
+        slice_ = Slice(core_id=fallback_core_id, os="zephyr", board=board)
+    else:
+        preset, core_id = found
+        topo = preset["topology"][core_id]
+        soc_spec = _load_json(_silicon_to_soc_path(preset["silicon"], metadata_root))
+        debug = _resolve_variant_debug(preset, soc_spec)
+        declared = _jlink_flash_device_declared(debug)
+        flash_device = _resolve_jlink_flash_device(debug)
+        expect_dpidr, jlink_device = _resolve_flow_d_preflight(debug, core_id)
+        slice_ = _slice_from_resolved(
+            core_id,
+            {"os": "zephyr", "board": board, "toolchain": topo.get("toolchain")},
+            jlink_flash_device=flash_device,
+            jlink_flash_device_declared=declared,
+            expect_dpidr=expect_dpidr,
+            jlink_device=jlink_device,
+            slot0_load_address=(
+                _resolve_slot0_load_address(preset, core_id)
+                if (declared or flash_device is not None) else None),
+        )
+        # The same refusals the planned route applies per slice (loader.py).
+        core_type = next(
+            (str(c.get("type") or "") for c in (soc_spec.get("cores") or [])
+             if c.get("id") == core_id), "")
+        _enforce_flow_d_preflight_pair(slice_, debug, preset["sku"])
+        _enforce_os_matches_core_class(slice_, core_type)
+        hw_info.update(sku=preset["sku"], silicon=preset.get("silicon"))
+        base = soc_spec.get("soc_flash_base")
+        flash_base = int(base) if isinstance(base, int) else None
+
+    entry = slice_.to_manifest_entry()
+    if found is None:
+        # No SoM preset names this target: there is no recipe to compose, and a
+        # guessed one could program the wrong thing. `tan flash` skips a slice
+        # with no flash_method, naming this reason.
+        entry["flash_method"] = "none"
+        entry["flash_args"] = {}
+        entry["reason"] = (
+            f"no SoM preset in the SDK names board target `{board}`; "
+            "no flash recipe is known for it")
+    elif flash_base is not None:
+        # The SoC has a flash window, so WHERE the image is linked decides how it
+        # may be run. An image tan cannot classify must never inherit the MRAM
+        # recipe (slot0_load_address / jlink_flash_device): refuse it as RAM-only.
+        # TODO(tan-cli#1360): also set `slice_.link_target = "itcm"` and import
+        # RAM_RUN_ONLY_METHOD from `tan.core.link_refusal` once #1360 is in this
+        # base, so `tan flash` refuses the method by name.
+        low = lowest_load_address(elf_path) if elf_path else None
+        if low is None or low < flash_base:
+            _, args = _slice_flash_recipe(slice_)
+            entry["flash_method"] = RAM_RUN_ONLY
+            entry["flash_args"] = {k: v for k, v in (args or {}).items() if k in _RAM_RUN_KEYS}
+            if low is None:
+                entry["reason"] = (
+                    "the built ELF could not be classified (missing, unreadable, or "
+                    "no loadable segment); not treated as a flash image")
+    doc = {
+        "schema_version": 1,
+        "generated_by": "tan build --board",
+        "hw_info": hw_info,
+        "slices": [entry],
+        "ipc": [],
+        "helper_mcus": [],
+        "boot_order": [],
+    }
+    return yaml.safe_dump(doc, sort_keys=False, default_flow_style=False)

tan/planner/project_emit/__init__.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""board.yaml emitters whose `--emit` front door is `scripts/alp_project.py`.
+
+RELOCATED (was alp-sdk `scripts/alp_project_emit/`). The package keeps its shape
+so the move stays reviewable as a move: `dts.py`, `native_sim.py`, `hw_info.py`,
+`west_libs.py` and `bom_netlist.py` are the same files with their imports
+repointed at `tan.planner`'s own leaves.
+
+Two things alp-sdk's package root carried did NOT come across, because nothing
+these five modules do reaches them and a second copy would be a second source of
+truth:
+
+* `_PERIPHERAL_KCONFIG` -- `slugs.peripheral_kconfig(metadata_root)` already
+  reads `metadata/registries/peripheral-kconfig.json` here. It takes the
+  project's own root since alp-sdk#1485; there is no module-level table to
+  copy any more.
+* `_CHIP_SUBSYSTEMS` -- already in `slugs.py`, with its I-26 justification.
+
+`composed-route-table` came across too: `bom_netlist.py` carries
+`_emit_composed_route_table` alongside `_emit_carrier_netlist`, sharing the same
+`_composed_route_rows` helper.
+
+What DOES live here is the one fact genuinely shared by two leaves: the canonical
+E1M / E1M-X GPIO pad order, which `dts.py` (`--emit dts-overlay`) and
+`native_sim.py` (`--emit native-sim-overlay`) must agree on byte for byte -- the
+"Devicetree / overlay invariant" documented in the SDK's `e1m_pinout.h` /
+`e1m_x_pinout.h`. Kept here, not duplicated in either leaf, so the two overlays
+cannot drift.
+"""
+
+from __future__ import annotations
+
+__all__ = ["_e1m_gpio_canonical", "_e1m_x_gpio_canonical"]
+
+
+def _e1m_gpio_canonical() -> list[str]:
+    """Return the 52 ALP_E1M_GPIO_<suffix> names in canonical index order."""
+    names: list[str] = [f"IO{n}" for n in range(26)]      # 0..25
+    names += [f"PWM{n}" for n in range(8)]                 # 26..33
+    for e in range(4):                                     # 34..41
+        names += [f"ENC{e}_X", f"ENC{e}_Y"]
+    names += [f"ADC{n}" for n in range(8)]                 # 42..49
+    names += ["DAC0", "DAC1"]                              # 50..51
+    return names
+
+
+def _e1m_x_gpio_canonical() -> list[str]:
+    """Return the 99 ALP_E1M_X_GPIO_<suffix> names in canonical index order."""
+    names: list[str] = [f"IO{n}" for n in range(36)]       # 0..35
+    names += [f"PWM{n}" for n in range(8)]                 # 36..43
+    for e in range(4):                                     # 44..51
+        names += [f"ENC{e}_X", f"ENC{e}_Y"]
+    names += [f"ADC{n}" for n in range(8)]                 # 52..59
+    names += ["DAC0", "DAC1"]                              # 60..61
+    names += ["I2C2_SDA", "I2C2_SCL", "I2C3_SDA", "I2C3_SCL"]
+    names += ["SPI2_MISO", "SPI2_MOSI", "SPI2_SCLK", "SPI2_CS0", "SPI2_CS1"]
+    names += ["CAN1_H", "CAN1_L"]
+    names += [f"LCD_B{n}" for n in range(24)]
+    names += ["LCD_HSYNC", "LCD_VSYNC"]                    # 97..98
+    return names

tan/planner/project_emit/bom_netlist.py

@@ -0,0 +1,375 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Carrier netlist / BOM emission (`--emit carrier-netlist` /
+`--emit composed-route-table`).
+
+RELOCATED (was alp-sdk `scripts/alp_project_emit/bom_netlist.py`) -- see this
+package's `__init__.py` for the move's contract.
+
+`_emit_composed_route_table` relocated alongside `_emit_carrier_netlist`
+(tan-cli composed-route-table front door): the two share `_composed_route_rows`
+in full -- that is where the hw_rev pad-route override actually happens -- so a
+second copy of that resolution could not exist to drift.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..loader import _load_yaml
+from ..project_loader import (
+    _compose_route,
+    _hwrev_pad_route_overrides,
+    _resolve_pad_routes,
+)
+from ..som_metadata import _resolve_silicon_variant
+
+
+# ---------------------------------------------------------------------
+# Carrier route / netlist emitters
+# ---------------------------------------------------------------------
+#
+# `composed-route-table` stays as the original debug surface.  The
+# route-row helper below is shared by the production `carrier-netlist`
+# contract so the two views cannot drift on hw_rev pad-route overrides.
+
+
+def _composed_route_rows(
+    project: dict[str, Any],
+    sku_preset: dict[str, Any],
+    board_preset: dict[str, Any] | None,
+    metadata_root: Path,
+) -> tuple[list[dict[str, Any]], str | None, str | None]:
+    """Return composed route rows plus the selected hw_rev / variant.
+
+    Rows cover every E1M pad named by the board and every SoM-only pad
+    that has a dispatch route.  Board-defined rows preserve YAML order;
+    SoM-only rows are sorted by E1M ID for deterministic output.
+    """
+    pad_routes = _resolve_pad_routes(sku_preset)
+
+    # Apply the selected board revision's pad-route overrides on top of the
+    # base (production-rev) pad_routes, so the composed table -- and thus
+    # `--emit composed-route-table` -- differs by hw_rev.  The rev comes from
+    # the board's `som.hw_rev`, falling back to the SoM's `default_hw_rev`.
+    hw_rev = ((project.get("som") or {}).get("hw_rev")
+              or sku_preset.get("default_hw_rev"))
+    for ov in _hwrev_pad_route_overrides(project["som"]["sku"], hw_rev,
+                                         metadata_root):
+        pad_routes[ov["e1m"]] = ov
+
+    # Resolve silicon variant order_code for the top-level summary field.
+    variant = _resolve_silicon_variant(sku_preset, metadata_root)
+    silicon_variant_str = variant["order_code"] if variant else None
+
+    # Collect board-side entries, preserving the sub-category name.
+    # Build a mapping: e1m_id -> (category, entry_dict).
+    # When the same E1M pad appears multiple times (e.g. E1M_PWM1 maps to
+    # both EVK_PWM_LED_BLUE and EVK_ARD_PWM1 in the EVK YAML) we emit one
+    # row per board entry so no information is lost.
+    board_entries: list[tuple[str, dict[str, Any]]] = []
+    seen_from_board: set[str] = set()
+    if board_preset is not None:
+        e1m_routes = board_preset.get("e1m_routes") or {}
+        for category, entries in e1m_routes.items():
+            if not isinstance(entries, list):
+                continue
+            for entry in entries:
+                if not isinstance(entry, dict):
+                    continue
+                e1m = entry.get("e1m")
+                if not isinstance(e1m, str):
+                    continue
+                board_entries.append((category, entry))
+                seen_from_board.add(e1m)
+
+    # Also include SoM-only pads (in pad_routes but not in board).
+    som_only_pads = sorted(set(pad_routes.keys()) - seen_from_board)
+
+    routes: list[dict[str, Any]] = []
+
+    # Board-defined entries first (preserves YAML order).
+    for category, c_entry in board_entries:
+        e1m = c_entry["e1m"]
+        composed = _compose_route(e1m, c_entry, pad_routes)
+        row: dict[str, Any] = {"e1m": e1m, "board_category": category}
+        row["board_macro"] = composed.get("board_macro")
+        row["board_role"] = composed.get("board_role")
+        if "board_doc" in composed:
+            row["board_doc"] = composed["board_doc"]
+        # active_low is a board-side flag, not surfaced by _compose_route;
+        # read it directly from the board entry.
+        active_low = c_entry.get("active_low")
+        if active_low is not None:
+            row["active_low"] = bool(active_low)
+        row["dispatch"] = composed.get("dispatch", "direct")
+        if "dispatch_pin" in composed:
+            row["dispatch_pin"] = composed["dispatch_pin"]
+        if "som_doc" in composed:
+            row["som_doc"] = composed["som_doc"]
+        routes.append(row)
+
+    # SoM-only pads (not assigned a board role in this board YAML).
+    for e1m in som_only_pads:
+        composed = _compose_route(e1m, None, pad_routes)
+        row = {
+            "e1m": e1m,
+            "board_category": None,
+            "board_macro": None,
+            "board_role": None,
+            "dispatch": composed.get("dispatch", "direct"),
+        }
+        if "dispatch_pin" in composed:
+            row["dispatch_pin"] = composed["dispatch_pin"]
+        if "som_doc" in composed:
+            row["som_doc"] = composed["som_doc"]
+        routes.append(row)
+
+    return routes, hw_rev, silicon_variant_str
+
+
+def _manifest_path(kind: str, item_id: str, metadata_root: Path) -> Path:
+    return metadata_root / kind / f"{item_id}.yaml"
+
+
+def _load_optional_manifest(kind: str, item_id: str,
+                            metadata_root: Path) -> dict[str, Any] | None:
+    path = _manifest_path(kind, item_id, metadata_root)
+    if not path.is_file():
+        return None
+    return _load_yaml(path)
+
+
+def _passive_rows(passives: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for passive in passives or []:
+        if not isinstance(passive, dict):
+            continue
+        row: dict[str, Any] = {
+            "role": passive.get("role"),
+            "value": passive.get("value"),
+            "net": passive.get("net"),
+            "refdes_prefix": passive.get("refdes_prefix"),
+        }
+        rows.append({k: v for k, v in row.items() if v is not None})
+    return rows
+
+
+def _chip_bom_row(item_id: str, manifest: dict[str, Any],
+                  manifest_relpath: str) -> dict[str, Any]:
+    physical = manifest.get("physical") or {}
+    caveats: list[str] = []
+    if not physical:
+        caveats.append("missing_physical")
+    elif physical.get("visibility") == "internal":
+        caveats.append("physical_detail_internal")
+    if len(manifest.get("mpn_population") or []) > 1:
+        caveats.append("mpn_population_candidates")
+
+    row: dict[str, Any] = {
+        "item_id": item_id,
+        "kind": "chip",
+        "scope": "carrier",
+        "source": manifest_relpath,
+        "display_name": manifest.get("display_name"),
+        "vendor": manifest.get("vendor"),
+        "mpn_population": manifest.get("mpn_population") or [],
+        "bus": manifest.get("bus"),
+        "quantity": None,
+        "physical": {
+            "refdes_prefix": physical.get("refdes_prefix"),
+            "package": physical.get("package"),
+            "footprint": physical.get("footprint"),
+            "visibility": physical.get("visibility"),
+            "provenance": physical.get("provenance"),
+        },
+        "passives": _passive_rows(physical.get("passives")),
+    }
+    row["physical"] = {k: v for k, v in row["physical"].items()
+                       if v is not None}
+    if caveats:
+        row["caveats"] = caveats
+    return row
+
+
+def _block_bom_row(item_id: str, manifest: dict[str, Any],
+                   manifest_relpath: str) -> dict[str, Any]:
+    realizations = [
+        r for r in manifest.get("realizations") or []
+        if isinstance(r, dict)
+    ]
+    realization = realizations[0] if realizations else {}
+    caveats: list[str] = []
+    if not realizations:
+        caveats.append("missing_realization")
+    elif len(realizations) > 1:
+        caveats.append("multiple_realizations")
+    if realization.get("visibility") == "internal":
+        caveats.append("physical_detail_internal")
+    if not realization.get("parts"):
+        caveats.append("no_concrete_parts")
+
+    row: dict[str, Any] = {
+        "item_id": item_id,
+        "kind": "block",
+        "scope": "carrier",
+        "source": manifest_relpath,
+        "display_name": manifest.get("display_name"),
+        "quantity": None,
+        "realization": {
+            "id": realization.get("id"),
+            "physical_form": realization.get("physical_form"),
+            "visibility": realization.get("visibility"),
+        },
+        "parts": realization.get("parts") or [],
+        "passives": _passive_rows(realization.get("passives")),
+    }
+    row["realization"] = {k: v for k, v in row["realization"].items()
+                          if v is not None}
+    if caveats:
+        row["caveats"] = caveats
+    return row
+
+
+def _carrier_bom_rows(
+    board_preset: dict[str, Any] | None,
+    metadata_root: Path,
+) -> list[dict[str, Any]]:
+    """Build carrier BOM rows from board `populated: true`.
+
+    `populated:` is a logical population map, not a line-item BOM with
+    refdes or count, so rows deliberately leave `quantity` null unless a
+    future metadata field makes it authoritative.
+    """
+    rows: list[dict[str, Any]] = []
+    if board_preset is None:
+        return rows
+
+    populated = board_preset.get("populated") or {}
+    for item_id in sorted(k for k, v in populated.items() if v is True):
+        chip = _load_optional_manifest("chips", item_id, metadata_root)
+        if chip is not None:
+            rows.append(_chip_bom_row(
+                item_id, chip, f"metadata/chips/{item_id}.yaml"))
+            continue
+
+        block = _load_optional_manifest("blocks", item_id, metadata_root)
+        if block is not None:
+            rows.append(_block_bom_row(
+                item_id, block, f"metadata/blocks/{item_id}.yaml"))
+            continue
+
+        rows.append({
+            "item_id": item_id,
+            "kind": "unknown",
+            "scope": "carrier",
+            "source": None,
+            "quantity": None,
+            "caveats": ["missing_manifest"],
+        })
+    return rows
+
+
+def _route_to_net(row: dict[str, Any]) -> dict[str, Any]:
+    net_id = row.get("board_macro") or row["e1m"]
+    endpoints: list[dict[str, Any]] = [
+        {"kind": "e1m", "ref": row["e1m"]},
+    ]
+    if row.get("board_macro"):
+        endpoints.append({"kind": "board-macro", "ref": row["board_macro"]})
+    if row.get("dispatch") and row["dispatch"] != "direct":
+        endpoint: dict[str, Any] = {
+            "kind": "som-dispatch",
+            "ref": row["dispatch"],
+        }
+        if "dispatch_pin" in row:
+            endpoint["pin"] = row["dispatch_pin"]
+        endpoints.append(endpoint)
+
+    net: dict[str, Any] = {
+        "net_id": net_id,
+        "e1m": row["e1m"],
+        "board_category": row.get("board_category"),
+        "board_macro": row.get("board_macro"),
+        "board_role": row.get("board_role"),
+        "dispatch": row.get("dispatch", "direct"),
+        "endpoints": endpoints,
+    }
+    for key in ("board_doc", "active_low", "dispatch_pin", "som_doc"):
+        if key in row:
+            net[key] = row[key]
+    caveats = []
+    if row.get("board_macro") is None:
+        caveats.append("som_only_no_carrier_role")
+    if caveats:
+        net["caveats"] = caveats
+    return net
+
+
+def _emit_carrier_netlist(
+    project: dict[str, Any],
+    sku_preset: dict[str, Any],
+    board_preset: dict[str, Any] | None,
+    metadata_root: Path,
+) -> str:
+    """Emit the Studio-facing carrier netlist + BOM handoff contract.
+
+    This is intentionally not a KiCad, Gerber, or layout artifact.  It
+    exposes only public carrier-facing facts derivable from board.yaml,
+    board presets, chip/block manifests, and SoM pad dispatch metadata.
+    """
+    routes, hw_rev, silicon_variant_str = _composed_route_rows(
+        project, sku_preset, board_preset, metadata_root)
+    board_name = (board_preset or {}).get("name") or project.get("name")
+    result: dict[str, Any] = {
+        "schema_version": 1,
+        "kind": "alp.carrier_netlist",
+        "generated_by": "scripts/alp_project.py --emit carrier-netlist",
+        "board": board_name,
+        "som": project["som"]["sku"],
+        "hw_rev": hw_rev,
+        "silicon_variant": silicon_variant_str,
+        "nets": [_route_to_net(row) for row in routes],
+        "bom": {
+            "carrier": _carrier_bom_rows(board_preset, metadata_root),
+        },
+        "caveats": [
+            "carrier_handoff_not_pcb_layout",
+            "no_kicad_or_gerber_output",
+            "som_internals_excluded",
+            "quantity_null_when_board_populated_has_no_count",
+        ],
+    }
+    return json.dumps(result, indent=2) + "\n"
+
+
+def _emit_composed_route_table(
+    project: dict[str, Any],
+    sku_preset: dict[str, Any],
+    board_preset: dict[str, Any] | None,
+    metadata_root: Path,
+) -> str:
+    """Emit a JSON summary of the fully-composed pad route table for
+    the current (board x SoM) pair.
+
+    The table is derived by calling _resolve_pad_routes() (SoM side) and
+    _compose_route() (join with board side) for every E1M pad that
+    appears in either the board's e1m_routes: block or the SoM's
+    pad_routes: block.
+
+    Pads that only appear in the SoM's pad_routes: block (i.e. no
+    board-side role assigned) are included with null board_* fields
+    so the table is complete for the SoM-standalone scenario.
+    """
+    routes, hw_rev, silicon_variant_str = _composed_route_rows(
+        project, sku_preset, board_preset, metadata_root)
+    board_name = (board_preset or {}).get("name") or project.get("name")
+    result: dict[str, Any] = {
+        "board": board_name,
+        "som": project["som"]["sku"],
+        "hw_rev": hw_rev,
+        "silicon_variant": silicon_variant_str,
+        "routes": routes,
+    }
+    return json.dumps(result, indent=2) + "\n"