wandering1
7e77af08a0
推荐清单第 4a 步（结构债 S-2 剩余面里唯一带"静默失效"属性的那条）。 **问题不是风格**：HAL 的 SPI 完成/错误回调是**全局唯一符号**，整个工程只能有一份 实现，当前由 CH395F 代管并按 `hspi->Instance` 分发——于是 GD5F 的完成标志 `g_spi1_dma_done` 被 CH395F 跨模块裸 `extern` 直接写，**GD5F 出错时的"释放等待者" 寄居在别人的 .c 里**。谁哪天做"CH395F 清理"，把那两个 `else if (SPI1)` 分支当无关 代码删掉：编译零报错，GD5F 的 DMA 等待在出错时只能干等 `GD5F_SPI_TIMEOUT` 兜底。 **改法（时序一字不动，只换所有权）**： · 标志收为 GD5F 文件内 `static volatile uint8_t s_spi1_dma_done`（6 处引用同步改名） · GD5F 导出 `gd5f_spi1_notify_done()` / `gd5f_spi1_notify_error()`，头文件里写明 "SPI1 分支必须转调这两个函数，否则本模块的 DMA 等待在出错时只能靠超时兜底" · CH395F 删除裸 `extern`、include `gd5f2gq5ue.h`、两个 SPI1 分支改为转调并就地注明 "勿删：少了这行 GD5F 的 DMA 出错只能靠超时退出" `HAL_SPI_AbortCpltCallback`（`HAL_SPI_DMAStop()` 会触发）本次**刻意不做**——它会改 变中止语义、需要真机专项，当前超时兜底可用（已在报告 §0.4 记为观察项）。 **体量代价**：`ch395f.o` −8 B、`gd5f2gq5ue.o` +24 B → `Code` 213,188 → **213,204 B （+16 B）**，RO/RW/ZI 全不变，`ER_IROM1` 231,768 → **231,784 B（22.1%）**。16 B 换 掉一个静默失效类，划算。 **真机 `@test` PASS**：无 `[ERR]`/Fault，复位原因 software；`[STACK] heap free=15800 min_ever=8464` 与改前**逐项相同**；各任务实测峰值 default 2152 / net 1116 / ftp 764 / ui 4052 / timesync 616 / adc 952 / iec104 540 / protect 624， **静态最坏链全部未变**（3024/1912/1456/4052/1264/1320/1456/872）→ 9/9 PASS。 ⚠ 记一条读数陷阱：测试脚本打印的 "boot to net init: OK = 7,907 ms" 是采集窗口 锚点造成的度量偏差，真机日志里 `boot: syslog init OK → net init: OK` 实测 ≈699 ms， 与改前一致，**不是性能回退**。 **数字联动**：`data/ram_report_20261022.md`、`data/stack_report_20261022.md` 重跑； `ram_baseline.py --update/--write`；`check_mem_numbers.py --write`（RAM 方案受管区 + 台账）；`gen_memory_svg.py` 常量更新后重新生成 FLASH 与任务栈两张配图（逐文本按 字号与锚点复查越界 = 0；RAM 图无需变更）；报告 §1.3/§5.1/§5.4、部署文档 §3.3 的 Flash 数字同步；§0.4/§9 的 S-2 口径改为"24 处手写已消 23 处，只剩 `net_socket.c:77`"。 门禁：`@build` 0 错 0 警告；`cubemx-survival --check`、`mem-numbers`、`mem-budget` （57.4% / 87.9%）、`task-table`、`doc-links --all --sections-strict`（146 文档 0 问题）、 `id-check --strict`（增量拦截通过、可判定 82.83%）全绿；字节卫生 BOM/CR/U+FFFD/尾 空格全清；未提交 UV4 抖动的 `.uvprojx`（本次未被改写）。未推送。
Drivers/BSP/GD5F2GQ5UE/ — GD5F2GQ5UE SPI NAND 驱动 + FTL
256MB SPI NAND Flash 驱动，以及之上的 FTL（Flash 转换层，
nand_ftl.c）—— 提供逻辑块映射、坏块管理、磨损均衡。再上层是 dhara（坏块/磨损算法）与 FatFs。
文件一览
| 文件 | 作用 |
|---|---|
gd5f2gq5ue.c/h |
NAND 芯片底层驱动：读/写/擦除、页/块管理、ID 与状态查询 |
nand_ftl.c/h |
FTL 层：逻辑地址 → 物理地址映射、坏块表、磨损均衡 |
硬件接口
- SPI1：PE0 CS / PB3 SCK / PB4 MISO / PB5 MOSI / PB8 WP / PE1 HOLD
三层存储栈
FatFs（文件系统）
↓
dhara（坏块管理 + 磨损均衡算法，Lib/dhara/）
↓
nand_ftl.c（本目录，FTL 适配）
↓
gd5f2gq5ue.c（本目录，芯片驱动）
↓
GD5F2GQ5UE 芯片
⚠️ 改本驱动前必读陷阱
| 陷阱 | 说明 |
|---|---|
| FatFs 打开模式 | FA_OPEN_APPEND(0x30) 不含 FA_WRITE(0x02)——追加写必须 FA_WRITE|FA_OPEN_APPEND，否则 f_write 恒返 FR_DENIED(7) |
| FatFs 文件名 | 严格 8.3 短名、不得以点开头（.fschk 会 FR_INVALID_NAME，纯 RAM 判定不碰盘）；自愈逻辑严禁把名字类错误归入"卷损坏"触发集 |
f_write 簇分配失败返回 FR_OK + 短写 |
判失败必须校验写回字节数（无错误码） |
| 禁用 C 库堆分配 | MicroLIB 堆仅 512B，malloc 必返回 NULL；用 pvPortMalloc/vPortFree |
完整台账见
docs/问题记录/GD5F2GQ5UE_Trap_Records.md。
相关文档
- 存储架构：
docs/架构设计/STM32F4-Base存储架构说明.md - 测试指南：
docs/测试说明/GD5F2GQ5UE_Test_Guide.md - 容量恢复：
docs/测试说明/存储维护与容量恢复.md