存储架构说明增补§10.1使用注意事项:单写者/CCM-DMA约束/LVGL绘制护栏/FatFs短名与追加陷阱/栈钩子可观测性/BBT恢复模式

docs/STM32F4-Base存储架构说明.md

@@ -531,3 +531,13 @@ if (nand_ftl_format() == 0) {
 4. **坏块传播** — FTL 在擦除/编程失败后自动调用 `dhara_nand_mark_bad` → `gd5f2gq5ue_mark_block_bad`，BBT 在 RAM 中更新并立即通过 `gd5f_bbt_save()` 持久化到保留块池；下次复位后 `gd5f_bbt_scan()` 重建出厂坏块，`gd5f_bbt_load()` 再叠加保留池中保存的运行期坏块，因此运行期坏块在掉电后依然有效（详见 §4.8）。
 5. **功耗** — 擦除操作最大耗时约 5ms (驱动超时设为 5s)，页编程约 600ms (超时 1s)，读写操作快。在低功耗场景需注意合理安排操作时序。
 6. **缓存一致性** — 单页缓存 (s_cache_buf) 仅对 FatFS 层可见，多任务读写同一文件需在应用层同步。
+
+### 10.1 台架实证增补（2026-09，CCM 扩容 + 存储套件排障沉淀）
+
+7. **单写者规则** — 存储由 **defaultTask 独占**：挂载 / `f_mkfs` / 卷健康探针 / `net_cfg_load` / syslog 落盘 / 配置引擎全收敛于它。netTask / uiTask **不得**直接触碰配置引擎或 FatFS。启用存储测试套件（`TEST_SUITE_STORAGE`）时存储所有权整体移交 testTask，defaultTask 必须**完全跳过**存储 bring-up（`Src/freertos.c` 中 `#if !defined(TEST_SUITE_STORAGE)` 包裹）——否则后台文件写与测试的 `nand_ftl_deinit` 掉电模拟并发，互相踩坏 FTL/FatFs 状态（实测：mkfs 半途冻结 + BBT 被误写）。
+8. **内存布局与 DMA/CCM 约束** — FreeRTOS 堆（含全部任务栈）已迁至 **CCM `0x10000000`**（64KB，直连 M4 零等待），但 **DMA1/DMA2 物理不可达 CCM**。GD5F 驱动 `GD5F_DMA_THRESHOLD = 1024`：栈上的小缓冲（dhara meta 读 132B、`dhara_nand_is_free` 64B）一律走 **CPU 轮询**、绝不经 DMA；页级大块(2048)才走 DMA 且源/目的**全部是文件作用域静态缓冲**（落 SRAM）。新增任何 DMA 收发缓冲必须①文件作用域静态②大小≥阈值③确认落 SRAM。违反任一条 = 静默数据损坏（CCM 首轮扩容实验实证）。换料注意：克隆片可能缺 SRAM3(CCM)，必须重测。
+9. **LVGL 绘制缓冲越界护栏** — LVGL 9.3.0 对 I1(1bpp) 整帧渲染会在其算出的 `stride*h`(160×160/8=3200) 之后**多写 1 个字节**，紧邻 `g_ui_draw_buf` 之后的 `.bss`（如 `ui_menu_view` 的 `s_frame_box`）指针最低字节被打成 `0xFF` → 野指针 → HardFault（`PC=lv_obj_get_scroll_y`）。`ui_port.c` 的 `g_ui_draw_buf` 已预留 `UI_DRAW_BUF_GUARD=32` 字节护栏吸收该越界写（逻辑尺寸仍按 `UI_FB_SIZE` 上报，渲染数学不变）。**勿删护栏、勿把缓冲缩到与邻接 `.bss` 紧邻**。Lib/LVGL 为第三方不改。
+10. **FatFs 严格 8.3 短名** — 详见 AGENTS。补充：含冒号 `:` 的名字被 FatFs 先解析为**盘符前缀** → `f_open` 返回 `FR_INVALID_DRIVE`(11) 而非 `FR_INVALID_NAME`(6)；两者都属合法拒绝（测试用例须同时接受）。
+11. **FA_OPEN_APPEND 陷阱 / 短写** — 详见 AGENTS。追加写必须 `FA_WRITE | FA_OPEN_APPEND`；`f_write` 簇分配失败返回 `FR_OK`+短写（无错误码），判失败必须校验写回字节数。
+12. **崩溃可观测性（勿屏蔽）** — 已开启 `configCHECK_FOR_STACK_OVERFLOW=2` + `configUSE_MALLOC_FAILED_HOOK` + HardFault 现场报告（`Src/stm32f4xx_it.c`：裸 UART 打印 PC/LR/xPSR + CFSR/HFSR/BFAR/MMFAR 后复位，对照 `.map` 定位符号）。defaultTask **1024** words、testTask **2048** words 是**实测下限，勿降**。开机日志出现 `[ERR] STACK OVERFLOW task=` / `[ERR] HARDFAULT ...` / `MALLOC FAILED` 是精确定位线索，禁止屏蔽或降级。
+13. **BBT 恢复模式** — 运行期坏块会随 TC-STO-03 注入累积；当介质被**误标脏**（如 DMA 误打 CCM 栈导致随机块被写坏并持久化）时，打开 `test/storage_test.h` 的 `ENABLE_STORAGE_RECOVERY_TESTS` 编译**恢复构建**，testTask 会执行 `gd5f2gq5ue_bbt_rebuild()`（出厂扫描清除运行期误标）+ `nand_ftl_format()` 清账后复位。恢复后容量回到基线（即扣除 BBT 保留池后的正常容量，非出厂裸容量）。