Add runtime glyph cache for Thai font rendering

Author: rayriffy

.DS_Store

@@ -4,7 +4,7 @@
   "stock_sha256": "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
   "stock_url": "https://cdn.evenreal.co/firmware/fc250b05e98a9ff998b4b68f5f99f994.bin",
   "stock_size": 4476518,
-  "patched_sha256": "6d10399a7fec28d2389c7be7ffd293b0ea37beb6771f9de470336e826a54600f",
+  "patched_sha256": "749cf09ceea707620a79b029a1f02e0101b1d7bb44d09d9b700889d77307961b",
   "component_count": 6,
   "archive_hardware_validated": false,
   "selected_artifact": {

docs/rebases/2.2.9.22.json

@@ -47,6 +47,7 @@ Expected stock component hashes:
 | stock UTF-8 helper | `0x0048B9D4` | `0x00491E24` | 64 exact bytes and decoded behavior |
 | glyph release | `0x004DA018` | `0x004E64A0` | 24 exact bytes; descriptor offset evidence |
 | glyph descriptor | `0x004DA074` | `0x004E64FC` | 32 exact bytes; IAR short-enum layout |
+| LVGL allocator | — | `0x00458382` | 16 exact bytes; stock font-manager allocation caller |
 
 The rebase uses separate exact shifts (`+0x3890`, `+0x6450`, `+0xC488`); no
 global address delta was assumed.
@@ -60,20 +61,22 @@ global address delta was assumed.
   `688f2ef20776a1f0286bd73bef4dd5d5c76640f4a7c4f0ea5f7c1b8d87a969b7`);
   host-side Raqm shaping extracts combining marks without their dotted-circle
   scaffolds before the bitmap fallback is generated;
-  source rasters use 2× scale with one-pixel edge attenuation for a lighter
-  visual weight;
+  source outlines are supersampled, geometrically thinned by half a device
+  pixel per contour, and downsampled for a lighter visual weight;
   its embedded copyright is "All rights reserved" and its inclusion is
   user-authorized for this repository only;
 - patched output size: `4,606,432` bytes;
-- patched output SHA-256: `6d10399a7fec28d2389c7be7ffd293b0ea37beb6771f9de470336e826a54600f`;
-- patched main payload: `3,832,742` bytes;
-- patched programmed end: `0x007DFB86`; safe headroom: `66,682` bytes;
-- `make check`: 36 tests passed, including device-path emulation of the built
+- patched output SHA-256: `749cf09ceea707620a79b029a1f02e0101b1d7bb44d09d9b700889d77307961b`;
+- patched main payload: `3,834,766` bytes;
+- patched programmed end: `0x007E036E`; safe headroom: `64,658` bytes;
+- `make check`: 44 tests passed, including device-path emulation of the built
   payload (decoder dispatch, NULL-offset lookahead, tone+SARA AM remap, and a
   full 8-size glyph rasterization sweep through aligned and unaligned buffers
-  with guards);
+  with guards), plus allocator failure/out-of-range fallback, runtime-font
+  idempotence, cache hit after source erasure, LRU eviction, busy fallback, and
+  artifact-level chain-to-render integration;
 - non-main component payloads remain byte-identical to stock;
-- final hooks decode to chain wrapper `0x007BF0A0` and text wrapper `0x007BEE5C`;
+- final hooks decode to chain wrapper `0x007BF888` and text wrapper `0x007BF368`;
 - Case-USB writer requires the exact committed whole-bundle and main-payload pins;
 - two lenses were flashed with earlier broken artifacts; see the crash
   post-mortem below.

docs/rebases/2.2.9.22.md

@@ -70,6 +70,17 @@ cache flush. The only context-sensitive decoder case—tone marks after upper
 Thai marks—now identifies the immediately preceding fixed-width Thai UTF-8
 sequence directly instead of re-decoding the text prefix.
 
+The fallback also keeps four bounded A8 glyph slots in a writable runtime font
+clone allocated during stock font-chain initialization. A cache hit copies the
+already-expanded pixels into LVGL's caller-owned draw buffer, so descriptor
+ownership, cache-entry fields, release callbacks, and the stock cache flush
+remain unchanged. Slot capacity is derived from the largest bitmap in the
+selected size; a typical 28 px chain uses 2,768 bytes including metadata. If
+the authenticated stock allocator fails, returns outside SRAM, or any runtime
+header or slot bound is invalid, the chain attaches the original read-only font
+or the bitmap callback uses the uncached A4 path. The cache has a busy guard so
+re-entrant rendering also falls back instead of sharing mutable slot state.
+
 ## Thai shaping boundary
 
 LVGL decodes UTF-8 and supports font fallback, but it does not provide general

docs/research.md

@@ -15,6 +15,7 @@
 #define FONT_DATA_MAGIC 0xA11D0003u
 #define LV_FONT_GLYPH_FORMAT_A8 0x08u
 #define STOCK_CHAIN_BUILD_THUMB 0x00470989u
+#define LV_MALLOC_THUMB 0x00458383u
 /* The stock letter helper loads its UTF-8 decoder through the double pointer
    at 0x00491F14 (slot address, then function pointer) so it always matches
    the firmware's active text encoder. Calling any hardcoded entry instead
@@ -27,6 +28,10 @@
 #define GLYPH_DSC_SIZE 32u
 #define GLYPH_DSC_FORMAT_OFFSET 14u
 #define GLYPH_DSC_GID_OFFSET 24u
+#define THAI_RUNTIME_MAGIC 0x43414854u
+#define THAI_CACHE_SLOTS 4u
+#define THAI_CACHE_BUDGET 8192u
+#define FONT_WORD_COUNT 9u
 
 typedef struct {
     uint32_t bitmap_offset;
@@ -42,6 +47,24 @@ typedef struct {
 typedef void *(*stock_chain_build_fn)(void *configs, uint32_t count);
 typedef uint32_t (*stock_decode_fn)(const char *text, uint32_t *offset);
 typedef void (*flush_cache_fn)(const void *draw_buf, const void *area);
+typedef void *(*lv_malloc_fn)(uint32_t size);
+typedef uint32_t alias_u32_t __attribute__((__may_alias__));
+
+typedef struct {
+    uint32_t codepoint;
+    uint32_t stamp;
+} thai_cache_slot_t;
+
+typedef struct {
+    uint32_t font[FONT_WORD_COUNT];
+    uint32_t magic;
+    uint32_t clock;
+    uint16_t slot_bytes;
+    uint8_t slot_count;
+    uint8_t busy;
+    thai_cache_slot_t slots[THAI_CACHE_SLOTS];
+    uint8_t pixels[];
+} thai_runtime_font_t;
 
 static const uint8_t a4_to_a8[16] = {
     0u, 17u, 34u, 51u, 68u, 85u, 102u, 119u,
@@ -109,6 +132,26 @@ static void write_u32(uint8_t *p, uint32_t value) {
     p[3] = (uint8_t)(value >> 24);
 }
 
+static int writable_ram_range(const void *pointer, uint32_t size) {
+    uintptr_t address = (uintptr_t)pointer;
+    uint32_t capacity = WRITABLE_RAM_END - WRITABLE_RAM_BASE;
+    return size <= capacity && address >= WRITABLE_RAM_BASE &&
+           address <= WRITABLE_RAM_END - size;
+}
+
+static void copy_bytes(uint8_t *destination, const uint8_t *source, uint32_t count) {
+    if((((uintptr_t)destination | (uintptr_t)source) & 3u) == 0u) {
+        while(count >= 4u) {
+            *(alias_u32_t *)(uintptr_t)destination =
+                *(const alias_u32_t *)(uintptr_t)source;
+            destination += 4;
+            source += 4;
+            count -= 4u;
+        }
+    }
+    while(count--) *destination++ = *source++;
+}
+
 static const uint32_t *font_for_line_height(uint32_t height) {
     if(height < 28u) return thai_font_16;
     if(height < 34u) return thai_font_20;
@@ -139,6 +182,116 @@ static const thai_glyph_t *glyph_record(const uint32_t *font, uint32_t codepoint
     return (const thai_glyph_t *)(data + records_offset + record_index * 12u);
 }
 
+static uint16_t cache_slot_bytes_for_font(const uint32_t *font) {
+    const uint8_t *data = (const uint8_t *)(uintptr_t)thai_font_data_address;
+    uint32_t size_index = font[8];
+    if(size_index >= SIZE_COUNT) return 0;
+    uint32_t records_offset = read_u32(data + 12);
+    uint32_t largest = 0;
+    for(uint32_t index = 0; index < GLYPH_COUNT; index++) {
+        const thai_glyph_t *glyph = (const thai_glyph_t *)(
+            data + records_offset + (size_index * GLYPH_COUNT + index) * 12u);
+        if(!glyph->present) continue;
+        uint32_t cache_stride = ((uint32_t)glyph->box_w + 3u) & ~3u;
+        uint32_t bytes = cache_stride * glyph->box_h;
+        if(bytes > largest) largest = bytes;
+    }
+    if(!largest || largest > THAI_CACHE_BUDGET || largest > 0xFFFFu) return 0;
+    return (uint16_t)largest;
+}
+
+static thai_runtime_font_t *runtime_font_from(const uint32_t *font) {
+    if(!writable_ram_range(font, sizeof(thai_runtime_font_t))) return 0;
+    thai_runtime_font_t *runtime = (thai_runtime_font_t *)(uintptr_t)font;
+    if(runtime->magic != THAI_RUNTIME_MAGIC || !runtime->slot_bytes ||
+       !runtime->slot_count || runtime->slot_count > THAI_CACHE_SLOTS) return 0;
+    uint32_t cache_bytes = (uint32_t)runtime->slot_bytes * runtime->slot_count;
+    if(cache_bytes > THAI_CACHE_BUDGET ||
+       !writable_ram_range(runtime, sizeof(thai_runtime_font_t) + cache_bytes)) return 0;
+    return runtime;
+}
+
+static const uint32_t *runtime_font_create(const uint32_t *base_font) {
+    uint16_t slot_bytes = cache_slot_bytes_for_font(base_font);
+    if(!slot_bytes) return base_font;
+    uint32_t slot_count = THAI_CACHE_BUDGET / slot_bytes;
+    if(slot_count > THAI_CACHE_SLOTS) slot_count = THAI_CACHE_SLOTS;
+    if(!slot_count) return base_font;
+    uint32_t total = sizeof(thai_runtime_font_t) + slot_count * slot_bytes;
+    lv_malloc_fn allocate = (lv_malloc_fn)(uintptr_t)LV_MALLOC_THUMB;
+    thai_runtime_font_t *runtime = (thai_runtime_font_t *)allocate(total);
+    if(!runtime || !writable_ram_range(runtime, total)) return base_font;
+    uint8_t *bytes = (uint8_t *)runtime;
+    for(uint32_t index = 0; index < total; index++) bytes[index] = 0;
+    for(uint32_t index = 0; index < FONT_WORD_COUNT; index++) {
+        runtime->font[index] = base_font[index];
+    }
+    runtime->magic = THAI_RUNTIME_MAGIC;
+    runtime->slot_bytes = slot_bytes;
+    runtime->slot_count = (uint8_t)slot_count;
+    return runtime->font;
+}
+
+static uint8_t *cache_pixels(thai_runtime_font_t *runtime, uint32_t slot) {
+    return runtime->pixels + slot * runtime->slot_bytes;
+}
+
+static uint32_t cache_tick(thai_runtime_font_t *runtime) {
+    runtime->clock++;
+    if(!runtime->clock) {
+        runtime->clock = 1u;
+        for(uint32_t index = 0; index < runtime->slot_count; index++) {
+            runtime->slots[index].stamp = 0;
+        }
+    }
+    return runtime->clock;
+}
+
+static int cache_restore(thai_runtime_font_t *runtime, const thai_glyph_t *glyph,
+                         uint32_t codepoint, uint8_t *target, uint16_t stride) {
+    if(!runtime || runtime->busy || stride < glyph->box_w) return 0;
+    uint32_t cache_stride = ((uint32_t)glyph->box_w + 3u) & ~3u;
+    if(cache_stride * glyph->box_h > runtime->slot_bytes) return 0;
+    for(uint32_t slot = 0; slot < runtime->slot_count; slot++) {
+        if(runtime->slots[slot].codepoint != codepoint) continue;
+        runtime->busy = 1u;
+        const uint8_t *source = cache_pixels(runtime, slot);
+        for(uint32_t y = 0; y < glyph->box_h; y++) {
+            copy_bytes(target + y * stride, source + y * cache_stride, glyph->box_w);
+        }
+        runtime->slots[slot].stamp = cache_tick(runtime);
+        runtime->busy = 0u;
+        return 1;
+    }
+    return 0;
+}
+
+static void cache_store(thai_runtime_font_t *runtime, const thai_glyph_t *glyph,
+                        uint32_t codepoint, const uint8_t *source, uint16_t stride) {
+    if(!runtime || runtime->busy || stride < glyph->box_w) return;
+    uint32_t cache_stride = ((uint32_t)glyph->box_w + 3u) & ~3u;
+    if(cache_stride * glyph->box_h > runtime->slot_bytes) return;
+    uint32_t selected = 0;
+    for(uint32_t slot = 0; slot < runtime->slot_count; slot++) {
+        if(!runtime->slots[slot].codepoint) {
+            selected = slot;
+            break;
+        }
+        if(runtime->slots[slot].stamp < runtime->slots[selected].stamp) selected = slot;
+    }
+    runtime->busy = 1u;
+    uint8_t *destination = cache_pixels(runtime, selected);
+    for(uint32_t y = 0; y < glyph->box_h; y++) {
+        copy_bytes(destination + y * cache_stride, source + y * stride, glyph->box_w);
+        for(uint32_t x = glyph->box_w; x < cache_stride; x++) {
+            destination[y * cache_stride + x] = 0;
+        }
+    }
+    runtime->slots[selected].codepoint = codepoint;
+    runtime->slots[selected].stamp = cache_tick(runtime);
+    runtime->busy = 0u;
+}
+
 __attribute__((used, noinline))
 bool thai_get_glyph_dsc(const uint32_t *font, void *glyph_dsc,
                         uint32_t codepoint, uint32_t next_codepoint) {
@@ -173,6 +326,16 @@ const void *thai_get_glyph_bitmap(void *glyph_dsc, void *draw_buf) {
     uint8_t *draw = (uint8_t *)draw_buf;
     uint16_t stride = read_u16(draw + 8);
     uint8_t *target = (uint8_t *)(uintptr_t)read_u32(draw + 16);
+    if(!target || stride < glyph->box_w) return 0;
+
+    thai_runtime_font_t *runtime = runtime_font_from(font);
+    if(cache_restore(runtime, glyph, codepoint, target, stride)) {
+        const uint32_t *handlers = (const uint32_t *)(uintptr_t)read_u32(draw + 24);
+        if(handlers && handlers[4]) {
+            ((flush_cache_fn)(uintptr_t)handlers[4])(draw_buf, 0);
+        }
+        return draw_buf;
+    }
 
     for(uint32_t y = 0; y < glyph->box_h; y++) {
         const uint8_t *row = source + y * glyph->row_bytes;
@@ -197,6 +360,8 @@ const void *thai_get_glyph_bitmap(void *glyph_dsc, void *draw_buf) {
         }
     }
 
+    cache_store(runtime, glyph, codepoint, target, stride);
+
     const uint32_t *handlers = (const uint32_t *)(uintptr_t)read_u32(draw + 24);
     if(handlers && handlers[4]) {
         ((flush_cache_fn)(uintptr_t)handlers[4])(draw_buf, 0);
@@ -247,15 +412,15 @@ void thai_text_encoded_letter_next_2(const char *text, uint32_t *letter,
 }
 
 static int is_thai_font(const uint32_t *font) {
-    return font == thai_font_16 || font == thai_font_20 ||
+    if(font == thai_font_16 || font == thai_font_20 ||
            font == thai_font_24 || font == thai_font_28 ||
            font == thai_font_32 || font == thai_font_36 ||
-           font == thai_font_40 || font == thai_font_48;
+           font == thai_font_40 || font == thai_font_48) return 1;
+    return runtime_font_from(font) != 0;
 }
 
 static int writable_ram_node(const uint32_t *node) {
-    uintptr_t address = (uintptr_t)node;
-    return address >= WRITABLE_RAM_BASE && address < WRITABLE_RAM_END;
+    return writable_ram_range(node, 32u);
 }
 
 /* Appending must be idempotent: the stock builder runs again whenever a new
@@ -274,7 +439,8 @@ void *thai_chain_append(void *chain_ptr) {
             /* Only a verified writable stock node may receive the fallback
                pointer; XIP or flash tails are left untouched. */
             if(!writable_ram_node(last)) return chain_ptr;
-            last[7] = (uint32_t)(uintptr_t)font_for_line_height(root[3]);
+            const uint32_t *base_font = font_for_line_height(root[3]);
+            last[7] = (uint32_t)(uintptr_t)runtime_font_create(base_font);
             return chain_ptr;
         }
         if(is_thai_font((const uint32_t *)(uintptr_t)next)) return chain_ptr;

patches/thai_font.c

@@ -146,9 +146,9 @@ index 0000000..3e96428
 +
 +export const LOCAL_G2_TEMPLE_FLASH_TARGETS = Object.freeze([
 +  Object.freeze({
-+    imageSha256: "6d10399a7fec28d2389c7be7ffd293b0ea37beb6771f9de470336e826a54600f",
-+    mainSha256: "5a78331d285c5e4aaaca8acfeed252f7f02d6942ffe917c8701c9470b136041b",
-+    mainBytes: 3832742,
++    imageSha256: "749cf09ceea707620a79b029a1f02e0101b1d7bb44d09d9b700889d77307961b",
++    mainSha256: "f4b1a36f7d2e1837def914c8b8eefc8c6cae66bea6fc44097f1fcf925d9b0e3c",
++    mainBytes: 3834766,
 +    version: "2.2.9.22",
 +    reportedVersion: "2.2.9.22",
 +    label: "Thai G2 2.2.9.22 · 2005_iannnnnAMD · local Case USB only",

patches/thai_patches.json

@@ -21,7 +21,7 @@
     VALID_CODEPOINTS,
     _thin_mask,
 )
-from generate_patch import encode_bl, encode_bw
+from generate_patch import LV_MALLOC_SITE, encode_bl, encode_bw
 from render_preview import shape_for_preview
 from verify_firmware import verify
 
@@ -228,13 +228,19 @@ def test_callback_pins_authenticated_iar_descriptor_layout(self) -> None:
         self.assertIn("#define GLYPH_DSC_GID_OFFSET 24u", source)
         self.assertIn("#define STOCK_CHAIN_BUILD_THUMB 0x00470989u", source)
         self.assertIn("#define STOCK_DECODE_SLOT_INDIRECT 0x00491F14u", source)
+        self.assertIn("#define LV_MALLOC_THUMB 0x00458383u", source)
         self.assertNotIn("STOCK_UTF8_NEXT_THUMB", source)
         self.assertIn("uint32_t *active_offset = offset ? offset : &local_offset;", source)
         self.assertIn("next = decode(text + *active_offset, 0);", source)
         self.assertIn("if(!raise_tone && *active_offset >= 6u)", source)
         self.assertNotIn("previous_codepoint(", source)
         self.assertIn("a4_to_a8[16]", source)
         self.assertIn("a4_to_a8_pair[256]", source)
+        self.assertIn("static int cache_restore(", source)
+        self.assertIn("static void cache_store(", source)
+        self.assertIn("return runtime->font;", source)
+        self.assertEqual(self.spec["metadata"]["lv_malloc_address"], "0x00458382")
+        self.assertEqual(LV_MALLOC_SITE[0], 0x00458382)
 
     def test_chain_append_only_writes_writable_ram(self) -> None:
         source = (ROOT / "patches/thai_font.c").read_text()