tan-cli 0.7.0__py3-none-any.whl

tan/core/dp_id.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure SW-DP ID banner parsing for the read-only DPIDR preflight (tan-cli#520
+generalised this from Flow D-only; tan-cli#795 split it out of `tan.core.
+flash_plan` on its own, since these functions are pure string/bool logic that
+nothing in `flash_plan.py` itself calls -- only `tan.commands.flash_cmd.
+_flow_d_preflight`, the one caller that spawns `JLinkExe` and reads its
+banner, does. `flash_plan.py` keeps `_validate_expect_dpidr_width` (it raises
+`FlashPlanError`, defined there); this module has no IO and raises nothing.
+
+Extracted verbatim (names unchanged, including the leading underscore --
+matches this codebase's existing cross-module convention for a name that is
+implementation-private to the *feature*, not to the *file*, e.g. `flash_plan.
+_DEV_ROOT` imported straight into `flash_cmd.py`), no behaviour change -- see
+tan-cli#312/#369/#373/#795 in the docstrings below for the history of each
+refusal shape this parsing feeds.
+"""
+from __future__ import annotations
+
+import re
+
+
+def _dp_id_matches(expected: str, banner: str) -> bool:
+    """Whether the banner's reported SW-DP ID equals `expected`, compared as
+    PARSED 32-bit values (tan-cli#795) rather than the prior unanchored
+    substring match (`_hex_in`, since removed): that match accepted any
+    truncation of `expected` that happened to appear in the banner --
+    `0x2477` matched `Found SW-DP with ID 0x0BE12477`, and `0x477` (ARM's own
+    JEP106 designer field, shared by every ARM SW-DP) matched every ARM
+    board's banner. The caller already refuses a short `expected` via
+    `flash_plan.validate_flow_d_preflight_args`'s own width check
+    (`flash_plan._validate_expect_dpidr_width`, run at plan time, before this
+    ever executes -- see `tan.commands.flash_cmd._flow_d_preflight`);
+    `_dp_id_value` extracts the banner's own reported ID the same way the
+    mismatch-reporting branch below already does."""
+    actual = _dp_id_value(banner)
+    if actual is None:
+        return False
+    return int(actual, 16) == int(expected, 16)
+
+
+#: SEGGER's own wording for a successful SWD connect that read AN id, whatever
+#: it turned out to be -- "Found SW-DP with ID 0x........" / "DPIDR: 0x........".
+#: Matched loosely on purpose: what this distinguishes is "a real board
+#: answered with a different identity" from "nothing answered", not the exact
+#: firmware/DLL version's phrasing. The hex value is its own capture group
+#: (tan-cli#512) so `_dp_id_value` can report what was ACTUALLY read, not only
+#: whether something was -- `_dp_id_reported` still just asks whether this
+#: matches at all.
+_DP_ID_RE = re.compile(r"(?:with\s+ID|DPIDR)\s*:?\s*(0x[0-9A-Fa-f]+)", re.IGNORECASE)
+
+#: SEGGER's own wording for the PROBE itself refusing the connection outright
+#: -- measured verbatim on the rc3 bench run: "Connecting to J-Link ...FAILED:
+#: Cannot connect to the probe/programmer." (tan-cli#312). Deliberately NOT a
+#: bare `FAILED`/`Cannot connect` match (that was the tan-cli#312 review
+#: finding): JLinkExe prints "FAILED" in many contexts, and "Cannot connect"
+#: alone also fires on a TARGET-level refusal -- see `_CONNECT_FAILED_TARGET_RE`
+#: below -- which is a real wiring/probe-selection problem, not a re-enumerating
+#: probe.
+_CONNECT_FAILED_RE = re.compile(r"Cannot connect to the probe/programmer", re.IGNORECASE)
+
+#: SEGGER's own wording for a TARGET-level connect refusal -- "Cannot connect
+#: to target." (unplugged SWD ribbon, unpowered board) or "Cannot connect to
+#: J-Link." (a probe that IS reachable via USB but refuses the requested
+#: `jlink_serial`). Both are genuine wiring/probe-selection problems, so their
+#: presence forces `_connect_failed_outright` to False even alongside the
+#: probe-level phrase above -- asserting "wiring is fine" here would be the
+#: false negative tan-cli#312's review flagged (measured against a real
+#: unplugged-ribbon and a real unpowered-target banner).
+_CONNECT_FAILED_TARGET_RE = re.compile(r"Cannot connect to (?:target|J-Link)\b", re.IGNORECASE)
+
+
+def _dp_id_reported(banner: str) -> bool:
+    """Whether the banner names ANY SW-DP ID -- not whether it matches
+    `expected` (the caller already ruled that out via `_dp_id_matches`), only
+    whether a connect got far enough to read one at all."""
+    return _DP_ID_RE.search(banner) is not None
+
+
+def _dp_id_value(banner: str) -> str | None:
+    """The actual SW-DP ID text the banner reported, verbatim (whatever hex
+    casing/`0x` spelling SEGGER printed), or `None` if `_DP_ID_RE` does not
+    match at all. tan-cli#512: a caller that already knows `_dp_id_reported(
+    banner)` is `True` gets a non-`None` value here by construction -- both
+    read the same regex against the same banner."""
+    match = _DP_ID_RE.search(banner)
+    return match.group(1) if match else None
+
+
+def _connect_failed_outright(banner: str) -> bool:
+    """Whether the banner carries SEGGER's own wording for the PROBE itself
+    refusing the connection (still re-enumerating, no board reachable at all),
+    as opposed to a TARGET-level refusal -- a real wiring/probe-selection
+    problem that must keep the original remediation, not the re-enumeration
+    one."""
+    if _CONNECT_FAILED_TARGET_RE.search(banner) is not None:
+        return False
+    return _CONNECT_FAILED_RE.search(banner) is not None

tan/core/elf_load.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The lowest load address of an ELF image -- pure, stdlib-only.
+
+`tan build --board` (tan-cli#1370) needs one fact about a Zephyr ELF to decide
+how the image may be run: whether it is linked into the TCM (its lowest
+`PT_LOAD` sits below the SoC's flash base) or into flash. This reads the program
+headers and nothing else; it never raises on a file that is not an ELF.
+"""
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+_PT_LOAD = 1
+
+
+def lowest_load_address(path: str | Path) -> int | None:
+    """Lowest `p_paddr` among `PT_LOAD` segments that carry bytes (`p_filesz > 0`).
+
+    A NOBITS `.bss` segment (filesz 0) sits in RAM whatever the image is linked
+    to, so counting it would call every flash image a RAM image. `None` means
+    UNCLASSIFIABLE -- unreadable, not a little-endian ELF32/ELF64, a malformed
+    header table, or no loadable segment with bytes -- and never raises."""
+    try:
+        data = Path(path).read_bytes()
+        return _lowest(data)
+    except (OSError, struct.error, ValueError):
+        return None
+
+
+def _lowest(data: bytes) -> int | None:
+    if len(data) < 52 or data[:4] != b"\x7fELF" or data[5] != 1:
+        return None
+    if data[4] == 1:  # ELF32
+        min_ent, word = 32, "<I"
+        phoff, = struct.unpack_from("<I", data, 28)
+        phentsize, phnum = struct.unpack_from("<HH", data, 42)
+        paddr_at, filesz_at = 12, 16
+    elif data[4] == 2:  # ELF64
+        min_ent, word = 56, "<Q"
+        if len(data) < 64:
+            return None
+        phoff, = struct.unpack_from("<Q", data, 32)
+        phentsize, phnum = struct.unpack_from("<HH", data, 54)
+        paddr_at, filesz_at = 24, 32
+    else:
+        return None
+    if phentsize < min_ent or phnum == 0:
+        return None
+    lowest: int | None = None
+    for i in range(phnum):
+        off = phoff + i * phentsize
+        if off + phentsize > len(data):
+            return None
+        p_type, = struct.unpack_from("<I", data, off)
+        if p_type != _PT_LOAD:
+            continue
+        filesz, = struct.unpack_from(word, data, off + filesz_at)
+        if filesz == 0:
+            continue
+        paddr, = struct.unpack_from(word, data, off + paddr_at)
+        lowest = paddr if lowest is None else min(lowest, paddr)
+    return lowest

tan/core/error_catalog.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The alp-sdk error/diagnostic catalogue, as `tan explain --code` reads it.
+
+Port of the lookup half of alp-sdk's `scripts/alp_cli/explain.py` (ADR-0020
+end-state B: the verb moves to `tan`, it does not disappear). That command is
+the only reader of `<sdk>/metadata/error-catalog.json` today, and retiring it
+without this port would leave every `ALP-Bxxx` landing page and every
+`ALP_ERR_*` enum comment unreachable from any CLI.
+
+**The source is the generated catalogue, not the markdown.** The task this
+was written for described `explain.py` as reading `docs/diagnostics/ALP-B*.md`
+and the `ALP_ERR_*` enum directly. Measured against alp-sdk `origin/dev`, it
+does not: it reads `metadata/error-catalog.json` and nothing else
+(`explain.py:24-25,39-42`). Those two sources are what
+`scripts/gen_error_catalog.py` reads, and that generator stays in alp-sdk --
+it is a `pr-generated-files.yml` drift gate over alp-sdk's own headers and
+docs, not a user command, so ADR-0020 does not move it. tan reading the
+generated JSON is also the only shape compatible with I-26/ADR-0017: tan
+learns no hardware fact and parses no C header, it reads one JSON file out of
+the bound checkout the same way `presets` reads `metadata/e1m_modules/`.
+
+Pure apart from the one file read, so the lookup, the suggestion list and the
+rendered field order are unit-testable without a checkout on disk.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+from pathlib import Path
+
+#: `<sdk_root>/metadata/error-catalog.json`, as path segments -- the same
+#: shape `tan.core.shapes.SDK_MARKER` uses so a caller may join it either way.
+CATALOG_RELATIVE = ("metadata", "error-catalog.json")
+
+#: Rendered field order and label, verbatim from `explain.py`'s `_FIELD_ORDER`.
+#: A field the catalogue omits (an `api-error` carries no `cause`/`fix`) is
+#: SKIPPED, never rendered empty -- the generator's own "never fabricate a
+#: field that has no source" rule, preserved on the reading side.
+FIELD_ORDER: tuple[tuple[str, str], ...] = (
+    ("summary", "summary"),
+    ("cause", "cause"),
+    ("fix", "fix"),
+    ("doc", "doc"),
+)
+
+#: `difflib.get_close_matches` tuning, verbatim from `explain.py:87-88`. Kept
+#: as named constants because the SUGGESTION LIST is user-visible output: a
+#: different cutoff silently changes what a typo is answered with.
+SUGGESTION_LIMIT = 5
+SUGGESTION_CUTOFF = 0.4
+
+
+class CatalogUnreadable(Exception):
+    """The bound checkout has no readable `metadata/error-catalog.json`.
+
+    Raised for an absent file, an unreadable one, malformed JSON, and a
+    document whose top level is not an object -- one exception for all four
+    because the caller's answer is the same in every case: name the path it
+    looked at and say the checkout cannot answer, rather than guessing which
+    of alp-sdk's several possible states produced it.
+    """
+
+    def __init__(self, path: Path, detail: str) -> None:
+        super().__init__(f"{path}: {detail}")
+        self.path = path
+        self.detail = detail
+
+
+def catalog_path(sdk_root: Path | str) -> Path:
+    """`<sdk_root>/metadata/error-catalog.json`."""
+    return Path(os.path.join(str(sdk_root), *CATALOG_RELATIVE))
+
+
+def load_codes(sdk_root: Path | str) -> dict[str, dict]:
+    """The `{code: entry}` map from the bound checkout's catalogue.
+
+    Raises `CatalogUnreadable`; never returns a partial map. A document that
+    parses but carries no `codes` key yields `{}` rather than raising, exactly
+    as `explain.py`'s `data.get("codes", {})` does -- an empty catalogue is a
+    catalogue in which every code is unknown, which the miss path already
+    reports honestly.
+
+    Every VALUE in `codes` is also checked here, not just `codes` itself: a
+    catalogue shaped `{"codes": {"ALP-B003": "not an object"}}` (also a list,
+    also `null`) otherwise reaches `lookup`, matches on `ALP-B003`, and
+    `resolve_code`'s `entry = codes[key]` then hands a non-dict to
+    `summary_line`/`detail_lines`, both of which call `entry.get(...)`.
+    Measured with this guard removed: `AttributeError: 'str' object has no
+    attribute 'get'`, surfacing as `explain.internal-failure` at exit 5 for a
+    checkout problem the reader could fix -- the same exit-1-not-exit-5
+    concern `codes` itself is guarded for, just one dereference deeper.
+    """
+    path = catalog_path(sdk_root)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise CatalogUnreadable(
+            path,
+            "error catalog not found -- run `python3 scripts/gen_error_catalog.py` "
+            "in the alp-sdk checkout",
+        ) from None
+    except (OSError, UnicodeDecodeError) as err:
+        raise CatalogUnreadable(path, f"error catalog is unreadable: {err}") from None
+    try:
+        data = json.loads(raw)
+    except ValueError as err:
+        raise CatalogUnreadable(path, f"error catalog is not valid JSON: {err}") from None
+    if not isinstance(data, dict):
+        raise CatalogUnreadable(path, "error catalog is not a JSON object")
+    codes = data.get("codes", {})
+    if not isinstance(codes, dict):
+        raise CatalogUnreadable(path, "error catalog's `codes` is not a JSON object")
+    for code, entry in codes.items():
+        if not isinstance(entry, dict):
+            raise CatalogUnreadable(
+                path, f"error catalog entry '{code}' is not a JSON object"
+            )
+    return codes
+
+
+def normalise(code: str) -> str:
+    """Canonicalise user input for matching -- `explain.py`'s `_normalise`.
+
+    Case-insensitive and whitespace-trimmed, so `alp-b003`, ` ALP-B003 ` and
+    `alp_err_no_backend` all resolve.
+    """
+    return code.strip().upper()
+
+
+def lookup(codes: dict[str, dict], query: str) -> tuple[str | None, list[str]]:
+    """`(matched_key, suggestions)` for `query` against `codes`.
+
+    On a hit the suggestion list is empty; on a miss the key is `None` and the
+    suggestions are `explain.py`'s own `difflib` shortlist, mapped back to the
+    catalogue's real spelling. Both halves are returned together because the
+    caller needs exactly one of them and deciding which is this function's job.
+    """
+    by_upper = {normalise(key): key for key in codes}
+    wanted = normalise(query)
+    key = by_upper.get(wanted)
+    if key is not None:
+        return key, []
+    close = difflib.get_close_matches(
+        wanted, list(by_upper), n=SUGGESTION_LIMIT, cutoff=SUGGESTION_CUTOFF
+    )
+    return None, [by_upper[match] for match in close]
+
+
+def summary_line(entry: dict) -> str:
+    """`<CODE> (<kind>)` -- the header `explain.py`'s `_render` paints cyan.
+
+    ONE space, where `explain.py` writes two (`f"{code}  ({kind})"`): tan's
+    `explain` summary is `"<label> (<id>)"` for every other selector kind and a
+    per-mode spacing rule inside one command is a worse surface than a
+    one-character divergence. The CODE and the KIND are verbatim.
+    """
+    return f"{entry.get('code', '')} ({entry.get('kind', '')})".strip()
+
+
+def detail_lines(entry: dict) -> list[str]:
+    """`<label>: <value>` per populated field, in `FIELD_ORDER`.
+
+    The values are verbatim catalogue text -- no re-wrapping, no markdown
+    stripping, no truncation. `explain_cmd` prefixes each with `- ` and wraps
+    it exactly as it wraps a template's detail lines.
+    """
+    return [
+        f"{label}: {entry[key]}" for key, label in FIELD_ORDER if entry.get(key)
+    ]