tools: DTS-property inspector + XSA-reference parity test for AD9081

Every System-API hw-probe failure we debugged today was visible in
the rendered DTS *before* anything was flashed — but each fix still
cost one CI round-trip (push → ~5 min → parse logs → diff → fix →
repeat).  The iteration loop is the bottleneck, not the breadth of
the bugs.

Add `adidt.tools.dts_inspect`: a small text-grep parser that pulls
kernel-critical properties out of an emitted DTS and returns them
keyed by "grouping ancestor" — e.g. `tx-dacs:adi,link-mode`,
`channel@2:adi,divider`, `ad9081:clocks`.  A second helper,
`compare_properties`, returns a human-readable diff for a given set
of keys.

Commit a golden reference DTS pulled from a passing `hw-coord-mini2`
workflow artifact as `test/devices/fixtures/ad9081_zcu102_xsa_reference.dts`,
and parametrize a new test file over the full
`KERNEL_CRITICAL_KEYS` set — each property that diverges between
the XSA path (known to probe on hardware) and the System-API path
becomes an individual focused failure in <1 s.

Plus `adidt.tools.dts_compare_cli` for interactive diffing:

    python3 -m adidt.tools.dts_compare_cli \
        test/devices/fixtures/ad9081_zcu102_xsa_reference.dts \
        /tmp/candidate.dts

Running this test suite replays every DT-emission fix chased in
today's debug session as regression coverage:

    ad9081:clocks                              (dev_clk phandle)
    ad9081:clock-names                         (dev_clk name)
    tx-dacs / rx-adcs:adi,link-mode            (9 vs 10 per side)
    tx-dacs / rx-adcs:adi,converters-per-device (M=8 vs M=4 bug)
    tx-dacs / rx-adcs:adi,lanes-per-device     (L=4 vs L=0 bug)
    tx-dacs / rx-adcs:adi,octets-per-frame     (F=4 vs F=2)
    channel@{0,2,6}:adi,divider                (12 vs 8 bug)
    channel@{8,12}:adi,divider                 (6 vs 4 bug)
    channel@{3,13}:adi,divider                 (1536 vs 1024)

Author: tfcollins

adidt/tools/__init__.py

@@ -0,0 +1 @@
+"""Developer-facing tools (CLI diffing, DTS inspection, etc.)."""

adidt/tools/dts_compare_cli.py

@@ -0,0 +1,53 @@
+"""Standalone DTS-comparison CLI.
+
+Usage:
+
+    python3 -m adidt.tools.dts_compare_cli REFERENCE.dts CANDIDATE.dts
+
+Prints a diff of the kernel-critical properties between ``REFERENCE``
+and ``CANDIDATE`` — handy for iterating on the System API DT emission
+when you have a known-good DTS (e.g. pulled from a passing CI run's
+``hw-coord-<place>-output`` artifact) and want to see at a glance
+what the declarative path is doing differently.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .dts_inspect import KERNEL_CRITICAL_KEYS, compare_properties, extract_props
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Diff kernel-critical DT properties between two DTS files "
+            "(e.g. XSA-pipeline output vs System-API output)."
+        )
+    )
+    parser.add_argument("reference", type=Path, help="Reference DTS (known-good)")
+    parser.add_argument("candidate", type=Path, help="Candidate DTS (under test)")
+    parser.add_argument(
+        "--keys",
+        nargs="+",
+        default=KERNEL_CRITICAL_KEYS,
+        help="Subset of property keys to compare (default: every kernel-critical key).",
+    )
+    args = parser.parse_args(argv)
+
+    ref = extract_props(args.reference.read_text())
+    cand = extract_props(args.candidate.read_text())
+    diffs = compare_properties(ref, cand, keys=args.keys)
+    if not diffs:
+        print("OK — no diff on kernel-critical keys.")
+        return 0
+    print(f"Diff on {len(diffs)} key(s):")
+    for line in diffs:
+        print(f"  {line}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

adidt/tools/dts_inspect.py

@@ -0,0 +1,197 @@
+"""DTS property inspection + cross-path comparison helpers.
+
+Most hardware-probe failures on the System-API path today look like
+"System emits property X; XSA path (known to probe) emits Y".  That
+diff is visible in the generated DTS *before* anything is flashed, so
+a plain-text inspector that can pull a handful of kernel-critical
+properties out of any DTS and diff them against a reference catches
+the bug in unit tests rather than on hardware.
+
+Two entry points:
+
+``extract_props``
+    Grep the emitted DTS text for a curated set of kernel-critical
+    properties (``compatible``, ``adi,link-mode``,
+    ``adi,converters-per-device``, HMC7044 channel dividers, …).
+    Returns a ``{name: value}`` dict of first occurrences, with a
+    channel-qualified key for HMC7044 channels.  Intentionally a
+    text grep — sufficient for the properties the AD9081 /
+    ad_ip_jesd204_tpl driver probes read.
+
+``compare_properties``
+    Compute the set difference between two inspectors' outputs and
+    return a list of human-readable diffs.  No-op on keys only
+    present in one side.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+__all__ = [
+    "extract_props",
+    "compare_properties",
+    "KERNEL_CRITICAL_KEYS",
+]
+
+
+# Properties whose value actually feeds the AD9081 / jesd204 driver
+# probe path.  Ordered roughly by where they appear in the DTS.
+KERNEL_CRITICAL_KEYS: tuple[str, ...] = (
+    # Top-level AD9081 dev_clk wiring.
+    "ad9081:clocks",
+    "ad9081:clock-names",
+    # DAC (host-TX / jrx) framing.
+    "tx-dacs:adi,dac-frequency-hz",
+    "tx-dacs:adi,link-mode",
+    "tx-dacs:adi,converters-per-device",
+    "tx-dacs:adi,lanes-per-device",
+    "tx-dacs:adi,octets-per-frame",
+    "tx-dacs:adi,frames-per-multiframe",
+    "tx-dacs:adi,bits-per-sample",
+    "tx-dacs:adi,samples-per-converter-per-frame",
+    # ADC (host-RX / jtx) framing.
+    "rx-adcs:adi,adc-frequency-hz",
+    "rx-adcs:adi,link-mode",
+    "rx-adcs:adi,converters-per-device",
+    "rx-adcs:adi,lanes-per-device",
+    "rx-adcs:adi,octets-per-frame",
+    "rx-adcs:adi,frames-per-multiframe",
+    # HMC7044 channel dividers (full set; missing channels just
+    # get filtered out by the compare).
+    "channel@0:adi,divider",
+    "channel@2:adi,divider",
+    "channel@3:adi,divider",
+    "channel@6:adi,divider",
+    "channel@8:adi,divider",
+    "channel@10:adi,divider",
+    "channel@12:adi,divider",
+    "channel@13:adi,divider",
+)
+
+
+# Matches a single property line like ``adi,link-mode = <9>;``,
+# capturing the name (group 1) and the RHS (group 2, without trailing ;).
+_PROP_RE = re.compile(r"^\s*([A-Za-z0-9,#_.-]+)\s*=\s*(.+?)\s*;\s*$")
+
+# Matches the opening brace of a named DT node or anonymous node with
+# reg@N addressing: ``label: node@addr {``, ``node {``, ``node@0 {``.
+_NODE_RE = re.compile(
+    r"^\s*(?:([A-Za-z0-9_]+):\s*)?([A-Za-z][A-Za-z0-9,#_-]*(?:@[0-9a-fA-F]+)?)\s*\{\s*$"
+)
+
+
+# When choosing a key prefix for a property, prefer one of these
+# ancestors over the innermost node — they're the "grouping nodes" the
+# tests care about (``tx-dacs:adi,link-mode`` is far more useful than
+# ``link@0:adi,link-mode`` since a DTS can technically nest arbitrarily).
+_GROUPING_ANCESTORS: tuple[str, ...] = (
+    "channel@0",
+    "channel@1",
+    "channel@2",
+    "channel@3",
+    "channel@4",
+    "channel@5",
+    "channel@6",
+    "channel@7",
+    "channel@8",
+    "channel@9",
+    "channel@10",
+    "channel@11",
+    "channel@12",
+    "channel@13",
+    "adi,tx-dacs",
+    "adi,rx-adcs",
+    "ad9081",
+    "hmc7044",
+)
+
+# Normalise ancestor names that include a ``adi,`` prefix or ``@addr``
+# suffix to the short form used as a key prefix.
+_ANCESTOR_ALIAS: dict[str, str] = {
+    "adi,tx-dacs": "tx-dacs",
+    "adi,rx-adcs": "rx-adcs",
+}
+
+
+def _choose_prefix(stack: list[str]) -> str | None:
+    """Pick the most specific 'interesting' ancestor from *stack*.
+
+    Walk the stack innermost-first, return the first ancestor that
+    appears in :data:`_GROUPING_ANCESTORS`, with ``@addr`` stripped
+    off of ad9081/hmc7044-style nodes.
+    """
+    for node in reversed(stack):
+        # Try the exact form first (channel@N, adi,tx-dacs).
+        if node in _GROUPING_ANCESTORS:
+            return _ANCESTOR_ALIAS.get(node, node)
+        # Then the @addr-stripped form (ad9081@0 → ad9081).
+        base = node.split("@", 1)[0]
+        if base in _GROUPING_ANCESTORS:
+            return _ANCESTOR_ALIAS.get(base, base)
+    return None
+
+
+def extract_props(dts_text: str) -> dict[str, str]:
+    """Return ``{"<grouping-ancestor>:<prop>": "<rhs>"}`` for the DTS text.
+
+    The grouping ancestor is the most specific enclosing node from
+    :data:`_GROUPING_ANCESTORS` — so a property nested several levels
+    deep inside ``adi,tx-dacs`` still gets keyed under ``tx-dacs:``
+    rather than whatever the innermost node happens to be (e.g.
+    ``link@0``).  First-occurrence wins; the base node's value is what
+    the kernel sees at probe time before any ``&label`` overlays.
+    """
+    node_stack: list[str] = []
+    out: dict[str, str] = {}
+
+    for line in dts_text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped == "};":
+            if node_stack:
+                node_stack.pop()
+            continue
+        node_match = _NODE_RE.match(line)
+        if node_match:
+            _label, name = node_match.groups()
+            node_stack.append(name)
+            continue
+        prop_match = _PROP_RE.match(line)
+        if prop_match:
+            name, rhs = prop_match.groups()
+            prefix = _choose_prefix(node_stack)
+            if prefix is None:
+                continue
+            key = f"{prefix}:{name}"
+            if key not in out:
+                out[key] = rhs
+    return out
+
+
+def compare_properties(
+    reference: dict[str, str],
+    candidate: dict[str, str],
+    keys: Iterable[str] = KERNEL_CRITICAL_KEYS,
+) -> list[str]:
+    """Compare two ``extract_props`` outputs.  Returns diff lines.
+
+    - Keys present in both with different values → a ``"X: ref=... cand=..."`` line.
+    - Keys in ``reference`` but missing from ``candidate`` → ``"X: missing in candidate"``.
+    - Keys in ``candidate`` but missing from ``reference`` → not flagged
+      (reference may be less verbose; tests use ``keys`` to pin what
+      they actually care about).
+    """
+    diffs: list[str] = []
+    for key in keys:
+        if key not in reference:
+            continue
+        ref = reference[key]
+        cand = candidate.get(key)
+        if cand is None:
+            diffs.append(f"{key}: missing in candidate (reference={ref})")
+        elif cand != ref:
+            diffs.append(f"{key}: reference={ref!r}  candidate={cand!r}")
+    return diffs