大飞的技术博客

·约 4 分钟·

把 242KB 字库搬出 app 二进制:只读 FAT 分区上的 mmap 字库

墨水屏设备上最大的数据从来不是画面,是中文字库。PocketOracle 用 16px 点阵字:CJK 字形每个 34 字节(2B 码点 + 32B 位图),7131 个字就是 242KB——app 二进制里最大的单体。当时固件 1.49MB,槽只有 1.5MB,余量 139KB,再加一套语料就得重新分区。而 assets 分区那边更窘迫:704KB 实占 640KB,空闲 24KB,字库根本塞不下。

解法只有一条:重划分区,把字库整个搬出 app 二进制,住进 assets 分区。这篇讲搬家的三个关键决策:格式同构、不挂载的 FAT 解析、以及一条「坏了也能自救」的退化链。

格式设计:新格式迁就旧代码

gen_font.py 产出的 font.bin 布局:

u32 'PF16' | u32 count | count × { u16le 码点, u8 位图[32] }

定长 34B 一条,码点升序——和 app 里原来的 epd_glyph16_t 数组逐字节同构。这是整个迁移最重要的一个决定:固件里的字形查找是按码点二分,拿到的只要是一个连续升序的记录数组就行。mmap 返回指针后,查找代码一行不改,原来指向 rodata 的指针换成指向 flash 映射区,完事。

迁移的成本大头放在数据侧(生成器改一次),代码侧(热路径)零改动——数据格式迁就代码,而不是代码迁就格式。反过来做的诱惑是「顺便优化一下结构」,那样查找、预览、覆盖检查三条路径全要跟着改,回归面翻三倍。

两个刻意不搬的东西:96 个 ASCII 字形(1.5KB)留在固件——体量小,而且 UI 预览工具用正则直接从 font_data.c 里读它,留住就是工具链零改动。font_data.c 从此只剩 ASCII 表和一个 EPD_FONT16_EXPECT_COUNT 期望值,后面会讲到它是干嘛的。

运行时:不挂载,手工解析 FAT

第二个决定:不用 FATFS 挂载。挂载意味着 RAM 常驻文件系统状态、mount 有启动开销,而我们只读一个文件。需求退化到极简:给我这个文件的内存指针。

// app_main 开场:
assets_mount();                              // 分区可用性检查
const asset_blob_t *font = assets_mmap_file("FONT    BIN");
//   整分区 esp_partition_mmap → 从映射内存直接读:
//   BPB → 根目录(8.3 名匹配、跳 LFN/卷标)→ FAT12 簇链
font16_bind(font->data, font->count);        // 组件只认裸指针

整分区 esp_partition_mmap 之后,FAT 的元数据(BPB、根目录、簇链)直接当内存读:匹配 8.3 短文件名,跳过长文件名目录项和卷标,顺着 FAT12 簇链走一遍,校验簇链连续——生成的镜像文件天然连续,不连续只可能是镜像坏了,直接拒绝绑定,不伺候碎片。

代价:零 RAM 常驻。收益:字形访问走 flash cache,速度等同原来的 rodata,因为 mmap 本来就是 flash 映射。嵌入式的浪漫时刻——「文件」退化成「带名字的内存区间」。

分层:组件不认识文件系统

components/epaper 的字库模块只认 font16_bind(recs, count) / font16_unbind() 注入的裸指针,不 include 任何 assets 相关的头。FAT 的全部知识住在 main/core/assets.c,main 负责接线。epaper 组件保持可独立测试、可整体搬去别的项目——字库怎么来的,是字库组件不该问的问题。

退化链:坏了也要能自救

只读资产最怕的是「坏了 = 变砖」。这里的退化链分三层:

绑定失败(挂载失败/缺文件/魔数坏):CJK 全部画空心框,ASCII 正常,ERROR 日志。关键在于——菜单和设置页的图标是位图 blit,不走字库。所以界面照常可导航,用户能走到配网页把资产重传。优雅退化不是画一张错误页,是保证用户还能操作到修复路径。

直传期间( OTA 篇会讲 /api/assets 裸写 assets 分区):分区即将被擦除,开写前触发 evict 回调——font16_unbind() + 撤销 mmap,所有持有字形指针的模块先松手,悬垂指针不会踩进已擦除的 flash。传输失败时屏幕转空心框,但图标导航依然活着。

陈旧配对:字集是按「app 内全部 UI 文案 + 语料」收编的,font.bin 和 app 镜像一一配对。OTA 只更新 app 不更新 assets 时,新文案会缺字——以前这是文档里的一句约定,现在变成可观测的:EPD_FONT16_EXPECT_COUNT 是构建期烙进 app 的期望字数,启动时和 font.bin 头部的 count 对账,不一致就 WARN:

W (xxxx) font: font.bin has 7131 glyphs, app expects 7168

告警之后照常绑定:旧字全部正常,只有新增的几个字画空心框。缺字从「玄学花屏」变成「一行日志 + 几个空框」,排查成本差一个量级。

验证

tools/test_gen_font.py 断言 font.bin 的魔数、计数、码点升序、抽样记录内容,并检查 font_data.c 里只剩 EXPECT_COUNT 和 ASCII 表;idf.py build 自带的分区大小检查确认 app 从 1.49MB 降到 1.25MB、assets.bin = 1088KB。字库覆盖检查(check_glyph_coverage.py)改为直接读 assets/font.bin,和设备端看到的是同一份数据。

小结

这次迁移本质上是嵌入式版的数据库迁移,三板斧:格式同构保代码零改动,期望值对账保 app 与资产配对可观测,退化链保资产坏了设备还能自救。字库搬走之后,「大静态表归 assets 不归 app」才真正立住了——下一个想加语料的人,面对的是 170KB 的余量,而不是 139KB 的天花板。