tan-cli 0.7.0__py3-none-any.whl

tan/planner/slugs.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Kconfig / board-define slug derivation -- a shared leaf.
+
+The slug + symbol helpers the per-slice config emitters (alp.conf, cmake-args)
+share: the board-define slug, the on-module / helper-firmware Kconfig slug
+derivation (+ the non-chip field set they skip), and the two Kconfig-mapping
+tables (peripheral -> symbol bundle, chip -> subsystem dependency). A leaf that
+reaches only for `paths`, so every per-slice emitter pulls them from one place
+instead of duplicating. Extracted as a #285 leaf seam (the paths.py /
+memregion.py move) ahead of the kconfig emitter.
+
+`peripheral_kconfig` is RELOCATED from alp-sdk's `scripts/alp_registries.py` and
+`_CHIP_SUBSYSTEMS` from `scripts/alp_project_emit/__init__.py` -- the last two
+edges this leaf and `kconfig.py` made into the SDK's Python. The peripheral
+table is still READ from the SDK's `metadata/registries/peripheral-kconfig.json`
+(the fact stays there, ADR-0017); `_CHIP_SUBSYSTEMS` has no registry file to
+read from today, so it moves with its one and only consumer -- see the note
+above the table.
+
+`peripheral_kconfig` used to be a module-level constant computed once at
+import time from the SDK's own in-tree metadata/ -- a project's own
+`--metadata-root` override never reached it (alp-sdk #1485). It now takes
+*metadata_root* as a required argument; callers pass
+`project.effective_metadata_root()` at the point of use.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+from pathlib import Path
+
+from .paths import REPO
+
+
+@functools.lru_cache(maxsize=None)
+def peripheral_kconfig(metadata_root: Path) -> dict[str, tuple[str, ...]]:
+    """Return board.yaml peripheral tokens -> Zephyr Kconfig symbol bundles.
+
+    *metadata_root* is REQUIRED -- every caller must pass the project's own
+    ``project.effective_metadata_root()`` (or the SDK's own in-tree
+    ``METADATA_ROOT`` for a repo self-check). A module-level default here
+    is exactly the shape that let this registry silently ignore a project's
+    `--metadata-root` override (#1485); the cache is keyed on
+    *metadata_root* so a second root in the same process doesn't reuse the
+    first root's table.
+
+    The validation below is alp-sdk#1545's, re-rooted at *metadata_root*.
+    Upstream wrote it for two import-time callers; in tan the one caller is
+    `kconfig._emit_subsystems`, and it now reads the table at RENDER time
+    rather than at import (that is what #1485's move bought). A malformed
+    on-disk registry therefore lands here mid-render, where a raw
+    `JSONDecodeError`/`KeyError`/`AttributeError` would name neither the
+    file nor the problem -- and where `tan generate` turns an exception into
+    an envelope, so the message IS the diagnosis a customer gets. Raise a
+    `ValueError` naming the real problem instead.
+
+    A consequence tan owns and alp-sdk does not: `planner_emit.unavailable()`
+    measures in-process availability by IMPORTING `tan.planner`, so while
+    this table was a module constant, a checkout missing the registry
+    disabled the in-process engine for EVERY target. It no longer does --
+    only the emits that actually need the table fail, and they fail with the
+    message above (`tests/parity/test_planner_emit_parity.py::
+    test_a_fallback_on_an_incomplete_checkout_says_so` moved to a different
+    trigger for exactly this reason, tan-cli#868).
+    """
+    registry = Path(metadata_root) / "registries" / "peripheral-kconfig.json"
+    try:
+        rel = registry.relative_to(REPO).as_posix()
+    except ValueError:
+        # `metadata_root` legitimately points outside REPO (a scratch root
+        # under `--metadata-root`, or a test fixture) -- `relative_to()`
+        # raises its own confusing "is not in the subpath of" there, which
+        # would mask whatever the caller actually did wrong. Fall back to
+        # the raw path string.
+        rel = str(registry)
+    try:
+        text = registry.read_text(encoding="utf-8")
+    except OSError as e:
+        # A missing/unreadable file is not "invalid JSON" -- report the
+        # real failure instead of mislabeling every OSError that way.
+        raise ValueError(f"{rel}: cannot read registry ({e})") from e
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{rel}: invalid JSON ({e})") from e
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"{rel}: expected a top-level object (got {type(data).__name__})")
+    if "peripherals" not in data:
+        raise ValueError(f"{rel}: missing top-level `peripherals` key")
+    peripherals = data["peripherals"]
+    if not isinstance(peripherals, dict):
+        raise ValueError(
+            f"{rel}: `peripherals` must be an object "
+            f"(got {type(peripherals).__name__})")
+    result: dict[str, tuple[str, ...]] = {}
+    for token, symbols in peripherals.items():
+        if not isinstance(symbols, list):
+            raise ValueError(
+                f"{rel}: peripherals[{token!r}] must be an array of "
+                f"Zephyr Kconfig symbols (got {type(symbols).__name__})")
+        result[token] = tuple(symbols)
+    return result
+
+
+def _is_tbd(value: object) -> bool:
+    """Case/whitespace-insensitive `TBD` placeholder match ("tbd", "Tbd",
+    " TBD " all match, alp-sdk #1048) -- the two chip-slug extractors below
+    both used a bare `== "TBD"` before, so an all-lowercase board.yaml
+    value silently fell through as a real chip slug instead of being
+    dropped as the placeholder it was hand-typed to mean."""
+    return isinstance(value, str) and value.strip().upper() == "TBD"
+
+
+def _board_define_slug(name: str) -> str:
+    """'E1M-X-EVK' -> 'E1M_X_EVK': the ALP_BOARD_* compile-define suffix.
+
+    Mirrors gen_board_header._board_slug (lower + '-'->'_') then uppercases
+    for the C macro. Used by <alp/board.h>'s board-selection facade.
+    """
+    return name.lower().replace("-", "_").upper()
+
+
+def _som_define_slug(sku: str) -> str:
+    """'E1M-AEN801' -> 'E1M_AEN801': the ALP_SOM_* compile-define suffix.
+
+    Same transform as _board_define_slug; kept as its own name so the
+    SoM-selection define (per-SKU capability restrictions in
+    <alp/soc_caps.h>, gen_soc_caps.som_token) reads distinctly from the
+    board facade define at call sites.
+    """
+    return _board_define_slug(sku)
+
+
+# on_module fields that carry non-chip-slug values — skip them when
+# walking the block for chip-driver enables.  Numeric fields, silicon
+# identifiers, and structured sub-blocks are excluded by name rather
+# than by type so the logic stays explicit and easy to audit.
+_ON_MODULE_NON_CHIP_FIELDS: frozenset[str] = frozenset({
+    "silicon",             # e.g. "renesas:rzv2n:n44" — SoC identifier, not a driver
+    "ethernet_phy_count",  # integer count, not a chip slug
+    "i2c_devices",         # sub-block: handled by extracting chip: entries below
+    "dxm1",                # sub-block: DX-M1 strap/reset pins, not chip slugs
+    "ospi_memories",       # sub-block: storage parts (flash/HyperRAM); MPNs have no chips/ driver -- excluded like nor_flash/emmc below
+    # Storage-class fields encode the SoC controller / peripheral name
+    # that reaches the on-module storage (e.g. `nor_flash: xspi` -> the
+    # NOR flash is wired to the xSPI controller; `emmc: sd0` -> eMMC on
+    # SD/MMC controller 0).  They are routing annotations, not chip
+    # slugs, and have no `chips/<part>/` driver behind them; emitting
+    # them as CHIP_<NAME> trips the Zephyr build with an undefined-symbol
+    # warning (no CONFIG_ALP_SDK_CHIP_XSPI / SD0 declaration exists).
+    "nor_flash",
+    "emmc",
+})
+
+# Any `<x>_driver_status` field (nor_flash_driver_status, emmc_driver_status,
+# and whatever the next one is) is a maturity tier -- none/planned/partial/
+# complete -- never a chip slug.  A denylist entry per field re-opens this
+# leak every time a new one is added (it did once already: the literal
+# string "none" reached CONFIG_ALP_SDK_CHIP_NONE=y before this suffix check
+# existed).  Matched by suffix, not enumerated by name, so it can't miss the
+# next one (alp-sdk #1169).
+_DRIVER_STATUS_SUFFIX = "_driver_status"
+
+
+def _slugs_from_on_module(on_module: dict) -> list[str]:
+    """Extract unique, non-TBD chip slugs from an ``on_module:`` block.
+
+    Walks every scalar field that is NOT in ``_ON_MODULE_NON_CHIP_FIELDS``,
+    then recurses into the ``i2c_devices`` sub-block (extracting the
+    ``chip:`` field from each device entry).  ``ospi_memories`` and the
+    ``hyperram`` block are storage parts (NOR flash / HyperRAM) with no
+    ``chips/<part>/`` driver, so their MPNs are NOT extracted as chip
+    slugs (emitting them as ``CONFIG_ALP_SDK_CHIP_<X>`` would trip
+    Zephyr's undefined-symbol guard).  Duplicate slugs and values of
+    ``TBD`` / ``null`` are silently dropped.
+
+    A chip can ALSO be named by a plain top-level scalar field (e.g.
+    ``secure_element: optiga_trust_m``) naming which part the design
+    carries, distinct from the ``i2c_devices`` entry that records whether
+    THIS SKU actually has it fitted. Where both exist for the same chip,
+    ``i2c_devices[].assembled`` is the more precise source and wins: a
+    device marked ``assembled: false`` (hard DNP, e.g. E1M-AEN801's
+    Optiga -- footprint shared with E1M-AEN803, DNP=1 on this batch) or
+    ``assembled: optional`` (BOM-variant; the customer opts in via
+    `board.populated:`) must not auto-enable as a chip driver EVEN when
+    a scalar field also names the same chip (#1980 follow-up -- fixing
+    only the `i2c_devices` loop left the scalar-field path still leaking
+    `optiga_trust_m` into `_resolve_chip_states`' always-True SoM-intrinsic
+    set).
+
+    Returns a sorted, deduplicated list of slug strings.
+    """
+    seen: set[str] = set()
+    not_auto_enable: set[str] = set()
+
+    def _add(val: object) -> None:
+        if not val or _is_tbd(val):
+            return
+        if not isinstance(val, str):
+            return
+        seen.add(val)
+
+    # 1. Scalar fields — every key whose value is a plain string and
+    #    is not in the exclusion list (or a `*_driver_status` field).
+    for key, val in on_module.items():
+        if key in _ON_MODULE_NON_CHIP_FIELDS or key.endswith(_DRIVER_STATUS_SUFFIX):
+            continue
+        if isinstance(val, str):
+            _add(val)
+
+    # 2. i2c_devices sub-block — each bus entry contains a `devices:`
+    #    list; extract the `chip:` field from each device.
+    #    Devices marked `assembled: false` (hard DNP) or `optional`
+    #    (BOM variant) must NOT be auto-enabled as chip drivers — the
+    #    customer explicitly enables an optional one via
+    #    `board.populated:`, and a hard-DNP one never auto-enables at all.
+    i2c_buses = on_module.get("i2c_devices")
+    if isinstance(i2c_buses, dict):
+        for _bus, bus_entry in i2c_buses.items():
+            if not isinstance(bus_entry, dict):
+                continue
+            for dev in bus_entry.get("devices") or []:
+                if not isinstance(dev, dict):
+                    continue
+                chip = dev.get("chip")
+                assembled = dev.get("assembled", True)
+                if assembled is False or assembled == "optional":
+                    if isinstance(chip, str):
+                        not_auto_enable.add(chip)
+                    continue
+                _add(chip)
+
+    seen -= not_auto_enable
+    return sorted(seen)
+
+
+def _slugs_from_helper_firmware(helper_firmware: list) -> list[str]:
+    """Extract unique, non-TBD chip slugs from a ``helper_firmware:`` list.
+
+    Each entry is a dict; we pull the ``chip:`` field.  TBD values and
+    missing fields are skipped.  Returns a sorted, deduplicated list.
+    """
+    seen: set[str] = set()
+    for entry in helper_firmware or []:
+        if not isinstance(entry, dict):
+            continue
+        chip = entry.get("chip")
+        if chip and not _is_tbd(chip):
+            seen.add(chip)
+    return sorted(seen)
+
+
+# Slugs that map to BLOCK_ Kconfig symbols rather than CHIP_.
+# These live under blocks/ + <alp/blocks/*.h> because they are
+# SDK-level *block* utilities (`alp_button_led_*`, `alp_pdm_mic_*`)
+# rather than third-party-IC chip drivers; see blocks/README.md.
+#
+# Single source of truth -- kconfig.py's emitter, check_example_portability.py
+# and alp_cli/validator.py's ALP-B008 chip-token check all consult this same
+# set rather than each carrying its own copy (a prior state that had drifted
+# into three independent copies).  Only the emitter's consumer relocated into
+# `tan`; the two SDK gates keep reading alp-sdk's own copy.
+_BLOCK_SLUGS = frozenset({"button_led", "pdm_mic"})
+
+
+# Chip name -> Zephyr subsystem CONFIG_* keys the chip driver
+# depends on.  Mirrors the `depends on ...` line in each
+# `config ALP_SDK_CHIP_<NAME>` entry in zephyr/Kconfig: enabling
+# a chip driver doesn't auto-select its subsystem, so the loader
+# emits the matching `CONFIG_<SUBSYS>=y` here.
+#
+# RELOCATED from alp-sdk's `scripts/alp_project_emit/__init__.py`, whose only
+# consumer was ever `_emit_chips` in this package's `kconfig.py`.
+#
+# DEBT, stated plainly: this IS a hardware fact and it now lives in `tan`
+# (ADR-0017 / I-26 says facts stay in `metadata/**`). It moved because no
+# metadata file carries it -- a chip manifest's `bus: i2c` cannot distinguish
+# `lsm6dso` -> `("I2C",)` from `tas2563` -> `("I2C", "GPIO")`, so deriving it
+# from existing metadata would change the emitted Kconfig. Retires when a
+# registry (`metadata/registries/chip-subsystems.json`, alongside
+# peripheral-kconfig.json) declares it and this table becomes a loader like
+# `peripheral_kconfig` above.
+_CHIP_SUBSYSTEMS: dict[str, tuple[str, ...]] = {
+    # GPIO-only
+    "button_led":         ("GPIO",),
+    "cam_mux_pi3wvr626":  ("GPIO",),
+    # SPI + GPIO
+    "ssd1331":            ("SPI", "GPIO"),
+    "cc3501e":            ("SPI", "GPIO"),
+    # I2C + GPIO
+    "tas2563":            ("I2C", "GPIO"),
+    # I2C-only
+    "lsm6dso":            ("I2C",),
+    "ssd1306":            ("I2C",),
+    "bme280":             ("I2C",),
+    "lis2dw12":           ("I2C",),
+    "ov5640":             ("I2C",),
+    "icm42670":           ("I2C",),
+    "bmi323":             ("I2C",),
+    "bmp581":             ("I2C",),
+    "tmp112":             ("I2C",),
+    "rv3028c7":           ("I2C",),
+    "optiga_trust_m":     ("I2C",),
+    "eeprom_24c128":      ("I2C",),
+    "tcal9538":           ("I2C",),
+    "ina228":             ("I2C",),
+    "ina236":             ("I2C",),
+    # pdm_mic helper has no subsystem dep declared in Kconfig
+    # (uses <alp/i2s.h> when enabled at v0.2+).
+    # v0.5 §D.AI batch -- 18 vision / display / accelerator chips.
+    "ov2640":             ("I2C",),
+    "ov5645":             ("I2C",),
+    "ov7670":             ("I2C",),
+    "ov9281":             ("I2C",),
+    "ar0234":             ("I2C",),
+    "imx219":             ("I2C",),
+    "imx477":             ("I2C",),
+    "gc2145":             ("I2C",),
+    "ti_ds90ub953_954":   ("I2C",),
+    "maxim_max9295_9296": ("I2C",),
+    "st7789":             ("SPI", "GPIO"),
+    "ili9341":            ("SPI", "GPIO"),
+    "ili9488":            ("SPI", "GPIO"),
+    "ra8875":             ("SPI",),
+    "sh1106":             ("I2C",),
+    "il3820":             ("SPI", "GPIO"),
+    "gdew0154t8":         ("SPI", "GPIO"),
+    "hailo_8l":           ("GPIO",),
+    # v0.5 §D.industrial batch -- 18 industrial sensing / control chips.
+    "bmp390":             ("I2C",),
+    "ms5611":             ("I2C",),
+    "lps22hb":            ("I2C",),
+    "vl53l1x":            ("I2C",),
+    "vl53l5cx":           ("I2C",),
+    "a02yyuw":            ("SERIAL",),
+    "drv8833":            ("PWM",),
+    "drv8825":            ("PWM", "GPIO"),
+    "tmc2209":            ("SERIAL",),
+    "a4988":              ("PWM", "GPIO"),
+    "as5048a_b":          ("I2C",),
+    "mt6701":             ("I2C",),
+    "hx711":              ("GPIO",),
+    "max31855":           ("SPI",),
+    "max31865":           ("SPI",),
+    "tsl2591":            ("I2C",),
+    "qmc5883l":           ("I2C",),
+    "veml7700":           ("I2C",),
+    # v0.5 §D.iot batch -- 9 IoT / connectivity chips.
+    "quectel_bg95":       ("SERIAL",),
+    "quectel_bg77":       ("SERIAL",),
+    "ublox_sara_r5":      ("SERIAL",),
+    "semtech_sx1262":     ("SPI", "GPIO"),
+    "semtech_sx1276":     ("SPI", "GPIO"),
+    "ublox_neo_m9n":      ("SERIAL",),
+    "ublox_max_m10s":     ("SERIAL",),
+    "atgm336h":           ("SERIAL",),
+    "atecc608b":          ("I2C",),
+    # v0.5 §D.audio batch -- 6 audio chips.
+    "ics_43434":          (),                 # no Zephyr subsystem dep; sample flow via <alp/i2s.h>
+    "inmp441":            (),
+    "wm8960":             ("I2C",),
+    "tlv320aic3204":      ("I2C",),
+    "max98357a":          ("GPIO",),
+    "es8388":             ("I2C",),
+    # SoM-intrinsic batch (issue #1487) -- act8760/tps628640/
+    # da9292/clk_5l35023b are I2C-only PMIC/clock parts; pi3dbs12212/
+    # murata_lbee5hy2fy/deepx_dxm1/gd32_swd are GPIO-only.  All nine were
+    # missing from this table despite each having a `config
+    # ALP_SDK_CHIP_<NAME>` / `depends on` entry in
+    # zephyr/kconfigs/chips.kconfig, so the loader turned the chip on
+    # without turning its dependency on, and Kconfig silently dropped
+    # the chip assignment as unmet (issue #1487).
+    "act8760":            ("I2C",),
+    "tps628640":          ("I2C",),
+    "pi3dbs12212":        ("GPIO",),
+    "da9292":             ("I2C",),
+    "clk_5l35023b":       ("I2C",),
+    "murata_lbee5hy2fy":  ("GPIO",),
+    "deepx_dxm1":         ("GPIO",),
+    "gd32_swd":           ("GPIO",),
+    # gd32g553 declares `depends on (SPI || I2C)` -- an OR, not an AND:
+    # the driver's bridge protocol is genuinely hybrid (both transports
+    # compiled in, either usable at runtime; see chips/gd32g553/
+    # gd32g553.c and docs/gd32-bridge-protocol.md), so there is no
+    # single right subsystem to force on.  Deliberately over-inclusive
+    # here rather than under (issue #1487's own bug class): turning on
+    # both is always sufficient for the `||`, whereas picking only one
+    # would silently drop the other transport the same way the missing
+    # entries above did.
+    "gd32g553":           ("SPI", "I2C"),
+}