tan-cli 0.7.0__py3-none-any.whl

tan/planner/manifest.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""System-manifest emitter -- assembles system-manifest.yaml from the model.
+
+`emit_system_manifest` renders the spec-§5.2 manifest (slices, carve-outs,
+storage, memory regions, helper-MCU block) off the parsed BoardProject + the
+resolved carve-outs / partitions / memory regions; `_helper_mcus` builds the
+manifest's `helper_mcus[]` block (shared with the Orchestrator's materialise
+path, which back-imports it). Extracted as the #285 manifest emit seam.
+
+`memory[]` is the region table the other two panes refer INTO by name
+(#1365 item 3) -- `memory.resolve_memory_regions` shapes it, and it is
+OMITTED rather than emitted empty when a SoM resolves no regions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import yaml
+
+from .carveout import resolve_carve_outs
+from .memory import resolve_memory_regions
+from .models import BoardProject, Slice, SystemManifest
+from .partition import resolve_storage_partitions
+
+
+def emit_system_manifest(
+    project: BoardProject,
+    *,
+    slices: Optional[list[Slice]] = None,
+) -> str:
+    """Generate system-manifest.yaml per spec §5.2.
+
+    If `slices` is None, projects the BoardProject's `cores` dict
+    as-is (typical "describe what will run" call).  When the
+    orchestrator finishes fan_out it passes its updated Slice list
+    so the manifest carries status / log_path / etc.
+    """
+    carve_outs = resolve_carve_outs(project)
+    partitions = resolve_storage_partitions(project)
+    memory_regions = resolve_memory_regions(project)
+    effective_slices = list(slices) if slices is not None else list(project.cores.values())
+
+    boot_order = list(project.som_preset.get("boot_order") or [])
+
+    manifest = SystemManifest(
+        project=project,
+        slices=effective_slices,
+        carve_outs=carve_outs,
+        partitions=partitions,
+        boot_order=boot_order,
+        helper_mcus=_helper_mcus(project),
+        memory_regions=memory_regions,
+    )
+
+    out = manifest.to_dict()
+    # Comment when boot_order is empty so reviewers see the gap.
+    text = yaml.safe_dump(out, sort_keys=False, default_flow_style=False)
+    if not boot_order:
+        text += ("\n# boot_order is empty -- add a `boot_order:` list to "
+                 f"metadata/e1m_modules/{project.sku}.yaml when the\n"
+                 "# bring-up order is finalised.\n")
+    return text
+
+
+def _helper_mcus(project: BoardProject) -> list[dict[str, Any]]:
+    """Build the manifest's `helper_mcus[]` block.
+
+    Source: the SoM preset's `helper_firmware:` list (Phase 3).  Each key
+    the entry declares is projected INDEPENDENTLY -- how the image is
+    written locally (flash_method + flash_args), how it is updated in the
+    field (update_channel), and who may invoke the flash method
+    (flash_policy) are three separate axes, and a helper may declare any
+    combination.  The GD32 bridge declares two: an `alp_ota_spi_bridge`
+    channel for normal field updates, and (until tan-cli#732 removed its
+    local write path, `swd_probe`) a `recovery_only` local flash method for
+    a bricked board.  Dropping the flash keys because a channel exists would
+    DELETE that recovery path from the manifest rather than let `tan flash`
+    decline it, so this function must never make one key's presence
+    suppress another's (alp-sdk #1357).  `firmware_path` is entirely ABSENT
+    from the row when
+    the preset doesn't declare one (e.g. GD32 bridge SKUs pending a
+    released binary, alp-sdk #852/#936) -- it is never emitted as `null`,
+    because `system-manifest-v1.schema.json` types it `string` when present
+    (the orchestrator does NOT fail the build on a missing helper firmware
+    path -- the Renesas + Alif flash flows are independently scriptable).
+
+    Every in-tree SoM preset carries a `helper_firmware:` list (no more
+    Phase-1 stragglers), so there is no back-compat `on_module.{
+    supervisor_mcu,wifi_ble}` fallback here -- no-legacy-compat.
+    """
+    out: list[dict[str, Any]] = []
+
+    helper_firmware = project.som_preset.get("helper_firmware")
+    if isinstance(helper_firmware, list):
+        for entry in helper_firmware:
+            if not isinstance(entry, dict):
+                continue
+            row: dict[str, Any] = {
+                "name": entry.get("name"),
+                "chip": entry.get("chip"),
+            }
+            # Project every declared key independently.  No key's presence
+            # suppresses another's: `update_channel` describes field
+            # updates, `flash_method`/`flash_args` describe a local write,
+            # and `flash_policy` says who may perform that write.  A helper
+            # declaring both halves keeps both -- `tan flash` decides what
+            # to do with them from `flash_policy` (alp-sdk #1357).
+            for key in ("firmware_path", "flash_method", "flash_args",
+                        "flash_policy", "update_channel"):
+                value = entry.get(key)
+                if value is not None:
+                    row[key] = value
+            out.append(row)
+    return out

tan/planner/memory.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Resolved memory-region view for the system manifest (alp-sdk#1365 item 3).
+
+`resolve_memory_regions()` projects the SoM's effective memory-region table
+into the `memory[]` pane `system-manifest-v1` declares -- the third pane
+`ipc[]` and `storage[]` refer INTO by name, not a third copy of them.
+
+Three vocabularies, each taken from what the code already produces rather
+than from #1365's issue body (which predates splits A and B and proposes
+shapes the shipped derivation cannot fill):
+
+* `kind` is `aperture.classify_region()`'s own four verdicts --
+  `flash` / `ram` / `unclassified` / `unresolved`. Collapsing them onto the
+  issue's two (`ram` | `flash`) would have to invent a class for the two
+  verdicts that exist precisely to say "not proven": `unclassified` (outside
+  the aperture AND preset-authored -- an Ensemble OSPI XIP window is outside
+  and still flash) and `unresolved` (no extent, or no aperture declared for
+  this SoC at all, which is every non-Alif SoM).
+
+* the authority field is `write_authority`, passed through verbatim with
+  som-preset-v2's six values. The issue's 3-value `owner` was replaced
+  during review because one axis cannot separate flash-time from runtime
+  authority: `customer_image` and `customer_runtime` would both collapse to
+  `customer`, which is the exact distinction the AEN `storage`-vs-`he_slot0`
+  hazard needs. A row that authors no `write_authority` carries no key --
+  absent means unresolved, never `customer_runtime` (ADR-0034 clause 4).
+
+* `status` is `ok` / `unresolved`, the word this schema's own items
+  description already made normative, not `ipc[]`'s `ok` / `blocked`. They
+  are not synonyms: `blocked` is a verdict about an allocation request,
+  while a region is a fact that either resolved an address or did not.
+
+`source` is derived here rather than tagged in `alp_project.resolve_memory_map`
+on purpose. That function's precedence is ALL-OR-NOTHING (an authored
+`memory_map:` wins the whole table, else the SoC's fixed `memory_regions`,
+else the silicon-variant derivation), so provenance is a property of the
+table, not of a row -- `carveout.py` and `partition.py` already read it the
+same way, via `bool(som_preset.get("memory_map"))`. Tagging rows inside the
+loader would also add a key to dicts that flow into `$defs/memory_region`'s
+`additionalProperties: false` validation path.
+
+Depends only downward -- `som_metadata`, `aperture` and `memregion`; nothing
+calls back into the package.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .aperture import classify_region, resolve_aperture
+from .memregion import _region_size_bytes
+from .models import BoardProject
+from .som_metadata import resolve_memory_map
+
+# The two provenance values a region row can carry.  `board_yaml` (the third
+# value #1365's issue body proposes) has no producer: board.yaml never
+# AUTHORS a region, it only NAMES one via `ipc[].carve_out_region` /
+# `storage[].flash_device`, so a board_yaml-sourced region row cannot occur.
+_SOURCE_PRESET = "som_preset"
+_SOURCE_SOC = "soc_derived"
+
+
+def resolve_memory_regions(project: BoardProject) -> list[dict[str, Any]]:
+    """Project the SoM's memory regions into the manifest's `memory[]` pane.
+
+    Returns `[]` when the SoM resolves no regions at all (an unresolvable
+    `silicon_variant`, e.g. `TBD`). The caller must then OMIT the
+    key rather than emit `memory: []` -- the schema draws a load-bearing
+    distinction between an absent pane ("this producer does not emit it
+    yet") and an empty one, and collapsing the two would tell every
+    consumer that a SoM with a pending HW-config writeup has no memory.
+    """
+    metadata_root = project.effective_metadata_root()
+    memory_map = resolve_memory_map(project.som_preset, metadata_root)
+    if not memory_map:
+        return []
+
+    # Same two signals `carveout.py` / `partition.py` derive, read the same
+    # way: the SoC's declared on-die flash aperture (None on every non-Alif
+    # SoM), and whether THIS preset authored the table.
+    aperture = resolve_aperture(project.som_preset, metadata_root)
+    is_preset_authored = bool(project.som_preset.get("memory_map"))
+    source = _SOURCE_PRESET if is_preset_authored else _SOURCE_SOC
+
+    return [
+        _resolved_row(region, aperture, is_preset_authored, source)
+        for region in memory_map
+        if isinstance(region, dict) and region.get("name")
+    ]
+
+
+def _resolved_row(
+    region: dict[str, Any],
+    aperture: Optional[tuple[int, int]],
+    is_preset_authored: bool,
+    source: str,
+) -> dict[str, Any]:
+    """Shape one region into a manifest row.
+
+    Key order is deliberate and load-bearing for the byte-golden `.snap`
+    fixtures: identity first (`name`, `source`), then the two derived
+    verdicts (`kind`, `status`), then the resolved numbers, then the
+    authored passthroughs, then the explanation.  Builds a NEW dict --
+    the loader's region dicts are never mutated.
+    """
+    row: dict[str, Any] = {
+        "name":   str(region.get("name")),
+        "source": source,
+        "kind":   classify_region(region, aperture, is_preset_authored),
+    }
+
+    # `status` keys off the BASE, not off the extent: a region whose base
+    # resolves but whose size does not has still resolved its address, and
+    # the schema's rule is written about `base` ("carries no `base` and says
+    # why").  `region_extent()` folds both into one None, so it cannot
+    # answer this question on its own.
+    base = region.get("base")
+    base_ok = isinstance(base, int) and not isinstance(base, bool)
+    row["status"] = "ok" if base_ok else "unresolved"
+    if base_ok:
+        row["base"] = base
+
+    size_bytes = _region_size_bytes(region)
+    if size_bytes is not None:
+        row["size_bytes"] = size_bytes
+
+    write_authority = region.get("write_authority")
+    if isinstance(write_authority, str) and write_authority:
+        row["write_authority"] = write_authority
+
+    accessible_from = region.get("accessible_from")
+    if isinstance(accessible_from, list) and accessible_from:
+        row["accessible_from"] = [str(core) for core in accessible_from]
+
+    if not base_ok:
+        row["reason"] = _unresolved_reason(row["name"], base, size_bytes)
+
+    return row
+
+
+def _unresolved_reason(name: str, base: Any, size_bytes: Optional[int]) -> str:
+    """Say WHY a base did not resolve, in terms the author can act on.
+
+    Never a guessed address (ADR-0034 clause 4): the reason names the field
+    that is missing and where to declare it, which is what makes an
+    unresolved row actionable instead of merely absent.
+    """
+    if base is None:
+        cause = ("carries no `base:` -- the silicon default applies and no "
+                 "address is declared for it")
+    elif isinstance(base, str):
+        cause = f"declares `base: {base}`, a placeholder, not an address"
+    else:
+        cause = f"declares a non-integer `base:` ({type(base).__name__})"
+    sizing = (" Its size resolves, so only the address is missing."
+              if size_bytes is not None else
+              " Neither its address nor its size resolves.")
+    return (f"Region '{name}' {cause}, so no extent can be resolved and no "
+            f"class derived.{sizing} Declare `base:` in this SoM preset's "
+            f"`memory_map:` to resolve it.")

tan/planner/memregion.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Memory-region math shared across the resolvers -- a leaf.
+
+The page granularity and the memory_map size-field -> bytes conversion, used by
+both the carve-out resolver and the storage-partition resolver. A dependency-
+free leaf (typing only) so each resolver imports it directly instead of one
+reaching into the other (or back through the package __init__). Extracted as a
+#285 leaf seam -- the same move as paths.py -- so the partition resolver lands
+cleanly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# Page granularity for carve-out / partition base + size alignment.
+_PAGE = 4096
+
+
+def _region_size_bytes(region: dict[str, Any]) -> Optional[int]:
+    """Convert a memory_map entry's size_mib / size_kib to bytes.
+
+    Reads each field by its VALUE, not by key presence: the
+    `memory_region` schema lets `size_kib` and `size_mib` each
+    independently be an int or the literal `"TBD"`, so a `"TBD"` in one
+    field must never mask a usable integer sitting in the other (e.g.
+    `{size_mib: "TBD", size_kib: 64}` must resolve via `size_kib`, not
+    bail out because `size_mib` is present but unresolved). `size_mib`
+    is checked first -- matching this module's real prior behaviour: on
+    `origin/dev` before alp-sdk#1365 split B, this function's only two
+    callers (`carveout.py` and `partition.py`) both went through a
+    key-PRESENCE check that looked at `size_mib` first
+    (`if "size_mib" in region: ...`). `check_atoc_reservation.py` was
+    NOT a caller of this module then -- it carried its own private,
+    unrelated `_region_size_kib` helper (kib-first), which split B
+    retired in favour of importing this module instead. That gate
+    becoming a caller here is what split B changed; it is not evidence
+    of this module's own prior precedence, which was mib-first.
+
+    The schema permits both fields on one region (neither `som-preset-
+    v1.schema.json`'s `memory_region` nor `soc-spec-v1.schema.json`'s
+    forbids it), and no region in `metadata/e1m_modules/*.yaml` today
+    sets both, so this precedence has no real-preset evidence either
+    way -- pinned here by test only, matching the module's actual
+    history rather than a caller that did not exist yet.
+
+    Returns None only when NEITHER field resolves to a usable integer.
+    """
+    size_mib = region.get("size_mib")
+    if isinstance(size_mib, int) and not isinstance(size_mib, bool):
+        return size_mib * 1024 * 1024
+    size_kib = region.get("size_kib")
+    if isinstance(size_kib, int) and not isinstance(size_kib, bool):
+        return size_kib * 1024
+    return None