pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/backends/pyocd_backend.py

@@ -0,0 +1,271 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Probes and targets through pyOCD.
+
+Kept thin on purpose: each method is the pyOCD call that does it, with the
+exception said again in pyflashgui's words. Anything worth testing without a
+probe plugged in is in ``core`` or in the base class, and what is left here
+can only be tried on hardware.
+
+pyOCD is imported inside the methods that use it. It is the slowest thing
+pyflashgui loads, and a window should not wait for it to say which probes
+are plugged in before it can be drawn.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pyflashgui.backends.base import (
+    ERASE_CHIP,
+    ERASE_SECTORS,
+    Backend,
+    BackendError,
+    Connection,
+    ProbeInfo,
+    Progress,
+    TargetInfo,
+    _nothing,
+)
+from pyflashgui.core.images import Segment
+from pyflashgui.core.memory_map import FLASH, OTHER, RAM, ROM, Region
+
+#: What pyOCD's loader calls the two ways of erasing.
+_CHIP_ERASE = {ERASE_SECTORS: "sector", ERASE_CHIP: "chip"}
+
+
+def _kind(region) -> str:
+    """One of pyflashgui's kinds of memory, for one of pyOCD's regions."""
+    if region.is_flash:
+        return FLASH
+    if region.is_ram:
+        return RAM
+    if region.is_rom:
+        return ROM
+    return OTHER
+
+
+def regions_of(memory_map) -> list[Region]:
+    """A pyOCD memory map as pyflashgui's own regions, lowest address first."""
+    out = []
+    for region in memory_map:
+        alias = region.alias
+        out.append(
+            Region(
+                name=region.name,
+                start=region.start,
+                length=region.length,
+                kind=_kind(region),
+                # pyOCD's "blocksize" is what is erased at a time, for flash.
+                sector_size=int(getattr(region, "blocksize", 0) or 0) if region.is_flash else 0,
+                page_size=int(getattr(region, "page_size", 0) or 0) if region.is_flash else 0,
+                # An alias is given as the region itself, or as its name.
+                alias_of=getattr(alias, "name", alias) or "",
+            )
+        )
+    return sorted(out, key=lambda r: r.start)
+
+
+def needs_one_packet_at_a_time(*names: str | None) -> bool:
+    """Whether a probe called this must be sent one command and then waited for.
+
+    pyOCD's own advice for the TI XDS110, whose firmware loses track when
+    several commands are outstanding. Set for every one of them, since it
+    is not known which versions are free of it, and the cost is only speed.
+    """
+    return any("xds110" in (name or "").lower() for name in names)
+
+
+def _said(doing: str, exc: Exception) -> BackendError:
+    """A library's exception as a sentence about what was being attempted."""
+    detail = str(exc).strip() or type(exc).__name__
+    return BackendError(f"{doing} failed: {detail}")
+
+
+class PyocdConnection(Connection):
+    def __init__(self, session) -> None:
+        self._session = session
+
+    def _target(self):
+        if self._session is None:
+            raise BackendError("This connection has been closed.")
+        return self._session.target
+
+    def regions(self) -> list[Region]:
+        return regions_of(self._target().memory_map)
+
+    def erase_chip(self) -> None:
+        from pyocd.flash.eraser import FlashEraser
+
+        self._target()
+        try:
+            FlashEraser(self._session, FlashEraser.Mode.CHIP).erase()
+        except Exception as exc:
+            raise _said("Erasing the flash", exc) from exc
+
+    def erase_ranges(self, ranges: Sequence[tuple[int, int]]) -> None:
+        from pyocd.flash.eraser import FlashEraser
+
+        flash = [r for r in self.regions() if r.kind == FLASH and not r.alias_of]
+        for start, length in ranges:
+            # Checked here: asked to erase what is not flash, pyOCD stops
+            # with a line in its own log and no error, having erased
+            # nothing, and that would be reported as done.
+            if not any(r.start <= start and start + length <= r.end for r in flash):
+                raise BackendError(
+                    f"{start:08X} to {start + length - 1:08X} is not all within one "
+                    "region of the target's flash."
+                )
+        try:
+            # pyOCD takes where each range starts and where it stops.
+            FlashEraser(self._session, FlashEraser.Mode.SECTOR).erase(
+                [(start, start + length) for start, length in ranges]
+            )
+        except Exception as exc:
+            raise _said("Erasing the flash", exc) from exc
+
+    def program(
+        self,
+        segments: Sequence[Segment],
+        erase: str = ERASE_SECTORS,
+        progress: Progress = _nothing,
+    ) -> None:
+        from pyocd.flash.loader import MemoryLoader
+
+        self._target()
+        if erase not in _CHIP_ERASE:
+            raise BackendError(f"There is no way of erasing called {erase!r}.")
+        try:
+            # smart_flash off: with it, pyOCD reads the flash first and
+            # leaves alone a page it judges unchanged. Every byte in the file
+            # is written here, and verifying afterwards says whether it took.
+            loader = MemoryLoader(
+                self._session,
+                progress=progress,
+                chip_erase=_CHIP_ERASE[erase],
+                smart_flash=False,
+            )
+            for segment in segments:
+                loader.add_data(segment.address, segment.data)
+            loader.commit()
+        except Exception as exc:
+            raise _said("Programming", exc) from exc
+
+    def read(self, address: int, length: int) -> bytes:
+        target = self._target()
+        try:
+            return bytes(target.read_memory_block8(address, length))
+        except Exception as exc:
+            raise _said(f"Reading {length} bytes at {address:08X}", exc) from exc
+
+    def reset(self, halt: bool = False) -> None:
+        target = self._target()
+        try:
+            if halt:
+                target.reset_and_halt()
+            else:
+                target.reset()
+        except Exception as exc:
+            raise _said("Resetting the target", exc) from exc
+
+    def close(self) -> None:
+        session, self._session = self._session, None
+        if session is not None:
+            try:
+                session.close()
+            except Exception as exc:
+                raise _said("Disconnecting", exc) from exc
+
+
+class PyocdBackend(Backend):
+    name = "pyocd"
+    label = "pyOCD"
+
+    def probes(self) -> list[ProbeInfo]:
+        from pyocd.core.helpers import ConnectHelper
+
+        try:
+            found = ConnectHelper.get_all_connected_probes(blocking=False)
+        except Exception as exc:
+            raise _said("Looking for probes", exc) from exc
+        return [
+            ProbeInfo(
+                unique_id=probe.unique_id,
+                description=probe.description,
+                vendor=probe.vendor_name or "",
+                product=probe.product_name or "",
+            )
+            for probe in found
+        ]
+
+    def targets(self) -> list[TargetInfo]:
+        from pyocd.target import TARGET
+
+        out = [
+            TargetInfo(name, vendor=getattr(cls, "VENDOR", "") or "", source="built in")
+            for name, cls in TARGET.items()
+        ]
+        seen = {t.name for t in out}
+        for device in self._pack_devices():
+            name = device.part_number.lower()
+            if name not in seen:
+                seen.add(name)
+                out.append(TargetInfo(name, vendor=device.vendor or "", source="pack"))
+        return sorted(out, key=lambda t: t.name)
+
+    @staticmethod
+    def _pack_devices() -> list:
+        """The devices in the CMSIS-Packs installed here. None is not a fault."""
+        try:
+            from pyocd.target.pack.pack_target import ManagedPacks
+
+            return list(ManagedPacks.get_installed_targets())
+        except Exception:
+            # A pack index that is missing or damaged must not cost the
+            # built-in targets, which need no pack at all.
+            return []
+
+    def regions(self, target: str) -> list[Region]:
+        from pyocd.target import TARGET
+
+        cls = TARGET.get(target.lower())
+        memory_map = getattr(cls, "MEMORY_MAP", None)
+        # A built-in target carries its memory map on the class. A pack's is
+        # read from the pack as the target is made, which needs a connection.
+        return regions_of(memory_map) if memory_map is not None else []
+
+    def connect(
+        self,
+        probe: str,
+        target: str,
+        frequency: int | None = None,
+        interface: str | None = None,
+    ) -> Connection:
+        from pyocd.core.helpers import ConnectHelper
+        from pyocd.core.session import Session
+
+        try:
+            found = ConnectHelper.get_all_connected_probes(blocking=False, unique_id=probe)
+        except Exception as exc:
+            raise _said("Looking for the probe", exc) from exc
+        # Asked for by the whole id. pyOCD matches any id that *contains*
+        # what it is given, and given two would ask on a console which was
+        # meant -- a console pyflashgui does not have.
+        chosen = next((p for p in found if p.unique_id == probe), None)
+        if chosen is None:
+            raise BackendError(f"The probe {probe} is not plugged in.")
+        options: dict = {
+            "target_override": target,
+            # pyflashgui reports progress itself, through the callback.
+            "hide_programming_progress": True,
+        }
+        if frequency is not None:
+            options["frequency"] = int(frequency)
+        if needs_one_packet_at_a_time(chosen.description, chosen.product_name):
+            options["cmsis_dap.limit_packets"] = True
+        try:
+            session = Session(chosen, auto_open=False, options=options)
+            session.open()
+        except Exception as exc:
+            raise _said(f"Connecting to {target}", exc) from exc
+        return PyocdConnection(session)

pyflashgui/backends/simulated.py

@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""A probe and a target that exist only in memory.
+
+For the tests, which cannot have a board plugged in, and for working on
+pyflashgui at a desk with no hardware on it. It behaves as flash does where
+that matters to what is built on it: erased flash reads as FF, a sector is
+erased whole, and bytes can only be put where the target has memory.
+
+What is programmed stays for as long as the backend object does, so that a
+second connection to the same probe finds what the first one wrote -- as a
+board keeps its flash between one connection and the next.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pyflashgui.backends.base import (
+    ERASE_CHIP,
+    ERASE_SECTORS,
+    Backend,
+    BackendError,
+    Connection,
+    ProbeInfo,
+    Progress,
+    TargetInfo,
+    _nothing,
+)
+from pyflashgui.core.images import Segment
+from pyflashgui.core.memory_map import FLASH, RAM, Region, region_at
+
+ERASED = 0xFF
+
+PROBES = (
+    ProbeInfo("SIM0001", "Simulated probe 1", vendor="pyflashgui", product="Simulated probe"),
+    ProbeInfo("SIM0002", "Simulated probe 2", vendor="pyflashgui", product="Simulated probe"),
+)
+
+#: The targets, and the memory of each. Sizes chosen to be awkward in the
+#: ways real parts are: one with a single flash, one with two that do not
+#: touch and have different sector sizes.
+TARGETS: dict[str, tuple[Region, ...]] = {
+    "sim_single": (
+        Region("flash", 0x0800_0000, 0x4_0000, FLASH, sector_size=0x1000, page_size=0x100),
+        Region("ram", 0x2000_0000, 0x1_0000, RAM),
+    ),
+    "sim_dual": (
+        Region("boot", 0x0000_0000, 0x8000, FLASH, sector_size=0x400, page_size=0x100),
+        Region("application", 0x1000_0000, 0x10_0000, FLASH, sector_size=0x1000, page_size=0x100),
+        Region(
+            "application_mirror",
+            0x1100_0000,
+            0x10_0000,
+            "rom",
+            alias_of="application",
+        ),
+        Region("ram", 0x2000_0000, 0x2_0000, RAM),
+    ),
+}
+
+
+class _Board:
+    """What is on the end of one simulated probe: a target and its memory."""
+
+    def __init__(self, target: str) -> None:
+        self.target = target
+        self.regions = TARGETS[target]
+        self.memory = {
+            r.name: bytearray([ERASED if r.kind == FLASH else 0]) * r.length
+            for r in self.regions
+            if not r.alias_of
+        }
+        self.resets = 0
+
+    def storage(self, region: Region) -> bytearray:
+        """The bytes behind a region, which for an alias are another's."""
+        return self.memory[region.alias_of or region.name]
+
+
+class SimulatedConnection(Connection):
+    def __init__(self, backend: SimulatedBackend, probe: str, board: _Board) -> None:
+        self._backend = backend
+        self._probe = probe
+        self._board: _Board | None = board
+
+    def _open(self) -> _Board:
+        if self._board is None:
+            raise BackendError("This connection has been closed.")
+        return self._board
+
+    def regions(self) -> list[Region]:
+        return list(self._open().regions)
+
+    def erase_chip(self) -> None:
+        board = self._open()
+        for region in board.regions:
+            if region.kind == FLASH and not region.alias_of:
+                board.memory[region.name][:] = bytes([ERASED]) * region.length
+
+    def erase_ranges(self, ranges: Sequence[tuple[int, int]]) -> None:
+        board = self._open()
+        # Everything is placed before anything is erased, so that a range
+        # that is not flash leaves the target as it was.
+        placed = [self._place(board, start, length) for start, length in ranges]
+        for runs in placed:
+            for region, _offset, _length in runs:
+                if region.kind != FLASH:
+                    raise BackendError(f"{region.name} is not flash, and cannot be erased.")
+        for runs in placed:
+            for region, offset, length in runs:
+                size = region.sector_size
+                start = offset // size * size
+                stop = -(-(offset + length) // size) * size
+                board.memory[region.name][start:stop] = bytes([ERASED]) * (stop - start)
+
+    def _place(self, board: _Board, address: int, length: int) -> list[tuple[Region, int, int]]:
+        """A run of bytes as (region, offset in it, length), region by region."""
+        out = []
+        end = address + length
+        while address < end:
+            region = region_at(board.regions, address)
+            if region is None:
+                raise BackendError(f"The target has no memory at {address:08X}.")
+            if region.alias_of or region.kind not in (FLASH, RAM):
+                raise BackendError(f"{address:08X} is in {region.name}, which cannot be written.")
+            stop = min(end, region.end)
+            out.append((region, address - region.start, stop - address))
+            address = stop
+        return out
+
+    def program(
+        self,
+        segments: Sequence[Segment],
+        erase: str = ERASE_SECTORS,
+        progress: Progress = _nothing,
+    ) -> None:
+        board = self._open()
+        if erase not in (ERASE_SECTORS, ERASE_CHIP):
+            raise BackendError(f"There is no way of erasing called {erase!r}.")
+        # Everything is placed before anything is changed, so that a file
+        # that does not fit leaves the target as it was.
+        placed = [(s, self._place(board, s.address, len(s))) for s in segments]
+        if erase == ERASE_CHIP:
+            self.erase_chip()
+        else:
+            for _segment, runs in placed:
+                for region, offset, length in runs:
+                    if region.kind != FLASH:
+                        continue
+                    size = region.sector_size
+                    start = offset // size * size
+                    stop = -(-(offset + length) // size) * size
+                    board.memory[region.name][start:stop] = bytes([ERASED]) * (stop - start)
+        total = sum(len(s) for s in segments)
+        done = 0
+        for segment, runs in placed:
+            position = 0
+            for region, offset, length in runs:
+                data = segment.data[position : position + length]
+                board.memory[region.name][offset : offset + length] = data
+                position += length
+                done += length
+                progress(done / total)
+
+    def read(self, address: int, length: int) -> bytes:
+        board = self._open()
+        out = bytearray()
+        end = address + length
+        while address < end:
+            region = region_at(board.regions, address)
+            if region is None:
+                raise BackendError(f"The target has no memory at {address:08X}.")
+            stop = min(end, region.end)
+            offset = address - region.start
+            out += board.storage(region)[offset : offset + stop - address]
+            address = stop
+        return bytes(out)
+
+    def reset(self, halt: bool = False) -> None:
+        board = self._open()
+        board.resets += 1
+        # What a reset does to RAM on a real part is nothing anybody should
+        # rely on. Cleared here, so that relying on it shows up.
+        for region in board.regions:
+            if region.kind == RAM:
+                board.memory[region.name][:] = bytes(region.length)
+
+    def close(self) -> None:
+        if self._board is not None:
+            self._board = None
+            self._backend._released(self._probe)
+
+
+class SimulatedBackend(Backend):
+    name = "simulated"
+    label = "Simulated"
+
+    def __init__(self) -> None:
+        #: Probe id -> what it is attached to. Made when first connected to,
+        #: and kept, so that flash outlives a connection.
+        self._boards: dict[str, _Board] = {}
+        self._in_use: set[str] = set()
+
+    def probes(self) -> list[ProbeInfo]:
+        return list(PROBES)
+
+    def targets(self) -> list[TargetInfo]:
+        return [TargetInfo(name, vendor="pyflashgui", source="built in") for name in TARGETS]
+
+    def regions(self, target: str) -> list[Region]:
+        return list(TARGETS.get(target, ()))
+
+    def connect(
+        self,
+        probe: str,
+        target: str,
+        frequency: int | None = None,
+        interface: str | None = None,
+    ) -> Connection:
+        if probe not in {p.unique_id for p in PROBES}:
+            raise BackendError(f"There is no probe with the id {probe}.")
+        if target not in TARGETS:
+            raise BackendError(f"{target} is not a target the simulated backend has.")
+        if probe in self._in_use:
+            raise BackendError(f"Probe {probe} is already connected.")
+        board = self._boards.get(probe)
+        if board is None or board.target != target:
+            # A different target on the same probe is a different board
+            # plugged in, with nothing of the last one's on it.
+            board = self._boards[probe] = _Board(target)
+        self._in_use.add(probe)
+        return SimulatedConnection(self, probe, board)
+
+    def _released(self, probe: str) -> None:
+        self._in_use.discard(probe)
+
+    def board(self, probe: str) -> _Board | None:
+        """What is on the end of a probe, for a test to look at or tamper with."""
+        return self._boards.get(probe)

pyflashgui/core/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg

pyflashgui/core/checkout.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Which commit a source checkout is running, for a report to name.
+
+The version number is the same for every build between two releases, which is
+no use when somebody is running what they pulled this morning: "it does X" and
+"it did X yesterday" are the same sentence about two different programs. A
+checkout knows exactly what it is, and the answer is in ``.git`` for the
+reading.
+
+Read from the files rather than by running ``git``: the launcher starts
+pythonw, so a subprocess would flash a console window on Windows, it would be
+a process start on the way to the first window, and a frozen build has no git
+to run. Reading two small files costs nothing and works the same everywhere.
+
+Nothing here reports whether the working tree has been edited. That needs the
+index compared against the files, which is what git is for; the commit is what
+somebody needs to tell one build from another.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: Enough of a hash to be unambiguous in any repository this size, and short
+#: enough to be read out over a telephone.
+SHORT = 7
+
+
+def _git_dir(root: Path) -> Path | None:
+    """The .git directory, which for a worktree is a file pointing at one."""
+    git = root / ".git"
+    if git.is_dir():
+        return git
+    if git.is_file():
+        # A linked worktree: ".git" holds "gitdir: <path>".
+        try:
+            said = git.read_text(encoding="utf-8").strip()
+        except OSError:
+            return None
+        if said.startswith("gitdir:"):
+            where = Path(said.split(":", 1)[1].strip())
+            if not where.is_absolute():
+                where = (root / where).resolve()
+            return where if where.is_dir() else None
+    return None
+
+
+def _packed(git: Path, ref: str) -> str | None:
+    """A ref that has been packed away, which is where an old branch ends up."""
+    try:
+        lines = (git / "packed-refs").read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+    for line in lines:
+        if line.startswith("#") or line.startswith("^"):
+            continue
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == ref:
+            return parts[0]
+    return None
+
+
+def _resolve(git: Path, ref: str) -> str | None:
+    """A ref's commit: the loose file first, because packed can be stale."""
+    loose = git / ref
+    try:
+        if loose.is_file():
+            return loose.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+    return _packed(git, ref)
+
+
+def _tag_for(git: Path, commit: str) -> str | None:
+    """A tag pointing at this commit, if one does: that is the better name."""
+    tags = git / "refs" / "tags"
+    if tags.is_dir():
+        for path in sorted(tags.rglob("*")):
+            try:
+                if path.is_file() and path.read_text(encoding="utf-8").strip() == commit:
+                    return path.name
+            except OSError:
+                continue
+    try:
+        lines = (git / "packed-refs").read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+    for line in lines:
+        parts = line.split()
+        if len(parts) == 2 and parts[1].startswith("refs/tags/") and parts[0] == commit:
+            return parts[1][len("refs/tags/") :]
+    return None
+
+
+def head(root: Path | None = None) -> tuple[str | None, str] | None:
+    """(branch, full commit) this checkout is on, or None outside a checkout.
+
+    The branch is None when the checkout is on a commit rather than
+    following a branch -- a tag, or an old commit checked out.
+    """
+    root = Path(__file__).resolve().parents[2] if root is None else Path(root)
+    git = _git_dir(root)
+    if git is None:
+        return None
+    try:
+        said = (git / "HEAD").read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if said.startswith("ref:"):
+        ref = said.split(":", 1)[1].strip()
+        commit = _resolve(git, ref)
+        branch = ref.removeprefix("refs/heads/")
+    else:
+        commit, branch = said, None
+    return (branch, commit) if commit else None
+
+
+def describe(root: Path | None = None) -> str | None:
+    """The branch or tag and the short hash, or None outside a checkout.
+
+    None is the ordinary answer for an installed or frozen build, which has
+    no repository to ask and a version number that means something anyway.
+    """
+    root = Path(__file__).resolve().parents[2] if root is None else Path(root)
+    if (found := head(root)) is None:
+        return None
+    branch, commit = found
+    git = _git_dir(root)
+    tag = _tag_for(git, commit) if git is not None else None
+    # Detached: sitting on a commit rather than following a branch, which is
+    # what checking out a tag or an old commit leaves.
+    name = tag or (branch.rsplit("/", 1)[-1] if branch else "detached")
+    return f"{name} {commit[:SHORT]}"