enginehall 2.0.0__py3-none-any.whl

pcba/rules/cross_domain.py

@@ -0,0 +1,496 @@
+"""Cross-domain rules — where the schematic, the MCU config and the firmware disagree.
+
+This is the product. Every other rule here is a single-domain check that some other tool
+also does; these are the ones nothing else does, because nothing else reads all three
+artifacts at once.
+
+Precedence: **the schematic wins.** The board is fabricated from it. If the `.ioc` and the
+schematic disagree, the copper is already the way the schematic drew it and it is the
+firmware configuration that is wrong — not the other way round.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from pcba.model.finding import Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import Project, Resolution, is_power_pin
+from pcba.rules.locate import at_pin
+from pcba.rules.signals import compatible, normalize, peripheral_instance
+from pcba.rules import stm32
+
+
+def mcu_part_mismatch(project: Project) -> Iterator[Finding]:
+    """The schematic and CubeMX name different silicon, so pin comparisons are unsafe."""
+    if not (project.part_conflict and project.mcu and project.mcu.part):
+        return
+    actual, sheet = project.part_conflict
+    ioc_source = project.relative(project.mcu.source)
+    sheet_source = project.relative(sheet)
+    key = "Mcu.UserName" if project.mcu.raw.get("Mcu.UserName") else "Mcu.Name"
+    yield Finding(
+        rule_id="cross_domain.mcu.part_mismatch",
+        title="The schematic and MCU configuration name different MCU parts",
+        severity=Severity.ERROR,
+        domain=Domain.CROSS_DOMAIN,
+        location=Location(artifact=ioc_source, key=key),
+        evidence=(
+            Evidence(kind="ioc_part", value=f"{key}={project.mcu.part}", source=ioc_source),
+            Evidence(kind="schematic_part", value=actual, source=sheet_source),
+        ),
+        explanation=(
+            f"The CubeMX configuration names {project.mcu.part}, while a schematic MCU symbol "
+            f"names {actual}. These parts are not orderable variants of the same identifier."
+        ),
+        consequence=(
+            "Pin and peripheral comparisons cannot be trusted across different MCU parts; "
+            "those checks were skipped for this review."
+        ),
+        recommendation=(
+            "Select the matching schematic and CubeMX configuration for this board revision, "
+            "or correct the MCU selection in CubeMX and regenerate the configuration."
+        ),
+    )
+
+
+def schematic_signal_pins(project: Project) -> dict[str, list[tuple[str, object]]]:
+    """normalized signal -> every (pin, Pin) the schematic puts it on, by geometry."""
+    out: dict[str, list[tuple[str, object]]] = {}
+    for pin in project.schematic.pins.values():
+        if is_power_pin(pin.name) or pin.resolution in (Resolution.NONE, Resolution.AMBIGUOUS):
+            continue
+        signal = normalize(pin.net)
+        if signal:
+            out.setdefault(signal, []).append((pin.port_pin, pin))
+    return out
+
+
+def ioc_signal_pins(project: Project) -> dict[str, list[tuple[str, object]]]:
+    """normalized signal -> every (pin, PinAssignment) the .ioc puts it on."""
+    out: dict[str, list[tuple[str, object]]] = {}
+    for pin, assignment in project.mcu.assignments.items():
+        signal = normalize(assignment.signal)
+        if signal:
+            out.setdefault(signal, []).append((pin, assignment))
+    return out
+
+
+# What a configured placement found on the schematic pad it names. The first three are
+# comparisons; the rest are why no comparison was possible.
+COMPARED_AT_PIN = frozenset({"same_signal", "functional_net", "different_peripheral"})
+
+
+def pin_placements(project: Project) -> list[tuple[str, object, str, object, str]]:
+    """Every peripheral placement in the .ioc, set against the schematic pin on that pad.
+
+    Returns (pin, PinAssignment, normalized signal, schematic Pin or None, status).
+
+    Comparing by name alone compares nothing on a board whose nets carry functional names
+    (RMII_TXD0, WIFI_SPI_SCK, HSE_IN): neither side names the other's signal. Comparing by
+    pad does not depend on naming. A net that names a compatible peripheral signal agrees
+    (`same_signal`); a functional name is accepted as the wire for whatever the pad is
+    configured as (`functional_net`); a net naming a different peripheral disagrees
+    (`different_peripheral`).
+    """
+    if not (project.schematic and project.mcu) or project.part_conflict:
+        return []
+    by_pin = project.schematic.by_pin_name()
+    out = []
+    for port_pin, assignment in sorted(project.mcu.assignments.items()):
+        signal = normalize(assignment.signal)
+        if not signal:
+            continue
+        pin = by_pin.get(port_pin)
+        if pin is None:
+            status = "pin_not_in_schematic"
+        elif pin.resolution == Resolution.AMBIGUOUS:
+            status = "ambiguous_net"
+        elif not pin.net:
+            status = "unnamed_connection" if pin.connected else "unconnected_pin"
+        elif normalize(pin.net) == signal or compatible(pin.net, signal):
+            status = "same_signal"
+        elif peripheral_instance(pin.net):
+            status = "different_peripheral"
+        else:
+            status = "functional_net"
+        out.append((port_pin, assignment, signal, pin, status))
+    return out
+
+
+# A signal on several pins of one side has no single pin to compare. It is left out of the
+# comparison, never compared first-wins, and coverage lists it as ambiguous.
+def _schematic_signals(project: Project) -> dict[str, tuple[str, object]]:
+    return {s: pins[0] for s, pins in schematic_signal_pins(project).items() if len(pins) == 1}
+
+
+def _ioc_signals(project: Project) -> dict[str, tuple[str, object]]:
+    return {s: pins[0] for s, pins in ioc_signal_pins(project).items() if len(pins) == 1}
+
+
+def pin_mismatch(project: Project) -> Iterator[Finding]:
+    """The headline rule: the same signal on two different pins.
+
+    The schematic routes USART3_TX to PD8; the .ioc assigns it to PB10. One of them is
+    wrong, the board will be built from the schematic, and today nothing tells you before
+    the boards arrive.
+
+    Only signals that BOTH sides name are compared, so a GPIO the schematic calls
+    SENSOR_ENABLE and the .ioc leaves unlabelled produces nothing rather than a guess.
+    """
+    if not (project.schematic and project.mcu) or project.part_conflict:
+        return
+
+    schematic = _schematic_signals(project)
+    ioc = _ioc_signals(project)
+    ioc_source = project.relative(project.mcu.source)
+
+    for signal in sorted(set(schematic) & set(ioc)):
+        sch_pin, sch = schematic[signal]
+        ioc_pin, _ = ioc[signal]
+        if sch_pin == ioc_pin:
+            continue
+        yield Finding(
+            rule_id="cross_domain.pin.mismatch",
+            title=f"{signal} is on a different pin in the schematic than in the MCU config",
+            severity=Severity.ERROR,
+            domain=Domain.CROSS_DOMAIN,
+            location=at_pin(project, sch),
+            evidence=(
+                Evidence(
+                    kind="schematic_net",
+                    value=f"{sch_pin} (package pin {sch.package_pin}) carries net {sch.net!r}",
+                    source=project.relative(sch.sheet),
+                ),
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{ioc_pin}.Signal = {signal}",
+                    source=ioc_source,
+                ),
+            ),
+            explanation=(
+                f"The schematic routes {signal} to {sch_pin}, resolved from wire geometry. "
+                f"The MCU configuration assigns {signal} to {ioc_pin}."
+            ),
+            consequence=(
+                f"The board is fabricated from the schematic, so the signal will be on "
+                f"{sch_pin}. Firmware configured for {ioc_pin} will drive the wrong pad and "
+                f"the interface will not work on assembled hardware."
+            ),
+            recommendation=(
+                f"Decide which pin is intended. If the schematic is right, move {signal} to "
+                f"{sch_pin} in CubeMX and regenerate. If the config is right, the schematic "
+                f"needs an ECO before layout."
+            ),
+        )
+
+
+def pin_signal_conflict(project: Project) -> Iterator[Finding]:
+    """The schematic net on a pad names a different peripheral than the .ioc puts there.
+
+    The pad comparison's disagreeing case: PE6 carries net SPI2_MOSI while the .ioc gives
+    PE6 to I2C1_SDA. A net whose signal the .ioc places on another pin is left to
+    `pin_mismatch`, which already names both pins.
+    """
+    placements = pin_placements(project)
+    if not placements:
+        return
+    # Exactly the cases pin_mismatch reports: the net's signal on one pin of each side, and
+    # not the same pin. Anything else (a signal on several pins of a side) it skips, so the
+    # pad finding must stand.
+    schematic, ioc = _schematic_signals(project), _ioc_signals(project)
+    ioc_source = project.relative(project.mcu.source)
+    for port_pin, assignment, signal, pin, status in placements:
+        if status != "different_peripheral":
+            continue
+        net = normalize(pin.net)
+        if net in schematic and net in ioc and schematic[net][0] != ioc[net][0]:
+            continue
+        yield Finding(
+            rule_id="cross_domain.pin.signal_conflict",
+            title=f"{port_pin} carries net {pin.net} but the MCU config gives it to {signal}",
+            severity=Severity.WARNING,
+            domain=Domain.CROSS_DOMAIN,
+            location=at_pin(project, pin),
+            evidence=(
+                Evidence(
+                    kind="schematic_net",
+                    value=f"{port_pin} (package pin {pin.package_pin}) carries net {pin.net!r}",
+                    source=project.relative(pin.sheet),
+                ),
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{assignment.signal_key or port_pin + '.Signal'} = "
+                          f"{assignment.signal}",
+                    source=ioc_source,
+                ),
+            ),
+            explanation=(
+                f"The net on {port_pin} names {normalize(pin.net)}, a different peripheral "
+                f"signal than the {assignment.signal} the MCU configuration assigns to it."
+            ),
+            consequence=(
+                "Either the net label is wrong, or the firmware drives this pad as the wrong "
+                "peripheral and the interface will not work on the assembled board."
+            ),
+            recommendation=(
+                f"Rename the net if {port_pin} really carries {assignment.signal}; otherwise "
+                f"assign {normalize(pin.net)} to {port_pin} in CubeMX and regenerate."
+            ),
+        )
+
+
+# Above this fraction of the schematic's signals missing from the .ioc, the honest
+# conclusion is not "N pins need configuring" but "this .ioc does not describe this board".
+STUB_THRESHOLD = 0.5
+
+
+def pin_unconfigured(project: Project) -> Iterator[Finding]:
+    """The schematic routes a peripheral signal to a pin the .ioc never configures.
+
+    Collapses when the `.ioc` is clearly not a peer of the schematic. Measured on a real
+    design whose `.ioc` was still a hand-authored placeholder, the per-pin form emitted 65
+    findings — all individually true, and collectively worthless. They did not say "65 pins
+    need attention"; they said "this .ioc is a stub", 65 times, and buried 9 real errors
+    while doing it. One finding that names the actual problem beats 65 that imply the wrong
+    one.
+    """
+    if not (project.schematic and project.mcu) or project.part_conflict:
+        return
+
+    ioc = _ioc_signals(project)
+    schematic = _schematic_signals(project)
+    table = stm32.af_table(project)
+
+    missing = []
+    for signal, (sch_pin, sch) in sorted(schematic.items()):
+        if signal in ioc:
+            continue
+        assignment = project.mcu.assignments.get(sch_pin)
+        if assignment and normalize(assignment.signal):
+            continue  # the pin does something else; pin_mismatch or a human owns that
+        if table is not None and sch_pin in table and not table[sch_pin]:
+            # ST lists the pad with no configurable signal at all (OTG1_TXRTUNE, a
+            # calibration resistor pin). No .ioc can ever assign it, so it is never missing.
+            continue
+        missing.append((signal, sch_pin, sch))
+
+    if not missing:
+        return
+
+    mcu_name = project.mcu.part or "the MCU configuration"
+    ioc_source = project.relative(project.mcu.source)
+    if schematic and len(missing) / len(schematic) >= STUB_THRESHOLD:
+        names = ", ".join(s for s, _, _ in missing[:6])
+        yield Finding(
+            rule_id="cross_domain.mcu_config.incomplete",
+            title=(
+                f"The MCU configuration covers almost none of the schematic "
+                f"({len(schematic) - len(missing)} of {len(schematic)} signals)"
+            ),
+            severity=Severity.WARNING,
+            domain=Domain.CROSS_DOMAIN,
+            location=Location(artifact=ioc_source, key="Mcu"),
+            evidence=(
+                Evidence(
+                    kind="schematic_net",
+                    value=f"{len(schematic)} peripheral signals routed on the schematic",
+                    source=project.relative(project.schematic.source),
+                ),
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{len(missing)} of them are unassigned in {mcu_name}",
+                    source=ioc_source,
+                ),
+                Evidence(kind="schematic_net", value=f"unconfigured: {names}, …"),
+            ),
+            explanation=(
+                f"{len(missing)} of {len(schematic)} peripheral signals on the schematic have "
+                f"no assignment in {project.mcu.source}. At that proportion the configuration "
+                "is a placeholder, targets a different board, or belongs to a different "
+                "revision — rather than having a large number of individually missing pins."
+            ),
+            consequence=(
+                "Per-pin cross-checks cannot say anything useful until the configuration "
+                "describes this board, so this review is not yet covering the MCU config."
+            ),
+            recommendation=(
+                "Point --ioc at the configuration for this board, or generate the pin "
+                "assignment from the schematic before relying on cross-domain review."
+            ),
+        )
+        return
+
+    for signal, sch_pin, sch in missing:
+        yield Finding(
+            rule_id="cross_domain.pin.unconfigured",
+            title=f"{signal} is wired on the schematic but not configured on the MCU",
+            severity=Severity.WARNING,
+            domain=Domain.CROSS_DOMAIN,
+            location=at_pin(project, sch),
+            evidence=(
+                Evidence(
+                    kind="schematic_net",
+                    value=f"{sch_pin} carries net {sch.net!r}",
+                    source=project.relative(sch.sheet),
+                ),
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{sch_pin} is unassigned in {mcu_name}",
+                    source=ioc_source,
+                ),
+            ),
+            explanation=(
+                f"The schematic connects {signal} to {sch_pin}, but the MCU configuration "
+                f"leaves {sch_pin} unassigned."
+            ),
+            consequence=(
+                "The hardware exists but no firmware initialises it. The interface is dead "
+                "on the assembled board until the pin is configured."
+            ),
+            recommendation=(
+                f"Assign {sch_pin} to {signal} in CubeMX, or confirm the net is intentionally "
+                "unpopulated on this revision."
+            ),
+        )
+
+
+def peripheral_unconnected(project: Project) -> Iterator[Finding]:
+    """The .ioc configures a peripheral with no corresponding schematic connection.
+
+    Scoped to peripherals that need pins. A peripheral configured with every one of its pins
+    physically unconnected is either a leftover from a copied project or a feature nobody wired.
+    A wire need not have a peripheral-style net label to count as a connection.
+    """
+    if not (project.schematic and project.mcu) or project.part_conflict:
+        return
+
+    schematic_families = {
+        signal.split("_")[0] for signal in _schematic_signals(project)
+    }
+    schematic_pins = project.schematic.by_pin_name()
+    ioc_by_family: dict[str, list[str]] = {}
+    for signal, (pin, _) in _ioc_signals(project).items():
+        ioc_by_family.setdefault(signal.split("_")[0], []).append(pin)
+    ioc_source = project.relative(project.mcu.source)
+
+    for family, pins in sorted(ioc_by_family.items()):
+        if family in schematic_families or any(
+            schematic_pins.get(pin) and schematic_pins[pin].connected for pin in pins
+        ):
+            continue
+        yield Finding(
+            rule_id="cross_domain.peripheral.unconnected",
+            title=f"{family} is configured on the MCU but not connected on the schematic",
+            severity=Severity.WARNING,
+            domain=Domain.CROSS_DOMAIN,
+            location=Location(artifact=ioc_source, key=family),
+            evidence=(
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{family} configured on {', '.join(sorted(pins))}",
+                    source=ioc_source,
+                ),
+                Evidence(
+                    kind="schematic_net",
+                    value=f"none of {family}'s configured pads touches a schematic connection",
+                    source=project.relative(project.schematic.source),
+                ),
+            ),
+            explanation=(
+                f"The MCU configuration enables {family} and assigns pins to it, but none "
+                "of those pins touches a wire, component pin, or named net in the schematic."
+            ),
+            consequence=(
+                "Firmware will initialise a peripheral that goes nowhere. If those pads are "
+                "connected to something else on the board, driving them may conflict with it."
+            ),
+            recommendation=(
+                f"Remove {family} from the MCU configuration, or confirm the schematic is "
+                "incomplete for this revision."
+            ),
+        )
+
+
+def firmware_hardcoded_pin_drift(project: Project) -> Iterator[Finding]:
+    """Hand-written firmware names a pin the MCU config assigns to something else.
+
+    This is the drift that survives a regeneration. CubeMX rewrites `main.h` when a pin
+    moves, so generated code follows automatically — but a USER CODE block that spelled out
+    `GPIOD, GPIO_PIN_8` by hand does not. It keeps driving the old pad, and it still
+    compiles.
+    """
+    if not (project.firmware and project.mcu):
+        return
+
+    ioc_source = project.relative(project.mcu.source)
+    for pin, references in sorted(project.firmware.pins().items()):
+        # Reading a pin does not drive it. A wrapper or a pin table is not recognised as a
+        # read, so it still counts: dropping it would hide the drift this rule exists for.
+        references = [r for r in references if r.operation != "read"]
+        if not references:
+            continue
+        assignment = project.mcu.assignments.get(pin)
+        signal = assignment.signal if assignment else None
+        # A pin configured as plain GPIO is exactly what hand-written code should be
+        # touching. Only a pin owned by a peripheral is a conflict.
+        if not normalize(signal):
+            continue
+        first = references[0]
+        # The first three references, then one more per file not yet named: --changed-only
+        # keeps a finding only when its evidence names a changed file.
+        shown = references[:3]
+        for r in references[3:]:
+            if r.path not in {s.path for s in shown}:
+                shown.append(r)
+        yield Finding(
+            rule_id="cross_domain.firmware.hardcoded_pin_drift",
+            title=f"Firmware drives {pin} directly, but the MCU config gives it to {signal}",
+            severity=Severity.ERROR,
+            domain=Domain.CROSS_DOMAIN,
+            location=Location(artifact=project.relative(first.path), pin=pin, line=first.line),
+            # The first reference changes when another file that sorts earlier names the pin;
+            # the pin and its .ioc key do not, so a baseline entry keeps matching.
+            identity=Location(
+                artifact=ioc_source, pin=pin, key=assignment.signal_key or f"{pin}.Signal"
+            ),
+            evidence=tuple(
+                Evidence(
+                    kind="firmware_reference",
+                    value=r.text,
+                    source=f"{project.relative(r.path)}:{r.line}",
+                )
+                for r in shown
+            )
+            + (
+                Evidence(
+                    kind="ioc_assignment",
+                    value=f"{pin}.Signal = {signal}",
+                    source=ioc_source,
+                ),
+            ),
+            explanation=(
+                f"{len(references)} hand-written reference(s) address {pin} directly as a "
+                f"GPIO, but the MCU configuration assigns {pin} to {signal}. Because the "
+                f"reference is hardcoded rather than using CubeMX's generated define, it did "
+                f"not move when the pin did."
+            ),
+            consequence=(
+                f"The code reconfigures or drives a pad owned by {signal}, corrupting that "
+                "peripheral at runtime. It compiles cleanly, so this only shows up on hardware."
+            ),
+            recommendation=(
+                f"Use the generated `<label>_GPIO_Port` / `<label>_Pin` defines instead of "
+                f"naming {pin} directly, or move {signal} off {pin} if the hand-written code "
+                "is correct."
+            ),
+        )
+
+
+RULES = (
+    mcu_part_mismatch,
+    pin_mismatch,
+    pin_signal_conflict,
+    pin_unconfigured,
+    peripheral_unconnected,
+    firmware_hardcoded_pin_drift,
+)