pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""pyflashgui — a graphical flash programming tool."""
+
+__version__ = "0.1.0"
+APP_NAME = "pyflashgui"  # single place to change the display name

pyflashgui/__main__.py

@@ -0,0 +1,334 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Entry point: `python -m pyflashgui`, or the `pyflashgui` command pip installs."""
+
+# Deliberately out of order (hence the noqa): timing's clock starts when it is
+# imported, so it has to come before the imports whose cost is being measured.
+# It pulls in nothing but the standard library.
+import importlib  # noqa: I001
+import os
+import sys
+
+from pyflashgui.core import timing
+from PySide6.QtWidgets import QApplication
+
+from pyflashgui import APP_NAME
+
+#: Imported by ``--selftest``. These are the modules a packaged build is most
+#: likely to be missing, because they are loaded by name at run time and so no
+#: static analysis can see them.
+SELFTEST_MODULES = (
+    "bincopy",
+    "pyocd",
+    "pyocd.core.helpers",
+    "pyocd.flash.file_programmer",
+    "pyocd.flash.eraser",
+    "cmsis_pack_manager",
+    "usb.core",
+    "libusb_package",
+    "pyflashgui.core.images",
+    "pyflashgui.core.memory_map",
+    "pyflashgui.backends.pyocd_backend",
+    "pyflashgui.backends.jlink_backend",
+    "pyflashgui.backends.simulated",
+    "pyflashgui.ui.main_window",
+)
+
+#: The probe drivers pyOCD has to be able to find. It looks them up through
+#: entry points, which a build that left pyOCD's package metadata behind
+#: does not have: every one of them would then be missing, with no error.
+#: Not the J-Link driver, which pyOCD only offers where SEGGER's own library
+#: is installed, and that is the user's to install.
+PROBE_DRIVERS = ("cmsisdap", "picoprobe", "stlink")
+
+#: Targets that are part of pyOCD itself rather than a CMSIS-Pack, and so
+#: have to work in a build with no packs installed.
+BUILTIN_TARGETS = ("cortex_m", "rp2040", "rp2350")
+
+
+def missing_probe_drivers() -> list[str]:
+    """The PROBE_DRIVERS pyOCD cannot load here."""
+    from pyocd.probe.aggregator import PROBE_CLASSES
+
+    return [name for name in PROBE_DRIVERS if name not in PROBE_CLASSES]
+
+
+def missing_builtin_targets() -> list[str]:
+    """The BUILTIN_TARGETS this pyOCD does not have."""
+    from pyocd.target import builtin
+
+    return [name for name in BUILTIN_TARGETS if name not in builtin.BUILTIN_TARGETS]
+
+
+def selftest() -> int:
+    """Import everything a build could plausibly be missing. Exit code only:
+    a windowed build has nowhere to print to."""
+    failures = []
+    for name in SELFTEST_MODULES:
+        try:
+            importlib.import_module(name)
+        except Exception as exc:
+            failures.append(f"{name}: {exc}")
+
+    try:
+        failures += [f"pyOCD probe driver {name}: not found" for name in missing_probe_drivers()]
+        failures += [f"pyOCD target {name}: not found" for name in missing_builtin_targets()]
+    except Exception as exc:
+        failures.append(f"pyocd: {exc}")
+
+    # libusb is a native library carried inside a Python package, which is
+    # the kind of file a build leaves behind. Without it pyOCD lists no
+    # CMSIS-DAP v2 probe and no ST-Link, and says nothing about why.
+    try:
+        import libusb_package
+
+        if libusb_package.get_libusb1_backend() is None:
+            failures.append("libusb: the library libusb-package carries would not load")
+    except Exception as exc:
+        failures.append(f"libusb: {exc}")
+
+    # The manual is package data, so it is exactly the kind of file a build
+    # drops silently. Every page, by name: one missing page is a topic that
+    # vanished, and a manual that still opens is the worst way for that to
+    # be found.
+    try:
+        from pyflashgui.help import missing_images, missing_pages
+
+        for page in missing_pages():
+            failures.append(f"pyflashgui/help/{page}: not shipped with this build")
+        for image in missing_images():
+            failures.append(f"pyflashgui/help/{image}: shown in the manual but not shipped")
+    except Exception as exc:
+        failures.append(f"pyflashgui.help: {exc}")
+
+    # Help > Licences reads these at run time from beside the executable. A
+    # build that ships them where _find cannot see them would show three empty
+    # tabs, and no import check would notice.
+    try:
+        from pyflashgui.ui.help_menu import missing_licence_files
+
+        failures += [
+            f"{name}: not found beside the application"
+            for name in missing_licence_files(getattr(sys, "frozen", False))
+        ]
+    except Exception as exc:
+        failures.append(f"pyflashgui.ui.help_menu: {exc}")
+
+    if failures:
+        sys.stderr.write("selftest failures:" + "".join(f"\n  {f}" for f in failures) + "\n")
+        return 1
+    return 0
+
+
+#: Who Windows thinks the windows belong to. Without one, a pyflashgui started
+#: from source is grouped under pythonw.exe and the taskbar shows Python's
+#: icon whatever the window says -- the window icon only reaches the title bar.
+APP_USER_MODEL_ID = "davhodg.pyflashgui"
+
+
+def set_icon(app) -> None:
+    """The application icon, before any window exists.
+
+    Set on the application rather than on the main window so that a message
+    shown during start-up carries it too. The .ico rather than the PNG:
+    it holds each size drawn for that size, and Qt picks the nearest one.
+    """
+    from PySide6.QtGui import QIcon
+
+    from pyflashgui import resources
+
+    if sys.platform == "win32":
+        try:
+            import ctypes
+
+            ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(APP_USER_MODEL_ID)
+        except (AttributeError, OSError):  # an unusual shell: the title bar still has it
+            pass
+    app.setWindowIcon(QIcon(str(resources.path("pyflashgui.ico"))))
+
+
+#: The libraries Qt's X11 plugin needs that Debian, Ubuntu and Linux Mint can
+#: leave out, each with the package it comes in. Without one, Qt stops with
+#: "could not load the Qt platform plugin xcb" and does not say which.
+XCB_LIBRARIES = (
+    ("libxcb-cursor.so.0", "libxcb-cursor0"),
+    ("libxcb-icccm.so.4", "libxcb-icccm4"),
+    ("libxcb-image.so.0", "libxcb-image0"),
+    ("libxcb-keysyms.so.1", "libxcb-keysyms1"),
+    ("libxcb-render-util.so.0", "libxcb-render-util0"),
+    ("libxkbcommon-x11.so.0", "libxkbcommon-x11-0"),
+)
+
+
+def uses_xcb(environ=None) -> bool:
+    """Whether Qt will draw through X11 here, where XCB_LIBRARIES are needed."""
+    if not sys.platform.startswith("linux"):
+        return False
+    environ = os.environ if environ is None else environ
+    chosen = environ.get("QT_QPA_PLATFORM", "")
+    if chosen:
+        return chosen.startswith("xcb")
+    return environ.get("XDG_SESSION_TYPE") != "wayland"
+
+
+def missing_xcb_packages(load=None) -> list[str]:
+    """The packages to install for the XCB_LIBRARIES that cannot be loaded."""
+    if load is None:
+        import ctypes
+
+        load = ctypes.CDLL
+    missing = []
+    for library, package in XCB_LIBRARIES:
+        try:
+            load(library)
+        except OSError:
+            missing.append(package)
+    return missing
+
+
+def main() -> int:
+    if "--selftest" in sys.argv:
+        return selftest()
+    if uses_xcb() and (missing := missing_xcb_packages()):
+        sys.stderr.write(
+            "Qt needs libraries this system does not have to draw the window. On Debian,\n"
+            "Ubuntu and Linux Mint:\n\n"
+            f"    sudo apt install {' '.join(missing)}\n"
+        )
+        return 1
+    app = QApplication.instance() or QApplication(sys.argv)
+    app.setApplicationName(APP_NAME)
+    app.setOrganizationName(APP_NAME)  # QSettings uses these two for the registry/ini path
+    set_icon(app)
+    # Before anything is drawn, so the first window is already in the colours chosen.
+    from pyflashgui.ui import theme
+
+    theme.apply(theme.chosen())
+    timing.mark("Qt started")
+    # From here on, which package each imported second belongs to. Installed
+    # after Qt because Qt is already in by now, and its cost is its own line.
+    timing.watch_imports()
+
+    # confirm.py is cheap -- Qt widgets and nothing else -- and has to come
+    # before the rest of the imports, because it is what covers them.
+    from pyflashgui.ui.confirm import accept_notice
+
+    loaded: dict = {}
+
+    def load() -> None:
+        """The slow half of starting up, done behind the notice.
+
+        Loading the libraries with nothing on screen is how a tool comes to
+        feel heavy. Behind a dialog somebody is reading, it is free. Run on
+        a thread of its own, so imports only: the window is made on the GUI
+        thread after.
+
+        Imported here rather than at the top of the file for a second reason
+        as well: a library which is not installed becomes a dialog. Started
+        from pyflashgui.cmd there is no console -- it runs pythonw -- so an
+        ImportError on the way up is a window that never appears and not one
+        word about why.
+        """
+        try:
+            from pyflashgui.ui.main_window import MainWindow
+            from pyflashgui.ui.session import Session
+
+            loaded["classes"] = (Session, MainWindow)
+            timing.mark(timing.LIBRARIES_STEP)
+        except Exception as exc:
+            # Not ImportError alone. A library that is installed and will
+            # not load fails however it likes, and anything not caught
+            # here is a window that never appears.
+            loaded["error"] = exc
+
+    # Before the window is built, and therefore before anything can reach
+    # for a probe: a notice read after that is a notice that was too late.
+    if not accept_notice(while_shown=load):
+        return 0
+    # Its own line, because the libraries load behind the notice and the
+    # window is built after it: without this, every step between the two
+    # carries however long somebody took to read the notice and press
+    # Continue, and the report blames the first thing the window does.
+    timing.mark(timing.NOTICE_STEP)
+    if (failed := loaded.get("error")) is not None:
+        from pyflashgui.ui import messages
+
+        messages.critical(None, f"{APP_NAME} cannot start", why_it_cannot_start(failed))
+        sys.stderr and sys.stderr.write(why_it_cannot_start(failed) + "\n")
+        return 1
+
+    # Held by a Session rather than a local, because switching workspace
+    # replaces the window rather than reconfiguring it.
+    session_class, window_class = loaded["classes"]
+    session = session_class(window_class)
+    window = session.open()
+    timing.mark("window on screen")
+    note_a_slow_start(window)
+    return app.exec()
+
+
+def why_it_cannot_start(failed: BaseException) -> str:
+    """What to tell somebody whose libraries would not load, and what to do.
+
+    Two different faults. A library that is not there is put right by
+    installing it. One that is there and will not load is usually two
+    libraries that no longer agree -- a new release of one, which the other
+    was not written for -- and installing again changes nothing: it wants the
+    name of the file that failed, so that the pair can be found.
+    """
+    if isinstance(failed, ModuleNotFoundError):
+        return (
+            f"A library {APP_NAME} needs is missing:\n\n    {failed}\n\n"
+            "Start it with pyflashgui.cmd (or pyflashgui.sh), which installs "
+            "anything missing before starting, or install it with pip."
+        )
+    import traceback
+
+    where = traceback.extract_tb(failed.__traceback__)
+    place = f"\n    in {where[-1].filename}, line {where[-1].lineno}" if where else ""
+    return (
+        f"A library {APP_NAME} needs is installed but would not load:\n\n"
+        f"    {type(failed).__name__}: {failed}{place}\n\n"
+        "This is usually two libraries that no longer agree, after a new release "
+        "of one of them. Upgrading the one named above, or going back a version "
+        "of the one it was loading, normally puts it right; in a source folder, "
+        "deleting .venv and starting the launcher installs them all again."
+    )
+
+
+def note_a_slow_start(window) -> None:
+    """What starting had to do and how long it took, as far as it is worth saying.
+
+    Two separate lines, each only when there is something to say: how many
+    files Python compiled, and -- for a slow start -- what took over a second,
+    with a pointer to *Help > Diagnostics*, which always has the whole report.
+    ``--timing`` puts the whole report in the Event Log after every start.
+    """
+    from pyflashgui.core import slow_start
+
+    if (compiled := slow_start.compiled_note(timing.started_at())) is not None:
+        window.events.information(compiled)
+    slow = slow_start.message(
+        timing.total_work(), steps=timing.step_times(), packages=timing.import_times()
+    )
+    if slow is not None:
+        window.events.information(slow)
+    if timing.enabled():
+        report(window)
+
+
+def report(window) -> None:
+    """Say where the time went, in the Event Log and in a file.
+
+    Both, because the launcher starts pythonw and there is no console to
+    print to, and because a number somebody has to read off the screen is a
+    number that does not reach a bug report.
+    """
+    for line in [timing.why_shown(), *timing.report_lines()]:
+        window.events.information(line)
+    if (path := timing.write_report(window.ctx.user_dir)) is not None:
+        window.events.information(f"Startup timing written to {path}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyflashgui/backends/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""The ways pyflashgui has of reaching a probe, by name.
+
+A backend is made when it is first asked for and kept, so that there is one
+of each: the simulated one holds what has been programmed into it, and two
+of them would be two different sets of boards.
+"""
+
+from __future__ import annotations
+
+from pyflashgui.backends.base import Backend, BackendError
+
+#: What a workspace uses when it has not said.
+DEFAULT = "pyocd"
+
+#: In the order they are offered.
+NAMES = ("pyocd", "jlink", "simulated")
+
+_made: dict[str, Backend] = {}
+
+
+def get(name: str = DEFAULT) -> Backend:
+    """The backend of this name. Imported here, and only when asked for."""
+    if name not in _made:
+        if name == "pyocd":
+            from pyflashgui.backends.pyocd_backend import PyocdBackend
+
+            _made[name] = PyocdBackend()
+        elif name == "jlink":
+            from pyflashgui.backends.jlink_backend import JLinkBackend
+
+            _made[name] = JLinkBackend()
+        elif name == "simulated":
+            from pyflashgui.backends.simulated import SimulatedBackend
+
+            _made[name] = SimulatedBackend()
+        else:
+            raise BackendError(f"There is no backend called {name}.")
+    return _made[name]

pyflashgui/backends/base.py

@@ -0,0 +1,272 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""What pyflashgui asks of whatever talks to a probe.
+
+Two objects. A ``Backend`` knows what is plugged in and which targets it can
+handle, and none of that needs anything connected. A ``Connection`` is one
+probe attached to one target, and is what erases, programs and reads.
+
+The rest of pyflashgui is written against these and never against a
+flashing library, for two reasons. A second library can be added behind the
+same interface without a pane noticing; and the simulated backend stands in
+for a probe in the tests, and on a desk with no hardware on it.
+
+**Every call blocks**, some of them for as long as programming takes. They
+are meant to be run on a worker thread, one at a time for a given probe:
+nothing here is safe to call from two threads at once, because a probe is
+not.
+
+Nothing here imports Qt or a flashing library.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from pyflashgui.core.images import Segment
+from pyflashgui.core.memory_map import Region
+
+#: Called with how far along something is, from 0.0 to 1.0.
+Progress = Callable[[float], None]
+#: Asked between steps whether to stop. True means somebody pressed Cancel.
+Cancelled = Callable[[], bool]
+
+#: Erase only the sectors about to be written, leaving the rest of the flash.
+ERASE_SECTORS = "sectors"
+#: Erase all of the flash first, so nothing of what was there is left.
+ERASE_CHIP = "chip"
+
+#: What verifying reads at a time. Small enough that progress moves and a
+#: cancel is noticed; large enough that the probe is not asked a thousand
+#: times for one sector.
+VERIFY_CHUNK = 4096
+#: What reading back asks for at a time, for the same two reasons.
+READ_CHUNK = 0x4000
+
+
+class BackendError(Exception):
+    """Something went wrong that the user can be told about in its own words.
+
+    Raised with a whole sentence, because the message is what is shown: a
+    library's own exception is caught where it is raised and said again here
+    in terms of what was being attempted.
+    """
+
+
+class CancelledError(BackendError):
+    """Stopped because it was asked to, and not because anything failed."""
+
+
+@dataclass(frozen=True)
+class ProbeInfo:
+    """One debug probe that is plugged in."""
+
+    #: What tells this probe from another of the same kind: its serial number.
+    unique_id: str
+    description: str
+    vendor: str = ""
+    product: str = ""
+
+
+@dataclass(frozen=True)
+class TargetInfo:
+    """One kind of device a backend knows how to program."""
+
+    #: What the backend calls it, and what ``connect`` is given.
+    name: str
+    vendor: str = ""
+    #: Where the backend's knowledge of it comes from: "built in", or the
+    #: pack it was installed with.
+    source: str = ""
+    #: The processor in it, where the backend knows: "Cortex-M7".
+    core: str = ""
+
+
+@dataclass(frozen=True)
+class Verification:
+    """What comparing a target's memory with the files found."""
+
+    checked: int  # bytes compared
+    different: int  # bytes that were not what the file has
+    #: The first byte that differed -- its address, what the file has there
+    #: and what the target has -- or None when nothing did.
+    first: tuple[int, int, int] | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.different == 0
+
+
+def _nothing(_fraction: float) -> None:
+    """Progress nobody is listening to."""
+
+
+def _never() -> bool:
+    return False
+
+
+class Connection(ABC):
+    """One probe, attached to one target. Closed when finished with.
+
+    Usable in a ``with`` statement, which closes it however the block ends:
+    a probe left attached is one nothing else can use.
+    """
+
+    @abstractmethod
+    def regions(self) -> list[Region]:
+        """The target's memory, as it turned out to be once connected."""
+
+    @abstractmethod
+    def erase_chip(self) -> None:
+        """Erase all of the target's flash."""
+
+    @abstractmethod
+    def erase_ranges(self, ranges: Sequence[tuple[int, int]]) -> None:
+        """Erase these stretches of flash, each an address and a length.
+
+        Flash is erased a sector at a time, so every sector that any of
+        a range falls in is erased whole.
+        """
+
+    @abstractmethod
+    def program(
+        self,
+        segments: Sequence[Segment],
+        erase: str = ERASE_SECTORS,
+        progress: Progress = _nothing,
+    ) -> None:
+        """Erase what has to be erased and write these bytes.
+
+        Not cancellable. Stopping half way through leaves a target that is
+        neither what it was nor what it was going to be, which is worse than
+        either; a board can always be programmed again afterwards.
+        """
+
+    @abstractmethod
+    def read(self, address: int, length: int) -> bytes:
+        """This many bytes of the target's memory, from this address."""
+
+    @abstractmethod
+    def reset(self, halt: bool = False) -> None:
+        """Restart the target, and leave it running unless ``halt``."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Let go of the probe. Safe to call twice."""
+
+    def read_range(
+        self,
+        address: int,
+        length: int,
+        progress: Progress = _nothing,
+        cancelled: Cancelled = _never,
+        skip_setup: bool = False,
+    ) -> bytes:
+        """A long run of the target's memory, a piece at a time.
+
+        ``skip_setup`` asks a backend that sets a device up on connecting
+        to it -- which on some parts writes to its RAM -- to leave that
+        out for this read. It means something only where the backend's
+        ``can_skip_setup`` says so, and is passed over elsewhere.
+
+        In pieces so that there is progress to report and a cancel is
+        noticed: a megabyte asked for in one go is a window that says
+        nothing for as long as it takes.
+        """
+        out = bytearray()
+        while len(out) < length:
+            if cancelled():
+                raise CancelledError("Reading was cancelled.")
+            out += self.read(address + len(out), min(READ_CHUNK, length - len(out)))
+            progress(len(out) / length)
+        return bytes(out)
+
+    def verify(
+        self,
+        segments: Sequence[Segment],
+        progress: Progress = _nothing,
+        cancelled: Cancelled = _never,
+    ) -> Verification:
+        """Read back what these bytes should have become, and compare.
+
+        Read through ``read`` rather than left to a library's own check, so
+        that it means the same thing with every backend: the bytes that are
+        in the target now are the bytes that are in the file.
+        """
+        total = sum(len(s) for s in segments)
+        checked = different = 0
+        first: tuple[int, int, int] | None = None
+        for segment in segments:
+            for offset in range(0, len(segment), VERIFY_CHUNK):
+                if cancelled():
+                    raise CancelledError("Verifying was cancelled.")
+                wanted = segment.data[offset : offset + VERIFY_CHUNK]
+                found = self.read(segment.address + offset, len(wanted))
+                if found != wanted:
+                    for index, (want, have) in enumerate(zip(wanted, found, strict=True)):
+                        if want != have:
+                            different += 1
+                            if first is None:
+                                first = (segment.address + offset + index, want, have)
+                checked += len(wanted)
+                progress(checked / total)
+        return Verification(checked=checked, different=different, first=first)
+
+    def __enter__(self) -> Connection:
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+
+class Backend(ABC):
+    """One way of reaching probes and targets."""
+
+    #: What the backend is called in settings, which must not change.
+    name: str = ""
+    #: What it is called on screen.
+    label: str = ""
+    #: The debug interfaces that can be asked for, the first being the
+    #: one used when none is. Empty where the backend chooses for itself.
+    interfaces: tuple[str, ...] = ()
+    #: Whether ``regions`` is every address the target can be written at.
+    #: Where it is not, a file outside them is worth a warning and is
+    #: not refused: the backend may know of memory that it does not list.
+    map_is_complete: bool = True
+    #: Whether a read can be made without the backend first setting the
+    #: device up in its own way. See ``Connection.read_range``.
+    can_skip_setup: bool = False
+
+    @abstractmethod
+    def probes(self) -> list[ProbeInfo]:
+        """The probes plugged in now. Empty when there are none: never waits."""
+
+    @abstractmethod
+    def targets(self) -> list[TargetInfo]:
+        """Every target this backend can be asked for, by name."""
+
+    @abstractmethod
+    def regions(self, target: str) -> list[Region]:
+        """A target's memory as far as is known without connecting to one.
+
+        Empty when it is not known until then, which is not an error: the
+        memory map says it could not check, and ``Connection.regions`` has
+        the answer once there is a connection.
+        """
+
+    @abstractmethod
+    def connect(
+        self,
+        probe: str,
+        target: str,
+        frequency: int | None = None,
+        interface: str | None = None,
+    ) -> Connection:
+        """Attach the probe with this unique id to a target of this name.
+
+        ``frequency`` is the debug clock in hertz, or None for the probe's
+        own choice. ``interface`` is one of ``interfaces``, or None for
+        the first of them.
+        """