wandering1
2575177e81
纯改名，检查行为一个字没动：规则逻辑、阈值、豁免形状全部原样。 改名原因（用户一句「R4 到底是什么」问出来的）：R1~R4 是我在 check_bsp_err.py 注释里 自造的序号，而这个裸形在本仓另有含义——R1~R8 已在 scripts/id_registry.json 登记为 "专项风险"的文档内编号（保护规划与看门狗的风险表都在用），带连字符的那一族又是审查 报告的可靠性 / 内存优化项编号（编号规范 §1 的"连字符承载语义"一行正是这么写的）。 **同一个裸形四种意思**。最刺人的一点：编号门禁**不会报**这种撞法，因为编号规范 §4.3 已把这些裸形声明为"同号不同义"、走 collides_with 白名单，校验 4 不计事故——同一天里 我起的另一组自造号被当场拦下、这组代号却一路绿灯，差别不在我做对了什么，而在白名单 挡的是"事故"、不是"可读性"。 新名同时是基线键的第二字段（格式 文件|标签|名字）： · err-type 错误通道不外泄（对外接口不拿 HAL_StatusTypeDef / bool 当成败） · timeout-name 超时宏不取负值 · return-doc 公开函数必须写「返回值：」 · consume-result 返回值不得裸丢弃（须接住或显式 (void)） 老名对照：R1=err-type、R2=timeout-name、R3=return-doc、R4=consume-result。 同步面：脚本里的规则码与 38 条基线键的字段**一起换**（中途不跑 --prune，否则改名会被 读成"38 条全还清 + 38 条新账"），换完 --emit-baseline 复核仍是 38/38/0、RC=0。现状类 文本全部换新名：AGENTS.md、pre-commit使用说明.md §2.27（新增"检查项叫什么"一行含老新 对照与撞号说明）、bsp_err.h 边界纪律、报告 §0.4 / §9 / 附录 A，以及代码注释里的 5 处 （gd5f2gq5ue.c/.h、nand_ftl.h、ui_menu_tab.h）。已提交的变更记录行里的老名按"冻结历史 不回改"处理，以 §2.27 对照行为准。ui_menu_tab.h 带 BOM，Edit 又剥掉、已按原样补回。 写说明文字时又被编号门禁拦了一次：我为了举例"老名撞车"，在那段话里写了两个编号字面， 被判"未紧邻文档名 / 未登记前缀"共 3 类新账——连批评自造编号的段落本身都在自造编号。 改法是不写号、只描述形态并指向权威条目。 验证：@build **0 错 0 警告**，Program Size 与上一笔**逐字段相同**（Code 213,676、RO 18,860、RW 1,188、ZI 131,500）→ 证明确为注释与文案，故不跑 @test（无指令变化）； pre-commit run 全绿 **17 项 Passed**；check_doc_links --all --sections-strict 147 篇 0 问题（中途我自己写的 §4.3 没紧邻文档名，被判成本文自引用，已补全路径）；9 个文件字节 卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、均有尾换行）。
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