refactor(nand): dhara 几何字面量收单一真源 + 两条编译期守卫
CI / L0 静态门禁 (pre-commit) (push) Failing after 1m45s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 18s

上一笔提交 720f841 留下的待办,已登记在报告与 GD5F Trap Records 遗留 3。

ftl_page_in_range() 的越界上界 = num_blocks << log2_ppb,完全依赖 log2_ppb;
而这两个 log2_* 原本在 disk_initialize 里是裸字面量 11 / 6。将来换 128 页/块
的兼容片、只改了 GD5F_* 常量而忘了同步字面量,守卫会**静默算错**——偏大就是
越界守卫失效,正是它要防的那一类错误,且不报任何错。

收口方式比"加一条断言"更彻底:字面量收成 FTL_LOG2_PAGE_SIZE / FTL_LOG2_PPB
单一真源(disk_initialize 与守卫同取此宏,杜绝两处各写一遍再各自漂移),再加
两条负数组编译期守卫 FTL_PAGE_SIZE == (1 << FTL_LOG2_PAGE_SIZE) 与
GD5F_PAGES_PER_BLOCK == (1 << FTL_LOG2_PPB)。AC5 不支持 C11 _Static_assert,
负数组是本项目惯用法(同本目录 gd5f2gq5ue.h 的 N-26 DMA 契约守卫)。

验证:@build 0 错 0 警且**代码尺寸逐字节不变**(Code 213,540 / ER_IROM1
232,280 B / RW_IRAM1 75,232 B)→ 纯语义等价重构;主机侧移植层单测
149/149 PASSED。**守卫牙齿实测**:临时把 FTL_LOG2_PPB 改成 7 → 编译失败
(nand_ftl.c:70 error C2118 负下标),改回即恢复,证明它真会拦而不是摆设。

文档:GD5F Trap Records 遗留 3 由"待办"改为"同日已收口"并记收口方式;
nand_ftl.c 模块头修改记录补第 ④ 条。
This commit is contained in:
2026-10-15 13:35:31 +08:00
parent 720f841494
commit db16694a87
2 changed files with 30 additions and 7 deletions
+7 -4
View File
@@ -293,8 +293,11 @@ if (ok) {
2. **空白卷首启成本**:dhara resume 扫到的每个检查点页都是全 0xFF → 每页要 32 次列读
(旧实现 1 次)。量级仍小(O(log N) × ppc),但**首次挂载(新格式化卷)会明显变慢**。
台架若观察到该现象,根因在此,**不是回归**。
3. **守卫上界依赖硬编码 `log2_ppb = 6`**:`ftl_page_in_range()` 的上界 =
`n->num_blocks << n->log2_ppb`,而这两个 `log2_*` 在 `disk_initialize` 里是字面量。
3. **守卫上界依赖硬编码 `log2_ppb = 6`** ✅ **同日已收口**:`ftl_page_in_range()` 的上界 =
`n->num_blocks << n->log2_ppb`,而这两个 `log2_*` 原本在 `disk_initialize` 里是裸字面量。
将来换 128 页/块的芯片,守卫会**静默算错**(偏大 = 越界守卫失效,正是它要防的那类)。
→ 待办:加编译期断言 `GD5F_PAGES_PER_BLOCK == (1u << 6)`(本仓 `gd5f2gq5ue.h` 已有
"负数组 typedef"式契约断言先例,照抄即可)。
→ 收口方式比"加一条断言"更彻底:字面量收成 `FTL_LOG2_PAGE_SIZE` / `FTL_LOG2_PPB`
**单一真源**(`disk_initialize` 与守卫同取此宏,杜绝两处各写一遍再各自漂移),
再加两条负数组编译期守卫 `FTL_PAGE_SIZE == (1 << FTL_LOG2_PAGE_SIZE)` /
`GD5F_PAGES_PER_BLOCK == (1 << FTL_LOG2_PPB)`——改 GD5F 常量而不同步几何即编译错。
AC5 不支持 C11 `_Static_assert`,负数组是本项目惯用法(同本目录 `gd5f2gq5ue.h` 的 N-26 守卫)。