pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/core/flasher.py

@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""The one thing in the window that talks to a backend.
+
+Every call to a backend blocks, and programming blocks for as long as it
+takes, so none of them is made from the GUI thread. They are queued on one
+worker and run one at a time, which is also what a probe wants: it is one
+piece of hardware and does one thing at a time.
+
+What comes back arrives as signals, on the GUI thread, and as lines in the
+Event Log. A pane asks for something to be done and listens; it never holds a
+connection of its own, so two panes cannot be talking to the same probe.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from PySide6.QtCore import QObject, Signal
+
+from pyflashgui import backends
+from pyflashgui.backends.base import (
+    ERASE_SECTORS,
+    Backend,
+    BackendError,
+    CancelledError,
+    Connection,
+    Verification,
+)
+from pyflashgui.core.events import EventLog
+from pyflashgui.core.images import Image, Segment
+from pyflashgui.core.memory_map import Region
+from pyflashgui.core.worker import Worker
+
+#: Progress is passed on when it has moved this far, and not otherwise: a
+#: library reporting every page would otherwise queue a thousand signals to
+#: move a bar a thousand times by less than a pixel.
+PROGRESS_STEP = 0.01
+
+
+def size_text(count: int) -> str:
+    """A number of bytes as somebody would say it: 512 bytes, 12.5 KiB, 2.0 MiB."""
+    if count < 1024:
+        return "1 byte" if count == 1 else f"{count} bytes"
+    if count < 1024 * 1024:
+        return f"{count / 1024:.1f} KiB"
+    return f"{count / (1024 * 1024):.1f} MiB"
+
+
+def verification_text(result: Verification) -> str:
+    """What verifying found, in a sentence."""
+    if result.ok:
+        return f"Verified: {size_text(result.checked)} match the files."
+    address, wanted, found = result.first
+    count = "1 byte differs" if result.different == 1 else f"{result.different} bytes differ"
+    return (
+        f"Verify failed: {count} of {result.checked}. The first is at {address:08X}, "
+        f"where the file has {wanted:02X} and the target has {found:02X}."
+    )
+
+
+class Flasher(QObject):
+    #: The probes plugged in, as a list of ProbeInfo, after ``refresh_probes``.
+    probes_changed = Signal(list)
+    #: The targets the backend has, as a list of TargetInfo.
+    targets_changed = Signal(list)
+    #: Connected, or not any more.
+    connection_changed = Signal(bool)
+    #: Something is being done, or has finished. Nothing else can be asked
+    #: for in between.
+    busy_changed = Signal(bool)
+    #: What is being done, and how far along it is from 0.0 to 1.0.
+    progress = Signal(str, float)
+    #: The memory of the target in question is known, or has changed.
+    regions_changed = Signal()
+    #: An operation ended: its name, and whether it did what was asked.
+    finished = Signal(str, bool)
+    #: Memory was read from a target: where it starts, the bytes, and the
+    #: target they came from.
+    memory_read = Signal(int, bytes, str)
+
+    def __init__(
+        self,
+        events: EventLog,
+        backend: str = backends.DEFAULT,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.events = events
+        self.backend: Backend = backends.get(backend)
+        self.connection: Connection | None = None
+        #: What is connected to, while something is: the target's name and
+        #: the probe's id.
+        self.target = ""
+        self.probe = ""
+        #: The memory of the target last asked about, connected or not.
+        self.regions: list[Region] = []
+        self._regions_for = ""
+        self.busy = False
+        self._cancel = threading.Event()
+        self._worker = Worker(self)
+        self._last_progress = -1.0
+        self._shut = False
+
+    # --- running things --------------------------------------------------------------
+    @property
+    def connected(self) -> bool:
+        return self.connection is not None
+
+    def _run(
+        self,
+        name: str,
+        work: Callable[[], Any],
+        done: Callable[[Any], None],
+        quiet: bool = False,
+    ) -> bool:
+        """Queue ``work`` for the worker, and ``done`` for its result.
+
+        ``quiet`` is for looking things up, which is not something being done
+        to a target: it does not mark the flasher busy, so the buttons stay
+        as they are, and it may be asked for while something else runs.
+        Returns False, having said why, if it could not be started.
+        """
+        if not quiet:
+            if self.busy:
+                self.events.warning(f"{name} was not started: something else is still running.")
+                return False
+            self._set_busy(True)
+            self._cancel.clear()
+            self._last_progress = -1.0
+
+        def job() -> tuple[Any, str | None, bool]:
+            # A backend's own error is a sentence already and is passed on as
+            # one. Anything else is a fault in pyflashgui or in a library,
+            # and says what kind it was.
+            try:
+                return work(), None, False
+            except CancelledError as exc:
+                return None, str(exc), True
+            except BackendError as exc:
+                return None, str(exc), False
+
+        def deliver(result, error: str | None) -> None:
+            cancelled = False
+            if error is None:
+                result, error, cancelled = result
+            if not quiet:
+                self._set_busy(False)
+            if error is not None:
+                (self.events.warning if cancelled else self.events.error)(error)
+                if not quiet:
+                    self.finished.emit(name, False)
+                return
+            ok = done(result)
+            if not quiet:
+                self.finished.emit(name, ok is not False)
+
+        self._worker.submit(job, deliver)
+        return True
+
+    def _set_busy(self, busy: bool) -> None:
+        if busy != self.busy:
+            self.busy = busy
+            self.busy_changed.emit(busy)
+
+    def _progress(self, label: str) -> Callable[[float], None]:
+        """A progress callback for the worker thread, saying this is what is done.
+
+        Emitting a signal from another thread is the one thing here that is
+        safe to do from it: Qt queues it for the GUI thread.
+        """
+
+        def report(fraction: float) -> None:
+            fraction = max(0.0, min(1.0, float(fraction)))
+            if fraction >= 1.0 or fraction - self._last_progress >= PROGRESS_STEP:
+                self._last_progress = fraction if fraction < 1.0 else -1.0
+                self.progress.emit(label, fraction)
+
+        return report
+
+    def cancel(self) -> None:
+        """Ask whatever is running to stop, if it is something that can."""
+        self._cancel.set()
+
+    # --- what is there ---------------------------------------------------------------
+    def set_backend(self, name: str) -> None:
+        """Use another backend. Whatever was connected is let go of first."""
+        if name == self.backend.name:
+            return
+        if self.connected:
+            self.disconnect()
+        self.backend = backends.get(name)
+        self.regions, self._regions_for = [], ""
+        self.regions_changed.emit()
+        self.refresh_targets()
+        self.refresh_probes()
+
+    def refresh_probes(self) -> None:
+        backend = self.backend
+        self._run("Looking for probes", backend.probes, self.probes_changed.emit, quiet=True)
+
+    def refresh_targets(self) -> None:
+        backend = self.backend
+        self._run("Listing targets", backend.targets, self.targets_changed.emit, quiet=True)
+
+    def set_target(self, target: str) -> None:
+        """Find out the memory of this target, as far as can be told unconnected."""
+        if self.connected or target == self._regions_for:
+            return
+        self._regions_for = target
+        backend = self.backend
+
+        def known(regions: list[Region]) -> None:
+            # Asked for and answered on different turns of the loop: a
+            # target picked since, or a connection made, has the say.
+            if not self.connected and self._regions_for == target:
+                self.regions = regions
+                self.regions_changed.emit()
+
+        self._run("Reading the target's memory map", lambda: backend.regions(target), known, True)
+
+    # --- connecting ------------------------------------------------------------------
+    def connect_to(
+        self,
+        probe: str,
+        target: str,
+        frequency: int | None = None,
+        interface: str | None = None,
+    ) -> None:
+        backend = self.backend
+
+        def work() -> tuple[Connection, list[Region]]:
+            connection = backend.connect(probe, target, frequency, interface)
+            try:
+                return connection, connection.regions()
+            except Exception:
+                connection.close()
+                raise
+
+        def done(result: tuple[Connection, list[Region]]) -> None:
+            self.connection, self.regions = result
+            self.probe, self.target = probe, target
+            self._regions_for = target
+            self.events.good(f"Connected to {target} through probe {probe}.")
+            self.connection_changed.emit(True)
+            self.regions_changed.emit()
+
+        if not self._run(f"Connecting to {target}", work, done):
+            return
+        self.events.information(f"Connecting to {target} through probe {probe}...")
+
+    def disconnect(self) -> None:
+        connection, self.connection = self.connection, None
+        if connection is None:
+            return
+        target = self.target
+        self.connection_changed.emit(False)
+        self._run(
+            "Disconnecting",
+            connection.close,
+            lambda _r: self.events.information(f"Disconnected from {target}."),
+            quiet=True,
+        )
+
+    def _connection(self, name: str) -> Connection | None:
+        if self.connection is None:
+            self.events.warning(f"{name} needs a probe connected to a target first.")
+        return self.connection
+
+    # --- what is done to a target ----------------------------------------------------
+    def erase(self, ranges: Sequence[tuple[int, int]] | None = None) -> None:
+        """Erase all of the target's flash, or these stretches of it.
+
+        Each of ``ranges`` is an address and a length.
+        """
+        if (connection := self._connection("Erasing")) is None:
+            return
+        target = self.target
+        started = time.monotonic()
+        if ranges is None:
+            what = f"all of the flash of {target}"
+            work = connection.erase_chip
+        else:
+            asked = list(ranges)
+            what = ", ".join(f"{a:08X} to {a + n - 1:08X}" for a, n in asked) + f" of {target}"
+
+            def work() -> None:
+                connection.erase_ranges(asked)
+
+        def done(_result) -> None:
+            took = time.monotonic() - started
+            self.events.good(f"Erased {what} in {took:.1f} s.")
+
+        if self._run("Erasing", work, done):
+            self.events.information(f"Erasing {what}...")
+            self.progress.emit("Erasing", 0.0)
+
+    def program(
+        self,
+        images: Sequence[Image],
+        erase: str = ERASE_SECTORS,
+        verify: bool = True,
+        reset: bool = True,
+    ) -> None:
+        """Program these files, then verify and reset if asked to."""
+        if (connection := self._connection("Programming")) is None:
+            return
+        segments: list[Segment] = [s for image in images for s in image.segments]
+        if not segments:
+            self.events.warning("There is nothing to program: no file is ticked.")
+            return
+        size = sum(len(s) for s in segments)
+        started = time.monotonic()
+
+        def work() -> Verification | None:
+            connection.program(segments, erase=erase, progress=self._progress("Programming"))
+            result = None
+            if verify:
+                self._last_progress = -1.0
+                result = connection.verify(
+                    segments, progress=self._progress("Verifying"), cancelled=self._cancel.is_set
+                )
+            # Not reset after a verify that failed: what is in the flash is
+            # not what was meant to be, and starting it helps nobody.
+            if reset and (result is None or result.ok):
+                connection.reset()
+            return result
+
+        def done(result: Verification | None) -> bool:
+            took = time.monotonic() - started
+            files = "1 file" if len(images) == 1 else f"{len(images)} files"
+            if result is not None and not result.ok:
+                self.events.error(
+                    f"Programmed {files}, and the target does not hold what was sent. "
+                    + verification_text(result)
+                )
+                return False
+            parts = [f"Programmed {files}, {size_text(size)}"]
+            if result is not None:
+                parts.append("verified")
+            if reset:
+                parts.append("and reset the target")
+            self.events.good(", ".join(parts) + f", in {took:.1f} s.")
+            return True
+
+        if self._run("Programming", work, done):
+            names = ", ".join(image.name for image in images)
+            self.events.information(f"Programming {self.target} with {names}...")
+
+    def verify(self, images: Sequence[Image]) -> None:
+        if (connection := self._connection("Verifying")) is None:
+            return
+        segments: list[Segment] = [s for image in images for s in image.segments]
+        if not segments:
+            self.events.warning("There is nothing to verify: no file is ticked.")
+            return
+
+        def work() -> Verification:
+            return connection.verify(
+                segments, progress=self._progress("Verifying"), cancelled=self._cancel.is_set
+            )
+
+        def done(result: Verification) -> bool:
+            (self.events.good if result.ok else self.events.error)(verification_text(result))
+            return result.ok
+
+        self._run("Verifying", work, done)
+
+    def read_memory(self, address: int, length: int, skip_setup: bool = False) -> None:
+        """Read this much of the target's memory, and say so with ``memory_read``.
+
+        Into memory and not into a file: most reads are to look at what is
+        there, and whoever shows it can save it once it has been looked at.
+        """
+        if (connection := self._connection("Reading")) is None:
+            return
+        target = self.target
+
+        def work() -> bytes:
+            return connection.read_range(
+                address, length, self._progress("Reading"), self._cancel.is_set, skip_setup
+            )
+
+        def done(data: bytes) -> None:
+            self.events.good(f"Read {size_text(len(data))} at {address:08X} of {target}.")
+            self.memory_read.emit(address, data, target)
+
+        if self._run("Reading", work, done):
+            self.events.information(f"Reading {size_text(length)} at {address:08X} of {target}...")
+
+    def reset(self) -> None:
+        if (connection := self._connection("Resetting")) is None:
+            return
+        self._run(
+            "Resetting",
+            connection.reset,
+            lambda _r: self.events.information(f"Reset {self.target}."),
+        )
+
+    # --- going away ------------------------------------------------------------------
+    def shutdown(self) -> None:
+        """Let go of the probe and stop the worker. For when the window closes."""
+        if self._shut:
+            return  # a window asked to close twice closes once
+        self._shut = True
+        self._cancel.set()
+        connection, self.connection = self.connection, None
+        self._worker.stop()
+        if connection is not None:
+            # After the worker has stopped, so nothing is half way through
+            # using it, and here rather than queued, so that it happens
+            # before the application has gone.
+            try:
+                connection.close()
+            except BackendError:
+                pass

pyflashgui/core/images.py

@@ -0,0 +1,279 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Firmware images: ELF, Intel HEX, Motorola S-record and raw binary.
+
+Reading and writing is bincopy's job. What is here is the part bincopy cannot decide:
+which format a file is, what its address is, and what to do when it does not
+have one.
+
+Every format is read the same way and comes out as the same thing -- runs of
+bytes, each at an address -- so that the memory map and whatever does the
+programming are shown exactly the bytes that were read, rather than each
+reading the file again in its own way and the two disagreeing.
+
+An ELF, a hex or an S-record file carries the address of every byte in it. A
+raw binary does not -- it is bytes and nothing else -- so the address has to
+be supplied before it can be put anywhere, and an image loaded without one
+says so rather than guessing at zero.
+
+**An ELF is read at its load addresses.** Initialised data is linked to run
+from RAM and stored in flash, and the two addresses are both in the file. The
+load address is where the bytes have to be programmed; the other is where
+start-up code copies them to, which is no business of a programmer's.
+
+Gaps are left as they are found. Padding the holes in a file would mean
+writing bytes it never contained, over whatever the target had there.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# bincopy is needed only when somebody picks a firmware file, so it is
+# imported in the function that reads one.
+
+ELF = "ELF"
+IHEX = "Intel HEX"
+SREC = "Motorola S-record"
+BINARY = "raw binary"
+
+#: Suffixes that mean "this file has no addresses in it".
+BINARY_SUFFIXES = {".bin", ".raw", ".img", ".rom", ".dat"}
+
+#: For the file dialogs. One "any of them" entry first, because guessing the
+#: format from the contents is what the reader does anyway.
+READ_FILTER = (
+    "Firmware images (*.elf *.axf *.out *.hex *.ihex *.ihx *.s19 *.s28 *.s37 *.srec *.mot "
+    "*.bin *.raw *.img);;"
+    "ELF (*.elf *.axf *.out);;"
+    "Intel HEX (*.hex *.ihex *.ihx);;"
+    "Motorola S-record (*.s19 *.s28 *.s37 *.srec *.mot);;"
+    "Raw binary (*.bin *.raw *.img);;"
+    "All files (*)"
+)
+
+#: S-record address widths, by the suffix that names them. S19 is 16-bit
+#: addresses, S28 24-bit, S37 32-bit; the suffix is the usual way of saying so.
+SREC_SUFFIXES = {".s19": 16, ".s28": 24, ".s37": 32, ".srec": 32, ".mot": 32, ".sre": 32}
+IHEX_SUFFIXES = {".hex", ".ihex", ".ihx", ".i32", ".a90"}
+
+#: For saving what was read back. Raw binary first: it is what was read,
+#: with nothing added.
+WRITE_FILTER = (
+    "Raw binary (*.bin);;Intel HEX (*.hex);;Motorola S-record (*.s19 *.s28 *.s37);;All files (*)"
+)
+
+#: How an ELF file starts, whatever it is called.
+_ELF_MAGIC = b"\x7fELF"
+
+
+class ImageError(Exception):
+    """The file could not be read, or could be read but not placed."""
+
+
+@dataclass(frozen=True)
+class Segment:
+    """One run of contiguous bytes at a known address."""
+
+    address: int
+    data: bytes
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    @property
+    def end(self) -> int:
+        """The address after the last byte."""
+        return self.address + len(self.data)
+
+
+@dataclass(frozen=True)
+class Image:
+    """What a firmware file turned out to contain."""
+
+    path: str
+    format: str  # one of ELF, IHEX, SREC, BINARY
+    segments: tuple[Segment, ...]
+    #: Lines of an Intel HEX file that were not records -- comments, a title
+    #: -- and so were passed over. Said in the summary, so it is never silent.
+    ignored: int = 0
+    #: Where execution starts, for a file that says: an ELF always does, and
+    #: a hex or S-record file may. None for one that does not.
+    entry: int | None = None
+
+    @property
+    def name(self) -> str:
+        return Path(self.path).name
+
+    @property
+    def size(self) -> int:
+        return sum(len(s) for s in self.segments)
+
+    @property
+    def address(self) -> int:
+        return self.segments[0].address if self.segments else 0
+
+    def summary(self) -> str:
+        """One line: what was read, how much of it, and where it goes."""
+        if not self.segments:
+            return f"{self.name}: {self.format}, empty"
+        where = ", ".join(f"{s.address:08X}+{len(s)}" for s in self.segments[:4])
+        if len(self.segments) > 4:
+            where += f", and {len(self.segments) - 4} more"
+        segments = "1 segment" if len(self.segments) == 1 else f"{len(self.segments)} segments"
+        line = f"{self.name}: {self.format}, {self.size} bytes, {segments} [{where}]"
+        if self.ignored:
+            lines = "1 line" if self.ignored == 1 else f"{self.ignored} lines"
+            line += f"; {lines} not starting with ':' ignored"
+        return line
+
+
+def looks_binary(path: str) -> bool:
+    """Whether choosing this file will need an address typed in.
+
+    Answered from the name, because a pane has to enable or disable the
+    address box the moment a file is picked; reading settles it properly.
+    """
+    return Path(path).suffix.lower() in BINARY_SUFFIXES
+
+
+#: An Intel HEX record: a colon, then hex digits -- at least a length, an
+#: address, a type and a checksum.
+_IHEX_RECORD = re.compile(rb"^:[0-9A-Fa-f]{10,}$")
+
+
+def _sniff(raw: bytes) -> str | None:
+    """Which format carries its own addresses here, or None for none of them.
+
+    From the contents, not the name: a build that calls its ELF ``firmware``
+    or its hex file ``image.txt`` has still made an ELF and a hex file.
+    """
+    if raw.startswith(_ELF_MAGIC):
+        return ELF
+    for line in raw.splitlines():
+        text = line.strip()
+        if not text:
+            continue
+        if text.startswith(b":"):
+            return IHEX
+        if text[:1] in (b"S", b"s") and text[1:2].isdigit():
+            return SREC
+        break
+    # Intel HEX that opens with a comment or a title. Every record starts with
+    # a colon, so anything else in a text file of records is not data.
+    try:
+        lines = raw.decode("ascii").splitlines()
+    except UnicodeDecodeError:
+        return None
+    if any(_IHEX_RECORD.match(line.strip().encode()) for line in lines):
+        return IHEX
+    return None
+
+
+def _ihex_records(text: str) -> tuple[str, int]:
+    """The records of an Intel HEX file, and how many other lines there were."""
+    records, ignored = [], 0
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(":"):
+            records.append(stripped)
+        elif stripped:
+            ignored += 1
+    return "\n".join(records) + "\n", ignored
+
+
+def read(path: str, address: int | None = None) -> Image:
+    """Read a firmware file, whatever format it is in.
+
+    `address` is where a raw binary starts. It is required for one, ignored
+    for a file that carries its own addresses -- there the file is right and a
+    typed-in number would only be a way to get it wrong.
+    """
+    try:
+        raw = Path(path).read_bytes()
+    except OSError as exc:
+        raise ImageError(str(exc)) from exc
+    if not raw:
+        raise ImageError("the file is empty")
+
+    import bincopy
+
+    binfile = bincopy.BinFile()
+    fmt = _sniff(raw)
+    ignored = 0
+    if fmt == ELF:
+        try:
+            binfile.add_elf(raw)
+        except Exception as exc:
+            # Not bincopy's own error alone: a damaged ELF fails inside the
+            # ELF reader, in whichever way the damage takes it.
+            raise ImageError(f"not readable as {fmt}: {exc}") from exc
+        if not binfile.segments:
+            raise ImageError("this ELF has nothing in it to program: no loadable section")
+    elif fmt is not None:
+        try:
+            text = raw.decode("ascii", "strict")
+            if fmt == IHEX:
+                text, ignored = _ihex_records(text)
+                binfile.add_ihex(text)
+            else:
+                binfile.add_srec(text)
+        except (UnicodeDecodeError, bincopy.Error, ValueError) as exc:
+            raise ImageError(f"not readable as {fmt}: {exc}") from exc
+    else:
+        if address is None:
+            raise ImageError(
+                "this file is raw binary -- it carries no addresses, so the "
+                "start address has to be supplied"
+            )
+        fmt = BINARY
+        binfile.add_binary(raw, address=address)
+
+    segments = tuple(Segment(s.address, bytes(s.data)) for s in binfile.segments)
+    return Image(
+        path=path,
+        format=fmt,
+        segments=segments,
+        ignored=ignored,
+        entry=binfile.execution_start_address,
+    )
+
+
+def _srec_width(suffix: str, address: int, size: int) -> int:
+    """How wide the addresses of an S-record file have to be.
+
+    What the suffix asks for, or wider where the addresses will not fit:
+    flash at 08000000 saved as .s19 is given 32-bit addresses rather
+    than refused, since a file that holds the data is what was wanted.
+    """
+    top = address + size
+    needed = 16 if top <= 0x1_0000 else 24 if top <= 0x100_0000 else 32
+    return max(SREC_SUFFIXES.get(suffix, needed), needed)
+
+
+def write(path: str, address: int, data: bytes) -> str:
+    """Write bytes read back from a target, in the format the name asks for.
+
+    Exactly what was read, at the address it was read from: nothing padded
+    and nothing filled in. Returns the format used, for the log.
+    """
+    import bincopy
+
+    binfile = bincopy.BinFile()
+    binfile.add_binary(data, address=address)
+    suffix = Path(path).suffix.lower()
+    try:
+        if suffix in IHEX_SUFFIXES:
+            fmt, text = IHEX, binfile.as_ihex()
+        elif suffix in SREC_SUFFIXES:
+            width = _srec_width(suffix, address, len(data))
+            fmt, text = SREC, binfile.as_srec(address_length_bits=width)
+        else:
+            Path(path).write_bytes(data)
+            return BINARY
+        Path(path).write_text(text, encoding="ascii")
+    except (OSError, bincopy.Error, ValueError) as exc:
+        raise ImageError(str(exc)) from exc
+    return fmt