@glassly/bluetooth-sdk 0.1.0-dev.26

package/ios/Source/sgcs/G2CfwTextureCache.swift

@@ -0,0 +1,233 @@
+import Foundation
+
+/// Phone-side model of the Glassly CFW's lease-scoped 64 KiB texture cache,
+/// plus the mode-12/13/14 wire encoders.
+///
+/// The firmware allocates and zeroes the cache on the first mode-12 write and
+/// frees it when the fbguard lease ends, so this model is only valid for one
+/// lease/generation: the owner bumps a generation counter whenever the lease
+/// cycles (or a send fails and residency becomes unknown) and the model
+/// re-learns from scratch — uploads are cheap (a full mono font is a few KiB).
+///
+/// Cached image format: `[width:u8][height:u8][4bpp RLE]` where the RLE covers
+/// exactly width*height pixels with NO row-pad nibbles (unlike modes 3/6).
+/// Mode-14 fonts are a 96-entry little-endian u16 image-offset table for
+/// characters 32..127; a zero entry points at cache offset 0, so the first
+/// two bytes of the cache are left zero (width 0 ⇒ invalid image) and real
+/// allocations start past them.
+final class G2CfwTextureCache {
+    static let cacheSize = 64 * 1024
+    static let fontTableChars = 96 // ASCII 32..127
+    /// Keep mode-12 payloads comfortably inside one BLE image message.
+    static let maxUploadPayloadBytes = 3600
+    /// 0x0F: identity ramp (top color 15), opaque — a full-cell glyph or a
+    /// full-box image drawn opaque self-erases whatever was under it.
+    static let opaqueDrawOptions: UInt8 = 0x0F
+
+    final class FontEntry {
+        let tableOffset: Int
+        let cellWidth: Int
+        let lineHeight: Int
+        /// Cache offset per printable char (index = char - 32), nil = not resident.
+        var glyphOffsets = [Int?](repeating: nil, count: G2CfwTextureCache.fontTableChars)
+
+        init(tableOffset: Int, cellWidth: Int, lineHeight: Int) {
+            self.tableOffset = tableOffset
+            self.cellWidth = cellWidth
+            self.lineHeight = lineHeight
+        }
+    }
+
+    private(set) var generation = -1
+    private var fonts: [Int32: FontEntry] = [:]
+    private var images: [String: Int] = [:]
+    /// Content hashes seen in earlier frames. Streaming content (a minimap
+    /// re-rendered every frame) never repeats a hash, so it never enters the
+    /// cache; static icons promote on their second sighting.
+    private var seenImageHashes: [String] = []
+    /// Bump allocator. Bytes 0..1 stay zero as the invalid-image guard.
+    private var nextOffset = 2
+    /// Mode-12 entries not yet flushed into payloads.
+    private var pendingUploads: [(offset: Int, data: Data)] = []
+    /// The bump allocator filled up. The reference client recycles a full
+    /// cache (`TextureCacheState.reset` "or we ran out of space"); without
+    /// recovery every later ensure fails and the texture path silently dies
+    /// for the rest of the lease. The renderer checks this before each frame
+    /// and starts a fresh generation.
+    private(set) var exhausted = false
+
+    /// Forget everything and adopt `generation` (the on-glass cache was freed
+    /// or its state became unknown).
+    func reset(generation: Int) {
+        self.generation = generation
+        fonts.removeAll()
+        images.removeAll()
+        seenImageHashes.removeAll()
+        nextOffset = 2
+        pendingUploads.removeAll()
+        exhausted = false
+    }
+
+    private func allocate(_ length: Int) -> Int? {
+        guard length > 0, nextOffset + length <= Self.cacheSize else {
+            if length > 0 { exhausted = true }
+            return nil
+        }
+        defer { nextOffset += length }
+        return nextOffset
+    }
+
+    /// The font table for `fontSize`, allocating (and zero-filling on-glass by
+    /// virtue of the fresh cache) the 192-byte offset table on first use.
+    func font(fontSize: Int32, cellWidth: Int, lineHeight: Int) -> FontEntry? {
+        if let existing = fonts[fontSize] { return existing }
+        guard let tableOffset = allocate(Self.fontTableChars * 2) else { return nil }
+        let entry = FontEntry(tableOffset: tableOffset, cellWidth: cellWidth, lineHeight: lineHeight)
+        fonts[fontSize] = entry
+        return entry
+    }
+
+    /// Make `char` (ASCII 32..126) resident for `font`, uploading its RLE
+    /// raster and patching the font table. `rasterize` supplies the full-cell
+    /// 8-bit grayscale raster (cellWidth × lineHeight) on first upload.
+    /// Returns false when the cache is full or the raster is unavailable.
+    func ensureGlyph(font: FontEntry, char: UInt8, rasterize: () -> Data?) -> Bool {
+        guard char >= 32, char <= 126 else { return false }
+        let index = Int(char) - 32
+        if font.glyphOffsets[index] != nil { return true }
+        guard let gray = rasterize(), gray.count == font.cellWidth * font.lineHeight else { return false }
+        var image = Data([UInt8(font.cellWidth), UInt8(font.lineHeight)])
+        image.append(Self.rleEncodePixels(gray))
+        guard let offset = allocate(image.count) else { return false }
+        font.glyphOffsets[index] = offset
+        pendingUploads.append((offset: offset, data: image))
+        pendingUploads.append((
+            offset: font.tableOffset + index * 2,
+            data: Data([UInt8(offset & 0xFF), UInt8((offset >> 8) & 0xFF)])
+        ))
+        return true
+    }
+
+    /// Record a sighting of an image content hash; true when it was already
+    /// seen in an earlier frame (worth caching).
+    func noteImageSighting(_ hash: String) -> Bool {
+        if images[hash] != nil { return true }
+        if seenImageHashes.contains(hash) { return true }
+        seenImageHashes.append(hash)
+        if seenImageHashes.count > 32 { seenImageHashes.removeFirst() }
+        return false
+    }
+
+    /// The cache offset of an image, uploading it on first residency.
+    /// `gray` is the width×height 8-bit grayscale raster.
+    func ensureImage(hash: String, gray: Data, width: Int, height: Int) -> Int? {
+        if let offset = images[hash] { return offset }
+        guard width > 0, width <= 255, height > 0, height <= 255,
+              gray.count == width * height
+        else { return nil }
+        var image = Data([UInt8(width), UInt8(height)])
+        image.append(Self.rleEncodePixels(gray))
+        guard let offset = allocate(image.count) else { return nil }
+        images[hash] = offset
+        pendingUploads.append((offset: offset, data: image))
+        return offset
+    }
+
+    /// Drain the pending mode-12 entries into `[12][offset16][len16][data]...`
+    /// payloads, each at most `maxUploadPayloadBytes`. An entry larger than
+    /// the budget gets a payload of its own (the BLE fragmenter splits it).
+    func takeUploadPayloads() -> [Data] {
+        guard !pendingUploads.isEmpty else { return [] }
+        var payloads: [Data] = []
+        var current = Data([12])
+        for entry in pendingUploads {
+            var record = Data()
+            record.append(UInt8(entry.offset & 0xFF))
+            record.append(UInt8((entry.offset >> 8) & 0xFF))
+            record.append(UInt8(entry.data.count & 0xFF))
+            record.append(UInt8((entry.data.count >> 8) & 0xFF))
+            record.append(entry.data)
+            if current.count > 1, current.count + record.count > Self.maxUploadPayloadBytes {
+                payloads.append(current)
+                current = Data([12])
+            }
+            current.append(record)
+        }
+        if current.count > 1 { payloads.append(current) }
+        pendingUploads.removeAll()
+        return payloads
+    }
+
+    // MARK: - Wire encoders
+
+    /// RLE over a flat 8-bit grayscale pixel sequence (quantized to 4bpp),
+    /// covering exactly the pixel count — no row padding, per the cached-image
+    /// contract. Token forms match modes 3/6.
+    static func rleEncodePixels(_ gray: Data) -> Data {
+        var output = Data()
+        let bytes = [UInt8](gray)
+        var index = 0
+        while index < bytes.count {
+            // Same rounded quantization as pack4Bpp: a cached draw must
+            // reproduce the composited frame's exact levels or the phone-side
+            // shadow diverges from the panel.
+            let color = G2CfwRenderer.grayNibble(bytes[index])
+            var end = index + 1
+            while end < bytes.count, G2CfwRenderer.grayNibble(bytes[end]) == color { end += 1 }
+            var remaining = end - index
+            while remaining > 0 {
+                let chunk = min(remaining, 0xFFFF)
+                if chunk <= 15 {
+                    output.append(UInt8(chunk << 4) | color)
+                } else if chunk <= 255 {
+                    output.append(color)
+                    output.append(UInt8(chunk))
+                } else {
+                    output.append(color)
+                    output.append(0)
+                    output.append(UInt8(chunk & 0xFF))
+                    output.append(UInt8((chunk >> 8) & 0xFF))
+                }
+                remaining -= chunk
+            }
+            index = end
+        }
+        return output
+    }
+
+    /// Mode-13 cached-image draw: `[13][offset:u16][x:u16][y:u16][options]`.
+    static func imageDrawPayload(offset: Int, x: Int, y: Int, options: UInt8) -> Data? {
+        guard offset >= 0, offset <= 0xFFFF, x >= 0, x <= 0xFFFF, y >= 0, y <= 0xFFFF
+        else { return nil }
+        var payload = Data([13])
+        for value in [offset, x, y] {
+            payload.append(UInt8(value & 0xFF))
+            payload.append(UInt8((value >> 8) & 0xFF))
+        }
+        payload.append(options)
+        return payload
+    }
+
+    /// Mode-14 cached-glyph run:
+    /// `[14][font-offset:u16][x:u16][y:u16][options][strlen:u8][chars]`.
+    /// Every char must be 32..126 and resident (the firmware validates each
+    /// referenced glyph and rejects the whole draw otherwise).
+    static func stringRunPayload(
+        fontTableOffset: Int, x: Int, y: Int, options: UInt8, chars: [UInt8]
+    ) -> Data? {
+        guard !chars.isEmpty, chars.count <= 255,
+              fontTableOffset >= 0, fontTableOffset <= cacheSize - fontTableChars * 2,
+              x >= 0, x <= 0xFFFF, y >= 0, y <= 0xFFFF,
+              chars.allSatisfy({ $0 >= 32 && $0 <= 126 })
+        else { return nil }
+        var payload = Data([14])
+        for value in [fontTableOffset, x, y] {
+            payload.append(UInt8(value & 0xFF))
+            payload.append(UInt8((value >> 8) & 0xFF))
+        }
+        payload.append(options)
+        payload.append(UInt8(chars.count))
+        payload.append(contentsOf: chars)
+        return payload
+    }
+}

package/ios/Source/sgcs/G2FlashProtocol.swift

@@ -0,0 +1,312 @@
+//
+//  G2FlashProtocol.swift
+//  Glassly's pure Swift port of the G2 AA21/EVENOTA protocol.
+//
+//  PURE-LOGIC layer, NO CoreBluetooth and NO writes: the byte-exact OTA framing +
+//  CRC16/CRC32C + EVENOTA container parsing + the MRAM brick-guard, plus a golden-vector
+//  self-test. The BLE flash state machine (which drives these over the link) lives in
+//  G2Flasher; this file is the protocol + the safety guard, deliberately isolated so it
+//  can be reasoned about (and, in CI, unit-checked) on its own.
+//
+//  Every algorithm here was verified against the independent Python reference on the two
+//  real bundled images before transcription (crc16 on random vectors; crc32c against both
+//  images' stored TOC CRCs; the guard against the captured golden vectors below).
+//  Portions of the protocol are derived from that reference implementation.
+//
+
+import Foundation
+
+enum G2FlashProtocolError: Error, CustomStringConvertible {
+    case badImage(String)
+    var description: String {
+        switch self { case let .badImage(m): return "bad firmware image: \(m)" }
+    }
+}
+
+enum G2FlashProtocol {
+    /// ---- CRC16 (CCITT, init 0xFFFF, poly 0x1021) — the OTA body trailer, LE bytes. ----
+    static func crc16(_ data: [UInt8]) -> [UInt8] {
+        BinaryCodec.crc16CCITTLittleEndian(data)
+    }
+
+    /// ---- CRC32C (Castagnoli, MSB-first, init 0, xorout 0) — per-component payload CRC. ----
+    private static let crc32cTable: [UInt32] = {
+        var t = [UInt32](repeating: 0, count: 256)
+        for b in 0 ..< 256 {
+            var c = UInt32(b) << 24
+            for _ in 0 ..< 8 {
+                c = (c & 0x8000_0000) != 0 ? (c << 1) ^ 0x1EDC_6F41 : (c << 1)
+            }
+            t[b] = c
+        }
+        return t
+    }()
+
+    static func crc32c(_ buf: [UInt8]) -> UInt32 {
+        var crc: UInt32 = 0
+        for byte in buf {
+            crc = (crc << 8) ^ crc32cTable[Int(((crc >> 24) ^ UInt32(byte)) & 0xFF)]
+        }
+        return crc
+    }
+
+    /// ---- little-endian u32 read ----
+    static func readU32LE(_ b: [UInt8], _ o: Int) -> UInt32 {
+        return UInt32(b[o]) | (UInt32(b[o + 1]) << 8) | (UInt32(b[o + 2]) << 16) | (UInt32(b[o + 3]) << 24)
+    }
+
+    /// ---- OTA transport framing (validated byte-for-byte against the Python reference) ----
+    /// body = pb + crc16(pb); chunk into 232-byte frames; per frame:
+    ///   [0xAA, 0x21, seq, len(chunk), tot, serial(1-based), sid, flag] + chunk
+    /// sid = 0xC0 ctrl, 0xC1 data. A shared `seq` links a marker+block pair.
+    static let CHUNK = 232
+
+    static func frames(sid: UInt8, pb: [UInt8], flag: UInt8 = 0, seq: UInt8) -> [[UInt8]] {
+        let body = pb + crc16(pb)
+        let tot = max(1, (body.count + CHUNK - 1) / CHUNK)
+        var out: [[UInt8]] = []
+        var off = 0
+        for i in 0 ..< tot {
+            let end = min(off + CHUNK, body.count)
+            let ch = Array(body[off ..< end])
+            off = end
+            var frame: [UInt8] = [0xAA, 0x21, seq, UInt8(ch.count), UInt8(tot), UInt8(i + 1), sid, flag]
+            frame.append(contentsOf: ch)
+            out.append(frame)
+        }
+        return out
+    }
+
+    static func ctrlFrames(_ op: UInt8, _ data: [UInt8] = [], seq: UInt8) -> [[UInt8]] {
+        return frames(sid: 0xC0, pb: [op] + data, seq: seq)
+    }
+
+    static func dataFrames(_ block: [UInt8], seq: UInt8) -> [[UInt8]] {
+        return frames(sid: 0xC1, pb: block, seq: seq)
+    }
+
+    /// Stock DEVICE_SETTINGS/AUTHENTICATION request sent before every OTA BEGIN.
+    /// The phone type is iOS (3); the captured Android request uses phone type 4.
+    static func authenticationFrames(magic: UInt8) -> [[UInt8]] {
+        let pb: [UInt8] = [
+            0x08, 0x04, // commandId = AUTHENTICATION
+            0x10, magic, // magicRandom
+            0x1A, 0x04, 0x08, 0x01, 0x10, 0x03, // AuthMgr { secAuth=true, phoneType=iOS }
+        ]
+        return frames(sid: 0x80, pb: pb, seq: magic)
+    }
+
+    /// Accept the successful stock authentication response: matching command and
+    /// magic, followed by an empty result message (the default result code is zero).
+    static func isAuthenticationSuccess(_ frame: [UInt8], magic: UInt8) -> Bool {
+        guard let decoded = parseRx(frame), decoded.sid == 0x80 else { return false }
+        return decoded.pb == [0x08, 0x04, 0x10, magic, 0x1A, 0x00]
+    }
+
+    /// Unwrap an `aa12` reply envelope → (sequence, sid, pb).
+    /// pb = [opcode, status, ...].
+    static func parseRx(_ frame: [UInt8]) -> (sequence: UInt8, sid: UInt8, pb: [UInt8])? {
+        guard frame.count >= 10, frame[0] == 0xAA, frame[1] == 0x12 else { return nil }
+        let sequence = frame[2]
+        let ln = Int(frame[3])
+        let sid = frame[6]
+        let n = max(0, ln - 2)
+        let end = min(8 + n, frame.count)
+        guard end >= 8 else { return (sequence, sid, []) }
+        return (sequence, sid, Array(frame[8 ..< end]))
+    }
+
+    /// OTA replies are correlated by notification characteristic + opcode. The
+    /// firmware does not promise to echo the request's AA21 sequence or SID in
+    /// its AA12 response (and real block ACKs do not consistently do so).
+    static func otaAckStatus(in frames: [[UInt8]], opcode: UInt8) -> UInt8? {
+        for frame in frames {
+            guard let decoded = parseRx(frame),
+                  decoded.pb.count >= 2,
+                  decoded.pb[0] == opcode
+            else { continue }
+            return decoded.pb[1]
+        }
+        return nil
+    }
+
+    /// ---- EVENOTA container parsing ----
+    struct Segment {
+        let eid: UInt32
+        let off: UInt32
+        let size: UInt32
+        let crc: UInt32
+        let sub: [UInt8] // 128-byte subheader
+        let ps: UInt32 // payload size
+        let fn: String // component name
+    }
+
+    struct ValidatedImage {
+        let segments: [Segment]
+        let guardResult: GuardResult
+    }
+
+    static func parseSegments(_ img: [UInt8]) throws -> [Segment] {
+        guard img.count >= 0x40 else { throw G2FlashProtocolError.badImage("file too small") }
+        let n = readU32LE(img, 8)
+        guard n > 0 && n <= 64 else { throw G2FlashProtocolError.badImage("implausible component count \(n)") }
+        var segs: [Segment] = []
+        for i in 0 ..< Int(n) {
+            let base = 0x40 + i * 16
+            guard base + 16 <= img.count else { throw G2FlashProtocolError.badImage("TOC entry \(i) past EOF") }
+            let eid = readU32LE(img, base)
+            let off = readU32LE(img, base + 4)
+            let size = readU32LE(img, base + 8)
+            let crc = readU32LE(img, base + 12)
+            let so = Int(off)
+            guard so >= 0, so + 128 <= img.count else {
+                throw G2FlashProtocolError.badImage("segment \(i) subheader past EOF")
+            }
+            let sub = Array(img[so ..< so + 128])
+            let ps = readU32LE(sub, 8)
+            let nameBytes = sub[48 ..< 128].prefix(while: { $0 != 0 })
+            let fn = String(bytes: nameBytes, encoding: .isoLatin1) ?? ""
+            segs.append(Segment(eid: eid, off: off, size: size, crc: crc, sub: sub, ps: ps, fn: fn))
+        }
+        return segs
+    }
+
+    /// Full preflight for every image, regardless of where it came from. This
+    /// validates structure, each component's payload CRC32C against both stored
+    /// copies, and the main-app MRAM bounds before any BLE write is allowed.
+    static func validateFirmware(_ img: [UInt8]) throws -> ValidatedImage {
+        let segments = try parseSegments(img)
+        let names = segments.map(\.fn)
+        guard (5 ... 6).contains(segments.count) else {
+            throw G2FlashProtocolError.badImage(
+                "expected 5-6 segments, found \(segments.count): \(names)"
+            )
+        }
+        guard names.contains(REQUIRED_SEGMENT) else {
+            throw G2FlashProtocolError.badImage(
+                "required segment \(REQUIRED_SEGMENT) not found; segments are: \(names)"
+            )
+        }
+
+        for (index, segment) in segments.enumerated() {
+            let payloadOffset = Int(segment.off) + 128
+            let payloadSize = Int(segment.ps)
+            guard payloadSize > 0, payloadOffset >= 128,
+                  payloadOffset <= img.count,
+                  payloadSize <= img.count - payloadOffset
+            else {
+                throw G2FlashProtocolError.badImage(
+                    "segment \(index) (\(segment.fn)) payload extends past EOF"
+                )
+            }
+            guard segment.ps <= UInt32.max - 128,
+                  segment.size == segment.ps + 128
+            else {
+                throw G2FlashProtocolError.badImage(
+                    "segment \(index) (\(segment.fn)) TOC size \(segment.size) != payload+header \(segment.ps + 128)"
+                )
+            }
+
+            let payload = Array(img[payloadOffset ..< payloadOffset + payloadSize])
+            let calculated = crc32c(payload)
+            let subheaderCRC = readU32LE(segment.sub, 12)
+            guard calculated == segment.crc, calculated == subheaderCRC else {
+                throw G2FlashProtocolError.badImage(
+                    String(
+                        format: "segment %d (%@) CRC32C mismatch: payload=%08x TOC=%08x sub=%08x",
+                        index, segment.fn, calculated, segment.crc, subheaderCRC
+                    )
+                )
+            }
+        }
+
+        let guardResult = checkMainAppFitsMram(img, segments)
+        guard guardResult.pass else {
+            throw G2FlashProtocolError.badImage("brick guard blocked image: \(guardResult.reason)")
+        }
+        return ValidatedImage(segments: segments, guardResult: guardResult)
+    }
+
+    // ---- MRAM brick-guard (the ONLY thing preventing a hard, SWD-only brick) ----
+    static let APP_LOAD_ADDR: UInt32 = 0x0043_8000
+    static let APP_MAX_END: UInt32 = 0x007F_0000
+    static let OTA_FLAG_ADDR: UInt32 = 0x007F_E000
+    static let MRAM_END: UInt32 = 0x0080_0000
+    static let APP_PREAMBLE = 0x20
+    static let REQUIRED_SEGMENT = "ota/s200_firmware_ota.bin"
+
+    struct GuardResult {
+        let ps: UInt32
+        let loadAddr: UInt32
+        let preLen: UInt32
+        let progEnd: UInt32
+        let pass: Bool
+        let reason: String
+    }
+
+    /// Re-derives the guard directly from the image bytes using the independently
+    /// verified MRAM-fit algorithm. Call before EVERY flash (never cache).
+    static func checkMainAppFitsMram(_ img: [UInt8], _ segs: [Segment]) -> GuardResult {
+        guard let s = segs.first(where: { $0.fn == REQUIRED_SEGMENT }) else {
+            return GuardResult(ps: 0, loadAddr: 0, preLen: 0, progEnd: 0, pass: false,
+                               reason: "main-app segment \(REQUIRED_SEGMENT) not found")
+        }
+        let ps = s.ps
+        let po = Int(s.off) + 128
+        guard po + APP_PREAMBLE <= img.count else {
+            return GuardResult(ps: ps, loadAddr: 0, preLen: 0, progEnd: 0, pass: false,
+                               reason: "main-app payload smaller than its 32-byte preamble")
+        }
+        let pre = Array(img[po ..< po + APP_PREAMBLE])
+        let loadAddr = readU32LE(pre, 0x14)
+        let preLen = readU32LE(pre, 0) & 0x00FF_FFFF
+        if loadAddr != APP_LOAD_ADDR {
+            return GuardResult(ps: ps, loadAddr: loadAddr, preLen: preLen, progEnd: 0, pass: false,
+                               reason: String(format: "load addr 0x%08x != 0x00438000", loadAddr))
+        }
+        if preLen != ps {
+            return GuardResult(ps: ps, loadAddr: loadAddr, preLen: preLen, progEnd: 0, pass: false,
+                               reason: "preamble length \(preLen) != staged payload size \(ps)")
+        }
+        let progEnd = APP_LOAD_ADDR &+ ps &- UInt32(APP_PREAMBLE)
+        if progEnd > APP_MAX_END {
+            return GuardResult(ps: ps, loadAddr: loadAddr, preLen: preLen, progEnd: progEnd, pass: false,
+                               reason: String(format: "too large: prog_end 0x%08x past ceiling 0x%08x", progEnd, APP_MAX_END))
+        }
+        return GuardResult(ps: ps, loadAddr: loadAddr, preLen: preLen, progEnd: progEnd, pass: true, reason: "ok")
+    }
+
+    /// ---- Golden-vector self-test (council fix #2) ----
+    /// Captured from the Python reference on the exact bundled stock, SHA-verified image.
+    /// The Swift guard MUST reproduce these; a mis-transcribed constant that silently
+    /// disabled the guard would fail this test (and we refuse to flash if it does).
+    struct GoldenVector {
+        let sha256: String
+        let ps: UInt32
+        let progEnd: UInt32
+        let pass: Bool
+    }
+
+    static let goldenStock = GoldenVector(
+        sha256: "f4dfb0b49ad3de3c2daf17f8a27a157c3dc98411d6a0d3ab2cfd0918f41b9afa",
+        ps: 3_523_396, progEnd: 0x0079_4324, pass: true
+    )
+
+    /// Run the parse+guard on `img` and assert it reproduces the golden vector. Returns
+    /// nil on success, or a failure description. Any non-nil result MUST block flashing.
+    static func selfTestGuard(_ img: [UInt8], expect gv: GoldenVector) -> String? {
+        let segs: [Segment]
+        do { segs = try parseSegments(img) } catch { return "parse failed: \(error)" }
+        let r = checkMainAppFitsMram(img, segs)
+        if r.pass != gv.pass {
+            return "guard pass=\(r.pass) != golden \(gv.pass)"
+        }
+        if r.ps != gv.ps {
+            return "ps \(r.ps) != golden \(gv.ps)"
+        }
+        if r.progEnd != gv.progEnd {
+            return String(format: "prog_end 0x%08x != golden 0x%08x", r.progEnd, gv.progEnd)
+        }
+        return nil
+    }
+}