merge: task/N15-nand-ftl-pagebuf 合入 v2-on-ui

任务 N15（1 个提交）经 task-worktree 回收： - docs(存储): 补上 N-15 页缓冲可合并性论证，判定三块不可合并
2026-10-23 12:14:40 +08:00
parent 6822726b2c b22779d244
commit b145e74ded
3 changed files with 100 additions and 6 deletions
@@ -297,7 +297,8 @@ int dhara_nand_prog(const struct dhara_nand *n, dhara_page_t p, const uint8_t *d
 *
 * 成本处理：先查页首 64 B——页首就有数据的页（绝大多数已编程页）当场返回非空，
 * 与旧实现同价；只有"目前读到的全是 0xFF"的页才继续扫后段。分块用栈上 64 B
- * 缓冲，不新增 2 KB 静态 RAM（页缓冲三块不可合并的评估见报告 R-3）。
+ * 缓冲，不新增 2 KB 静态 RAM（页缓冲三块不可合并的论证见
+ * docs/内存管理/存储栈RAM优化调研.md §5）。
 */
 int dhara_nand_is_free(const struct dhara_nand *n, dhara_page_t p) {
    uint8_t buf[64];
@@ -402,8 +403,9 @@ DSTATUS disk_initialize(BYTE pdrv) {

    /* N-26 启动期地址自检（2026-10-12）：本文件三个页缓冲是 SPI1 DMA 路径上
     * 唯一的**静态**缓冲（dhara_map_read/write → dhara_nand_read/prog/copy，
-     * 2048 B > GD5F_DMA_THRESHOLD；s_page_buf 现仅装 dhara meta 132 B 走轮询，
-     * 但它同为页尺寸且交给 dhara 内部使用，一并守住防将来越窗）。
+     * 2048 B > GD5F_DMA_THRESHOLD；s_page_buf 页内虽只攒 132 B 元数据，
+     * 但编程的是**整页**（journal.c:992），传输长度同为 2048 B、同样走 DMA，
+     * 一并守住防将来越窗）。
     * DMA1/DMA2 不可达 CCM——若 scatter 改动/段放置把它们挪进 CCM，DMA 会
     * **静默不落地**（数据错而传输"成功"）。缓冲地址链接期才确定，armcc
     * 无法编译期断言（见 gd5f2gq5ue.h 的窗口常量注释），故在 init 期自检：
@@ -1,6 +1,6 @@
 # 存储栈 RAM 优化调研

-> 版本 v1.1　日期 2026-09-21　作者 AI 辅助调研
+> 版本 v1.2　日期 2026-10-23（v1.2：新增 §5 页缓冲可合并性论证，承接报告的 N-15）　作者 AI 辅助调研
 > 数据来源：`data/ram_report_20260921.md`（.map 静态占用）+ 逐行代码核验（`nand_ftl.c` / `gd5f2gq5ue.c` / `Lib/dhara` / `Lib/FatFs/ffconf.h` / `lftpd*`）
 > 定位：`RAM使用分析与优化方案.md` 的存储专项补充；优化项编号 P0/P1/P2，与 `docs/内存管理/RAM使用分析与优化方案.md` §6 的 S 序号在"规划"一节对齐
 > v1.1 清理（2026-09-21 同日）：移除已落地的 P0-1 BBT 页缓冲收缩（−1,776B，commit `be1a30a`）与编程回读校验整体移除的实施记录（详见 GD5F TRAP-GD5F-05），以及过期逐模块基线表；仅保留未实施项与回归要求
@@ -47,3 +47,94 @@
 - P0-2/P2-x：待 RAM 余量需要时再议
 - 下次存储改动照常执行台架破坏性套件 + 掉电 resume
 - 基线数字可用 `data/ram_report_20260921.md`（P0-1 前快照）复核；实施后重生成基线报告并回填总方案
+
+## 5. 页缓冲可合并性论证（2026-10-23）
+
+> 本节的来源：`Drivers/BSP/GD5F2GQ5UE/nand_ftl.c` 原注释声称"页缓冲三块不可合并的评估见报告"，
+> 而 `../问题记录/项目审查与优化建议报告.md` 里只有一行"中 / 暂缓"，**论证从来没写过**——本节补上
+> （该注释已在本轮改为指向本节）。
+> 结论：**三块不能合并**（最坏路径上同时存活，合并后的失败形态是**静默数据损坏**，不是报错）；
+> 可削减的只有 `s_copy_buf` 一块，上限 −2,048 B，而**收益落点不是红线区** →
+> `docs/问题记录/项目审查与优化建议报告.md` N-15 由"待评估"改为"**已评估、判定不做**"，
+> 与本文件 §2 那两条残余方案一起留在暂缓簇里。
+
+### 5.1 6,216 B 的构成（`.map` 实证）
+
+| 符号 | 尺寸 | 链接地址（2026-10-23 构建） | 角色 | 谁在写它 |
+|---|---:|---|---|---|
+| `s_page_buf` | 2,048 | 0x200066B4 | dhara journal 的 checkpoint 页缓冲（`dhara_map_init` 传入，`nand_ftl.c:426`） | `journal.c`：逐页累加 132 B 元数据，攒满 16 页后整页编程 |
+| `s_cache_buf` | 2,048 | 0x20006EB4 | FatFS 页缓存（512 B 扇区 → 2 KB 页的 RMW） | `disk_read` / `disk_write` / `ftl_flush_cache` |
+| `s_copy_buf` | 2,048 | 0x200076B4 | `dhara_nand_copy()` 的搬页暂存（GC） | `dhara_nand_copy`（`nand_ftl.c:379`/`:383`） |
+| `s_map` / `s_nand` / 3 个标量 | 56 + 8 + 8 | 0x2000667C 起 | dhara 状态与缓存标志 | — |
+
+`nand_ftl.o` 合计 **6,216 B = RW 16 + ZI 6,200**，其中三块页缓冲 6,144 B 占 **98.8%**。
+`../问题记录/项目审查与优化建议报告.md` §5.2 的 Top-5 表用 ZI 口径写 6,200，与本节的 6,216 差的就是那 16 B 的 RW，两处不矛盾。
+
+### 5.2 三块同时存活的证据链（最坏路径）
+
+触发条件是**一次脏页回写正好撞上 journal 满 → 自动 GC**，稳态写入下是常态而非边角：
+
+1. `disk_write()` 把 512 B 扇区拼进 `s_cache_buf` 并置脏（`nand_ftl.c:565`）；
+2. 整页凑满或 `CTRL_SYNC` → `ftl_flush_cache()` → `dhara_map_write(&s_map, lpn, s_cache_buf, …)`
+   （`nand_ftl.c:195`）——**此刻 `s_cache_buf` 就是被写的数据本身**：dhara 把它当 `data` 直接交给
+   `dhara_nand_prog()`（`journal.c:1021`），坏块重试时还要再读一次；
+3. `dhara_map_write()` 先调 `prepare_write()`（`map.c:356`），而后者**第一件事**就是 `auto_gc()`
+   （`map.c:327`）——回收发生在数据落盘**之前**；
+4. `auto_gc → dhara_map_gc → raw_gc → dhara_journal_copy → dhara_nand_copy(src, head)`
+   （`map.c:247`、`journal.c:1042`），搬页需要一块 2 KB 暂存 = `s_copy_buf`；
+5. 与此同时 `s_page_buf` 里攒着**当前 checkpoint 周期内已入队页的元数据**：`push_meta()` 每入队一页
+   就 `memcpy` 一段 132 B 进去（`journal.c:972`），攒满 16 页才整页编程（`journal.c:992`）。
+   这是**跨调用存活的状态**，不是暂存。
+
+于是第 4 步执行时三块同时持有活数据：待写的缓存页、已攒的 checkpoint 元数据、搬页暂存。
+任取两块合并，被覆盖的一方都会变成垃圾，而**没有一处会报错**——这与 E-31 / N-21 两次
+"宁可报错，不可静默"的教训同族，属于必须回避的失败形态。
+
+### 5.3 逐对否证
+
+| 合并方案 | 看似可行的理由 | 实际后果 |
+|---|---|---|
+| `s_copy_buf` ⊕ `s_cache_buf` | "搬页只是中转，用完即弃" | 覆盖的正是**还没写下去的那一页**；`journal.c:1019` 的重试循环会拿被污染的数据再编程一次 → 该页永久错数据 |
+| `s_copy_buf` ⊕ `s_page_buf` | "元数据才 132 B，占不了多少" | checkpoint 元数据在页内**跨 0..1,999 偏移**分布（`hdr_user_offset()`，`journal.c:89`；本卷 `log2_ppc=4` → 15 段），被覆盖 → checkpoint 内容错 → 复位后整段回退或 `E_CORRUPT_MAP` |
+| `s_page_buf` ⊕ `s_cache_buf` | "都是页缓冲，都是 2 KB" | 同第二行；且 `s_page_buf` 的存活期以**16 页**为单位，远长于缓存页 |
+| 条件别名（脏时用 A，否则用 B） | "只有一条路径同时用" | 需要"缓存是否脏"这个跨模块标志；将来任何从 dhara 侧新进的调用点都会静默踩中。为省 2 KB 引入一条**不可静态验证**的隐式契约，收益与风险不成比例 |
+
+`s_page_buf` 也不能缩：虽然每页只用到 132 B 元数据，但**编程的是整页**（`journal.c:196` 整页
+`memset` 0xFF + `journal.c:992` 整页 `prog`），且元数据段一直排到偏移 1,999 → 必须 2,048 B。
+
+### 5.4 真正可动的只有 `s_copy_buf`
+
+| 方案 | 收益 | 做法 | 代价 / 风险 |
+|---|---:|---|---|
+| `s_copy_buf` 分块（本文件 §2 方案清单） | **−1,536 B** | 512 B 分块：`page_read` 一次 → 4×(read_from_cache → program_load) → **一次** `program_exec` | 正确性风险低（仍是一次编程，ECC 一次算完，不是"部分页编程"）；但 512 B 不大于 `GD5F_DMA_THRESHOLD`(1024) → 4 次全走 CPU 轮询：SPI1 42 MHz 下 2 KB 线上时间 0.39 ms，轮询比 DMA 多约 25~50%，即每页多 ~0.1~0.2 ms 且全程占住 CPU（不 yield）。要保住 DMA 就得下调阈值，而那会破坏"阈值 ≥ 存储路径最大栈缓冲"这条编译期契约（`gd5f2gq5ue.h:105`），不建议 |
+| 内部搬页（copy-back，本文件 §2 方案清单） | **−2,048 B** | `PAGE READ(13H)` src → `WRITE ENABLE` → `PROGRAM EXECUTE(10H)` dst，**主机侧零缓冲**（`../芯片手册/GD5F2GQ5UExxG.md` §9.6） | ① 手册限定"只能在**奇偶属性相同**的块之间搬"，跨属性行为须台架实证；② 读侧 ECC 校正后的数据才进 cache register，语义上等价于"搬页 + 纠错"，但同样要实测；③ 主机侧假芯片把 `program_exec` 建模成"必须 `program_load` 过"（`test/host/nand_port/nand_port_test.c:187`），要先补 internal-data-move 语义，否则正确实现会被判失败 |
+
+两条都**替代不了**"三块合一"：做满也只能把 6,216 B 压到 4,168 B，压不回 2 KB 级。
+
+### 5.5 为什么省下来也没用（落点分析）
+
+- 三块页缓冲全在 `RW_IRAM1`（0x2000_0000 窗口内，`gd5f_dma_buf_ok()` 白名单覆盖），该区
+  2026-10-23 实测 **75,264 / 57.4%，余 55,808 B**；
+- 红线在 **`RW_CCM`：57,376 / 87.9%，余 7,904 B**（FreeRTOS 堆 56 KB 吃掉了它）；
+- 所以这条线即使做满（−2,048 B）也**一分不减红线**；反过来把页缓冲搬进 CCM（本文件 §2 的 P1-5②）
+  才是"对红线有害"的方向——6,144 B 会吃掉 CCM 余量的 78%；
+- 把 `s_copy_buf` 挪到栈上同理：defaultTask 静态最坏链 3,024 B / 5,120 B，再塞 2 KB 直接顶到上限，
+  而任务栈本身就在 CCM。
+
+结论：**页缓冲合并这条线的收益没有消费者**。这正是 2026-10-15 整簇暂缓的机制原因，本节只是把它从"判断"
+补成了"论证"——所以暂缓不变，重开仍按 `../问题记录/项目审查与优化建议报告.md` §5.3 的三条条件。
+
+### 5.6 复现
+
+```bash
+grep -n "  nand_ftl.o" MDK-ARM/STM32F407-Demo/STM32F407-Demo.map   # 6,216 = RW 16 + ZI 6,200
+grep -n "s_page_buf\|s_cache_buf\|s_copy_buf" MDK-ARM/STM32F407-Demo/STM32F407-Demo.map
+```
+
+### 5.7 顺带订正的两处注释
+
+- `nand_ftl.c:300` 原写"页缓冲三块不可合并的评估见报告 R-3"，而报告里此前**没有**这份评估
+  → 改为指向本节。
+- `nand_ftl.c:405` 原写"`s_page_buf` 现仅装 dhara meta 132 B 走轮询"，**不成立**：`s_page_buf` 是
+  按整页编程的（`journal.c:992` → `dhara_nand_prog` → `gd5f_program_load(0, data, 2048)`），
+  与另两块一样走 DMA。原文这句话会误导后来做 P1-5②（迁 CCM）的人，已按实况改写。
@@ -63,7 +63,7 @@ B0h 验 `ECC_EN`**——原先那两行的注释自己写着"否则后续 I/O
 把 host 侧 SPI 失败与 DMA 等待超时也标成坏块，而 dhara 只在 `DHARA_E_BAD_BLOCK` 才 retire；改它得先定
 "host 侧失败给哪个码"，见变更记录） |
 | 网络 | N-09 / PHY ❌（N-25） | `NET_MAX_SOCKETS` 仍为 8（与单连接复用语义不符）；PHY 强制 100M 无自协商回退；PASV 每次新建监听 | 见 §4.2；随 N-25 一并处置 |
-| 存储 | N-15 🟡（N-25） | `nand_ftl.o` 静态 6,216 B——三块 2 KB 级页缓冲并存未合并 | 与 R-3 同批评估 |
+| 存储 | N-15 🟡 **观察项**（N-25） | `nand_ftl.o` 静态 6,216 B = 三块 2 KB 页缓冲 6,144 B + dhara 状态 72 B；**已论证三块不可合并**——GC 撞上脏页回写时三块同时持有活数据，合并后的失败形态是静默错数据 | **判定不做**（2026-10-23）：可削减的只有 `s_copy_buf`（−1,536 / −2,048 B），而收益落点 `RW_IRAM1` 余 55,808 B、红线在 CCM → 论证见 `../内存管理/存储栈RAM优化调研.md` §5 |
 | 存储/日志 | P2-10 ❌（N-25） | 卷锁现有 5 个使用者（配置原子写 / 日志 / SOE / lftpd_io / defaultTask），容量轮转删除与 UI 读并发仍未全覆盖 | 登记簿 S-5 面（卷锁覆盖面） |
 | 仓库 | D-1 ❌（N-29） | jpg 707 个 / 37.3 MB；`docs` 45.3 MB 里芯片手册占 39.5 MB；`.git` **248 MB** | 降采样 / 拆 submodule / LFS 三选一 + 历史重写；已决策暂不做 |
 | UI | U2 残余（U 簇） | 组件库只有 `ui_w_records.c/h` 一个；其余仍是页内自绘 | 按产品需求决定要不要继续抽组件 |
@@ -378,7 +378,7 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
 | **N-09** | `NET_MAX_SOCKETS`/PHY/PASV 三项网络债 | ❌ 在策 | 本文 §4.2、登记簿 N-25 |
 | N-10 ~ N-13 | 主机侧 nand/dhara 移植层单测动因 | ✅ 已建 | `test/host/nand_port/`（第 16 个单测钩子） |
 | **N-14** | FTL 写回缓存无空闲/掉电强制 flush | ⏸ 暂缓 | 本文 §4.3、登记簿 N-22 |
-| **N-15** | `nand_ftl` 三块 2 KB 页缓冲未合并 | 🟡 在策 | 本文 §5.2、登记簿 N-25 |
+| **N-15** | `nand_ftl` 三块 2 KB 页缓冲未合并 | 🟡 **观察项（2026-10-23 判定不做）** | `../内存管理/存储栈RAM优化调研.md` §5、登记簿 N-25 |
 | N-16 / N-17 | 台架窗口项（task stall 归因等） | 🟡 待窗口 | 登记簿 N-16/N-17 |
 | **N-18** | V0.1 双转换器无共同采样触发 | ❌ 待 V0.2 | 本文 §0.3、AGENTS 硬件引脚节 |
 | N-19 ~ N-21 | 时钟/对时与已销项条目 | ✅ 已闭环 | 本文变更记录与去处表 |
@@ -627,6 +627,7 @@ USER CODE 区内只留「读 RCC_CSR → 写 RMVF 清除」两句、顺序约束
 |  | **S-2 第一步（实测纠偏）**：删掉 `gd5f2gq5ue.c:47`、`sd2506.c:20` 两处与 `Inc/spi.h`/`Inc/i2c.h` 重复的 `extern`，GD5F 改 `#include "spi.h"`（沿用 `ch395f.c:22` 的既有做法）。**镜像逐字节不变**：`Code=213,188 RO=18,580 RW=1,184 ZI=131,504` 与改动前完全相同，`@build` 0 错 0 警告 → 证明这两步是行为中性的。同时把 §0.4/§9 的旧口径换成实测值：**S-2 不是 4 处而是 25 处**（`App/task/default_task.c:52-69` 一次就有 18 行；`stm32f4xx_it.c` 的 `fault_entry_hard` 属 ARMCC `__asm` 合法例外，不该「修」），**S-1 不是语义错位而是真实反向依赖**（NETCFG include `App/cfg/cfg_file.h` 10 处 + UI 3 个文件）。**这两个旧数字是我 v3.0 重写时沿用未测，一并认错。** SPI 回调归属这条隐患（CH395F 替 GD5F 释放错误路径）目前只在本文 §0.4 留了痕，**尚未进登记簿**——要不要立项等你定。 |
 | **2026-10-22** | **执行 §5.4：F-6 落地、F-4 判定不做、F-5 降级观察项**（登记簿 N-28 同步改写） | 动手前逐条对 `.map` 与源码核（本报告"建议栏不可照抄"总口径的又一次复现——三处误判全部出在**建议栏**，"发现"栏字节数全对）。**F-6 ✅**：`App/algo/prot_set.h` 两个 Q10 宏去掉显式 `(double)`、`1024.0`→`1024.0f` → `@build` 0 错 0 警、Code 213,520→**213,188（−332 B）**；`.map` 中 `dflti`、`d2f`、`f2d`、`dfixi`、`fepilogue` 共 300 B 消失，自研侧不再引用任何双精度 helper。**原报告"来自 `printf` 的 `%f`"是误判**：全库 0 处 `%f`，剩余 `dadd`+`dmul`+`ddiv`+`depilogue`+`dfixul` = 1,018 B 由 `mc_w.l(printfa.o)` 的 `_printf_core → _fp_digits` 无条件引用，MicroLIB 层面删不掉。**数值等价用穷举证明**（宏内 42 个字面量 + `int32` 全域 ÷1024 往返 4.49×10⁶ 例零差异；×1024 方向 2×10⁵ 例零差异）；回归 = `prot_set` 90/90、`prot_elm` 47/47、`iec104` 97/97 主机单测全过。**F-4 ❌ 判定不做**：五项字节数逐字节仍准（合计 10,060 B）但**无一项有开关**，根因是 `lv_draw_sw.c` 的 `execute_drawing()` 无条件 switch 引用全部 task 类型；唯一总开关 `LV_DRAW_SW_COMPLEX` 被 `ui_deco.c` 的"浅 V"3 px 粗斜腿锁死（**2026-09-03 已实测失败并两端固化 =1**）；**原"mask/grad 是文字必经路径"的理由同时证伪**（字形走 blend 层 `mask_buf`，不经 `lv_draw_sw_mask_*`）。**F-5 🟡 降级观察项**：uvprojx 实测 326 个 `.c` / LVGL 201 个 / `.map` 零产出 **127 个**，但增量构建实测 4~5 s、远程 CI 刻意不跑 `@build`，原"−40%"无基线记录。同步更正 §0.1 Flash 行、§0.4 Flash 行、注册表 uvprojx 行、§1 口径行、§5.1 快照注与要点行、§6.4 LVGL 占比分母、W4 波次行；台账受管区与内存快照已 `--write` 回填（`mem-budget` / `mem-numbers` 转绿）。**`@test` 台架 PASS**（固件戳 `fw build: Oct 22 2026 10:36:15 suite=NONE dstr=off`；无 `[ERR]`/`ERROR`/`FAIL`/Fault，708 ms 到 `net init: OK`，`protect task start`、`i104: listening on 2404`、`[STACK]` 三面水位齐；`adc`/`phasor`/`freq` 心跳持续） |
 | **2026-10-14** | **清理：删除已完成与过时内容** | ① **已修复项按销项删除**（去处见下表）：N-02（FTP 鉴权）、N-03c（`Error_Handler` 降级）、**N-11（DMA 可达性三层防线 + 规则族 R1~R4）**、S-3（注册反向校验）、P2-5/P2-6（SD2506 负温度与 WRTC）、P2-8（`NET_RECV_TIMEOUT_MS` 已删）、P2-9（`mkdir` 幂等重试）、§5.5 前三条（内存治理三件套）、交付物清单已建项。② **删除过时层**：2026-09-16 / 2026-10-11 双列基线表与"复核期间未提交改动"口径说明、旧"组合结果预估"表、逐条"2026-10-11 复核"批注、历史变更记录行——内存数字改由 `../内存管理/RAM预算台账.md` 与 `scripts/ram_baseline.tsv` 持有。③ **按 2026-10-14 `.map` 与代码重测**全部保留结论的数字（含 `lftpd_log.c` 已删除并入 `lftpd_auth.c`，N-06 残余只剩 `rs485_task.c` 一条刻意缺口）。④ **修正三处错误**：R-5（`configMAX_PRIORITIES` 56→32）**判定不可行**（CMSIS-RTOS2 `#error`）；原 §7 把报告 S-5（驱动统一错误码）与登记簿 S-5（卷锁覆盖面）混为一谈；原 §5.5 第 4 条建议的 `_Static_assert` 形态在 AC5 上取不到链接期地址，已被"窗口断言 + 启动自检 + 运行时守卫"三层取代。⑤ 报告自有编号**不回改、不重排**（`../编号规范.md`） |
+| **2026-10-23** | **N-15 由"待评估"改判"判定不做"：补上页缓冲可合并性论证** | 报告此前把 N-15（`nand_ftl.o` 6,216 B、三块 2 KB 页缓冲）写成"与 R-3 同批评估"，但**评估本身从来没写过**——`nand_ftl.c:300` 的注释直接引用了这份不存在的"报告 R-3"。本次补齐（论证落 `../内存管理/存储栈RAM优化调研.md` §5）：① `.map` 实证 6,216 = RW 16 + ZI 6,200，三块缓冲 6,144 B 占 98.8%；② **不可合并**——`dhara_map_write()` 先 `auto_gc()`（`map.c:327`）再落数据，回收里的 `dhara_nand_copy()` 与"待写的 `s_cache_buf`""攒了 16 页的 checkpoint 元数据 `s_page_buf`"三方同时存活，任两块合并都是**静默错数据而非报错**；`s_page_buf` 也不能缩（元数据跨 0..1,999 偏移，编程的是整页）；③ 唯一可动的是 `s_copy_buf`：分块 512 B（−1,536 B，代价是 4 次 CPU 轮询）或内部搬页 copy-back（−2,048 B，须实证手册"奇偶属性相同"限制、并先给主机侧假芯片补 internal-data-move 语义）；④ **省下来也没用**：三块都在 `RW_IRAM1`（余 55,808 B），红线是 `RW_CCM`（余 7,904 B），做满也不减红线，搬进 CCM 反而吃掉其 78% → 暂缓不变、重开仍按 §5.3 三条条件。顺带订正 `nand_ftl.c:405` 一句错注释（原写 `s_page_buf` "仅装 132 B 走轮询"，实际按整页 2,048 B 编程、同样走 DMA，会误导 P1-5② 迁 CCM）。**仅注释 + 文档，镜像零变化**（`@build` 0 错 0 警告，Code/RO/RW/ZI 逐项不变） |

 ### 已销项条目的记录去处