pyflashgui 0.1.0__tar.gz → 0.2.1__tar.gz

pyflashgui-0.2.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: pyflashgui
+Version: 0.2.1
+Summary: Graphical flash programming tool: Arm Cortex-M with any probe pyOCD supports, and more through J-Link Commander
+Author: davhodg
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/davhodg/pyflashgui
+Project-URL: Documentation, https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md
+Project-URL: Repository, https://github.com/davhodg/pyflashgui
+Project-URL: Issues, https://github.com/davhodg/pyflashgui/issues
+Project-URL: Discussions, https://github.com/davhodg/pyflashgui/discussions
+Project-URL: Releases, https://github.com/davhodg/pyflashgui/releases
+Project-URL: Changelog, https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/changelog.md
+Keywords: flash,programmer,debug probe,SWD,CMSIS-DAP,ST-Link,J-Link,pyOCD,Cortex-M,microcontroller,embedded,firmware,Intel HEX,S-record,ELF,Qt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PySide6-Essentials>=6.8
+Requires-Dist: pyocd>=0.46
+Requires-Dist: bincopy>=20.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff==0.16.*; extra == "dev"
+Requires-Dist: trove-classifiers; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/resources/pyflashgui.png" alt="pyflashgui icon: a chip with pins on every side and a flash across it" width="128">
+</p>
+
+# pyflashgui
+
+[![CI](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml/badge.svg)](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/davhodg/pyflashgui)](https://github.com/davhodg/pyflashgui/releases)
+[![PyPI](https://img.shields.io/pypi/v/pyflashgui)](https://pypi.org/project/pyflashgui/)
+![python](https://img.shields.io/badge/python-3.12+-blue)
+![platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)
+![license](https://img.shields.io/badge/license-Apache--2.0-green)
+
+A graphical flash programming tool. It works with any debug probe [pyOCD](https://pyocd.io) supports, for Arm Cortex-M targets: CMSIS-DAP probes such as the Raspberry Pi Debug Probe, DAPLink, NXP MCU-Link and Atmel-ICE, TI XDS110 and the probes built into many development boards, as well as ST-Link and J-Link. With a J-Link it can also use SEGGER's J-Link Commander, for the many other devices that supports.
+
+![pyflashgui on its simulated probe: the Files pane with a firmware file and a read, the memory map under them, the bytes of the read beside them, and the Event Log below](https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/help/main-window.png)
+
+## Install and run
+
+To install it:
+
+```
+pip install pyflashgui
+```
+
+To run it (`python -m pyflashgui` does the same):
+
+```
+pyflashgui
+```
+
+To update it:
+
+```
+pip install --upgrade pyflashgui
+```
+
+**Python 3.15 on Windows is not supported yet:** libraries pyOCD needs there have not been released for 3.15. Use 3.14, 3.13 or 3.12 until they have.
+
+On Linux, Qt needs a system library to draw the window, and Debian, Ubuntu, Linux Mint and the like often leave it out:
+
+```
+sudo apt install libxcb-cursor0
+```
+
+A probe is usable without root on Linux once a udev rule allows it; pyOCD publishes [a set of them](https://github.com/pyocd/pyOCD/tree/main/udev).
+
+## What it does
+
+- **Probe and target** in a bar across the top: the probe by its serial number, the target by name, the debug clock, and Connect -- through pyOCD, stopping the target or leaving it running.
+- **Files**: ELF, Intel HEX, Motorola S-record and raw binary, in one list with what has been read from a target. A file is read again whenever a build writes it.
+- **Device packs**: every Cortex-M device there is a CMSIS-Pack for, found by part number and installed from inside pyflashgui, with the address each pack comes from -- or added from a `.pack` file, for a computer with no internet.
+- **Memory map**: where everything ticked will land on the chosen target, how full each flash region is and how much is erased, checked before anything is sent. A file built for another part, or two that write the same addresses, are found here.
+- **Program and verify** in one press, with each half on its own beside it and **Program without erasing** for flash erased already, **Erase** of all the flash, some regions or a range, and **Reset**, by the reset pin or another way where a device needs it.
+- **Read** any range of a target's memory back, shown as addresses, bytes and text, with a search for bytes or text and a way to an address. A read is saved as raw binary, Intel HEX or S-record, can be cropped to what is in use or to a range, and can be programmed like a file.
+- **Compare** any two of them -- what is in the target against the file that should be, or one read against another -- with each difference marked.
+- **Workspaces**: one for each board or project, holding its probe, target, files and layout.
+- **A Python console** with the probe and the target as `flash`: read, write RAM, erase, program, verify and reset from a prompt or a script, each call waiting for its answer. *File > Run script...* runs one, and keeps the last five a click away.
+- **A simulated probe and target**, to try all of it with no hardware.
+- **Help > Diagnostics**: how the connection was made, the last operations in order and what pyOCD reported, ready to paste into a bug report.
+
+The [manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md) covers each of these, and is also under **Help > Documentation** in the application.
+
+## Probes and targets
+
+Through [pyOCD](https://pyocd.io), any probe it supports, for Arm Cortex-M targets: CMSIS-DAP probes, ST-Link, and J-Link. The targets are those pyOCD has built in and those in CMSIS-Packs, which **Tools > pyOCD device packs** finds and installs.
+
+Through SEGGER's J-Link Commander, a J-Link reaches the devices beyond Cortex-M that SEGGER's software supports -- Cortex-A and Cortex-R, RISC-V and others. SEGGER's software is not included: install it, and pyflashgui finds it.
+
+The [README](https://github.com/davhodg/pyflashgui#probes) says which probes need which drivers.
+
+## More
+
+- [Source, issues and releases](https://github.com/davhodg/pyflashgui)
+- [Standalone Windows installer](https://github.com/davhodg/pyflashgui/releases)
+- [Questions and ideas](https://github.com/davhodg/pyflashgui/discussions)
+- [Manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md)
+
+## Safety notice and licence
+
+pyflashgui talks to real equipment. It is intended only for people trained and experienced in working with microcontrollers, debug probes and the equipment they are part of. It is a tool for development and the bench, and is not meant for production programming.
+
+Erasing and programming replace what a device holds, and cannot be undone. A device given the wrong file, or one that changes its protection or configuration, may not run, and may no longer be reachable through its debug port. Connecting, resetting and reading can stop or restart a device that is running, and with it whatever that device controls.
+
+Like any software, pyflashgui can have faults, so do not rely on it alone to say that a device holds what was meant. Where a mistake could hurt someone or damage equipment, keep a way to stop that equipment within reach.
+
+pyflashgui is provided under the Apache License 2.0, without warranty of any kind.

pyflashgui-0.2.1/PYPI.md

@@ -0,0 +1,87 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/resources/pyflashgui.png" alt="pyflashgui icon: a chip with pins on every side and a flash across it" width="128">
+</p>
+
+# pyflashgui
+
+[![CI](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml/badge.svg)](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/davhodg/pyflashgui)](https://github.com/davhodg/pyflashgui/releases)
+[![PyPI](https://img.shields.io/pypi/v/pyflashgui)](https://pypi.org/project/pyflashgui/)
+![python](https://img.shields.io/badge/python-3.12+-blue)
+![platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)
+![license](https://img.shields.io/badge/license-Apache--2.0-green)
+
+A graphical flash programming tool. It works with any debug probe [pyOCD](https://pyocd.io) supports, for Arm Cortex-M targets: CMSIS-DAP probes such as the Raspberry Pi Debug Probe, DAPLink, NXP MCU-Link and Atmel-ICE, TI XDS110 and the probes built into many development boards, as well as ST-Link and J-Link. With a J-Link it can also use SEGGER's J-Link Commander, for the many other devices that supports.
+
+![pyflashgui on its simulated probe: the Files pane with a firmware file and a read, the memory map under them, the bytes of the read beside them, and the Event Log below](https://raw.githubusercontent.com/davhodg/pyflashgui/master/pyflashgui/help/main-window.png)
+
+## Install and run
+
+To install it:
+
+```
+pip install pyflashgui
+```
+
+To run it (`python -m pyflashgui` does the same):
+
+```
+pyflashgui
+```
+
+To update it:
+
+```
+pip install --upgrade pyflashgui
+```
+
+**Python 3.15 on Windows is not supported yet:** libraries pyOCD needs there have not been released for 3.15. Use 3.14, 3.13 or 3.12 until they have.
+
+On Linux, Qt needs a system library to draw the window, and Debian, Ubuntu, Linux Mint and the like often leave it out:
+
+```
+sudo apt install libxcb-cursor0
+```
+
+A probe is usable without root on Linux once a udev rule allows it; pyOCD publishes [a set of them](https://github.com/pyocd/pyOCD/tree/main/udev).
+
+## What it does
+
+- **Probe and target** in a bar across the top: the probe by its serial number, the target by name, the debug clock, and Connect -- through pyOCD, stopping the target or leaving it running.
+- **Files**: ELF, Intel HEX, Motorola S-record and raw binary, in one list with what has been read from a target. A file is read again whenever a build writes it.
+- **Device packs**: every Cortex-M device there is a CMSIS-Pack for, found by part number and installed from inside pyflashgui, with the address each pack comes from -- or added from a `.pack` file, for a computer with no internet.
+- **Memory map**: where everything ticked will land on the chosen target, how full each flash region is and how much is erased, checked before anything is sent. A file built for another part, or two that write the same addresses, are found here.
+- **Program and verify** in one press, with each half on its own beside it and **Program without erasing** for flash erased already, **Erase** of all the flash, some regions or a range, and **Reset**, by the reset pin or another way where a device needs it.
+- **Read** any range of a target's memory back, shown as addresses, bytes and text, with a search for bytes or text and a way to an address. A read is saved as raw binary, Intel HEX or S-record, can be cropped to what is in use or to a range, and can be programmed like a file.
+- **Compare** any two of them -- what is in the target against the file that should be, or one read against another -- with each difference marked.
+- **Workspaces**: one for each board or project, holding its probe, target, files and layout.
+- **A Python console** with the probe and the target as `flash`: read, write RAM, erase, program, verify and reset from a prompt or a script, each call waiting for its answer. *File > Run script...* runs one, and keeps the last five a click away.
+- **A simulated probe and target**, to try all of it with no hardware.
+- **Help > Diagnostics**: how the connection was made, the last operations in order and what pyOCD reported, ready to paste into a bug report.
+
+The [manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md) covers each of these, and is also under **Help > Documentation** in the application.
+
+## Probes and targets
+
+Through [pyOCD](https://pyocd.io), any probe it supports, for Arm Cortex-M targets: CMSIS-DAP probes, ST-Link, and J-Link. The targets are those pyOCD has built in and those in CMSIS-Packs, which **Tools > pyOCD device packs** finds and installs.
+
+Through SEGGER's J-Link Commander, a J-Link reaches the devices beyond Cortex-M that SEGGER's software supports -- Cortex-A and Cortex-R, RISC-V and others. SEGGER's software is not included: install it, and pyflashgui finds it.
+
+The [README](https://github.com/davhodg/pyflashgui#probes) says which probes need which drivers.
+
+## More
+
+- [Source, issues and releases](https://github.com/davhodg/pyflashgui)
+- [Standalone Windows installer](https://github.com/davhodg/pyflashgui/releases)
+- [Questions and ideas](https://github.com/davhodg/pyflashgui/discussions)
+- [Manual](https://github.com/davhodg/pyflashgui/blob/master/pyflashgui/help/manual.md)
+
+## Safety notice and licence
+
+pyflashgui talks to real equipment. It is intended only for people trained and experienced in working with microcontrollers, debug probes and the equipment they are part of. It is a tool for development and the bench, and is not meant for production programming.
+
+Erasing and programming replace what a device holds, and cannot be undone. A device given the wrong file, or one that changes its protection or configuration, may not run, and may no longer be reachable through its debug port. Connecting, resetting and reading can stop or restart a device that is running, and with it whatever that device controls.
+
+Like any software, pyflashgui can have faults, so do not rely on it alone to say that a device holds what was meant. Where a mistake could hurt someone or damage equipment, keep a way to stop that equipment within reach.
+
+pyflashgui is provided under the Apache License 2.0, without warranty of any kind.

{pyflashgui-0.1.0 → pyflashgui-0.2.1}/README.md

@@ -5,7 +5,7 @@
 # pyflashgui
 
 [![CI](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml/badge.svg)](https://github.com/davhodg/pyflashgui/actions/workflows/ci.yml)
-[![release](https://img.shields.io/github/v/release/davhodg/pyflashgui?include_prereleases)](https://github.com/davhodg/pyflashgui/releases)
+[![release](https://img.shields.io/github/v/release/davhodg/pyflashgui)](https://github.com/davhodg/pyflashgui/releases)
 [![PyPI](https://img.shields.io/pypi/v/pyflashgui)](https://pypi.org/project/pyflashgui/)
 ![python](https://img.shields.io/badge/python-3.12+-blue)
 ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)
@@ -21,7 +21,9 @@ A graphical flash programming tool. It works with any debug probe [pyOCD](https:
 
 - **Any probe.** A low-cost CMSIS-DAP probe or the ST-Link on a development board does the job a dedicated programmer does.
 - **Workspaces.** The target, the probe, its speed and the files to program are kept together, one workspace per product, so programming a board is one click.
-- **Files.** ELF, Intel HEX, Motorola S-record and raw binary, with a map of what will be written where.
+- **Files.** ELF, Intel HEX, Motorola S-record and raw binary, with a map of what will be written where, and what is read back from a target in the same list, to compare and save.
+- **Device packs.** Every Cortex-M device there is a CMSIS-Pack for, found by part number and installed from inside pyflashgui -- or from a file, for a computer with no internet.
+- **Python.** A console with the probe and the target to hand, and *File > Run script...*, for what the buttons do not do: watching a value in RAM, writing a test pattern, a loop that programs and reads back.
 
 ## Installing
 
@@ -29,6 +31,8 @@ There are three options:
 
 1. **With pip** -- from [PyPI](https://pypi.org/project/pyflashgui/), into whichever Python environment you choose. Python 3.12 or newer is needed.
 
+   **Python 3.15 on Windows is not supported yet:** libraries pyOCD needs there have not been released for 3.15. Use 3.14, 3.13 or 3.12 until they have.
+
    To install it:
 
    ```
@@ -55,10 +59,14 @@ There are three options:
 
    It asks first who it is for: **everybody who uses the computer**, which needs administrator rights, or **only you**, which does not.
 
-3. **From a Git clone** -- clone the repository, then double-click `pyflashgui.cmd` (Windows) or run `./pyflashgui.sh` (Linux). This is the way to have the latest changes before they are released, or to contribute. Python 3.12 or newer must be on the PATH.
+3. **From a Git clone** -- clone the repository, then double-click `pyflashgui.cmd` (Windows) or run `./pyflashgui.sh` (Linux). This is the way to have the latest changes before they are released, or to contribute. Python 3.12 or newer is needed: on Windows 3.14, 3.13 or 3.12, as below.
 
    The first run sets itself up: it creates a *virtual environment* -- a folder called `.venv` holding its own copy of Python and only the libraries pyflashgui needs, so nothing else on the machine is touched -- and downloads a couple of hundred megabytes into it. That takes a few minutes once; every later start is immediate, and deleting `.venv` undoes the whole thing. If `uv` is installed it is used instead of pip, which makes rebuilding that folder a matter of seconds.
 
+   **On Windows** the launcher makes `.venv` from Python 3.14, 3.13 or 3.12 when the `py` launcher has one of them, newest first, even if a newer Python is the one on the PATH: those are the versions every library pyflashgui runs on has a ready-made download for. 3.15 is not one of them yet; if it is the only Python installed, `py install 3.14` adds one the launcher will choose.
+
+   **If the Python `.venv` was made with is uninstalled** -- or replaced by a newer version -- the launcher says so, and offers to delete `.venv` and set it up again with the Python installed now. Workspaces and settings are not in `.venv`, and are kept.
+
    **On Linux**, run it from a terminal, so its messages can be read:
 
    ```
@@ -73,7 +81,7 @@ There are three options:
 
    Double-clicking `pyflashgui.sh` in a file manager works too: choose *Run in Terminal* when it asks, for the same reason.
 
-   At the end of the first run it offers to add pyflashgui to the Start menu, or to the applications menu on Linux, and *Tools > Settings > Add shortcut to Start menu* does the same later. The entry starts the launcher, so a start from the menu after a pull still picks up new libraries.
+   For a shortcut, *Tools > Settings > Add shortcut to Start menu* (the applications menu on Linux) and, on Windows, *Add shortcut to desktop*. The entry starts the launcher, so a start from it after a pull still picks up new libraries.
 
    The launcher keeps its own `.venv` on purpose and will not use an environment you already have. That is the point of it: it is the way in for somebody who does not want to think about Python environments, and one that sometimes used yours and sometimes did not would be worse than one that never does. To run a checkout in an environment of your own instead, `pip install -e .` installs it there, reading the source.
 
@@ -110,11 +118,11 @@ CMSIS-DAP is a protocol and not a product, so a great many probes speak it. Amon
 
 **With pyOCD, the target has to be an Arm Cortex-M, whichever probe it is.** The probe carries the debug port; what is on the far side of it is pyOCD's to understand, and Cortex-M is what it understands. A probe that can reach other kinds of processor with its maker's own software -- a Cortex-A or Cortex-R, a RISC-V core -- still reaches only Cortex-M here.
 
-pyflashgui has not yet been tried with any of these probes: this is what pyOCD says it supports, and how.
+**Which Cortex-M devices** is a matter of CMSIS-Packs. pyOCD has a few dozen devices built in; every other is described by a pack its maker publishes. **Tools > pyOCD device packs** finds a device by its part number and downloads the pack it is in, however pyflashgui was installed.
 
 ### Beyond Cortex-M, with a J-Link
 
-pyflashgui can instead drive a J-Link through SEGGER's own J-Link Commander, which comes with SEGGER's J-Link software. That reaches every device SEGGER's software knows -- Cortex-A and Cortex-R, RISC-V and others -- and works with a J-Link and nothing else. SEGGER's software is yours to install, under SEGGER's licence: it is for genuine SEGGER probes, and SEGGER describes J-Link Commander as a tool for development, not for production programming. Of this, listing the probe, connecting and reading have been tried, on one board.
+pyflashgui can instead drive a J-Link through SEGGER's own J-Link Commander, which comes with SEGGER's J-Link software. That reaches every device SEGGER's software knows -- Cortex-A and Cortex-R, RISC-V and others -- and works with a J-Link and nothing else. SEGGER's software is yours to install, under SEGGER's licence: it is for genuine SEGGER probes, and SEGGER describes J-Link Commander as a tool for development, not for production programming.
 
 On Linux a probe is usable without root once a udev rule allows it; pyOCD publishes [a set of them](https://github.com/pyocd/pyOCD/tree/main/udev). Vendor software is never bundled with pyflashgui: install the vendor's own, and pyflashgui finds it.
 
@@ -130,10 +138,11 @@ On Linux a probe is usable without root once a udev rule allows it; pyOCD publis
 
 - **The Windows installer:** *Settings > Apps* (or *Add or remove programs*), or *Uninstall
   pyflashgui* in its Start menu folder. It takes away its shortcuts too.
-- **pip:** `pip uninstall pyflashgui`.
-- **A Git clone:** delete the folder. If a Start menu entry was added, take that away as well:
-  it is `%APPDATA%\Microsoft\Windows\Start Menu\Programs\pyflashgui.lnk` (on Linux,
-  `~/.local/share/applications/pyflashgui.desktop`).
+- **pip:** `pip uninstall pyflashgui`, and what *Tools > Settings* added, as for a clone.
+- **A Git clone:** delete the folder. If *Tools > Settings* was used to add a shortcut, take
+  that away as well: the shortcuts are
+  `%APPDATA%\Microsoft\Windows\Start Menu\Programs\pyflashgui.lnk` and `pyflashgui.lnk` on
+  the desktop (on Linux, `~/.local/share/applications/pyflashgui.desktop`).
 
 Your workspaces and settings are in `%APPDATA%\pyflashgui` (`~/.config/pyflashgui` on Linux),
 and no way of uninstalling touches them; delete that folder to remove them too.

{pyflashgui-0.1.0 → pyflashgui-0.2.1}/pyflashgui/__init__.py

@@ -2,5 +2,5 @@
 # SPDX-FileCopyrightText: 2026 davhodg
 """pyflashgui — a graphical flash programming tool."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 APP_NAME = "pyflashgui"  # single place to change the display name

{pyflashgui-0.1.0 → pyflashgui-0.2.1}/pyflashgui/__main__.py

@@ -29,6 +29,7 @@ SELFTEST_MODULES = (
     "pyflashgui.core.images",
     "pyflashgui.core.memory_map",
     "pyflashgui.backends.pyocd_backend",
+    "pyflashgui.backends.pyocd_packs",
     "pyflashgui.backends.jlink_backend",
     "pyflashgui.backends.simulated",
     "pyflashgui.ui.main_window",
@@ -76,9 +77,19 @@ def selftest() -> int:
     except Exception as exc:
         failures.append(f"pyocd: {exc}")
 
+    # Tools > pyOCD device packs is the only way an installed copy has of getting a
+    # target pyOCD has not built in, and what does it is a native library.
+    # Opening the store of packs loads it; nothing is downloaded.
+    try:
+        from pyflashgui.backends import pyocd_packs
+
+        pyocd_packs.installed()
+    except Exception as exc:
+        failures.append(f"device packs: {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.
+    # CMSIS-DAP v2 probe and no ST-Link, so the self-test checks for it.
     try:
         import libusb_package
 
@@ -149,7 +160,8 @@ def set_icon(app) -> None:
 
 #: 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.
+#: "could not load the Qt platform plugin xcb", so they are looked for first
+#: and the package to install is named.
 XCB_LIBRARIES = (
     ("libxcb-cursor.so.0", "libxcb-cursor0"),
     ("libxcb-icccm.so.4", "libxcb-icccm4"),

{pyflashgui-0.1.0 → pyflashgui-0.2.1}/pyflashgui/backends/base.py

@@ -28,8 +28,10 @@ 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]
+#: Called with how far along something is, from 0.0 to 1.0, and -- where
+#: one piece of work is done in stages -- what is being done now, when that
+#: changes: "Erasing", then "Programming".
+Progress = Callable[..., None]
 #: Asked between steps whether to stop. True means somebody pressed Cancel.
 Cancelled = Callable[[], bool]
 
@@ -37,6 +39,24 @@ Cancelled = Callable[[], bool]
 ERASE_SECTORS = "sectors"
 #: Erase all of the flash first, so nothing of what was there is left.
 ERASE_CHIP = "chip"
+#: Erase nothing: the flash written to was erased beforehand. Flash can only
+#: be written where it is blank; written over anything else, it holds
+#: neither what was there nor what was written.
+ERASE_NONE = "none"
+
+#: Ways of restarting a target. Not every device restarts properly every
+#: way: an XMC4500 asked to reset itself through pyOCD stayed stopped, and
+#: started from its reset pin, as from its reset button.
+#: The backend's own choice for the target: for most, the next one.
+RESET_DEFAULT = "default"
+#: The processor asked to reset the whole device (SYSRESETREQ).
+RESET_SYSTEM = "system"
+#: The device's reset line pulled by the probe, as its reset button does.
+#: Only where the probe is wired to it: some, the Raspberry Pi Debug Probe
+#: among them, are not.
+RESET_PIN = "pin"
+#: The processor alone, leaving the rest of the device as it is.
+RESET_CORE = "core"
 
 #: 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
@@ -114,6 +134,12 @@ class Connection(ABC):
     a probe left attached is one nothing else can use.
     """
 
+    #: The debug clock it runs at, said in the Event Log on connecting:
+    #: "4 MHz", or how the backend chooses it. Empty where it cannot say.
+    speed: str = ""
+    #: Anything else worth saying on connecting, a sentence each.
+    notes: tuple[str, ...] = ()
+
     @abstractmethod
     def regions(self) -> list[Region]:
         """The target's memory, as it turned out to be once connected."""
@@ -136,9 +162,12 @@ class Connection(ABC):
         segments: Sequence[Segment],
         erase: str = ERASE_SECTORS,
         progress: Progress = _nothing,
-    ) -> None:
+    ) -> str | None:
         """Erase what has to be erased and write these bytes.
 
+        Returns anything about how it went worth saying in the Event Log, a
+        sentence, or None.
+
         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.
@@ -148,14 +177,36 @@ class Connection(ABC):
     def read(self, address: int, length: int) -> bytes:
         """This many bytes of the target's memory, from this address."""
 
+    def write(self, address: int, data: bytes) -> None:
+        """Write these bytes to RAM, or to a peripheral's registers, as they are.
+
+        Not for flash, which has to be erased before it can be written and
+        is written by ``program``. A backend that cannot says so.
+        """
+        raise BackendError("This way of reaching the probe cannot write to memory.")
+
     @abstractmethod
-    def reset(self, halt: bool = False) -> None:
-        """Restart the target, and leave it running unless ``halt``."""
+    def reset(self, halt: bool = False, kind: str = RESET_DEFAULT) -> str | None:
+        """Restart the target, and leave it running unless ``halt``.
+
+        ``kind`` is one of the backend's ``reset_kinds``. Returns anything
+        about it worth saying in the Event Log, a sentence, or None.
+        """
 
     @abstractmethod
     def close(self) -> None:
         """Let go of the probe. Safe to call twice."""
 
+    def details(self) -> list[str]:
+        """What Help > Diagnostics says of this connection, a line each.
+
+        How the backend was asked to connect and what it found there, beyond
+        the probe and the target the window already knows. Read on the
+        window's thread while the worker may be using the connection, so
+        only what is already known is said: nothing here asks the probe.
+        """
+        return []
+
     def read_range(
         self,
         address: int,
@@ -235,6 +286,18 @@ class Backend(ABC):
     #: 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
+    #: What the speed box offers first, for leaving the speed to the
+    #: backend: said with what that comes to, since it is not always fast.
+    default_speed: str = "Default"
+    #: The ways it can restart a target, the one used unless told otherwise
+    #: first.
+    reset_kinds: tuple[str, ...] = (RESET_DEFAULT,)
+    #: Whether it can connect leaving the target running, rather than only
+    #: stopping it: ``connect``'s ``stop``.
+    can_attach: bool = False
+    #: Whether it can program without erasing first, for flash erased
+    #: already: ``ERASE_NONE``.
+    can_skip_erase: bool = False
     #: 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
@@ -263,6 +326,7 @@ class Backend(ABC):
         target: str,
         frequency: int | None = None,
         interface: str | None = None,
+        stop: bool = True,
     ) -> Connection:
         """Attach the probe with this unique id to a target of this name.
 

{pyflashgui-0.1.0 → pyflashgui-0.2.1}/pyflashgui/backends/jlink_backend.py

@@ -36,6 +36,7 @@ from pathlib import Path
 from pyflashgui.backends.base import (
     ERASE_CHIP,
     ERASE_SECTORS,
+    RESET_DEFAULT,
     Backend,
     BackendError,
     Cancelled,
@@ -71,13 +72,14 @@ NOT_FOUND = (
 )
 
 #: Said by Commander when the probe is there and the device does not answer.
-#: Looked for as well as its exit code, which has been seen to be 0 with it.
+#: Looked for as well as its exit code, which can be 0 with it.
 NO_TARGET = "Cannot connect to target"
 
-#: A J-Link script that does nothing where SEGGER's software would set the
+#: A J-Link script that does nothing where J-Link's software would set the
 #: device up after connecting to it. On some parts that set-up writes to
 #: the device -- an S32K3's RAM is filled, for its error correction -- and
-#: a read made to see what a running program left there finds it gone.
+#: a read made to see what a running program left there finds the set-up's
+#: bytes instead.
 NO_SETUP_SCRIPT = "int SetupTarget(void) {\n  return 0;\n}\n"
 
 #: Where Commander is, when it has been said. None to go and look.
@@ -145,6 +147,20 @@ def find_commander() -> list[str] | None:
     return None
 
 
+def report() -> list[str]:
+    """For Help > Diagnostics: the Commander used, how it was found, and every
+    J-Link software folder there is, newest first."""
+    found = find_commander()
+    if found is None:
+        lines = ["not found"]
+    else:
+        how = "chosen in Tools > Settings" if _chosen is not None else "found"
+        lines = [f"{' '.join(found)} ({how})"]
+    folders = _installed()
+    lines += [f"installed: {folder}" for folder in folders] or ["no J-Link software folder found"]
+    return lines
+
+
 def _is_seggers(program: Path) -> bool:
     """Whether a program of Commander's name is Commander, and not Java's jlink.
 
@@ -247,6 +263,38 @@ def run(arguments: Sequence[str], commands: Sequence[str], timeout: float, doing
 
 
 # --- reading what Commander says ---------------------------------------------------------
+#: The line SEGGER's software ends a download with, saying how long each part
+#: took: ``J-Link: Flash download: Total: 3.052s (Prepare: 0.071s, Compare:
+#: 0.014s, Erase: 1.890s, Program & Verify: 1.029s, Restore: 0.046s)``. Older
+#: versions say "Total time needed".
+_DOWNLOAD = re.compile(
+    r"Flash download:\s*Total(?: time needed)?:\s*([\d.]+)\s*s\s*\(([^)]*)\)", re.I
+)
+_PART = re.compile(r"([A-Za-z& ]+?):\s*([\d.]+)\s*s")
+#: Said when the flash held the image already, and nothing was written.
+_SKIPPED = re.compile(r"Flash download:\s*Skipped", re.I)
+
+
+def download_text(output: str) -> str | None:
+    """What J-Link said a download did, as a sentence: what it took to erase,
+    and to program and check, which happen inside one command and cannot be
+    shown as they go. None if it did not say."""
+    if _SKIPPED.search(output) and not _DOWNLOAD.search(output):
+        return "J-Link found the flash held this already, and wrote nothing."
+    found = _DOWNLOAD.search(output)
+    if found is None:
+        return None
+    parts = {name.strip().lower(): float(seconds) for name, seconds in _PART.findall(found[2])}
+    said = []
+    if "erase" in parts:
+        said.append(f"erased in {parts['erase']:.1f} s")
+    if "program & verify" in parts:
+        said.append(f"programmed and checked in {parts['program & verify']:.1f} s")
+    if not said:
+        return None
+    return f"J-Link {' and '.join(said)}, {float(found[1]):.1f} s in all."
+
+
 #: One line of ShowEmuList for each J-Link:
 #: ``J-Link[0]: Connection: USB, Serial number: 801012345, ProductName: J-Link PLUS``
 _PROBE = re.compile(r"Serial number:\s*(\d+)(?:.*?ProductName:\s*([^,\r\n]+))?", re.I)
@@ -374,6 +422,11 @@ class JLinkConnection(Connection):
     def regions(self) -> list[Region]:
         return list(self._regions)
 
+    def details(self) -> list[str]:
+        if self._arguments is None:
+            return ["closed"]
+        return [f"device: {self._device}", f"Commander run with: {' '.join(self._arguments)}"]
+
     def erase_chip(self) -> None:
         self._run(["H", "Erase"], WORK_S, f"Erasing {self._device}")
 
@@ -390,7 +443,7 @@ class JLinkConnection(Connection):
         segments: Sequence[Segment],
         erase: str = ERASE_SECTORS,
         progress: Progress = _nothing,
-    ) -> None:
+    ) -> str | None:
         if erase not in (ERASE_SECTORS, ERASE_CHIP):
             raise BackendError(f"There is no way of erasing called {erase!r}.")
         import bincopy
@@ -413,8 +466,9 @@ class JLinkConnection(Connection):
             # LoadFile erases the sectors it writes to, and checks what it
             # wrote, by itself.
             commands.append(f"LoadFile {_named(path)}")
-            self._run(commands, WORK_S, f"Programming {self._device}")
+            said = self._run(commands, WORK_S, f"Programming {self._device}")
         progress(1.0)
+        return download_text(said)
 
     def read(
         self, address: int, length: int, resume: bool = False, skip_setup: bool = False
@@ -491,7 +545,20 @@ class JLinkConnection(Connection):
             progress(checked / total)
         return Verification(checked=checked, different=different, first=first)
 
-    def reset(self, halt: bool = False) -> None:
+    def write(self, address: int, data: bytes) -> None:
+        """Stopped while it is written, and set going again, as a read is."""
+        with tempfile.TemporaryDirectory(prefix="pyflashgui-jlink-") as folder:
+            path = Path(folder) / "write.bin"
+            path.write_bytes(data)
+            commands = ["H", f"LoadBin {_named(path)}, 0x{address:X}", "G"]
+            self._run(commands, WORK_S, f"Writing {len(data)} bytes at {address:08X}")
+
+    def reset(self, halt: bool = False, kind: str = RESET_DEFAULT) -> None:
+        if kind != RESET_DEFAULT:
+            raise BackendError(
+                "Through J-Link Commander, a device is reset the usual way only. The other "
+                "ways are offered through pyOCD."
+            )
         # R restarts the device and leaves it stopped; G sets it going.
         self._run(["R"] if halt else ["R", "G"], QUICK_S, f"Resetting {self._device}")
 
@@ -500,6 +567,8 @@ class JLinkConnection(Connection):
 
 
 class JLinkBackend(Backend):
+    # Commander's -speed auto: the J-Link finds the fastest that works.
+    default_speed = "Default (auto)"
     name = "jlink"
     label = "J-Link Commander"
     interfaces = INTERFACES
@@ -535,8 +604,8 @@ class JLinkBackend(Backend):
                 # it that is not, and latin-1 reads any byte there is.
                 text = path.read_text(encoding="latin-1")
             except (BackendError, OSError):
-                # A Commander that will not write the list still programs a
-                # device whose name is typed in.
+                # Without the list, a device whose name is typed in is still
+                # programmed.
                 text = ""
         self._devices = {device.name.upper(): device for device in parse_devices(text)}
         return self._devices
@@ -561,6 +630,7 @@ class JLinkBackend(Backend):
         target: str,
         frequency: int | None = None,
         interface: str | None = None,
+        stop: bool = True,
     ) -> Connection:
         if not probe:
             raise BackendError("No J-Link is chosen.")
@@ -593,4 +663,6 @@ class JLinkBackend(Backend):
         # With nothing to do but leave: a run that comes back clean has
         # opened the probe and found the device answering.
         run(arguments, [], QUICK_S, f"Connecting to {target}")
-        return JLinkConnection(arguments, target, regions)
+        connection = JLinkConnection(arguments, target, regions)
+        connection.speed = "the speed J-Link chooses" if speed == "auto" else f"{speed} kHz"
+        return connection