mfreak-peek 0.1.0__tar.gz

mfreak_peek-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Arturia's binaries are NEVER committed here. Firmware payloads, .mff
+# containers, bootloader dumps and factory vocabulary are the user's own
+# property and every command takes them as an explicit argument. See NOTICE.
+*.mff
+*.raw
+*.bin
+# SysEx dumps and audio the tools produce. A .syx or a .wav off the
+# instrument is the user's own data, the same as the binaries above, and
+# `audition` writes WAVs when pointed at a directory with --out-dir.
+*.syx
+*.wav
+
+# Scratch space: anything in ignored/ stays out of git.
+ignored/
+.DS_Store

mfreak_peek-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mfreak_peek-0.1.0/NOTICE

@@ -0,0 +1,103 @@
+microfreak-tools
+Copyright 2025-2026 Greg Bryant
+
+This product includes software developed as original work by the above
+copyright holder, licensed under the Apache License, Version 2.0 (see
+LICENSE).
+
+It also includes third-party material, which is licensed separately and
+retains its own copyright. The sections below are the attributions those
+licenses require.
+
+
+================================================================================
+Mutable Instruments Plaits -- MIT
+================================================================================
+
+The MicroFreak's Speech engine is Mutable Instruments' Plaits LPC speech
+synthesiser. This was established by byte-exact comparison against
+`pichenettes/eurorack`, not by inference: the 14-byte frame struct, the
+15-entry phoneme table, the quantisation lookup tables, the 640-entry
+excitation pulse, and the word banks all match the published MIT source
+value for value. The evidence is recorded in the companion
+analysis repository, microfreak-emu.
+
+Because that upstream source is MIT, the tables in this repository are
+redistributable under the terms below. They are Emilie Gillet's work, not
+Arturia's and not this project's.
+
+The following files contain material derived from `pichenettes/eurorack`:
+
+    microfreak/lpc.py
+                       the energy, period and k0..k9 quantisation tables, and
+                       the LPC bitstream layout, from
+                       plaits/dsp/speech/lpc_speech_synth_controller.cc and
+                       plaits/dsp/speech/lpc_speech_synth.h
+
+    plugins/speech/mfreak_speech/render.py
+                       a Python port of LPCSpeechSynth, and the 640-entry
+                       int8 excitation pulse `lut_lpc_excitation_pulse`,
+                       from plaits/dsp/speech/lpc_speech_synth.cc and
+                       plaits/resources.cc
+
+Copyright 2016 Emilie Gillet.
+
+Author: Emilie Gillet (emilie.o.gillet@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+================================================================================
+Texas Instruments LPC10 speech data -- NOT redistributed
+================================================================================
+
+Plaits' five factory word banks are, in its own description, "LPC10-encoded
+speech data extracted from Texas Instruments ROMs". The MicroFreak's banks
+match them byte for byte.
+
+This repository does not contain that data and must not come to contain it.
+The tooling reads the banks out of a firmware image the user already owns,
+at run time, and never writes them into source or into a committed artefact.
+Keep it that way: the MIT licence covering the Plaits code around them is
+not an obvious grant for speech recorded off a TI ROM, and nothing here
+depends on redistributing it.
+
+
+================================================================================
+Arturia -- no code, no binaries, no affiliation
+================================================================================
+
+This project is not affiliated with, authorised by, endorsed by or connected
+to Arturia in any way. "Arturia" and "MicroFreak" are trademarks of their
+respective owners and are used here only to identify the hardware this
+tooling was written for.
+
+No Arturia code or data is included in this repository, and none should
+ever be added to it. There are no firmware images, no bootloader dumps, no
+factory vocabulary banks, no factory presets and no protocol captures here --
+not gitignored copies of them, not samples of them, none. `.gitignore` refuses
+`*.mff`, `*.raw` and `*.bin` as a second line of defence, but the first is that
+every command takes the file it needs as an explicit argument.
+
+Nothing is downloaded either. `fw patch` requires `--image`, pointing at a
+payload you already own, and refuses any payload whose sha256 is not the one
+its addresses were derived against.
+
+Source comments and docstrings here describe observed behaviour and give
+addresses within a firmware image. They do not reproduce it.

mfreak_peek-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: mfreak-peek
+Version: 0.1.0
+Summary: A read-only diagnostic MicroFreak firmware patch, and a bootloader dump, for microfreak-tools. Not affiliated with Arturia.
+Project-URL: Homepage, https://github.com/gbryant/microfreak-tools
+Project-URL: Issues, https://github.com/gbryant/microfreak-tools/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: <3.15,>=3.11
+Requires-Dist: microfreak-tools<0.2,>=0.1.0
+Description-Content-Type: text/markdown
+
+# mfreak-peek
+
+A read-only diagnostic firmware patch for the Arturia MicroFreak, and a
+bootloader dump. A plugin for
+[microfreak-tools](https://github.com/gbryant/microfreak-tools). Not
+affiliated with Arturia.
+
+    uv tool install microfreak-tools --with mfreak-peek
+
+The patch is stock firmware that can also read its own memory over SysEx.
+Installing it writes flash:
+
+    mfreak fw patch peek MicroFreak_Firmware_Update_5_0_0_2084.mff --out peek.mff
+    mfreak fw flash peek.mff
+    mfreak peek dump-bootloader --out bootloader.bin
+
+The bootloader dump contains your instrument's serial number. Keep it
+private. To remove the patch, flash the stock `.mff`. Read "Before you
+flash" in the microfreak-tools README first.
+
+Apache-2.0.

mfreak_peek-0.1.0/README.md

@@ -0,0 +1,21 @@
+# mfreak-peek
+
+A read-only diagnostic firmware patch for the Arturia MicroFreak, and a
+bootloader dump. A plugin for
+[microfreak-tools](https://github.com/gbryant/microfreak-tools). Not
+affiliated with Arturia.
+
+    uv tool install microfreak-tools --with mfreak-peek
+
+The patch is stock firmware that can also read its own memory over SysEx.
+Installing it writes flash:
+
+    mfreak fw patch peek MicroFreak_Firmware_Update_5_0_0_2084.mff --out peek.mff
+    mfreak fw flash peek.mff
+    mfreak peek dump-bootloader --out bootloader.bin
+
+The bootloader dump contains your instrument's serial number. Keep it
+private. To remove the patch, flash the stock `.mff`. Read "Before you
+flash" in the microfreak-tools README first.
+
+Apache-2.0.

mfreak_peek-0.1.0/mfreak_peek/__init__.py

@@ -0,0 +1,22 @@
+"""mfreak-peek: a read-only diagnostic firmware, and the commands that use it."""
+from microfreak.plugin import Command, Firmware, Plugin
+
+plugin = Plugin(
+    name="peek",
+    help="read the instrument's memory, and dump your bootloader",
+    doctor="mfreak_peek.doctor",
+    firmware=Firmware(
+        "mfreak_peek.build",
+        help="stock firmware that can also read its own memory",
+        identity="P"),
+    commands={
+        "dump-bootloader": Command(
+            "mfreak_peek.bootloader",
+            help="read your bootloader out (the file holds your serial)",
+            device=True, writes="file",
+            summary="Read your bootloader out over MIDI. Read-only on the "
+                    "device. THE FILE CONTAINS YOUR SERIAL NUMBER: do not "
+                    "publish it, or use --redact-serial. Needs the peek "
+                    "build flashed first."),
+    },
+)

mfreak_peek-0.1.0/mfreak_peek/bootloader.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Read your instrument's bootloader out of flash, over MIDI.
+
+    mfreak fw patch peek stock.mff --out peek.mff
+    mfreak fw flash peek.mff
+    mfreak peek dump-bootloader --out bootloader.bin
+    mfreak fw flash stock.mff
+
+Arturia's firmware files do not include the 48 KB bootloader, so this is the
+only way to get a copy. It needs the peek build installed. It only reads,
+and writes nothing to the instrument.
+
+The file contains your instrument's serial number. Do not publish it, attach
+it to a bug report, or commit it. --redact-serial zeroes the serial; the rest
+of the factory data page is written as read.
+
+microfreak-emu boots the real bootloader from this file: put it in that
+repository's data/bootloader/ folder.
+"""
+import argparse
+import random
+import sys
+import time
+
+from microfreak.firmware.peek import peek_reply
+from mfreak_peek.build import peek_message_nibble
+from microfreak.midi import open_synth, checksum_free_seq
+from microfreak import jsonout
+
+BASE = 0x08000000
+SIZE = 48 << 10                 # sectors 0, 1 and 2
+WORDS = SIZE // 4
+
+# The factory data page, and the serial's offset inside it. Measured: the page
+# starts at 0x08008000 and the serial is its first record -- sixteen ASCII
+# digits that fill the field exactly, with the NUL terminator after it at
+# +0x10, outside the field and outside what `redact` touches.
+DATA_PAGE = 0x08008000
+SERIAL_OFF, SERIAL_LEN = 0x00, 0x10
+
+
+def peek_word(synth, addr, seqgen, tries=4):
+    """-> the 32-bit word at `addr`, or None.
+
+    A blocked or never-dispatched peek STILL REPLIES, carrying whatever the
+    last successful one left in the septet slots, and the sequence number does
+    not catch it -- the dispatcher refreshes seq from the incoming message, so
+    a stale reply passes a seq check. That is why the dump is verified by
+    re-reading a sample afterwards rather than trusted request by request.
+    """
+    for _ in range(tries):
+        seq = next(seqgen)
+        synth.send(list(peek_message_nibble(addr, seq=seq)))
+        try:
+            reply = synth.recv(
+                lambda m: peek_reply(bytes(m), seq=seq) is not None, timeout=2.0)
+        except TimeoutError:
+            continue
+        word = peek_reply(bytes(reply), seq=seq)
+        if word is not None:
+            return word
+    return None
+
+
+def looks_like_a_vector_table(words):
+    """Is this actually the bootloader? -> (ok, why).
+
+    Three structural facts, all of them true of any Cortex-M image and none of
+    them true of a buffer of zeros, a buffer of 0xFF or a stale-reply smear:
+    the initial SP points into this chip's SRAM, the reset vector points into
+    the low 48 KB with the Thumb bit set, and the two differ.
+    """
+    if len(words) < 2:
+        return False, "no data"
+    sp, reset = words[0], words[1]
+    if not 0x20000000 <= sp <= 0x20020000:
+        return False, ("initial SP reads 0x%08X, which is not SRAM on this "
+                       "part -- the reads are not returning flash" % sp)
+    if not (BASE <= (reset & ~1) < BASE + SIZE):
+        return False, ("reset vector reads 0x%08X, which is not inside the "
+                       "bootloader" % reset)
+    if not reset & 1:
+        return False, ("reset vector 0x%08X has the Thumb bit clear, which no "
+                       "Cortex-M image has" % reset)
+    if len(set(words[:16])) < 4:
+        return False, ("the first 16 vectors are nearly all the same value, "
+                       "which is what a stale-reply smear looks like")
+    return True, "SP 0x%08X, reset 0x%08X" % (sp, reset)
+
+
+def redact(blob):
+    """Zero the serial's sixteen bytes. -> (blob, what was there).
+
+    Only those bytes. The rest of the factory data page is left as read.
+    """
+    off = DATA_PAGE - BASE + SERIAL_OFF
+    was = bytes(blob[off:off + SERIAL_LEN])
+    text = "".join(chr(b) if 0x20 <= b < 0x7F else "." for b in was)
+    blob[off:off + SERIAL_LEN] = b"\0" * SERIAL_LEN
+    return blob, text
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__.splitlines()[0],
+        epilog="\n".join(__doc__.splitlines()[1:]),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out", required=True, metavar="FILE",
+                    help="where to write the 48 KB image")
+    ap.add_argument("--port", default="MicroFreak",
+                    help="MIDI port substring (default: MicroFreak)")
+    ap.add_argument("--verify", type=int, default=256, metavar="N",
+                    help="re-read N random words afterwards and compare; "
+                         "0 skips it, which is not recommended (default: 256)")
+    ap.add_argument("--redact-serial", action="store_true",
+                    help="blank the serial number in the output")
+    args = ap.parse_args()
+
+    synth = open_synth(port_substring=args.port)
+    seqgen = checksum_free_seq()
+    print("reading 0x%08X..0x%08X (%d words) over MIDI" % (BASE, BASE + SIZE, WORDS))
+    print("this needs the peek build: `mfreak fw patch peek`\n")
+
+    blob = bytearray(SIZE)
+    started = time.time()
+    missing = []
+    for i in range(WORDS):
+        addr = BASE + i * 4
+        word = peek_word(synth, addr, seqgen)
+        if word is None:
+            missing.append(addr)
+            word = 0xFFFFFFFF
+        blob[i * 4:i * 4 + 4] = word.to_bytes(4, "little")
+        if i % 256 == 0 or i == WORDS - 1:
+            done = i + 1
+            rate = done / max(time.time() - started, 0.001)
+            print("\r  %5d/%d words  %5.1f%%  %4.0f words/s  %d failed"
+                  % (done, WORDS, 100.0 * done / WORDS, rate, len(missing)),
+                  end="", flush=True)
+    print()
+
+    words = [int.from_bytes(blob[k:k + 4], "little") for k in range(0, 64, 4)]
+    ok, why = looks_like_a_vector_table(words)
+    print("\nvector table: %s  (%s)" % ("plausible" if ok else "WRONG", why))
+    if not ok:
+        print("\nRefusing to write it. Nothing here is a bootloader.", file=sys.stderr)
+        return 1
+    if missing:
+        print("%d words never answered and are 0xFFFFFFFF in the file: %s%s"
+              % (len(missing), ", ".join("0x%08X" % a for a in missing[:6]),
+                 " ..." if len(missing) > 6 else ""))
+
+    if args.verify:
+        n = min(args.verify, WORDS)
+        print("\nverifying %d random words" % n)
+        bad = []
+        for addr in sorted(random.sample(range(WORDS), n)):
+            again = peek_word(synth, BASE + addr * 4, seqgen)
+            first = int.from_bytes(blob[addr * 4:addr * 4 + 4], "little")
+            if again is not None and again != first:
+                bad.append((BASE + addr * 4, first, again))
+        if bad:
+            print("  %d of %d disagreed on a re-read:" % (len(bad), n))
+            for a, f, s in bad[:8]:
+                print("    0x%08X  0x%08X -> 0x%08X" % (a, f, s))
+            print("\nRe-reads disagree, so the dump cannot be trusted. "
+                  "Not writing it.", file=sys.stderr)
+            return 1
+        print("  all %d agreed" % n)
+
+    if args.redact_serial:
+        blob, was = redact(blob)
+        # Do NOT echo the serial. The whole point of this flag is a file that
+        # is safe to share, and the terminal is the thing people paste into
+        # bug reports. Report the length so it is clear something was there.
+        blanked = sum(1 for c in was if c != ".")
+        print("\nserial field blanked: %d bytes at 0x%08X+0x%X, %d of them "
+              "printable."
+              % (SERIAL_LEN, DATA_PAGE, SERIAL_OFF, blanked))
+    else:
+        print("\n*** This file contains your instrument's SERIAL NUMBER, in the")
+        print("*** factory data page at 0x%08X. Do not publish it. Re-run with" % DATA_PAGE)
+        print("*** --redact-serial to zero those sixteen bytes.")
+
+    with open(args.out, "wb") as fh:
+        fh.write(bytes(blob))
+    # A caller has to know whether the file it now holds carries the serial.
+    jsonout.result(out=args.out, bytes=len(blob),
+                   serial_redacted=bool(args.redact_serial),
+                   contains_serial=not args.redact_serial,
+                   do_not_publish=not args.redact_serial)
+    print("\nwrote %s, %d bytes" % (args.out, len(blob)))
+    print("Use it with microfreak-emu:  cp %s <microfreak-emu>/data/bootloader/"
+          % args.out)
+    print("Then put your own firmware back on the instrument.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mfreak_peek-0.1.0/mfreak_peek/build.py

@@ -0,0 +1,295 @@
+"""A read-only diagnostic build: stock firmware that can also read its own
+memory, flash included. `mfreak peek dump-bootloader` needs it.
+
+    mfreak fw patch peek MicroFreak_Firmware_Update_5_0_0_2084.mff --out peek.mff
+    mfreak fw flash peek.mff
+
+Apart from that, the boot screen reads PATCHED peek18, asked for its version
+over MIDI it answers 5.0.P, build 18, and a fault reboots the instrument
+instead of hanging it. Flash the stock .mff again when you are done.
+"""
+import argparse
+import struct
+import sys
+
+from microfreak.firmware import patching as F
+from microfreak.firmware.patching import (BASE, OPCODE_BIAS, OPCODE_MAGIC,
+                                          OPCODE_TAIL, REPLY_BUILDER,
+                                          REPLY_CODE, assemble, beqw, bw)
+from microfreak.firmware.peek import PEEK_BASE, PEEK_OPCODE, PEEK_SPAN
+
+FLAVOUR, REV = "peek", 19
+NIBBLE_OPCODE = 0x46             # the nibble-addressed read
+
+# Every fault vector points at the `b .` at 0x0805F89C: NMI, HardFault,
+# MemManage, BusFault, UsageFault and every unused IRQ. This build points them
+# at `fault_handler` instead.
+DEFAULT_HANDLER = 0x0805F89D      # Thumb bit set
+VECTOR_TABLE = 0x0800C000         # the image base is the vector table
+NUM_VECTORS = 0x1A0 // 4
+
+# The reset handler zeroes .bss only up to 0x2001F230, and 0x2001F238..
+# 0x2001FB00 is never touched in normal running, so the dump goes there.
+FAULT_DUMP = 0x2001F240
+FAULT_MAGIC = 0xFA017DEA
+SCB_BASE = 0xE000ED00
+
+# What the handler writes, in order. Read it with the nibble opcode: the
+# septet form of its address is one the septet read cannot send safely.
+FAULT_FIELDS = ["magic", "ICSR", "CFSR", "HFSR", "MMFAR", "BFAR",
+                "stacked_PC", "stacked_LR", "stacked_xPSR", "frame_SP"]
+
+
+def fault_handler(base, dump_at=FAULT_DUMP, resume=False):
+    """-> bytes. Record why the instrument faulted, then reset.
+
+    Writes the ten FAULT_FIELDS words at `dump_at`. With `resume` it instead
+    skips the faulting instruction and returns, so the dump can be read at
+    once; a reset clears it. A fault that repeats under `resume` loops, which
+    hangs the instrument like the stock handler does.
+    """
+    src = """
+        mrs   r0, msp             // handler mode always runs on MSP...
+        tst   lr, #4              // ...but the FRAME may be on PSP
+        beq   1f
+        mrs   r0, psp
+    1:  movw  r1, #%#x
+        movt  r1, #%#x
+        movw  r2, #%#x
+        movt  r2, #%#x
+        ldr   r3, [r1, #0x04]     // ICSR -- VECTACTIVE says WHICH exception
+        str   r3, [r2, #4]
+        ldr   r3, [r1, #0x28]     // CFSR
+        str   r3, [r2, #8]
+        ldr   r3, [r1, #0x2c]     // HFSR
+        str   r3, [r2, #12]
+        ldr   r3, [r1, #0x34]     // MMFAR
+        str   r3, [r2, #16]
+        ldr   r3, [r1, #0x38]     // BFAR
+        str   r3, [r2, #20]
+        ldr   r3, [r0, #24]       // stacked PC -- the faulting instruction
+        str   r3, [r2, #24]
+        ldr   r3, [r0, #20]       // stacked LR
+        str   r3, [r2, #28]
+        ldr   r3, [r0, #28]       // stacked xPSR
+        str   r3, [r2, #32]
+        str   r0, [r2, #36]       // the frame pointer itself
+        movw  r3, #%#x
+        movt  r3, #%#x
+        str   r3, [r2, #0]        // magic LAST: present => the rest is complete
+    """ % (SCB_BASE & 0xFFFF, SCB_BASE >> 16,
+           dump_at & 0xFFFF, dump_at >> 16,
+           FAULT_MAGIC & 0xFFFF, FAULT_MAGIC >> 16)
+    if resume:
+        src += """
+        ldr   r2, [r0, #24]       // stacked PC
+        ldrh  r3, [r2]            // its first halfword
+        movw  r12, #0xe800        // >= 0xE800 means a 32-bit Thumb encoding
+        cmp   r3, r12
+        ite   lo
+        addlo r2, r2, #2
+        addhs r2, r2, #4
+        str   r2, [r0, #24]       // resume PAST the faulting instruction
+        mvn   r3, #0
+        str   r3, [r1, #0x28]     // CFSR is write-1-to-clear
+        str   r3, [r1, #0x2c]     // HFSR likewise
+        dsb
+        isb
+        bx    lr                  // EXC_RETURN: back to the thread
+    """
+    else:
+        src += """
+        dsb
+        movw  r3, #0x0004
+        movt  r3, #0x05fa
+        str   r3, [r1, #0x0c]     // SCB->AIRCR = SYSRESETREQ
+        dsb
+    2:  b     2b                  // the reset lands before this spins twice
+    """
+    return assemble(src)
+
+
+def decode_fault(words):
+    """-> a readable dump, or None if the magic is absent."""
+    if not words or words[0] != FAULT_MAGIC:
+        return None
+    out, icsr = {}, words[1]
+    for name, v in zip(FAULT_FIELDS, words):
+        out[name] = v
+    out["vectactive"] = icsr & 0x1FF
+    out["exception"] = {2: "NMI", 3: "HardFault", 4: "MemManage", 5: "BusFault",
+                        6: "UsageFault"}.get(icsr & 0x1FF,
+                                             "IRQ %d" % ((icsr & 0x1FF) - 16))
+    cfsr = out["CFSR"]
+    out["cfsr_bits"] = [n for b, n in (
+        (0, "IACCVIOL"), (1, "DACCVIOL"), (3, "MUNSTKERR"), (4, "MSTKERR"),
+        (7, "MMARVALID"), (8, "IBUSERR"), (9, "PRECISERR"), (10, "IMPRECISERR"),
+        (11, "UNSTKERR"), (12, "STKERR"), (15, "BFARVALID"),
+        (16, "UNDEFINSTR"), (17, "INVSTATE"), (18, "INVPC"), (19, "NOCP"),
+        (24, "UNALIGNED"), (25, "DIVBYZERO")) if cfsr & (1 << b)]
+    out["hfsr_bits"] = [n for b, n in (
+        (1, "VECTTBL"), (30, "FORCED"), (31, "DEBUGEVT"))
+        if out["HFSR"] & (1 << b)]
+    return out
+
+
+def peek_only_handlers(base, peek_base=None, letter="P", rev=None):
+    """-> bytes: two read handlers and the identity, entered from the dispatcher.
+
+        opcode 0x44  three septets, ORed onto `peek_base`
+        opcode 0x46  eight nibbles, high first: the full 32-bit address
+        opcode 0x48  the build's letter and revision, F.who_word
+
+    Both need the magic in `cat`. A message without it still gets a reply, so
+    the host can tell a refused read from a hung instrument.
+    """
+    pb = PEEK_BASE if peek_base is None else peek_base
+    src = """
+        cmp   r2, #%#x            // the nibble opcode, biased
+        nop                       //   -> beq.w the nibble handler
+        nop
+
+        ldrb  r0, [r5, #6]        // magic guard
+        cmp   r0, #%#x
+        bne   8f
+        cmp   r2, #%#x            // 0x48, biased
+        beq   4f
+
+        ldrb  r0, [r5, #8]        // --- 0x44: three septets
+        ldrb  r1, [r5, #9]
+        ldrb  r2, [r5, #10]
+        orr   r0, r0, r1, lsl #7
+        orr   r0, r0, r2, lsl #14
+        orr   r0, r0, #%#x
+        b     7f
+
+    4:  movw  r0, #%#x            // --- 0x48: who this is
+        b     5f
+
+    9:  ldrb  r0, [r5, #6]        // --- 0x46: eight nibbles, full 32 bits
+        cmp   r0, #%#x
+        bne   8f
+        movs  r0, #0
+        movs  r2, #8
+        add   r1, r5, #8
+    6:  ldrb  r3, [r1]
+        and   r3, r3, #0x0f
+        orr   r0, r3, r0, lsl #4
+        adds  r1, r1, #1
+        subs  r2, r2, #1
+        bne   6b
+
+    7:  ldr   r0, [r0]            // the one load, shared
+    5:  movs  r2, #5
+        add   r1, r4, #1
+    1:  and   r3, r0, #0x7f
+        strb  r3, [r1]
+        adds  r1, r1, #1
+        lsrs  r0, r0, #7
+        subs  r2, r2, #1
+        bne   1b
+        movs  r3, #%#x
+        nop                       //   -> b.w REPLY_BUILDER
+        nop
+
+    8:  nop                       //   -> b.w OPCODE_TAIL (guard bailed, replies)
+        nop
+    """ % (NIBBLE_OPCODE - OPCODE_BIAS, OPCODE_MAGIC, F.WHO_OPCODE - OPCODE_BIAS,
+           pb, F.who_word(letter, REV if rev is None else rev), OPCODE_MAGIC,
+           REPLY_CODE)
+    code = bytearray(assemble(src))
+
+    # Patch the three wide branches by locating their placeholders, so a change
+    # to the source above cannot silently patch the wrong bytes.
+    cmp_nib = bytes([(NIBBLE_OPCODE - OPCODE_BIAS) & 0xFF, 0x2A, 0x00, 0xBF, 0x00, 0xBF])
+    at = code.find(cmp_nib)
+    if at != 0:
+        sys.exit("nibble dispatch placeholder at %d, expected 0" % at)
+    # The two trailing placeholders are the last 8 bytes: reply tail, then bail.
+    reply_at, bail_at = len(code) - 8, len(code) - 4
+    code[2:6] = beqw(base + 2, base + _nibble_entry(code))
+    code[reply_at:reply_at + 4] = bw(base + reply_at, REPLY_BUILDER)
+    code[bail_at:bail_at + 4] = bw(base + bail_at, OPCODE_TAIL)
+    return bytes(code)
+
+
+def _nibble_entry(code):
+    """-> the offset of the nibble arm in `peek_only_handlers`: the second
+    `ldrb r0,[r5,#6]`, because that arm repeats the guard.
+    """
+    pat = assemble("ldrb r0, [r5, #6]")
+    first = code.find(pat)
+    second = code.find(pat, first + 1)
+    if first < 0 or second < 0:
+        sys.exit("could not locate the nibble arm's guard")
+    return second
+
+
+def apply(img, peek_base=None, fault=True, fault_resume=False):
+    """Patch `img` in place. -> a report dict."""
+    code = peek_only_handlers(F.CODE_BASE, peek_base=peek_base)
+    trimmed = F.make_room(img)
+    end = F.place(img, F.CODE_BASE, code, "the read handlers")
+    fault_at = fend = None
+    repointed = []
+    if fault:
+        fault_at = (end + 1) & ~1
+        fend = F.place(img, fault_at, fault_handler(
+            fault_at, dump_at=FAULT_DUMP, resume=fault_resume), "fault handler")
+        for i in range(NUM_VECTORS):
+            at = VECTOR_TABLE + i * 4
+            if struct.unpack_from("<I", img, at - BASE)[0] == DEFAULT_HANDLER:
+                struct.pack_into("<I", img, at - BASE, fault_at | 1)
+                repointed.append(i)
+        if not repointed:
+            sys.exit("no vector points at the 0x%08X default handler; the "
+                     "image is not what this expects" % DEFAULT_HANDLER)
+        end = fend
+    tramp = F.route(img, (PEEK_OPCODE, NIBBLE_OPCODE, F.WHO_OPCODE), F.CODE_BASE)
+    F.stamp_version(img, FLAVOUR, REV)
+    return dict(handler=(F.CODE_BASE, len(code)), trimmed=trimmed,
+                used=end - F.CODE_BASE, tramp=tramp,
+                fault=((fault_at, fend - fault_at) if fault else None),
+                fault_resume=fault_resume, fault_vectors=len(repointed),
+                peek_base=PEEK_BASE if peek_base is None else peek_base)
+
+
+def add_arguments(ap):
+    hide = argparse.SUPPRESS
+    ap.add_argument("--fault-resume", action="store_true", help=hide)
+    ap.add_argument("--peek-base", type=lambda x: int(x, 0), default=None,
+                    metavar="ADDR", help=hide)
+
+
+def build(img, args):
+    rep = apply(img, peek_base=args.peek_base, fault_resume=args.fault_resume)
+    pb = rep["peek_base"]
+    print("handler   0x%08X  %d bytes" % rep["handler"])
+    print("          opcode 0x%02X  three septets, window 0x%08X..0x%08X"
+          % (PEEK_OPCODE, pb, pb | PEEK_SPAN))
+    print("          opcode 0x%02X  eight nibbles, the full 32-bit address"
+          % NIBBLE_OPCODE)
+    print("          both need cat = 0x%02X; without it they still reply"
+          % OPCODE_MAGIC)
+    print("trampoline 0x%08X 4 bytes  (spends opcodes 0x%02X and 0x%02X)"
+          % (rep["tramp"][0], F.SPENT[0], F.SPENT[1]))
+    if rep["fault"]:
+        print("fault     0x%08X  %d bytes, %d hang-forever vectors repointed "
+              "at it" % (rep["fault"] + (rep["fault_vectors"],)))
+        print("          writes its dump to 0x%08X, then %s"
+              % (FAULT_DUMP, "skips the faulting instruction"
+                 if rep["fault_resume"] else "resets"))
+    F.report_banner(img)
+    F.report_room(rep["trimmed"], rep["used"])
+
+
+def peek_message_nibble(addr, seq=0, cat=OPCODE_MAGIC):
+    """A read request addressed as eight nibbles, high first. -> raw SysEx.
+
+    Any 32-bit address, flash or SRAM. Only this build answers it.
+    """
+    if addr & 3:
+        sys.exit("0x%08X is not word-aligned; peek reads a 32-bit word." % addr)
+    nibbles = [(addr >> sh) & 0xF for sh in (28, 24, 20, 16, 12, 8, 4, 0)]
+    return bytes([0xF0, 0x00, 0x20, 0x6B, 0x07, 0x01, seq, cat, NIBBLE_OPCODE]
+                 + nibbles + [0xF7])

mfreak_peek-0.1.0/mfreak_peek/doctor.py

@@ -0,0 +1,9 @@
+"""`mfreak doctor` checks for the peek plugin."""
+from microfreak import plugin
+
+
+def device(r, mo, mi, args, reply):
+    if plugin.running(reply)[0] == "peek":
+        r.ok("peek build", "running; `mfreak peek dump-bootloader` will work")
+    else:
+        r.note("peek build", "not running; only `peek dump-bootloader` needs it")

mfreak_peek-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "mfreak-peek"
+version = "0.1.0"
+description = "A read-only diagnostic MicroFreak firmware patch, and a bootloader dump, for microfreak-tools. Not affiliated with Arturia."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.11,<3.15"
+dependencies = ["microfreak-tools>=0.1.0,<0.2"]
+
+[project.entry-points."mfreak.plugins"]
+peek = "mfreak_peek:plugin"
+
+[project.urls]
+Homepage = "https://github.com/gbryant/microfreak-tools"
+Issues = "https://github.com/gbryant/microfreak-tools/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mfreak_peek"]
+
+[tool.uv.sources]
+microfreak-tools = { workspace = true }