wandering1
15aa08552c
用户裁定：该报告大部分内容已闭环，可删除；仍有价值的迁到合适文档。删前逐条核对， 确认绝大多数结论在仓内早已有权威副本（LV_DRAW_SW_COMPLEX / osFlagsNoClear / SPI 分频 8 / 分层反向依赖存量基线等），只迁真正独有的四类内容： 1. 暂缓理由与重开条件（三条量化门槛）→ RAM 使用分析与优化方案 §4，并明确「本节是唯一 权威」，其它文档只留指针；同时把 10 处指向报告 §5.3 的重开条件引用改指该节。 2. 2026-10-22「常驻 vs 动态」三项诊断（静态前五块 43,462 B = 58%；动态面只有 heap_4， 故栈余量=CCM 余量；栈深主因是日志/配置写链）→ 同文档 §2.5。 3. `_fp_digits` 1,018 B 删不掉的机理与 F-6 根因修法（Q10 宏改单精度，−332 B，4.49e6 例 逐位等价）→ §2.6.4。 4. 「UI 侧缓冲进 CCM」要按 DMA 可达性二分（LVGL 池可进，帧缓冲/推流缓冲不可）→ 暂缓清单。 编号侧（报告曾是 6 个族的属主登记处）： - 原报告 §9 的 26 行「号 → 现在详述于」对照表迁到 docs/编号规范.md 新增 §4.5，6 族 owner_docs 改指该节。规范正文含大量写法示例，直接当定义集会误伤，故 check_ids.py 新增 `_def_owners`：snapshot_only 族剔除规范正文，只恢复可判定、不参与悬空/撞号/裸形 /紧邻判定（实测若不分，裸形 S1 误报 238 条、S-3 与登记簿 S-3 误判重复定义）。 - 11 个已死号（N-03b/N-10~N-13/N-20/N-21/N-24/N-26/S-1/S-2）在 id_aliases.json 登记 status=void 并写明去处——它们被约 110 处代码注释与文档引用，原先只靠「报告里顺带提过 一句」才算有定义，报告一删就集体悬空。N-21/S-1/S-2 一号两义，注记已分别标明。 - 顺带修 id_aliases.json 的 note 被脚本累积重复 26 次；修 registry 里 3 处仍指向改名前的 任务卡文件名（W1-采集保护收尾.md / W8-数据可信.md），以及 iec104_master.py 两处同类注释。 门禁：check_ids --strict 通过（可判定 8747/10410 = 84.02%，基线由 82.6% 抬到 84.0%）； check_doc_links --all --sections-strict 通过（177 文档）；pre-commit 相关钩子全过。
4.9 KiB
lv-conf-sync — 两份 lv_conf.h 的生效值必须一致
一句话：MCU 那份与模拟器那份 LVGL 配置，比对的是最终生效值（含默认值回填），不是 "文件里写了什么"。不一致时最直接的伤害是：像素回归跑的不是固件真正编译的那套特性。
- 配置：
entry: python scripts/check_lv_conf_sync.py、pass_filenames: false；2026-10-11 加， 与 Flash 死代码裁剪那一簇同批落地（背景见docs/内存管理/RAM使用分析与优化方案.md§2.6.4）。
1. 它在查什么
比对 Lib/lv_conf.h（MCU）与 simulator/lv_conf.h（PC），对每个宏取生效值：文件里没定义的，
去 Lib/lvgl/src/lv_conf_internal.h 取默认值。四类判定：
| 类别 | 含义 | 级别 |
|---|---|---|
| MISMATCH | 生效值不同 | FAIL |
| INVALID | 写了 LVGL 根本不认的宏名（写了不生效） | FAIL |
| DUPLICATE | 同一文件里定义两次（后者生效，极易误读） | FAIL |
| IMPLICIT | 一边靠默认值生效 | 告警（若默认值与另一边不同，已升级为 MISMATCH） |
2. 为什么要它（本目录里"省了多少字节"最可量化的一篇）
-
此前长期漂移：模拟器早已 I1-only，MCU 端却让 11 个
LV_DRAW_SW_SUPPORT_*、5 个未用控件类、LV_USE_THEME_SIMPLE、LV_USE_FLEX/GRID全靠默认值隐式生效，把用不到的代码整份链进固件 = 实测 64,576 B 死代码（旧镜像的 23.5%）。 -
更糟的一面：
ui-golden跑的是模拟器那份配置 → 特性子集不一致时，回归验证不到固件真实行为。 -
首次落地实测（2026-10-11）：两端共清掉 26 个 LVGL 9.3 根本不存在的选项（LVGL 8 / 9.4 模板 残留）与 3 处同文件重复定义，并把 10 项 MCU 端靠默认值隐式生效的开关显式写成 0（含默认值为 1 的那批）。
-
lv_conf_internal.h里每个选项外面还套一层#ifdef LV_KCONFIG_PRESENT—— 取默认值必须穿过这层， 否则整表都会被算成"未定义"。
3. 触发面
-
files:覆盖两份lv_conf.h与本脚本；--mcu/--sim/--internal/--lvgl-src可换输入（测脚本自己用）。 -
--list打印全量对照表，是回答"到底哪些宏在两边不一样"的唯一可靠入口。 -
触发面覆盖两端任一改动（
Lib/lv_conf.h、simulator/lv_conf.h或脚本自身）。⚠ 早期版本只能由 MCU 端触发，因为顶层exclude把simulator/整目录挡掉了 —— 这正是"pre-commit 4.x 没有always: true，触发面必须写全"的典型案例（教训登记在docs/代码规范/pre-commit使用说明.md§5.5）。
4. 报错怎么读
两份 lv_conf.h 特性子集一致性.......Failed
MISMATCH LV_USE_GRID: MCU=1(默认) SIM=0
- 单独跑：
& '.venv\Scripts\python.exe' scripts/check_lv_conf_sync.py --list。 - 修法一律是两边都显式写出来（把生效值写成定义），别靠"两边都不写、默认值刚好一样"过门。
- 退出码 0 一致 / 1 有不一致或无效或重复 / 2 环境错误（文件缺失）。
5. 好处
- 直接防 Flash 回归（23.5% 那个量级），也让"模拟器看到的 = 固件编译的"这句前提成立。
- INVALID/DUPLICATE 两类抓到的是"写了却不生效"这种最难查的坑。
6. 限制与盲区
- 只比对这两份文件里出现的 + LVGL 认识的宏：某个宏两边都没写、默认值也相同 → IMPLICIT 都不报， 但一旦 LVGL 升级改了默认值，两边可能同时变成你不想要的值，而它是一致的、绿的。
- 依赖
lv_conf_internal.h的路径与形态（--internal可覆盖）：LVGL 换版本、内部头改名， 默认值回填会退化成"看不见"。 - 不校验条件编译：
#if defined(...)包住的#define是否真的生效，脚本不判断。 - 不校验特性之间的语义冲突（比如开了 A 必须开 B），只管两边一致。
- IMPLICIT 只是告警：长期靠"顺手补一行"来收敛，没有基线压力。
7. 豁免与基线
-
无基线（硬拦截）。两边确实要不同时，唯一正确做法是先问"为什么模拟器要偏离固件"—— 答案通常是"模拟器有桩/无硬件"，那属于平台后端差异，不该藏在
lv_conf.h里。 -
另有端专属白名单
ALLOW_DIFF：SDL2 驱动、演示工程、include 替换、调试辅助（LV_USE_OBJ_NAME等）、断言（固件关 / 模拟器开）、LV_USE_SNAPSHOT（模拟器截图回归要用）。登记必须写理由。
8. 改这个门禁本身
- 扩充受检宏清单要同步
--list输出；新增 INVALID 词表时要跟着 LVGL 版本走，否则会把合法宏 误判成不认（假阳性会逼人--no-verify，比没有门禁更糟）。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-23 | 首篇逐项文档（含 64,576 B / 23.5% 死代码实测出处） |