@glassly/bluetooth-sdk 0.1.0-dev.26

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2CfwTextureCache.kt

@@ -0,0 +1,270 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import java.io.ByteArrayOutputStream
+
+/**
+ * Phone-side model of the Glassly CFW's lease-scoped 64 KiB texture cache
+ * (g2flash texture_cache.c), 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.
+ */
+internal class G2CfwTextureCache {
+    companion object {
+        const val CACHE_SIZE = 64 * 1024
+        const val FONT_TABLE_CHARS = 96 // ASCII 32..127
+
+        /** Keep mode-12 payloads comfortably inside one BLE image message. */
+        const val MAX_UPLOAD_PAYLOAD_BYTES = 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.
+         */
+        const val OPAQUE_DRAW_OPTIONS = 0x0F
+
+        /**
+         * 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.
+         */
+        fun rleEncodePixels(gray: ByteArray): ByteArray {
+            val output = ByteArrayOutputStream()
+            var index = 0
+            while (index < gray.size) {
+                // 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.
+                val color = G2CfwRenderer.grayNibble(gray[index].toInt())
+                var end = index + 1
+                while (end < gray.size && G2CfwRenderer.grayNibble(gray[end].toInt()) == color) end += 1
+                var remaining = end - index
+                while (remaining > 0) {
+                    val chunk = minOf(remaining, 0xFFFF)
+                    when {
+                        chunk <= 15 -> output.write((chunk shl 4) or color)
+                        chunk <= 255 -> {
+                            output.write(color)
+                            output.write(chunk)
+                        }
+                        else -> {
+                            output.write(color)
+                            output.write(0)
+                            output.write(chunk and 0xFF)
+                            output.write((chunk ushr 8) and 0xFF)
+                        }
+                    }
+                    remaining -= chunk
+                }
+                index = end
+            }
+            return output.toByteArray()
+        }
+
+        /** Mode-13 cached-image draw: `[13][offset:u16][x:u16][y:u16][options]`. */
+        fun imageDrawPayload(offset: Int, x: Int, y: Int, options: Int): ByteArray? {
+            if (offset !in 0..0xFFFF || x !in 0..0xFFFF || y !in 0..0xFFFF) return null
+            val payload = ByteArrayOutputStream()
+            payload.write(13)
+            for (value in intArrayOf(offset, x, y)) {
+                payload.write(value and 0xFF)
+                payload.write((value ushr 8) and 0xFF)
+            }
+            payload.write(options and 0xFF)
+            return payload.toByteArray()
+        }
+
+        /**
+         * 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).
+         */
+        fun stringRunPayload(
+            fontTableOffset: Int,
+            x: Int,
+            y: Int,
+            options: Int,
+            chars: ByteArray,
+        ): ByteArray? {
+            if (chars.isEmpty() || chars.size > 255) return null
+            if (fontTableOffset !in 0..(CACHE_SIZE - FONT_TABLE_CHARS * 2)) return null
+            if (x !in 0..0xFFFF || y !in 0..0xFFFF) return null
+            if (chars.any { (it.toInt() and 0xFF) < 32 || (it.toInt() and 0xFF) > 126 }) return null
+            val payload = ByteArrayOutputStream()
+            payload.write(14)
+            for (value in intArrayOf(fontTableOffset, x, y)) {
+                payload.write(value and 0xFF)
+                payload.write((value ushr 8) and 0xFF)
+            }
+            payload.write(options and 0xFF)
+            payload.write(chars.size)
+            payload.write(chars)
+            return payload.toByteArray()
+        }
+    }
+
+    class FontEntry(val tableOffset: Int, val cellWidth: Int, val lineHeight: Int) {
+        /** Cache offset per printable char (index = char - 32), null = not resident. */
+        val glyphOffsets = arrayOfNulls<Int>(FONT_TABLE_CHARS)
+    }
+
+    var generation = -1
+        private set
+
+    private val fonts = mutableMapOf<Int, FontEntry>()
+    private val images = mutableMapOf<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 val seenImageHashes = ArrayDeque<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 val pendingUploads = mutableListOf<Pair<Int, ByteArray>>()
+
+    /**
+     * 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.
+     */
+    var exhausted = false
+        private set
+
+    /**
+     * Forget everything and adopt `generation` (the on-glass cache was freed
+     * or its state became unknown).
+     */
+    fun reset(generation: Int) {
+        this.generation = generation
+        fonts.clear()
+        images.clear()
+        seenImageHashes.clear()
+        nextOffset = 2
+        pendingUploads.clear()
+        exhausted = false
+    }
+
+    private fun allocate(length: Int): Int? {
+        if (length <= 0 || nextOffset + length > CACHE_SIZE) {
+            if (length > 0) exhausted = true
+            return null
+        }
+        val offset = nextOffset
+        nextOffset += length
+        return offset
+    }
+
+    /**
+     * 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.
+     */
+    fun font(fontSize: Int, cellWidth: Int, lineHeight: Int): FontEntry? {
+        fonts[fontSize]?.let { return it }
+        val tableOffset = allocate(FONT_TABLE_CHARS * 2) ?: return null
+        val entry = FontEntry(tableOffset, cellWidth, 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.
+     */
+    fun ensureGlyph(font: FontEntry, char: Int, rasterize: () -> ByteArray?): Boolean {
+        if (char < 32 || char > 126) return false
+        val index = char - 32
+        if (font.glyphOffsets[index] != null) return true
+        val gray = rasterize() ?: return false
+        if (gray.size != font.cellWidth * font.lineHeight) return false
+        val image = ByteArrayOutputStream()
+        image.write(font.cellWidth)
+        image.write(font.lineHeight)
+        image.write(rleEncodePixels(gray))
+        val bytes = image.toByteArray()
+        val offset = allocate(bytes.size) ?: return false
+        font.glyphOffsets[index] = offset
+        pendingUploads.add(offset to bytes)
+        pendingUploads.add(
+            (font.tableOffset + index * 2) to
+                byteArrayOf((offset and 0xFF).toByte(), ((offset ushr 8) and 0xFF).toByte())
+        )
+        return true
+    }
+
+    /**
+     * Record a sighting of an image content hash; true when it was already
+     * seen in an earlier frame (worth caching).
+     */
+    fun noteImageSighting(hash: String): Boolean {
+        if (images.containsKey(hash)) return true
+        if (hash in seenImageHashes) return true
+        seenImageHashes.addLast(hash)
+        if (seenImageHashes.size > 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.
+     */
+    fun ensureImage(hash: String, gray: ByteArray, width: Int, height: Int): Int? {
+        images[hash]?.let { return it }
+        if (width !in 1..255 || height !in 1..255 || gray.size != width * height) return null
+        val image = ByteArrayOutputStream()
+        image.write(width)
+        image.write(height)
+        image.write(rleEncodePixels(gray))
+        val bytes = image.toByteArray()
+        val offset = allocate(bytes.size) ?: return null
+        images[hash] = offset
+        pendingUploads.add(offset to bytes)
+        return offset
+    }
+
+    /**
+     * Drain the pending mode-12 entries into `[12][offset16][len16][data]...`
+     * payloads, each at most [MAX_UPLOAD_PAYLOAD_BYTES]. An entry larger than
+     * the budget gets a payload of its own (the BLE fragmenter splits it).
+     */
+    fun takeUploadPayloads(): List<ByteArray> {
+        if (pendingUploads.isEmpty()) return emptyList()
+        val payloads = mutableListOf<ByteArray>()
+        var current = ByteArrayOutputStream().apply { write(12) }
+        for ((offset, data) in pendingUploads) {
+            val record = ByteArrayOutputStream()
+            record.write(offset and 0xFF)
+            record.write((offset ushr 8) and 0xFF)
+            record.write(data.size and 0xFF)
+            record.write((data.size ushr 8) and 0xFF)
+            record.write(data)
+            if (current.size() > 1 && current.size() + record.size() > MAX_UPLOAD_PAYLOAD_BYTES) {
+                payloads.add(current.toByteArray())
+                current = ByteArrayOutputStream().apply { write(12) }
+            }
+            record.writeTo(current)
+        }
+        if (current.size() > 1) payloads.add(current.toByteArray())
+        pendingUploads.clear()
+        return payloads
+    }
+}

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2FlashProtocol.kt

@@ -0,0 +1,291 @@
+package com.glassly.bluetoothsdk.sgcs
+
+/** Byte-exact EVENOTA framing, validation, and MRAM brick guard. No BLE I/O lives here. */
+internal object G2FlashProtocol {
+    private const val U32_MASK = 0xFFFF_FFFFL
+    const val CHUNK = 232
+    const val APP_LOAD_ADDR = 0x0043_8000L
+    const val APP_MAX_END = 0x007F_0000L
+    const val APP_PREAMBLE = 0x20
+    const val REQUIRED_SEGMENT = "ota/s200_firmware_ota.bin"
+
+    class BadImageException(message: String) : Exception("bad firmware image: $message")
+
+    data class Rx(val sequence: Int, val sid: Int, val pb: ByteArray)
+
+    data class Segment(
+        val eid: Long,
+        val off: Long,
+        val size: Long,
+        val crc: Long,
+        val sub: ByteArray,
+        val ps: Long,
+        val fn: String,
+    )
+
+    data class GuardResult(
+        val ps: Long,
+        val loadAddr: Long,
+        val preLen: Long,
+        val progEnd: Long,
+        val pass: Boolean,
+        val reason: String,
+    )
+
+    data class ValidatedImage(val segments: List<Segment>, val guardResult: GuardResult)
+
+    data class GoldenVector(
+        val sha256: String,
+        val ps: Long,
+        val progEnd: Long,
+        val pass: Boolean,
+    )
+
+    val goldenStock =
+        GoldenVector(
+            sha256 = "f4dfb0b49ad3de3c2daf17f8a27a157c3dc98411d6a0d3ab2cfd0918f41b9afa",
+            ps = 3_523_396,
+            progEnd = 0x0079_4324,
+            pass = true,
+        )
+
+    fun crc16(data: ByteArray): ByteArray {
+        var crc = 0xFFFF
+        for (byte in data) {
+            crc = crc xor ((byte.toInt() and 0xFF) shl 8)
+            repeat(8) {
+                crc =
+                    if ((crc and 0x8000) != 0) {
+                        ((crc shl 1) xor 0x1021) and 0xFFFF
+                    } else {
+                        (crc shl 1) and 0xFFFF
+                    }
+            }
+        }
+        return byteArrayOf((crc and 0xFF).toByte(), ((crc ushr 8) and 0xFF).toByte())
+    }
+
+    private val crc32cTable =
+        LongArray(256).also { table ->
+            for (byte in 0 until 256) {
+                var crc = (byte.toLong() shl 24) and U32_MASK
+                repeat(8) {
+                    crc =
+                        if ((crc and 0x8000_0000L) != 0L) {
+                            ((crc shl 1) xor 0x1EDC_6F41L) and U32_MASK
+                        } else {
+                            (crc shl 1) and U32_MASK
+                        }
+                }
+                table[byte] = crc
+            }
+        }
+
+    fun crc32c(data: ByteArray): Long {
+        var crc = 0L
+        for (byte in data) {
+            val index = (((crc ushr 24) xor (byte.toLong() and 0xFF)) and 0xFF).toInt()
+            crc = (((crc shl 8) and U32_MASK) xor crc32cTable[index]) and U32_MASK
+        }
+        return crc
+    }
+
+    fun readU32LE(bytes: ByteArray, offset: Int): Long =
+        (bytes[offset].toLong() and 0xFF) or
+            ((bytes[offset + 1].toLong() and 0xFF) shl 8) or
+            ((bytes[offset + 2].toLong() and 0xFF) shl 16) or
+            ((bytes[offset + 3].toLong() and 0xFF) shl 24)
+
+    fun frames(sid: Int, pb: ByteArray, flag: Int = 0, seq: Int): List<ByteArray> {
+        val body = pb + crc16(pb)
+        val total = maxOf(1, (body.size + CHUNK - 1) / CHUNK)
+        return List(total) { index ->
+            val start = index * CHUNK
+            val chunk = body.copyOfRange(start, minOf(start + CHUNK, body.size))
+            byteArrayOf(
+                0xAA.toByte(),
+                0x21,
+                (seq and 0xFF).toByte(),
+                chunk.size.toByte(),
+                total.toByte(),
+                (index + 1).toByte(),
+                sid.toByte(),
+                flag.toByte(),
+            ) + chunk
+        }
+    }
+
+    fun ctrlFrames(op: Int, data: ByteArray = ByteArray(0), seq: Int): List<ByteArray> =
+        frames(sid = 0xC0, pb = byteArrayOf(op.toByte()) + data, seq = seq)
+
+    fun dataFrames(block: ByteArray, seq: Int): List<ByteArray> =
+        frames(sid = 0xC1, pb = block, seq = seq)
+
+    fun parseRx(frame: ByteArray): Rx? {
+        if (frame.size < 10 || (frame[0].toInt() and 0xFF) != 0xAA ||
+            (frame[1].toInt() and 0xFF) != 0x12
+        ) {
+            return null
+        }
+        val length = frame[3].toInt() and 0xFF
+        val payloadLength = maxOf(0, length - 2)
+        val end = minOf(8 + payloadLength, frame.size)
+        return Rx(
+            sequence = frame[2].toInt() and 0xFF,
+            sid = frame[6].toInt() and 0xFF,
+            pb = if (end >= 8) frame.copyOfRange(8, end) else ByteArray(0),
+        )
+    }
+
+    /** Real OTA replies correlate by notification characteristic and opcode, not echoed seq/SID. */
+    fun otaAckStatus(frames: Iterable<ByteArray>, opcode: Int): Int? {
+        for (frame in frames) {
+            val parsed = parseRx(frame) ?: continue
+            if (parsed.pb.size >= 2 && (parsed.pb[0].toInt() and 0xFF) == opcode) {
+                return parsed.pb[1].toInt() and 0xFF
+            }
+        }
+        return null
+    }
+
+    @Throws(BadImageException::class)
+    fun parseSegments(image: ByteArray): List<Segment> {
+        if (image.size < 0x40) throw BadImageException("file too small")
+        val count = readU32LE(image, 8)
+        if (count !in 1..64) throw BadImageException("implausible component count $count")
+        return List(count.toInt()) { index ->
+            val toc = 0x40 + index * 16
+            if (toc + 16 > image.size) throw BadImageException("TOC entry $index past EOF")
+            val offset = readU32LE(image, toc + 4)
+            if (offset > Int.MAX_VALUE || offset + 128 > image.size.toLong()) {
+                throw BadImageException("segment $index subheader past EOF")
+            }
+            val sub = image.copyOfRange(offset.toInt(), offset.toInt() + 128)
+            var nameEnd = 48
+            while (nameEnd < sub.size && sub[nameEnd].toInt() != 0) nameEnd += 1
+            Segment(
+                eid = readU32LE(image, toc),
+                off = offset,
+                size = readU32LE(image, toc + 8),
+                crc = readU32LE(image, toc + 12),
+                sub = sub,
+                ps = readU32LE(sub, 8),
+                fn = String(sub, 48, nameEnd - 48, Charsets.ISO_8859_1),
+            )
+        }
+    }
+
+    @Throws(BadImageException::class)
+    fun validateFirmware(image: ByteArray): ValidatedImage {
+        val segments = parseSegments(image)
+        val names = segments.map { it.fn }
+        if (segments.size !in 5..6) {
+            throw BadImageException("expected 5-6 segments, found ${segments.size}: $names")
+        }
+        if (REQUIRED_SEGMENT !in names) {
+            throw BadImageException("required segment $REQUIRED_SEGMENT not found; segments are: $names")
+        }
+        for ((index, segment) in segments.withIndex()) {
+            val payloadOffset = segment.off + 128
+            val payloadEnd = payloadOffset + segment.ps
+            if (segment.ps <= 0 || payloadOffset < 128 || payloadEnd > image.size.toLong()) {
+                throw BadImageException("segment $index (${segment.fn}) payload extends past EOF")
+            }
+            if (segment.ps > U32_MASK - 128 || segment.size != segment.ps + 128) {
+                throw BadImageException(
+                    "segment $index (${segment.fn}) TOC size ${segment.size} != payload+header ${segment.ps + 128}"
+                )
+            }
+            val payload = image.copyOfRange(payloadOffset.toInt(), payloadEnd.toInt())
+            val calculated = crc32c(payload)
+            val subheaderCrc = readU32LE(segment.sub, 12)
+            if (calculated != segment.crc || calculated != subheaderCrc) {
+                throw BadImageException(
+                    String.format(
+                        "segment %d (%s) CRC32C mismatch: payload=%08x TOC=%08x sub=%08x",
+                        index,
+                        segment.fn,
+                        calculated,
+                        segment.crc,
+                        subheaderCrc,
+                    )
+                )
+            }
+        }
+        val guard = checkMainAppFitsMram(image, segments)
+        if (!guard.pass) throw BadImageException("brick guard blocked image: ${guard.reason}")
+        return ValidatedImage(segments, guard)
+    }
+
+    fun checkMainAppFitsMram(image: ByteArray, segments: List<Segment>): GuardResult {
+        val segment =
+            segments.firstOrNull { it.fn == REQUIRED_SEGMENT }
+                ?: return GuardResult(0, 0, 0, 0, false, "main-app segment $REQUIRED_SEGMENT not found")
+        val payloadOffset = segment.off + 128
+        if (payloadOffset + APP_PREAMBLE > image.size.toLong()) {
+            return GuardResult(
+                segment.ps,
+                0,
+                0,
+                0,
+                false,
+                "main-app payload smaller than its 32-byte preamble",
+            )
+        }
+        val offset = payloadOffset.toInt()
+        val loadAddr = readU32LE(image, offset + 0x14)
+        val preLen = readU32LE(image, offset) and 0x00FF_FFFFL
+        if (loadAddr != APP_LOAD_ADDR) {
+            return GuardResult(
+                segment.ps,
+                loadAddr,
+                preLen,
+                0,
+                false,
+                String.format("load addr 0x%08x != 0x00438000", loadAddr),
+            )
+        }
+        if (preLen != segment.ps) {
+            return GuardResult(
+                segment.ps,
+                loadAddr,
+                preLen,
+                0,
+                false,
+                "preamble length $preLen != staged payload size ${segment.ps}",
+            )
+        }
+        val programEnd = (APP_LOAD_ADDR + segment.ps - APP_PREAMBLE) and U32_MASK
+        if (programEnd > APP_MAX_END) {
+            return GuardResult(
+                segment.ps,
+                loadAddr,
+                preLen,
+                programEnd,
+                false,
+                String.format("too large: prog_end 0x%08x past ceiling 0x%08x", programEnd, APP_MAX_END),
+            )
+        }
+        return GuardResult(segment.ps, loadAddr, preLen, programEnd, true, "ok")
+    }
+
+    fun selfTestGuard(image: ByteArray, expected: GoldenVector): String? {
+        val segments =
+            try {
+                parseSegments(image)
+            } catch (error: Exception) {
+                return "parse failed: $error"
+            }
+        val result = checkMainAppFitsMram(image, segments)
+        if (result.pass != expected.pass) return "guard pass=${result.pass} != golden ${expected.pass}"
+        if (result.ps != expected.ps) return "ps ${result.ps} != golden ${expected.ps}"
+        if (result.progEnd != expected.progEnd) {
+            return String.format(
+                "prog_end 0x%08x != golden 0x%08x",
+                result.progEnd,
+                expected.progEnd,
+            )
+        }
+        return null
+    }
+}