解决一个擦除的bug

docs/GD5F2GQ5UE_Trap_Records.md

@@ -0,0 +1,31 @@
+# GD5F2GQ5UE 陷阱记录
+
+## Trap 01 — 块擦除地址错误（有效）
+
+**发现时间**：2026-07-21
+
+**现象**：
+`gd5f_block_erase()` 使用 `byte_addr = block × 128KB`（字节地址）作为 D8h 命令的入参，但 GD5F2GQ5UE 要求的是**页地址**（`block × 64`）。
+
+只有 block 0 的 byte_addr=0 与 page_addr=0 巧合一致，其余块全部指向了错误的物理块。导致：
+- 验证流程从未擦除过大部分块，厂标坏块每次重启都恢复
+- 基于错误擦除的实验结论全部无效
+
+**根因**：
+- `gd5f_block_erase(block_addr)` 用 `block_addr × GD5F_BLOCK_SIZE` 计算地址
+- 芯片 D8h 命令将 24-bit 地址作为页地址（行地址）解析：`RA<16:6>` 选块，`RA<5:0>` 选页内页
+- 对于 block=1，发送 `{0xD8, 0x00, 0x02, 0x00}` → 芯片视为 page=512 → 擦除 block=8
+- 导致 block 1~7、9~15、17~23…等大量块从未被擦除
+
+**修复**：改用 `page_addr = block_addr × GD5F_PAGES_PER_BLOCK`（块首页地址）
+
+**验证结果**（修复后）：
+- 全部 2048 块正确擦除，厂标全部清除，重启后 BBT scan 为 0
+- ECC 开启时 BBT rescan 正常工作
+- ECC 校验码正确生成（ECCS=0）
+- Block 0 无特殊行为
+
+**经验教训**：
+- D8h 和 13h/10h 都使用 24-bit 行地址，格式一致
+- 块擦除不使用 `block × block_size`（字节偏移），而用块首页地址
+- 芯片手册的 memory mapping 必须严格遵守