From 07c647d40cc177f9b035f337819e878e362a9654 Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Mon, 21 Sep 2026 00:53:06 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AD=98=E5=82=A8=E6=9E=B6=E6=9E=84=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=E5=A2=9E=E8=A1=A5=C2=A710.1=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E6=B3=A8=E6=84=8F=E4=BA=8B=E9=A1=B9:=E5=8D=95=E5=86=99?=
 =?UTF-8?q?=E8=80=85/CCM-DMA=E7=BA=A6=E6=9D=9F/LVGL=E7=BB=98=E5=88=B6?=
 =?UTF-8?q?=E6=8A=A4=E6=A0=8F/FatFs=E7=9F=AD=E5=90=8D=E4=B8=8E=E8=BF=BD?=
 =?UTF-8?q?=E5=8A=A0=E9=99=B7=E9=98=B1/=E6=A0=88=E9=92=A9=E5=AD=90?=
 =?UTF-8?q?=E5=8F=AF=E8=A7=82=E6=B5=8B=E6=80=A7/BBT=E6=81=A2=E5=A4=8D?=
 =?UTF-8?q?=E6=A8=A1=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/STM32F4-Base存储架构说明.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/STM32F4-Base存储架构说明.md b/docs/STM32F4-Base存储架构说明.md
index e42823f3..4aef9eb8 100644
--- a/docs/STM32F4-Base存储架构说明.md
+++ b/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 保留池后的正常容量，非出厂裸容量）。