enginehall 2.0.0__py3-none-any.whl

pcba/parsers/firmware/index.py

@@ -0,0 +1,250 @@
+"""Index pin and peripheral references in firmware C sources.
+
+Deliberately shallow: regex plus structure, not a C parser. It only has to answer one
+question — *does the firmware name a pin that the .ioc disagrees about?* — and a full
+translation unit parse would buy nothing for that.
+
+The circularity trap
+--------------------
+CubeMX generates `main.h` **from** the `.ioc`:
+
+    #define USART3_TX_Pin       GPIO_PIN_8
+    #define USART3_TX_GPIO_Port GPIOD
+
+So checking those defines against the `.ioc` is vacuous — they agree by construction, and a
+rule built on them would report a permanent, meaningless pass. It would *look* like
+firmware/config validation while validating nothing.
+
+What is NOT circular is a **hardcoded** pin reference: hand-written code that says
+`GPIOD, GPIO_PIN_8` directly instead of using the generated define. That code does not move
+when the pin moves in CubeMX. It is the actual field failure — the pinout changes, the
+generated header follows, and the one USER CODE block that spelled the pin out by hand keeps
+driving the old pad. So this indexer separates generated references from hand-written ones,
+and only the hand-written ones feed the cross-domain rule.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from pcba.model.pinmap import FirmwareIndex, FirmwareReference
+
+SOURCE_SUFFIXES = (".c", ".h", ".cpp", ".hpp", ".cc")
+
+# Directories that hold vendor code we did not write and must not judge.
+SKIP_DIRECTORIES = frozenset(
+    {
+        "Drivers",
+        "Middlewares",
+        "Third_Party",
+        "ThirdParty",
+        "build",
+        "Debug",
+        "Release",
+        "cmake-build-debug",
+        ".git",
+        "node_modules",
+        "CMSIS",
+    }
+)
+
+# CubeMX's generated pin defines. Their presence marks a file as generated-ish and their
+# content is, by construction, whatever the .ioc says.
+_GENERATED_DEFINE = re.compile(r"^\s*#define\s+(\w+)_(?:Pin|GPIO_Port)\s+", re.MULTILINE)
+
+# HAL handle naming convention: `huart3` -> USART3/UART3, `hfdcan1` -> FDCAN1.
+_HANDLE = re.compile(r"\bh(adc|dma|fdcan|i2c|spi|tim|uart|usart|sdmmc|eth|rtc|iwdg|wwdg)(\d+)\b")
+
+# USER CODE blocks survive regeneration — code inside them is hand-written by definition.
+_USER_CODE_BEGIN = re.compile(r"/\*\s*USER CODE BEGIN")
+_USER_CODE_END = re.compile(r"/\*\s*USER CODE END")
+
+
+def _uncommented_lines(text: str) -> list[str]:
+    """Blank comments and literals while retaining offsets and line numbers.
+
+    Lines are split on `\n` only. `str.splitlines()` also splits on form feeds and Unicode
+    separators, which may sit inside a blanked comment, and the two line lists would drift.
+    A string or character literal ends at an unescaped newline: C does not allow a literal to
+    span lines, and an apostrophe in `#error Can't build` must not hide the rest of the file.
+    """
+    chars = list(text)
+    state = "code"
+    i = 0
+    while i < len(text):
+        pair = text[i:i + 2]
+        c = text[i]
+        if state == "code":
+            if pair in ("//", "/*"):
+                state = "line" if pair == "//" else "block"
+                chars[i:i + 2] = [" ", " "]
+                i += 2
+                continue
+            if c in ('"', "'"):
+                state = c
+                chars[i] = " "
+        elif state == "line":
+            if c == "\n":
+                state = "code"
+            else:
+                chars[i] = " "
+        elif state == "block":
+            if pair == "*/":
+                chars[i:i + 2] = [" ", " "]
+                state = "code"
+                i += 2
+                continue
+            if c != "\n":
+                chars[i] = " "
+        else:
+            if c == "\\" and i + 1 < len(text):
+                chars[i] = " "
+                if text[i + 1] != "\n":
+                    chars[i + 1] = " "
+                i += 2
+                continue
+            if c == state or c == "\n":
+                state = "code"
+            if c != "\n":
+                chars[i] = " "
+        i += 1
+    return "".join(chars).split("\n")
+
+
+def _is_generated(text: str) -> bool:
+    """Does CubeMX own this file outside its USER CODE blocks?
+
+    Two signs, either one sufficient. Generated pin defines mark `main.h`. USER CODE markers
+    mark every other file CubeMX writes (`main.c`, `gpio.c`, `*_hal_msp.c`, `*_it.c`): they
+    are how CubeMX knows what to keep when it regenerates the rest from the `.ioc`. Code
+    outside them is CubeMX's own, and an MSP DeInit that names `GPIOD, GPIO_PIN_8` for an
+    unlabelled USART pin agrees with the `.ioc` by construction. Counting it would report
+    every such pin as drift on every CubeMX project.
+    """
+    return len(_GENERATED_DEFINE.findall(text)) >= 2 or bool(_USER_CODE_BEGIN.search(text))
+
+
+# `HAL_GPIO_WritePin(GPIOD, GPIO_PIN_8, ...)` -> port D, pin 8. The mask argument may span
+# lines and combine pins; LL spells them `LL_GPIO_PIN_8`.
+_PIN_CALL = re.compile(r"\b(\w+)\s*\(\s*GPIO([A-K])\s*,")
+_PIN_MASK = re.compile(r"\b(?:LL_)?GPIO_PIN_(\d{1,2})\b")
+# A port/pin pair outside a recognised call: pin tables and hand-written convenience
+# defines such as `#define LED GPIOD, GPIO_PIN_8`.
+_PIN_PAIR = re.compile(r"\bGPIO([A-K])\s*,\s*((?:LL_)?GPIO_PIN_\d{1,2}(?:\s*\|\s*(?:LL_)?GPIO_PIN_\d{1,2})*)\b")
+_LITERAL_CONDITION = re.compile(r"#\s*(?:if|elif)\s+([01])")
+_OPERATIONS = {
+    "HAL_GPIO_WritePin": "write", "HAL_GPIO_TogglePin": "write",
+    "HAL_GPIO_ReadPin": "read", "HAL_GPIO_LockPin": "configure", "HAL_GPIO_DeInit": "configure",
+    "LL_GPIO_SetOutputPin": "write", "LL_GPIO_ResetOutputPin": "write", "LL_GPIO_TogglePin": "write",
+    "LL_GPIO_IsInputPinSet": "read", "LL_GPIO_IsOutputPinSet": "read", "LL_GPIO_IsPinLocked": "read",
+    "LL_GPIO_GetPinMode": "read", "LL_GPIO_GetPinOutputType": "read", "LL_GPIO_GetPinSpeed": "read",
+    "LL_GPIO_GetPinPull": "read", "LL_GPIO_GetAFPin_0_7": "read", "LL_GPIO_GetAFPin_8_15": "read",
+    "LL_GPIO_SetPinMode": "configure", "LL_GPIO_SetPinOutputType": "configure",
+    "LL_GPIO_SetPinSpeed": "configure", "LL_GPIO_SetPinPull": "configure",
+    "LL_GPIO_SetAFPin_0_7": "configure", "LL_GPIO_SetAFPin_8_15": "configure",
+    "LL_GPIO_LockPin": "configure",
+}
+
+
+def _argument_end(code: str, start: int) -> int:
+    """Offset where the argument beginning at `start` ends: its own `,` or `)`, or `;`."""
+    depth = 0
+    for i in range(start, len(code)):
+        c = code[i]
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            if depth == 0:
+                return i
+            depth -= 1
+        elif (c == "," and depth == 0) or c == ";":
+            return i
+    return len(code)
+
+
+def scan_file(path: Path) -> list[FirmwareReference]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    generated = _is_generated(text)
+    raw_lines = text.split("\n")
+    lines = _uncommented_lines(text)
+    user_code = False
+    # One entry per open conditional: [branch disabled, an earlier branch was taken].
+    # Only literal `0` and `1` conditions are resolved; anything else needs build context
+    # and is treated as live, so an unknown branch is never silently dropped.
+    stack: list[list[bool | None]] = []
+    for i, raw in enumerate(raw_lines):
+        if _USER_CODE_BEGIN.search(raw):
+            user_code = True
+        elif _USER_CODE_END.search(raw):
+            user_code = False
+        line = lines[i].strip()
+        literal = _LITERAL_CONDITION.fullmatch(line)
+        if re.match(r"#\s*(if|ifdef|ifndef)\b", line):
+            value = literal.group(1) == "1" if literal else None
+            stack.append([value is False, value])
+        elif re.match(r"#\s*endif\b", line) and stack:
+            stack.pop()
+        elif re.match(r"#\s*elif\b", line) and stack:
+            value = literal.group(1) == "1" if literal else None
+            taken = stack[-1][1]
+            stack[-1] = [taken is True or value is False, True if taken or value else taken]
+        elif re.match(r"#\s*else\b", line) and stack:
+            stack[-1] = [stack[-1][1] is True, True]
+        if any(entry[0] for entry in stack) or (generated and not user_code):
+            lines[i] = " " * len(lines[i])
+    code = "\n".join(lines)
+    where = str(path.absolute())
+    out: list[FirmwareReference] = []
+
+    def add(port: str, mask: str, start: int, end: int, operation: str) -> None:
+        first = code.count("\n", 0, start)
+        last = code.count("\n", 0, end)
+        text = " ".join(line.strip() for line in raw_lines[first:last + 1])[:240]
+        for pin in sorted(set(_PIN_MASK.findall(mask)), key=int):
+            out.append(FirmwareReference(
+                symbol=f"P{port}{int(pin)}", kind="pin", path=where, line=first + 1,
+                text=text, operation=operation,
+            ))
+
+    in_calls: set[int] = set()
+    for match in _PIN_CALL.finditer(code):
+        call, port = match.groups()
+        end = _argument_end(code, match.end())
+        in_calls.add(match.start(2) - len("GPIO"))
+        add(port, code[match.end():end], match.start(), end, _OPERATIONS.get(call, "unknown"))
+    for match in _PIN_PAIR.finditer(code):
+        if match.start() not in in_calls:
+            add(match.group(1), match.group(2), match.start(), match.end(), "unknown")
+    for match in _HANDLE.finditer(code):
+        number = code.count("\n", 0, match.start()) + 1
+        family, instance = match.groups()
+        out.append(FirmwareReference(
+            symbol=family.upper() + instance, kind="peripheral", path=where,
+            line=number, text=raw_lines[number - 1].strip()[:120],
+        ))
+    return out
+
+
+def _sources(root: Path) -> list[Path]:
+    """Every C/C++ source under `root`. Vendor and build trees are pruned before they are
+    entered, as discovery prunes its walk, rather than enumerated and filtered afterwards."""
+    found: list[Path] = []
+    for current, directories, files in os.walk(root):
+        directories[:] = [name for name in directories if name not in SKIP_DIRECTORIES]
+        found.extend(
+            Path(current, name) for name in files if Path(name).suffix in SOURCE_SUFFIXES
+        )
+    # Sorted as paths, so references (and the first one a drift finding is located at) come
+    # out in the same order on every machine.
+    return sorted(path for path in found if path.is_file())
+
+
+def index(root: Path) -> FirmwareIndex:
+    """Walk a firmware tree and index every pin/peripheral reference we can see."""
+    root = Path(root)
+    out = FirmwareIndex(root=str(root))
+    for path in _sources(root):
+        out.references.extend(scan_file(path))
+    return out

pcba/parsers/ioc/__init__.py

@@ -0,0 +1,49 @@
+"""STM32CubeMX `.ioc` and MCU-database reading.
+
+Read-only by design. The `.ioc` is CubeMX-owned; any write path must go through a CubeMX
+adapter and the change-plan workflow, never through this module.
+"""
+
+from pcba.parsers.ioc.mcu_db import (
+    alternate_function_table,
+    expand_variants,
+    find_mcu_db,
+    part_peripherals,
+    pin_signals,
+    resolve_part_xml,
+)
+from pcba.parsers.ioc.reader import (
+    IocError,
+    clocks,
+    collect_pins,
+    diff,
+    is_pin_key,
+    load,
+    parse_ioc,
+    part_name,
+    peripherals,
+    pin_name,
+)
+from pcba.parsers.ioc.validate import check_can_timing, load_manifest, validate
+
+__all__ = [
+    "IocError",
+    "alternate_function_table",
+    "check_can_timing",
+    "clocks",
+    "collect_pins",
+    "diff",
+    "expand_variants",
+    "find_mcu_db",
+    "is_pin_key",
+    "load",
+    "load_manifest",
+    "parse_ioc",
+    "part_name",
+    "part_peripherals",
+    "peripherals",
+    "pin_name",
+    "pin_signals",
+    "resolve_part_xml",
+    "validate",
+]

pcba/parsers/ioc/mcu_db.py

@@ -0,0 +1,180 @@
+"""STM32CubeMX's local MCU database — ST's own answer to "can this pin do that?".
+
+CubeMX ships a per-MCU XML listing every pin and every signal it can carry. It is the
+authority: never answer an alternate-function question from memory, and never from the
+datasheet PDF either.
+
+This reads CubeMX's *data*, never drives its *UI*, so it is safe from any shell.
+"""
+
+from __future__ import annotations
+
+import functools
+import itertools
+import os
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from pcba.parsers.ioc.reader import IocError
+
+MCU_DB_CANDIDATES = (
+    "/Applications/STMicroelectronics/STM32CubeMX.app/Contents/Resources/db/mcu",
+    "/opt/stm32cubemx/db/mcu",
+    "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/db/mcu",
+    "C:/Program Files (x86)/STMicroelectronics/STM32Cube/STM32CubeMX/db/mcu",
+    str(Path.home() / "STM32CubeMX/db/mcu"),
+    str(Path.home() / "STM32Cube/STM32CubeMX/db/mcu"),
+)
+
+
+# Overrides the install locations above. CI and the test suite pin it, so a review does not
+# depend on whether the machine running it happens to have CubeMX installed.
+DB_ENVIRONMENT = "PCBA_CUBEMX_DB"
+
+
+def find_mcu_db(explicit: Path | None = None) -> Path:
+    if explicit:
+        if not explicit.is_dir():
+            raise IocError(f"--db is not a directory: {explicit}")
+        return explicit
+    configured = os.environ.get(DB_ENVIRONMENT)
+    if configured:
+        path = Path(configured)
+        if not path.is_dir():
+            raise IocError(f"{DB_ENVIRONMENT} is not a directory: {configured}")
+        return path
+    for candidate in MCU_DB_CANDIDATES:
+        path = Path(candidate)
+        if path.is_dir():
+            return path
+    raise IocError(
+        "STM32CubeMX MCU database not found. Pass --db <dir> pointing at CubeMX's db/mcu."
+    )
+
+
+def expand_variants(stem: str) -> set[str]:
+    """'STM32G0B1C(B-C-E)Tx' -> {STM32G0B1CBTx, STM32G0B1CCTx, STM32G0B1CETx}.
+
+    ST groups flash/package variants into one XML with a parenthesised alternation, because
+    the die is identical and only the marketing suffix differs. Resolving a part therefore
+    means expanding those groups, not pattern-matching around them.
+
+    The previous implementation globbed `f"{user[:9]}*{user[-3:]}*.xml"` for this, which
+    built `STM32G0B1*ETx*.xml` and matched nothing at all — the real filename contains
+    `E)Tx`, not `ETx`. It survived only because the exact-name branch shadowed it, so the
+    fallback was dead code that would fail the moment it was actually needed.
+    """
+    groups = re.findall(r"\(([^)]*)\)", stem)
+    if not groups:
+        return {stem}
+    literals = re.split(r"\([^)]*\)", stem)
+    out: set[str] = set()
+    for combo in itertools.product(*(g.split("-") for g in groups)):
+        pieces = [literals[0]]
+        for choice, literal in zip(combo, literals[1:]):
+            pieces.append(choice)
+            pieces.append(literal)
+        out.add("".join(pieces))
+    return out
+
+
+@functools.lru_cache(maxsize=8)
+def _variant_index(db: str) -> dict[str, str]:
+    """Every orderable part name -> the XML file that describes it."""
+    index: dict[str, str] = {}
+    for xml in Path(db).glob("STM32*.xml"):
+        for variant in expand_variants(xml.stem):
+            index.setdefault(variant, str(xml))
+    return index
+
+
+def resolve_part_xml(db: Path, part: str | None, mcu_name: str | None = None) -> Path:
+    """Locate the XML for a part.
+
+    `Mcu.Name` in the `.ioc` is already the variant string (e.g. `STM32G0B1C(B-C-E)Tx`), so
+    it hits the file directly. `Mcu.UserName` is the orderable part (`STM32G0B1CETx`) and
+    needs the expanded index.
+    """
+    if not part:
+        raise IocError("the .ioc names no MCU part (neither Mcu.UserName nor Mcu.Name)")
+    if mcu_name:
+        exact = db / f"{mcu_name}.xml"
+        if exact.is_file():
+            return exact
+
+    index = _variant_index(str(db))
+    if part in index:
+        return Path(index[part])
+
+    # Temperature/quality grades (STM32H745IIT6 vs ...IITx) are the same die; ST's DB only
+    # carries the 'x' form. Try it before giving up.
+    relaxed = re.sub(r"[36]$", "x", part)
+    if relaxed in index:
+        return Path(index[relaxed])
+
+    raise IocError(f"no MCU XML found for {part!r} in {db}")
+
+
+def _tag(root: ET.Element, name: str) -> str:
+    """`name` qualified with the document's default namespace, if it has one.
+
+    ST's files declare one, so the qualified form is what normally matches. A file without
+    it used to yield an empty pin table and an empty peripheral set — silently, which is
+    worse than an error: the alternate-function rule then skips while coverage reports it
+    as having run.
+    """
+    namespace = root.tag.split("}")[0].strip("{") if "}" in root.tag else ""
+    return f"{{{namespace}}}{name}" if namespace else name
+
+
+def _parse_xml(xml_path: str) -> ET.Element:
+    """Parse one MCU XML, turning a corrupt file into a controlled failure.
+
+    `ET.ParseError` is a SyntaxError, which nothing on the review path catches; one damaged
+    file in CubeMX's database would take the whole review down with a traceback.
+    """
+    try:
+        return ET.parse(xml_path).getroot()
+    except ET.ParseError as exc:
+        raise IocError(f"cannot parse MCU database file {xml_path}: {exc}") from exc
+
+
+@functools.lru_cache(maxsize=16)
+def _pin_table(xml_path: str) -> dict[str, tuple[str, ...]]:
+    """pin -> every signal it can carry. Keyed on the bare pin name.
+
+    ST writes `PC14-OSC32_IN` and `PA11/PA9`; a caller asking about `PC14` must still hit.
+    """
+    root = _parse_xml(xml_path)
+    signal_tag = _tag(root, "Signal")
+    table: dict[str, tuple[str, ...]] = {}
+    for element in root.iter(_tag(root, "Pin")):
+        name = element.get("Name")
+        if not name:
+            continue
+        base = re.split(r"[-/(]", name)[0]
+        signals = tuple(
+            s.get("Name", "") for s in element.iter(signal_tag) if s.get("Name")
+        )
+        table[base] = signals
+    return table
+
+
+def pin_signals(xml_path: Path, pin: str) -> tuple[str, ...]:
+    return _pin_table(str(xml_path)).get(pin.upper(), ())
+
+
+def alternate_function_table(xml_path: Path) -> dict[str, set[str]]:
+    return {pin: set(signals) for pin, signals in _pin_table(str(xml_path)).items()}
+
+
+@functools.lru_cache(maxsize=16)
+def part_peripherals(xml_path: str) -> frozenset[str]:
+    """Every peripheral instance the silicon has (from the IP list)."""
+    root = _parse_xml(xml_path)
+    return frozenset(
+        element.get("InstanceName", "")
+        for element in root.iter(_tag(root, "IP"))
+        if element.get("InstanceName")
+    )

pcba/parsers/ioc/reader.py

@@ -0,0 +1,182 @@
+"""Read STM32CubeMX `.ioc` files.
+
+The `.ioc` is CubeMX-owned and must never be hand-edited — but reading it is the fastest way
+to know what a project is actually configured to do, and to verify what a regeneration
+changed.
+
+stdlib only.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pcba.model.pinmap import McuConfig, PinAssignment
+
+CLOCK_PREFIXES = ("RCC.", "PWR.")
+
+
+class IocError(RuntimeError):
+    """A controlled failure while reading an `.ioc`."""
+
+
+def parse_ioc(path: Path) -> dict[str, str]:
+    """Read an `.ioc` as a flat key -> value map.
+
+    The format is INI-like but flat: one `key=value` per line, no sections. Duplicate keys
+    mean the file is corrupt (CubeMX never emits them), so that is an error rather than
+    silently keeping the last one.
+
+    CubeMX writes Java properties, which are ISO-8859-1 by definition, while editors and
+    other tools save UTF-8, with or without a byte-order mark, and CRLF line endings. UTF-8
+    is tried first and Latin-1 decodes any byte, so an umlaut in a project name degrades to
+    a readable value rather than an internal error.
+    """
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        raise IocError(f"cannot read {path}: {exc}") from exc
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        text = data.decode("latin-1")
+
+    values: dict[str, str] = {}
+    # Split on line breaks only: `str.splitlines()` also breaks on NEL (0x85) and other
+    # separators that a Latin-1 value may contain.
+    for number, raw in enumerate(re.split(r"\r\n|\r|\n", text), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise IocError(f"{path}:{number}: line without '='")
+        key, value = line.split("=", 1)
+        if key in values:
+            raise IocError(f"{path}:{number}: duplicate key {key}")
+        values[key] = value
+    return values
+
+
+def normalise_pin(name: str) -> str:
+    r"""Undo CubeMX's escaping in pin keys.
+
+    CubeMX writes remapped and dual-function pins with escapes, e.g.
+        PA11\ [PA9].GPIO_Label
+        PC14-OSC32_IN\ (PC14).Mode
+    A parser that does not undo this silently fails to match 'PA11' or 'PC14'.
+    """
+    return name.replace("\\ ", " ").replace("\\(", "(").replace("\\)", ")")
+
+
+def pin_name(key: str) -> str:
+    r"""'PA11\ [PA9].GPIO_Label' -> 'PA11'; 'PB5(JTDO/TRACESWO).Signal' -> 'PB5'."""
+    base = normalise_pin(key).split(".", 1)[0]
+    for separator in (" ", "-", "("):
+        if separator in base:
+            base = base.split(separator, 1)[0]
+    return base
+
+
+# The guard that makes `pins` mean pins.
+#
+# The obvious filter is `key.startswith("P")`, and it is wrong: CubeMX's own metadata keys
+# start with P too, so `ProjectManager.ProjectName` and `PinOutPanel.RotationAngle` get
+# reported as pins of the MCU. An engineer who sees `ProjectManager` in a pin table stops
+# believing the rest of the table, which is the whole product.
+#
+# Ports run A..K on most families; the STM32N6 skips L and M and continues with PN..PQ.
+# Dedicated pins (OTG1_HSDP, CSI_D0P) do not look like ports at all; `collect_pins` takes
+# them from the `.ioc`'s own `Mcu.PinN` list instead.
+_PIN_KEY = re.compile(r"^P[A-KN-Q]\d{1,2}(_C)?([\\ ()\[\]\-].*)?$")
+
+
+def listed_pins(values: dict[str, str]) -> frozenset[str]:
+    """Physical pins the `.ioc` itself lists under `Mcu.PinN`, virtual `VP_` pins excluded.
+
+    This is how dedicated pins such as OTG1_HSDP or CSI_D0P are recognised. Their names do
+    not look like port pins, so without the list a USB device configured on the internal
+    PHY reads as unassigned.
+    """
+    return frozenset(
+        normalise_pin(value) for key, value in values.items()
+        if re.fullmatch(r"Mcu\.Pin\d+", key) and not value.startswith("VP_")
+    )
+
+
+def is_pin_key(key: str, listed: frozenset[str] = frozenset()) -> bool:
+    """Does this `.ioc` key describe a physical pin?"""
+    if "." not in key:
+        return False
+    base = normalise_pin(key).split(".", 1)[0]
+    return bool(_PIN_KEY.match(base)) or base in listed
+
+
+def collect_pins(values: dict[str, str]) -> dict[str, dict[str, str]]:
+    """pin -> {Signal, GPIO_Label, Mode, ...}, only for pins that carry a signal."""
+    listed = listed_pins(values)
+    pins: dict[str, dict[str, str]] = {}
+    for key, value in values.items():
+        if not is_pin_key(key, listed):
+            continue
+        field = key.rsplit(".", 1)[1]
+        if field in ("GPIOParameters",):
+            continue
+        pins.setdefault(pin_name(key), {})[field] = value
+    return {pin: fields for pin, fields in pins.items() if fields}
+
+
+def peripherals(values: dict[str, str]) -> list[str]:
+    """The `Mcu.IPn` list — the fastest way to see what is switched on."""
+    found = [
+        value for key, value in values.items() if key.startswith("Mcu.IP") and key[6:].isdigit()
+    ]
+    return sorted(found)
+
+
+def clocks(values: dict[str, str]) -> dict[str, str]:
+    return {k: v for k, v in sorted(values.items()) if k.startswith(CLOCK_PREFIXES)}
+
+
+def part_name(values: dict[str, str]) -> str | None:
+    """The orderable part (`Mcu.UserName`), else the variant name, else None.
+
+    None rather than a placeholder string: a truthy placeholder used to satisfy every
+    `if part:` guard downstream, so discovery skipped the schematic fallback and the
+    schematic extractor crashed trying to derive a part family from "(unknown part)".
+    """
+    return values.get("Mcu.UserName") or values.get("Mcu.Name") or None
+
+
+def load(path: Path) -> McuConfig:
+    """Read an `.ioc` into the normalized model."""
+    values = parse_ioc(path)
+    listed = listed_pins(values)
+    signal_keys = {pin_name(key): key for key in values
+                   if is_pin_key(key, listed) and key.endswith(".Signal")}
+    assignments = {
+        pin: PinAssignment(
+            pin=pin,
+            signal=fields.get("Signal"),
+            label=fields.get("GPIO_Label"),
+            mode=fields.get("Mode"),
+            signal_key=signal_keys.get(pin),
+        )
+        for pin, fields in collect_pins(values).items()
+    }
+    return McuConfig(
+        part=part_name(values),
+        source=str(path),
+        assignments=assignments,
+        peripherals=tuple(peripherals(values)),
+        raw=values,
+    )
+
+
+def diff(before: dict[str, str], after: dict[str, str]) -> dict[str, list]:
+    """What a regeneration (or a GUI edit) actually changed."""
+    return {
+        "removed": sorted(set(before) - set(after)),
+        "added": sorted(set(after) - set(before)),
+        "changed": sorted(k for k in set(before) & set(after) if before[k] != after[k]),
+    }